Skip to main content
Skip to content

Status de problemas, webhooks e fluxos de trabalho

Use webhooks e GitHub Actions fluxos de trabalho para responder quando o status de um problema for alterado.

Observação

Os status dos problemas estão dentro de prévia e só estão disponíveis para contas registradas na versão prévia. Os conteúdos do webhook e o status_changed tipo de atividade estão sujeitos a alterações.

Sobre eventos de alteração de status

Quando o status de um problema é alterado, GitHub envia um issues evento de webhook com a ação status_changed . Os conteúdos de cada issues ação também incluem o status atual do item em issue.status. Você pode usar esses eventos para manter outras ferramentas em sincronia com seus problemas ou para executar um GitHub Actions fluxo de trabalho quando um problema atinge um status específico.

Os status são incluídos apenas para issues em repositórios que usam status de issue. Para outros issues, os payloads não incluem issue.status, e GitHub não envia status_changed.

Para obter o esquema de conteúdo completo, consulte Eventos e cargas de webhook.

Objetos de status

Os payloads do webhook descrevem cada status com um objeto que tem três propriedades.

PropertyTipoDescription
idIntegerO identificador do status.
nameStringO nome de exibição do status, como In progress. O nome pode ser alterado.
categoryStringA categoria do status, como backlog, planned, started, completed, not_planned ou duplicate. Mais categorias podem ser adicionadas no futuro.

Mais de um status pode pertencer à mesma categoria. Por exemplo, In progress e In review pertencem à categoria started. Para identificar um status específico em seu código ou fluxo de trabalho, use seu id. Para corresponder a cada status em uma categoria, use sua category. Não corresponda a name.

issue.status é null quando o issue não tem um status. Por exemplo, um problema criado antes dos status estarem disponíveis em seu repositório não tem status até que alguém defina um ou até que o problema seja fechado ou reaberto.

O status_changed payload

Além de issue, repository, sender e as outras propriedades que cada payload issues inclui, um payload status_changed inclui as propriedades a seguir. Para essa ação, sender é a pessoa ou o aplicativo que alterou o status.

PropertyDescription
statusO status para o qual o item foi mudado.
changes.status.fromO status que o problema tinha antes da alteração ou null se ele não tinha um.
changes.state.fromO anterior state do problema, open ou closed. Incluído somente quando a alteração de status também fechou ou reabriu o problema.
changes.state_reason.fromO anterior state_reason do problema. Incluído somente quando a alteração de status também alterou o motivo do estado, por exemplo, fechando ou reabrindo o problema, ou alterando por que ele está fechado.
null É assim quando o problema não tinha um motivo de estado, por exemplo, na primeira vez em que é fechado.

Valores capturados e o item atual

As propriedades status e changes descrevem a alteração no momento em que ela foi salva. A propriedade issue, incluindo issue.status, descreve o problema quando a entrega foi compilada, o mesmo que para todas as outras issues ações. Se o item for alterado novamente antes disso, issue.status poderá ser diferente de status. Por exemplo, se alguém mover um item de Em andamento para Em revisão e, em seguida, rapidamente para Concluído, a entrega referente à primeira alteração poderá ter um issue.status de Concluído.

Para descobrir o que uma alteração específica fez, use status e changes. Uma carga atrasada, repetida ou reentregue pode estar obsoleta, portanto issue.status pode não ser o status mais recente do item. Para obter mais informações, consulte Entrega, mais adiante neste artigo.

Quando status_changed é enviado

GitHub envia status_changed sempre que o status de um problema é alterado, incluindo alterações feitas GitHub quando um problema é criado, fechado ou reaberto.

  • Definindo um status: alguém escolhe um status diferente para um problema.
  • Criando um item: um novo item obtém o status Backlog, a menos que a pessoa que o cria escolha outro status. changes.status.from é null. GitHub envia opened bem como status_changed.
  • Definindo um primeiro status: um problema existente sem um status recebe um status. changes.status.from é null.
  • Fechando ou reabrindo um problema: fechar um problema como concluído define o status Concluído, fechá-lo como não planejado define Não planejado e fechá-lo como duplicado define Duplicado. Reabrir um problema sem escolher um status define Backlog. GitHub envia closed ou reopened, bem como status_changed.
  • Vinculando uma solicitação de pull: vincular uma solicitação de pull aberta a um problema aberto que não tem status ou que tenha o status Backlog ou Todo, move o problema para Em andamento. sender é a pessoa ou aplicativo que vinculou o pull request. Se eles não puderem escolher um status para o problema, o status não será alterado.

GitHub não envia status_changed nestes casos:

  • O status não é alterado, por exemplo, quando alguém escolhe o status que a issue já tem.
  • A issue é transferida para outro repositório. O novo issue mantém seu status, que o payload transferred inclui em changes.new_issue.status.

Alterações de status que fecham ou reabrem um problema

Os status nas categorias completed, not_planned e duplicate são para problemas fechados. Escolher um desses status para um problema aberto encerra o problema e escolher um status em qualquer outra categoria para um problema fechado o reabre.

Quando uma alteração de status fecha ou reabre um problema, GitHub envia duas entregas: status_changede closed ou reopened. As duas entregas podem chegar em qualquer ordem.

Alterar um problema fechado para um status com um motivo próximo diferente, por exemplo, de Concluído para Não planejado, envia status_changed com changes.state_reason , mas sem changes.state. GitHub também envia outra closed entrega com o novo state_reason.

Se a integração manipular status_changed bem como closed ou reopened, verifique se ela pode lidar com a mesma alteração que está sendo relatada por ambas as entregas.

Entrega

GitHub entrega status_changed da mesma forma que outros eventos de webhook. A entrega é feita em regime de melhor esforço. GitHub não garante que cada alteração seja entregue exatamente uma vez ou que as entregas cheguem na ordem em que as alterações ocorreram.

  • Entregas com falha: uma entrega pode falhar, por exemplo, se o servidor não estiver disponível. GitHub não reenvia entregas com falha automaticamente, mas você pode reenviá-las. Para obter mais informações, consulte Como lidar com falhas de entrega de webhook.
  • Entregas repetidas: você pode receber a mesma entrega mais de uma vez, por exemplo, quando ela é reenviada. Uma nova animação tem o mesmo X-GitHub-Delivery cabeçalho que a entrega original, para que você possa usar o cabeçalho para ignorar as entregas que você já processou.
  • Ordem: as entregas podem chegar fora de ordem e as cargas atrasadas, repetidas ou reenviadas podem ser obsoletas, incluindo issue.status. Não use a ordem na qual as entregas chegam para determinar o status mais recente de um problema.

Para obter o status mais recente de um item, busque o item com a API REST. Para obter mais informações, consulte Pontos de extremidade da API REST para issues. Em repositórios de propriedade de uma organização, a resposta inclui status qualquer solicitação autenticada, incluindo solicitações autenticadas como uma GitHub App instalação e solicitações que usam GITHUB_TOKEN em um fluxo de trabalho. Durante o préviarepositório , em repositórios de propriedade de uma conta pessoal, a resposta inclui status somente quando a solicitação é feita em nome de um usuário que tem acesso à visualização. Se a resposta não incluir status, use o status das entregas com cuidado, pois um parto que chega mais tarde pode ter um status mais antigo.

Quem pode alterar um status

Pessoas com acesso de triagem ou superior a um repositório podem escolher o status de seus issues. Regras de permissão adicionais se aplicam a funções personalizadas, aplicativos, fluxos de trabalho e contas pessoais:

  • Funções de repositório personalizadas: em repositórios de propriedade de uma organização, pessoas com uma função personalizada que herda a função Triagem, Gravação ou Manutenção podem escolher status. Pessoas com uma função personalizada que herda a função de leitura não podem escolher status, mesmo que a função possa definir tipos de problema.
  • Aplicativos e fluxos de trabalho: em repositórios pertencentes a uma organização, GitHub Apps com acesso de escrita para a permissão de repositório "Problemas" também podem escolher status, incluindo fluxos de trabalho que usam GITHUB_TOKEN com a issues: write permissão.
  • Contas pessoais: durante o prévia, em repositórios de propriedade de uma conta pessoal, somente as pessoas que têm acesso à visualização podem escolher status.

Escolher um status que feche ou reabra um problema também requer permissão para fechar ou reabrir o problema. Alterar por que um problema fechado é fechado, por exemplo, de Concluído para Não planejado, requer permissão para fechá-lo e reabri-lo.

As pessoas que não podem escolher um status ainda podem alterá-lo fechando ou reabrindo um problema. Por exemplo, o autor de uma issue pode fechá-la e reabri-la com acesso de leitura ao repositório, o que define o status padrão para o novo estado. Essas alterações também enviam status_changed, e sender é a pessoa que fechou ou reabriu o problema.

Executando um fluxo de trabalho quando um status é alterado

Para executar um GitHub Actions fluxo de trabalho quando o status de um problema for alterado, use o status_changed tipo de atividade do issues evento. O fluxo de trabalho é executado sempre que o status de um problema é alterado. No fluxo de trabalho, as propriedades a seguir do github.event contexto descrevem a alteração.

  • github.event.status contém o status para o qual o issue foi alterado.
  • github.event.changes.status.from contém o status anterior ou null se o problema não tinha um.
  • github.event.issue.status contém o status do problema quando o payload foi criado. Os Payloads de cada tipo de atividade issues incluem essa propriedade.

Importante

Fluxos de trabalho que usam o evento issues sem types também são executados para status_changed. Esses fluxos de trabalho são executados sempre que alguém altera o status de um problema e executa um tempo extra quando um problema é criado, fechado ou reaberto, porque GitHub envia status_changed , bem como opened, closedou reopened. Para evitar execuções inesperadas, liste os tipos de atividade de que seu fluxo de trabalho precisa.

Durante o prévia, editores que validam arquivos de fluxo de trabalho, como o editor de fluxo de trabalho em GitHub, podem relatar status_changed como um tipo de atividade inválido. Pode ignorar este erro.

Por exemplo, fluxos de trabalho que correspondem a um status por sua ID e cada status em uma categoria, consulte Eventos que disparam fluxos de trabalho.

Exemplos de cargas úteis

Os trechos a seguir mostram as propriedades dos payloads status_changed que descrevem a alteração. Os payloads completos também incluem os objetos completos sender, issue e repository, além de outras propriedades.

Criar um problema

Quando alguém cria um problema sem escolher um status, o problema obtém o status backlog. changes.status.from é null, e changes não inclui state ou state_reason.

{
  "action": "status_changed",
  "issue": {
    "number": 1347,
    "state": "open",
    "state_reason": null,
    "status": {
      "id": 2,
      "name": "Backlog",
      "category": "backlog"
    }
  },
  "status": {
    "id": 2,
    "name": "Backlog",
    "category": "backlog"
  },
  "changes": {
    "status": {
      "from": null
    }
  }
}

Alterando para um status na mesma categoria

Mover um problema de Em andamento para Em revisão não altera seu estado ou sua categoria, portanto changes , inclui statusapenas .

{
  "action": "status_changed",
  "issue": {
    "number": 1347,
    "state": "open",
    "state_reason": null,
    "status": {
      "id": 8,
      "name": "In review",
      "category": "started"
    }
  },
  "status": {
    "id": 8,
    "name": "In review",
    "category": "started"
  },
  "changes": {
    "status": {
      "from": {
        "id": 4,
        "name": "In progress",
        "category": "started"
      }
    }
  }
}

Fechando um problema alterando seu status

Mover um problema do In review para Done encerra o problema. changes.state.from é open, e changes.state_reason.from é null porque o problema não tinha um motivo de estado antes. GitHub também envia uma closed implantação para essa alteração.

{
  "action": "status_changed",
  "issue": {
    "number": 1347,
    "state": "closed",
    "state_reason": "completed",
    "status": {
      "id": 5,
      "name": "Done",
      "category": "completed"
    }
  },
  "status": {
    "id": 5,
    "name": "Done",
    "category": "completed"
  },
  "changes": {
    "status": {
      "from": {
        "id": 8,
        "name": "In review",
        "category": "started"
      }
    },
    "state": {
      "from": "open"
    },
    "state_reason": {
      "from": null
    }
  }
}