Usando blocos de construção pré-gravados no seu fluxo de trabalho

Visão geral

Você pode usar blocos de construção pré-gravados, chamados de ações, no seu fluxo de trabalho. Uma ação é um conjunto predefinido e reutilizável de trabalhos ou código que desempenham tarefas específicas dentro de um fluxo de trabalho.

As ações podem ser:

• Reutilizáveis: as ações podem ser usadas em diferentes fluxos de trabalho e repositórios, permitindo que você evite regravar o mesmo código.
• Pré-gravadas: muitas ações estão disponíveis no GitHub Marketplace, abrangendo uma ampla variedade de tarefas como fazer check-out de código, configurar ambientes, executar testes e implantar aplicativos.
• Configuráveis: você pode configurar as ações com entradas, saídas e variáveis de ambiente para adaptá-las às suas necessidades específicas.
• Orientadas à comunidade: você pode criar as próprias ações e compartilhá-las com outras pessoas ou usar ações desenvolvidas pela comunidade.

As ações que você usa no seu fluxo de trabalho podem ser definidas em:

• O mesmo repositório do arquivo do fluxo de trabalho
• Qualquer repositório público
• Em uma imagem de contêiner Docker publicada no Docker Hub.

O GitHub Marketplace é um local central para você encontrar ações criadas pela comunidade do GitHub. A página do GitHub Marketplace permite filtrar ações por categoria.

Navegação nas ações do Marketplace no editor de fluxo de trabalho

Você pode pesquisar ações diretamente no seu editor do seu fluxo de trabalho do repositório. Na barra lateral, você pode pesquisar uma ação específica, visualizar ações em destaque e pesquisar categorias em destaque. Você também pode visualizar o número de estrelas que uma ação recebeu da comunidade GitHub.

1. No seu repositório, pesquise o arquivo do fluxo de trabalho que você deseja editar.
2. No canto superior direito da exibição de arquivo, para abrir o editor de fluxo de trabalho, clique em .
   
3. No lado direito do editor, use a barra lateral GitHub Marketplace para procurar ações. As ações com o selo de indicam que o GitHub verificou o criador da ação como uma organização parceira.
   

Adicionar uma ação ao seu fluxo de trabalho

Você pode adicionar uma ação ao seu fluxo de trabalho fazendo referência à ação no arquivo do seu fluxo de trabalho.

Você pode visualizar as ações referenciadas em seus fluxos de trabalho de GitHub Actions como dependências no gráfico de dependências do repositório que contém seus fluxos de trabalho. Para obter mais informações, confira “Sobre o grafo de dependência”.

Adicionando uma ação de GitHub Marketplace

Uma página de lista de ações incluem a versão da ação e a sintaxe do fluxo de trabalho necessárias para usar a ação. Para manter seu fluxo de trabalho estável mesmo quando atualizações são feitas em uma ação, você pode fazer referência à versão da ação a ser usada especificando o Git ou da tag do Docker no arquivo de fluxo de trabalho.

1. Navegue para a ação que você deseja usar no seu fluxo de trabalho.
2. Clique para exibir a listagem completa do marketplace para a ação.
3. Em "Instalação", clique em para copiar a sintaxe do fluxo de trabalho.
   
4. Cole a sintaxe como uma nova etapa no seu fluxo de trabalho. Para saber mais, confira Sintaxe de fluxo de trabalho para o GitHub Actions.
5. Se a ação exigir que você forneça entradas, defina-as no seu fluxo de trabalho. Para obter informações sobre as entradas que uma ação pode exigir, confira Usando blocos de construção pré-gravados no seu fluxo de trabalho.

Você também pode habilitar o Dependabot version updates para as ações que você adicionar ao seu fluxo de trabalho. Para obter mais informações, confira "Manter as suas ações atualizadas com o Dependabot".

Adicionando uma ação do mesmo repositório

Se uma ação for definida no mesmo repositório em que o arquivo de fluxo de trabalho usa a ação, você poderá referenciar a ação com a sintaxe {owner}/{repo}@{ref} ou ./path/to/dir no arquivo de fluxo de trabalho.

Exemplo de estrutura de arquivo de repositório:

|-- hello-world (repository)
|   |__ .github
|       └── workflows
|           └── my-first-workflow.yml
|       └── actions
|           |__ hello-world-action
|               └── action.yml

O caminho é relativo (./) ao diretório de trabalho padrão (github.workspace, $GITHUB_WORKSPACE). Se a ação fizer check-out do repositório para um local diferente do fluxo de trabalho, o caminho relativo usado para ações locais deverá ser atualizado.

Exemplo de arquivo de fluxo de trabalho:

jobs:
  my_first_job:
    runs-on: ubuntu-latest
    steps:
      # This step checks out a copy of your repository.
      - name: My first step - check out repository
        uses: actions/checkout@v4
      # This step references the directory that contains the action.
      - name: Use local hello-world-action
        uses: ./.github/actions/hello-world-action

O arquivo action.yml é usado para fornecer metadados para a ação. Saiba mais sobre o conteúdo deste arquivo em Sintaxe de metadados para o GitHub Actions.

Adicionando uma ação de um repositório diferente

Se uma ação for definida em um repositório diferente do arquivo de fluxo de trabalho, você poderá referenciar a ação com a sintaxe {owner}/{repo}@{ref} no arquivo de fluxo de trabalho.

A ação precisa ser armazenada em um repositório público.

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: actions/setup-node@v4

Fazer referência a um contêiner no Docker Hub

Se uma ação for definida em uma imagem de contêiner do Docker publicada no Docker Hub, você precisará referenciar a ação com a sintaxe docker://{image}:{tag} no arquivo de fluxo de trabalho. Para proteger seu código e os dados, é altamente recomendável verificar a integridade da imagem do contêiner Docker no Docker Hub antes de usá-la no fluxo de trabalho.

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: docker://alpine:3.8

Para ver alguns exemplos de ações do Docker, confira o fluxo de trabalho Docker-image.yml e o Criando uma ação de contêiner do Docker.

Proteção de segurança para usar ações em seus 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 o gerenciamento de versões para suas ações personalizadas

Os criadores de uma ação da comunidade têm a opção de usar tags, branches ou valores do SHA para gerenciar as versçoes da ação. Semelhante a qualquer dependência, você deve indicar a versão da ação que gostaria de usar com para o seu conforto para aceitar automaticamente as atualizações da ação.

Você irá designar a versão da ação no seu arquivo de fluxo de trabalho. Verifique a documentação da ação para informações sobre suas abordagens de gerenciamento de versões e para ver qual tag, branch ou valor de SHA usar.

Usar tags

As tags são úteis para permitir que você decida quando alternar entre versões maiores e menores, mas estas são mais efêmeras e podem ser movidas ou excluídas pelo mantenedor. Este exemplo demonstra como direcionar uma ação que foi marcada como v1.0.1:

steps:
  - uses: actions/javascript-action@v1.0.1

Usar SHAs

Se você precisar de uma versão mais confiável, você deverá usar o valor de SHA associado à versão da ação. Os SHAs são imutáveis e, portanto, mais confiáveis que tags ou branches. No entanto, esta abordagem significa que você não receberá automaticamente atualizações de uma ação, incluindo correções de bugs e atualizações de segurança importantes. Você deve usar o valor SHA completo de um commit e não um valor abreviado. Ao selecionar um SHA, verifique se ele está no repositório da ação e não em uma bifurcação do repositório. Este exemplo tem como destino um SHA de uma ação:

steps:
  - uses: actions/javascript-action@a824008085750b8e136effc585c3cd6082bd575f

Usar branches

Especificar um branch de destino para a ação significa que ele sempre irá executar a versão atualmente nesse branch. Essa abordagem pode criar problemas se uma atualização do branch incluir mudanças significativas. Este exemplo é direcionado a um branch chamado @main:

steps:
  - uses: actions/javascript-action@main

Para saber mais, confira Sobre ações personalizadas.

Usar entradas e saídas com uma ação

Uma ação geralmente aceita ou exige entradas e gera saídas que você pode usar. Por exemplo, uma ação pode exigir que você especifique um caminho para um arquivo, o nome de uma etiqueta ou outros dados que usará como parte do processamento da ação.

Para ver as entradas e as saídas de uma ação, verifique o action.yml ou o action.yaml no diretório raiz do repositório.

Neste exemplo de action.yml, a palavra-chave inputs define uma entrada obrigatória chamada file-path e inclui um valor padrão que será usado se nenhum for especificado. A palavra-chave outputs define uma saída chamada results-file, que informa o local em que os resultados se encontram.

name: "Example"
description: "Receives file and generates output"
inputs:
  file-path: # id of input
    description: "Path to test script"
    required: true
    default: "test-file.js"
outputs:
  results-file: # id of output
    description: "Path to results file"

Próximas etapas

Para continuar aprendendo sobre o GitHub Actions, confira Entendendo o GitHub Actions.