Sobre fluxos de trabalho

Sobre fluxos de trabalho

Um fluxo de trabalho é um processo automatizado configurável que executará um ou mais trabalhos. Os fluxos de trabalho são definidos por um arquivo YAML verificado no seu repositório e será executado quando acionado por um evento no repositório, ou eles podem ser acionados manualmente ou de acordo com um cronograma definido.

Os fluxos de trabalho são definidos no diretório .github/workflows de um repositório. Um repositório pode ter vários fluxos de trabalho, cada um dos quais pode executar um conjunto diferente de tarefas, como:

• Criar e testar pull requests.
• Implantar seu aplicativo sempre que uma versão for criada.
• Adicionar um rótulo sempre que um novo problema for aberto.

Noções básicas do fluxo de trabalho

Um fluxo de trabalho precisa conter os seguintes componentes básicos:

1. Um ou mais eventos que acionarão o fluxo de trabalho.
2. Um ou mais trabalhos, cada um deles será executado em um computador executor e executará uma série de uma ou mais etapas.
3. Cada etapa pode executar um script que você define ou executa uma ação, que é uma extensão reutilizável que pode simplificar seu fluxo de trabalho.

Para obter mais informações sobre esses componentes básicos, confira Entendendo o GitHub Actions.

Acionando um fluxo de trabalho

Os acionadores de fluxo de trabalho são eventos que fazem com que um fluxo de trabalho seja executado. Esses eventos podem ser:

• Eventos que ocorrem no repositório do fluxo de trabalho
• Eventos que ocorrem fora do GitHub e que disparam um evento repository_dispatch no GitHub
• Horários agendados
• Manual

Por exemplo, você pode configurar o fluxo de trabalho para executar quando um push é feito no branch padrão do seu repositório, quando uma versão é criada, ou quando um problema é aberto.

Para obter mais informações, confira Acionando um fluxo de trabalho, e para uma lista completa de eventos, confira Eventos que disparam fluxos de trabalho.

Sintaxe de fluxo de trabalho

Os fluxos de trabalho são definidos usando YAML. Para obter a referência completa da sintaxe do YAML para a criação de fluxos de trabalho, confira Sintaxe de fluxo de trabalho para o GitHub Actions.

Para obter mais informações sobre como gerenciar execuções de fluxo de trabalho, tais como executar novamente, cancelar ou excluir uma execução de fluxo de trabalho, confira Gerenciando execuções e implantações de fluxo de trabalho.

Usando modelos de fluxo de trabalho

O GitHub fornece modelos de fluxo de trabalho pré-configurados que você pode usar no estado em que se encontram ou personalizar para criar seu próprio fluxo de trabalho. O GitHub analisa seu código e mostra os modelos de fluxo de trabalho que podem ser úteis para seu repositório. Por exemplo, se o seu repositório contiver o código Node.js, você verá sugestões para projetos Node.js.

Esses modelos de fluxo de trabalho são projetados para ajudar a entrar em funcionamento rapidamente, oferecendo uma variedade de configurações, como:

• CI: fluxos de trabalho de integração contínua
• Implantações: fluxos de trabalho de implantação
• Automação: fluxos de trabalho de automação
• Varredura de código: fluxos de trabalho de varredura de código
• Páginas: fluxos de trabalho de páginas

Use esses fluxos de trabalho como ponto de partida para criar seu fluxo de trabalho personalizado ou usá-los no estado em que se encontram. É possível navegar pela lista completa de modelos de fluxo de trabalho no repositório actions/starter-workflows. Para obter mais informações, confira "Usando modelos de fluxo de trabalho".

Recursos avançados de fluxo de trabalho

Esta seção descreve brevemente alguns dos recursos avançados de GitHub Actions que ajudam a criar fluxos de trabalho mais complexos.

Armazenar segredos

Se os fluxos de trabalho usarem dados confidenciais, como senhas ou certificados, salve-os no GitHub como segredos e use-os nos seus fluxos de trabalho como variáveis de ambiente. Isso significa que você poderá criar e compartilhar fluxos de trabalho sem precisar incorporar valores confidenciais diretamente na origem YAML do fluxo de trabalho.

Este trabalho de exemplo demonstra como fazer referência a um segredo existente como uma variável de ambiente e enviá-lo como um parâmetro para um comando de exemplo.

jobs:
  example-job:
    runs-on: ubuntu-latest
    steps:
      - name: Retrieve secret
        env:
          super_secret: ${{ secrets.SUPERSECRET }}
        run: |
          example-command "$super_secret"

Para saber mais, confira Usar segredos em ações do GitHub.

Criar trabalhos dependentes

Por padrão, os trabalhos do seu fluxo de trabalho são executadas em paralelo e ao mesmo tempo. Se você tiver um trabalho que só precise ser executado após a conclusão de outro, use a palavra-chave needs para criar essa dependência. Se um dos trabalhos falhar, todos os trabalhos dependentes serão ignorados. No entanto, se você precisar que os trabalhos continuem, defina isso usando a instrução condicional if.

Neste exemplo, os trabalhos setup, build e test são executados em série, com build e test dependendo da conclusão bem-sucedida do trabalho anterior:

jobs:
  setup:
    runs-on: ubuntu-latest
    steps:
      - run: ./setup_server.sh
  build:
    needs: setup
    runs-on: ubuntu-latest
    steps:
      - run: ./build_server.sh
  test:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - run: ./test_server.sh

Para saber mais, confira Usando trabalhos em um fluxo de trabalho.

Usar uma matriz

Uma estratégia de matriz permite que você use variáveis em uma única definição de trabalho para criar automaticamente várias execuções de trabalho baseadas nas combinações das variáveis. Por exemplo, você pode usar uma estratégia de matriz para testar seu código em várias versões de um idioma ou em vários sistemas operacionais. A matriz é criada usando a palavra-chave strategy, que recebe as opções de construção como uma matriz. Por exemplo, essa matriz executará o trabalho várias vezes, usando diferentes versões de Node.js:

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node: [14, 16]
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}

Para saber mais, confira Executando variações de trabalhos em um fluxo de trabalho.

Memorizar dependências

Se os seus trabalhos reutilizam dependências regularmente, considere armazenar em cache esses arquivos para ajudar a melhorar o desempenho. Após a criação do armazenamento em cache, ele fica disponível para todos os fluxos de trabalho no mesmo repositório.

Este exemplo demonstra como armazenar o diretório ~/.npm em cache:

jobs:
  example-job:
    steps:
      - name: Cache node modules
        uses: actions/cache@v3
        env:
          cache-name: cache-node-modules
        with:
          path: ~/.npm
          key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-build-${{ env.cache-name }}-

Para saber mais, confira Memorizar dependências para acelerar os fluxos de trabalho.

Usar bancos de dados e contêineres de serviço

Se o trabalho exigir um banco de dados ou um serviço de cache, use a palavra-chave services para criar um contêiner efêmero para hospedar o serviço. O contêiner resultante ficará disponível para todas as etapas desse trabalho e será removido quando o trabalho for concluído. Este exemplo demonstra como um trabalho pode usar services para criar um contêiner postgres e usar node para se conectar ao serviço.

jobs:
  container-job:
    runs-on: ubuntu-latest
    container: node:20-bookworm-slim
    services:
      postgres:
        image: postgres
    steps:
      - name: Check out repository code
        uses: actions/checkout@v4
      - name: Install dependencies
        run: npm ci
      - name: Connect to PostgreSQL
        run: node client.js
        env:
          POSTGRES_HOST: postgres
          POSTGRES_PORT: 5432

Para saber mais, confira Usando serviços de contêineres.

Usar etiquetas para encaminhar fluxos de trabalho

Se você quiser ter certeza de que um determinado tipo de executor irá processar seu trabalho, você pode usar etiquetas para controlar os locais onde os trabalhos são executados. Você pode atribuir rótulos a um executor auto-hospedado, além do rótulo padrão de self-hosted. Em seguida, você pode consultar esses rótulos em seu fluxo de trabalho YAML, garantindo que o trabalho seja roteado de maneira previsível. Executores hospedados no GitHub têm rótulos predefinidos atribuídos.

Este exemplo mostra como um fluxo de trabalho pode usar etiquetas para especificar o executor obrigatório:

jobs:
  example-job:
    runs-on: [self-hosted, linux, x64, gpu]

Um fluxo de trabalho só será executado em um executor que tenha todos os rótulos na matriz runs-on. O trabalho irá preferencialmente para um executor auto-hospedado inativo com as etiquetas especificadas. Se não houver nenhum disponível e houver um corredor hospedado em GitHub com os rótulos especificados, o trabalho irá para um executor hospedado em GitHub.

Para saber mais sobre rótulos de executores auto-hospedados, confira Usar rótulos com os executores auto-hospedados.

Para saber mais sobre os rótulos de executores hospedados no GitHub, confira Usar executores hospedados no GitHub.

Reutilizar fluxos de trabalho

Você pode chamar um fluxo de trabalho de dentro de outro fluxo de trabalho. Isso permite a reutilização de fluxos de trabalho, evitando duplicação e tornando seus fluxos de trabalho mais fáceis de manter. Para obter mais informações, confira "Reutilizar fluxos de trabalho".

Proteção de segurança para fluxos de trabalho

O GitHub oferece recursos de segurança que você pode usar para aumentar a segurança de seus fluxos de trabalho. Você pode usar os recursos internos do GitHub para garantir que receba notificações sobre vulnerabilidades nas ações que consome ou para automatizar o processo de manter as ações em seus fluxos de trabalho atualizadas. Para obter mais informações, confira "Usar os recursos de segurança do GitHub para proteger seu uso do GitHub Actions".

Usar ambientes

Você pode configurar ambientes com regras e segredos de proteção para controlar a execução de trabalhos em um fluxo de trabalho. Cada trabalho em um fluxo de trabalho pode fazer referência a um único ambiente. Todas as regras de proteção configuradas para o ambiente têm de ser aprovadas antes que um trabalho de referência ao ambiente seja enviado a um executor. Para saber mais, confira Gerenciar ambientes para implantação.