Controlar a simultaneidade de fluxos de trabalho e trabalhos

Visão geral

Por padrão, GitHub Actions permite que vários trabalhos no mesmo fluxo de trabalho, vários fluxos de trabalho executados no mesmo repositório e vários fluxos de trabalho executados na conta do proprietário de um repositório sejam executados simultaneamente. Isso significa que várias execuções, trabalhos ou etapas de fluxo de trabalho podem ser executados ao mesmo tempo.

GitHub Actions também permite controlar a simultaneidade de execuções de fluxo de trabalho, para que você possa garantir que apenas uma execução, um trabalho ou uma etapa seja executado por vez em um contexto específico. Isso pode ser útil para controlar os recursos da sua conta ou organização em situações em que a execução de vários fluxos de trabalho, trabalhos ou etapas ao mesmo tempo pode causar conflitos ou consumir mais minutos e armazenamento de Ações do que o esperado.

Por exemplo, a capacidade de executar fluxos de trabalho simultaneamente significa que, se várias confirmações forem enviadas por push para um repositório em rápida sucessão, cada envio poderá disparar uma execução de fluxo de trabalho separada, e essas execuções serão executadas simultaneamente.

Usar a simultaneidade em diferentes cenários

Você pode usar jobs.<job_id>.concurrency para garantir que apenas um trabalho ou fluxo de trabalho que usa o mesmo grupo de simultaneidade seja executado por vez. Um grupo de concorrência pode ser qualquer string ou expressão. Contextos de expressão permitidos: github, inputs, vars, needs, strategy e matrix. Para obter mais informações sobre expressões, confira "Avaliar expressões em fluxos de trabalho e ações".

Especifique também concurrency no nível do fluxo de trabalho. Para obter mais informações, confira concurrency.

Isso significa que pode haver no máximo um trabalho em execução e um pendente em um grupo de simultaneidade a qualquer momento. Quando um trabalho ou um fluxo de trabalho simultâneo é colocado na fila, se outro trabalho ou fluxo de trabalho que usa o mesmo grupo de simultaneidade no repositório estiver em andamento, o trabalho ou o fluxo de trabalho na fila ficará pending. Qualquer trabalho ou fluxo de trabalho do pending existente no mesmo grupo de simultaneidade, se existir, será cancelado e o novo trabalho ou fluxo de trabalho na fila tomará seu lugar.

Para também cancelar qualquer trabalho ou fluxo de trabalho em execução no mesmo grupo de simultaneidade, especifique cancel-in-progress: true. Para cancelar condicionalmente trabalhos ou fluxos de trabalho em execução no mesmo grupo de simultaneidade, é possível especificar cancel-in-progress como uma expressão com qualquer um dos contextos de expressão permitidos.

Exemplos: Usar a simultaneidade e o comportamento padrão

O comportamento padrão de GitHub Actions é permitir que vários trabalhos ou execuções de fluxo de trabalho sejam executados simultaneamente. A palavra-chave concurrency permite controlar a simultaneidade de execuções de fluxo de trabalho.

Por exemplo, você pode usar a palavra-chave concurrency imediatamente após a definição das condições de disparo para limitar a simultaneidade de execuções de fluxo de trabalho inteiro para uma ramificação específica:

on:
  push:
    branches:
      - main

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

Você também pode limitar a simultaneidade de trabalhos em um fluxo de trabalho usando a palavra-chave concurrency no nível do trabalho:

on:
  push:
    branches:
      - main

jobs:
  job-1:
    runs-on: ubuntu-latest
    concurrency:
      group: example-group
      cancel-in-progress: true

Exemplo: grupos de simultaneidade

Os grupos de simultaneidade fornecem uma maneira de gerenciar e limitar a execução de execuções de fluxo de trabalho ou trabalhos que compartilham a mesma chave de simultaneidade.

A chave concurrency é usada para agrupar fluxos de trabalho ou trabalhos em um grupo de simultaneidade. Quando você define uma chave concurrency, GitHub Actions garante que apenas um fluxo de trabalho ou trabalho com essa chave seja executado a qualquer momento. Se um novo fluxo de trabalho for executado ou iniciado com a mesma chave concurrency, GitHub Actions cancelará qualquer fluxo de trabalho ou trabalho já em execução com essa chave. A chave concurrency pode ser uma cadeia de caracteres codificada ou pode ser uma expressão dinâmica que inclui variáveis de contexto.

É possível definir condições de simultaneidade em seu fluxo de trabalho para que o fluxo de trabalho ou trabalho faça parte de um grupo de simultaneidade.

Isso significa que, quando um fluxo de trabalho for executado ou iniciado, o GitHub cancelará todas as execuções de fluxo de trabalho ou trabalhos que já estejam em andamento no mesmo grupo de simultaneidade. Isso é útil em cenários em que você deseja impedir execuções paralelas para um determinado conjunto de fluxos de trabalho ou trabalhos, como os usados para implantações em um ambiente de preparo, a fim de evitar ações que possam causar conflitos ou consumir mais recursos do que o necessário.

Neste exemplo, job-1 faz parte de um grupo de simultaneidade chamado staging_environment. Isso significa que, se uma nova execução de job-1 for acionada, todas as execuções do mesmo trabalho no grupo de simultaneidade staging_environment que já estiverem em andamento serão canceladas.

jobs:
  job-1:
    runs-on: ubuntu-latest
    concurrency:
      group: staging_environment
      cancel-in-progress: true

Como alternativa, usar uma expressão dinâmica, como concurrency: ci-${{ github.ref }} em seu fluxo de trabalho, significa que o fluxo de trabalho ou trabalho faria parte de um grupo de simultaneidade nomeado ci- seguido pela referência da ramificação ou tag que acionou o fluxo de trabalho. Neste exemplo, se uma nova confirmação for enviada para a ramificação principal enquanto uma execução anterior ainda estiver em andamento, a execução anterior será cancelada e a nova será iniciada:

on:
  push:
    branches:
      - main

concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: true

Exemplo: Usar a concorrência para cancelar qualquer trabalho em andamento ou em execução

Para usar simultaneidade para cancelar qualquer trabalho em andamento ou executar no GitHub Actions, você pode usar a chave concurrency com o a opção cancel-in-progress definida como true:

concurrency:
  group: ${{ github.ref }}
  cancel-in-progress: true

Observe que, neste exemplo, sem definir um grupo de simultaneidade específico, GitHub Actions cancelará qualquer execução em andamento do trabalho ou fluxo de trabalho.

Exemplo: Usando um valor para segunda opção

Se você construir o nome do grupo com uma propriedade que só é definida para eventos específicos, você pode usar um valor de segunda opção. Por exemplo, github.head_ref só é definido em eventos pull_request. Se o fluxo de trabalho responder a outros eventos além de eventos pull_request, você precisará fornecer um fallback para evitar um erro de sintaxe. O grupo de simultaneidade a seguir cancela os trabalhos em andamento ou é executado somente em eventos pull_request. Se github.head_ref for indefinido, o grupo de simultaneidade fará fallback para a ID de execução, que tem a garantia de ser exclusiva e definida para a execução.

concurrency:
  group: ${{ github.head_ref || github.run_id }}
  cancel-in-progress: true

Exemplo: Cancele somente trabalhos em andamento ou execuções no fluxo de trabalho atual

Se você tiver vários fluxos de trabalho no mesmo repositório, os nomes dos grupos de concorrência devem ser únicos em todos os fluxos de trabalho para evitar o cancelamento de trabalhos em andamento ou de executores a partir de outros fluxos de trabalho. Caso contrário, qualquer trabalho em andamento ou pendente será cancelado, independentemente do fluxo de trabalho.

Para cancelar apenas as execuções em andamento do mesmo fluxo de trabalho, use a propriedade github.workflow para criar o grupo de simultaneidade:

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

Exemplo: cancelar apenas trabalhos em andamento em ramificações específicas

Se você quiser cancelar trabalhos em andamento em determinadas ramificações, mas não em outras, poderá usar expressões condicionais com cancel-in-progress. Por exemplo, é possível fazer isso se quiser cancelar trabalhos em andamento em branches de desenvolvimento, mas não em branches de lançamento.

Para cancelar apenas execuções em andamento do mesmo fluxo de trabalho quando não estiverem em execução em um branch de lançamento, é possível definir cancel-in-progress para uma expressão semelhante à seguinte:

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ !contains(github.ref, 'release/')}}

Neste exemplo, vários envios por push para um branch release/1.2.3 não cancelariam execuções em andamento. Envios por push para outro branch, como main, cancelariam execuções em andamento.