Skip to main content

Procurar e personalizar ações

Ações são os blocos de construção que alimentam seu fluxo de trabalho. Um fluxo de trabalho pode conter ações criadas pela comunidade, ou você pode criar suas próprias ações diretamente no repositório do seu aplicativo. Este guia mostrará como descobrir, usar e personalizar ações.

Visão geral

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 . Captura de tela de um arquivo de fluxo de trabalho mostrando a seção de cabeçalho. O ícone de lápis, para categorias de edição, é realçado com um contorno laranja escuro.
  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. Captura de tela de um arquivo de fluxo de trabalho no modo de edição. A barra lateral direita mostra as ações do Marketplace. Há uma marca de seleção em um ícone de selo, mostrando que o criador é verificado pelo GitHub, realçada em laranja.

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”.

Observação: para aprimorar a segurança, o GitHub Actions não dá suporte a redirecionamentos de ações ou fluxos de trabalho reutilizáveis. Isso significa que quando o proprietário, o nome do repositório de uma ação ou o nome da ação é alterado, todos os fluxos de trabalho que usarem essa ação com o nome anterior falharão.

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. Captura de tela da listagem do marketplace para uma ação. O ícone "Copiar para área de transferência" da ação está realçado com um contorno laranja escuro.
  4. Cole a sintaxe como uma nova etapa no seu fluxo de trabalho. Para obter mais informações, 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 "Procurar e personalizar ações".

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.

Example repository file structure:

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

The path is relative (./) to the default working directory (github.workspace, $GITHUB_WORKSPACE). If the action checks out the repository to a location different than the workflow, the relative path used for local actions must be updated.

Example workflow file:

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.

Observação: recomendamos que você use um valor SHA ao usar ações de terceiros. No entanto, é importante observar que o Dependabot apenas criará Dependabot alerts para GitHub Actions vulneráveis que usam controle de versão semântico. Para obter mais informações, confira "Fortalecimento de segurança para o GitHub Actions" e "Sobre alertas do Dependabot."

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 obter mais informações, 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 "Recursos essenciais do GitHub Actions".