Sintaxe de metadados para o GitHub Actions

Sobre sintaxe YAML para o GitHub Actions

Todas as ações exigem um arquivo de metadados. O nome de arquivo de metadados precisa ser action.yml ou action.yaml. Os dados no arquivo de metadados definem as entradas, saídas e executam a configuração para sua ação.

Arquivos de metadados de ação usam a sintaxe YAML. Se você não estiver familiarizado com o YAML, leia "Aprenda a usar o YAML em cinco minutos".

name

Obrigatório O nome da ação. O GitHub exibe o name na guia Actions para facilitar a identificação visual das ações em cada trabalho.

author

Opcional O nome do autor da ação.

description

Obrigatório Uma breve descrição da ação.

inputs

Opcional Os parâmetros de entrada permitem que você especifique os dados que a ação espera usar durante o runtime. O GitHub armazena parâmetros como variáveis de ambiente. Identificações de entrada com letras maiúsculas são alteradas para letras minúsculas no momento da execução. Recomenda-se usar identificações de entrada com letras minúsculas.

Exemplo: Especificando entradas

Este exemplo configura duas entradas: num-octocats e octocat-eye-color. A entrada num-octocats não é necessária e usará como padrão um valor de '1'; octocat-eye-color é necessária e não tem valor padrão. Os arquivos de fluxo de trabalho que usam essa ação precisam usar a palavra-chave with para definir um valor de entrada para octocat-eye-color. Para obter mais informações sobre a sintaxe with, confira "Sintaxe de fluxo de trabalho do GitHub Actions".

inputs:
  num-octocats:
    description: 'Number of Octocats'
    required: false
    default: '1'
  octocat-eye-color:
    description: 'Eye color of the Octocats'
    required: true

Quando você especifica uma entrada em um arquivo de fluxo de trabalho ou usa um valor de entrada padrão, o GitHub cria uma variável de ambiente para a entrada com o nome INPUT_<VARIABLE_NAME>. A variável de ambiente criada converte os nomes de entrada em letras maiúsculas e substitui os espaços por caracteres _.

Se a ação for gravada por meio de uma composição, ela não obterá INPUT_<VARIABLE_NAME> automaticamente. Se não ocorrer a conversão, você poderá alterar estas entradas manualmente.

Para acessar a variável de ambiente em uma ação de contêiner do Docker, você precisará transmitir a entrada usando a palavra-chave args no arquivo de metadados da ação. Para obter mais informações sobre o arquivo de metadados de ação para ações de contêiner do Docker, confira "Como criar uma ação de contêiner do Docker".

Por exemplo, se um fluxo de trabalho definir as entradas num-octocats e octocat-eye-color, o código da ação poderá ler os valores das entradas usando as variáveis de ambiente INPUT_NUM-OCTOCATS e INPUT_OCTOCAT-EYE-COLOR.

inputs.<input_id>

Obrigatório Um identificador string a ser associado à entrada. O valor de <input_id> é um mapa dos metadados da entrada. A <input_id> precisa ser um identificador exclusivo dentro do objeto inputs. A <input_id> precisa começar com uma letra ou _ e conter apenas caracteres alfanuméricos, - ou _.

inputs.<input_id>.description

Obrigatório Uma descrição string dos parâmetros de entrada.

inputs.<input_id>.required

Opcional Um boolean para indicar se a ação exige o parâmetro de entrada. Defina-o como true quando o parâmetro for obrigatório.

inputs.<input_id>.default

Opcional uma string que representa o valor padrão. O valor padrão é usado quando um parâmetro de entrada não é especificado em um arquivo de fluxo de trabalho.

inputs.<input_id>.deprecationMessage

Opcional se o parâmetro de entrada for usado, essa string será registrada em log como uma mensagem de aviso. Você pode usar este aviso para notificar os usuários de que o valor de entrada está obsoleto e mencionar outras alternativas.

outputs para ações de contêiner do Docker e de JavaScript

Opcional Os parâmetros de saída permitem que você declare os dados definidos por uma ação. As ações executadas posteriormente em um fluxo de trabalho podem usar os dados de saída definidos em ações executadas anteriormente. Por exemplo, se uma ação executou a adição de duas entradas (x + y = z), a ação poderia usar o resultado da soma (z) como entrada em outras ações.

As saídas são cadeias de caracteres Unicode e podem ter no máximo 1 MB. O total de todas as saídas em uma execução de fluxo de trabalho pode ter no máximo 50 MB.

Se você não declarar uma saída no seu arquivo de metadados de ação, você ainda poderá definir as saídas e usá-las no seu fluxo de trabalho. Para obter mais informações sobre como definir as saídas em uma ação, confira "Comandos do fluxo de trabalho do GitHub Actions".

Exemplo: Declarando saídas para o contêiner do Docker e ações do JavaScript

outputs:
  sum: # id of the output
    description: 'The sum of the inputs'

outputs.<output_id>

Obrigatório Um identificador string a ser associado à saída. O valor de <output_id> é um mapa dos metadados da saída. A <output_id> precisa ser um identificador exclusivo dentro do objeto outputs. A <output_id> precisa começar com uma letra ou _ e conter apenas caracteres alfanuméricos, - ou _.

outputs.<output_id>.description

Obrigatório Uma descrição string do parâmetro de saída.

outputs para ações compostas

Opcional outputs usa os mesmos parâmetros que outputs.<output_id> e outputs.<output_id>.description (confira "outputs para ações de contêiner do Docker e de JavaScript"), mas também inclui o token value.

As saídas são cadeias de caracteres Unicode e podem ter no máximo 1 MB. O total de todas as saídas em uma execução de fluxo de trabalho pode ter no máximo 50 MB.

Exemplo: Declarando saídas para ações compostas

outputs:
  random-number:
    description: "Random number"
    value: ${{ steps.random-number-generator.outputs.random-id }}
runs:
  using: "composite"
  steps:
    - id: random-number-generator
      run: echo "random-id=$(echo $RANDOM)" >> $GITHUB_OUTPUT
      shell: bash

outputs.<output_id>.value

Obrigatório O valor para o qual o parâmetro de saída será mapeado. Defina isso como uma string ou uma expressão com um contexto. Por exemplo, você pode usar o contexto steps para definir o value de uma saída como o valor de saída de uma etapa.

Para obter mais informações sobre como usar a sintaxe de contexto, confira "Contextos".

runs

Obrigatório Especifica se esta é uma ação de JavaScript, uma ação composta ou uma ação de contêiner do Docker e como a ação é executada.

runs para ações de JavaScript

Obrigatório Configura o caminho para o código da ação e o runtime usado para executar o código.

Exemplo: usando o Node.js v16

runs:
  using: 'node16'
  main: 'main.js'

runs.using

Obrigatório O runtime usado para executar o código especificado em main.

• Usar o node12 para Node.js v12.
• Usar a node16 para o Node.js v16.

runs.main

Obrigatório O arquivo que contém o código de ação. O runtime especificado em using executa este arquivo.

runs.pre

Opcional Permite que você execute um script no início de um trabalho, antes do início da ação main:. Por exemplo, você pode usar pre: para executar um script de configuração de pré-requisito. O runtime especificado com a sintaxe using executará esse arquivo. A ação pre: sempre é executada por padrão, mas você pode substituir isso usando runs.pre-if.

Neste exemplo, a ação pre: executa um script chamado setup.js:

runs:
  using: 'node16'
  pre: 'setup.js'
  main: 'index.js'
  post: 'cleanup.js'

runs.pre-if

Opcional Permite definir condições para a execução da ação pre:. A ação pre: só será executada se as condições em pre-if forem atendidas. Se isso não estiver definido, pre-if usará always() como padrão. Em pre-if, as funções de verificação de status são avaliadas em relação ao status do trabalho, não ao status próprio da ação.

Observe que o contexto step não está disponível, pois nenhuma etapa foi executada ainda.

Neste exemplo, cleanup.js só é executado em executores baseados em Linux:

  pre: 'cleanup.js'
  pre-if: runner.os == 'linux'

runs.post

Opcional Permite que você execute um script no final de um trabalho, depois que a ação main: for concluída. Por exemplo, você pode usar post: para encerrar alguns processos ou remover arquivos desnecessários. O runtime especificado com a sintaxe using executará esse arquivo.

Neste exemplo, a ação post: executa um script chamado cleanup.js:

runs:
  using: 'node16'
  main: 'index.js'
  post: 'cleanup.js'

A ação post: sempre é executada por padrão, mas você pode substituir isso usando post-if.

runs.post-if

Opcional Permite definir condições para a execução da ação post:. A ação post: só será executada se as condições em post-if forem atendidas. Se isso não estiver definido, post-if usará always() como padrão. Em post-if, as funções de verificação de status são avaliadas em relação ao status do trabalho, não ao status próprio da ação.

Por exemplo, este cleanup.js só será executado em executores baseados em Linux:

  post: 'cleanup.js'
  post-if: runner.os == 'linux'

runs para ações compostas

Obrigatório Configura o caminho para a ação composta.

runs.using

Obrigatório Você precisa definir esse valor como 'composite'.

runs.steps

Obrigatório As etapas que você pretende executar nesta ação. Elas podem ser etapas run ou etapas uses.

runs.steps[*].run

Opcional O comando que você deseja executar. Essa opção pode ser embutida ou um script no repositório de ação:

runs:
  using: "composite"
  steps:
    - run: ${{ github.action_path }}/test/script.sh
      shell: bash

Como alternativa, você pode usar $GITHUB_ACTION_PATH:

runs:
  using: "composite"
  steps:
    - run: $GITHUB_ACTION_PATH/script.sh
      shell: bash

Para obter mais informações, confira "github context".

runs.steps[*].shell

Opcional O shell no qual você deseja executar o comando. Use um dos shells listados aqui. Obrigatório se run for definido.

runs.steps[*].if

Opcional Use o condicional if para impedir que uma etapa seja executada, a não ser que uma condição seja atendida. Você pode usar qualquer contexto e expressão compatível para criar uma condicional.

Ao usar expressões em um condicional if, você pode omitir a sintaxe de expressão (${{ }}), porque o GitHub avalia automaticamente o condicional if como uma expressão. Para obter mais informações, confira "Expressões".

Exemplo: Usando contextos

Essa etapa só é executada quando o tipo de evento é uma pull_request e a ação do evento é unassigned.

steps:
 - run: echo This event is a pull request that had an assignee removed.
   if: ${{ github.event_name == 'pull_request' && github.event.action == 'unassigned' }}

Exemplo: Usando funções de verificação de status

O my backup step só é executada quando a etapa anterior de uma ação composta falha. Para obter mais informações, confira "Expressões".

steps:
  - name: My first step
    uses: octo-org/action-name@main
  - name: My backup step
    if: ${{ failure() }}
    uses: actions/heroku@1.0.0

runs.steps[*].name

Opcional O nome da etapa composta.

runs.steps[*].id

Opcional Um identificador exclusivo da etapa. Use a id para referenciar a etapa em contextos. Para obter mais informações, confira "Contextos".

runs.steps[*].env

Opcional Define um map das variáveis de ambiente apenas para essa etapa. Caso deseje modificar a variável de ambiente armazenada no fluxo de trabalho, use echo "{name}={value}" >> $GITHUB_ENV em uma etapa composta.

runs.steps[*].working-directory

Opcional Especifica o diretório de trabalho em que o comando é executado.

runs.steps[*].uses

Opcional Seleciona uma ação para executá-la como parte de uma etapa no trabalho. A ação é uma unidade reutilizável de código. Você pode usar uma ação definida no mesmo repositório do fluxo de trabalho, um repositório público ou em uma imagem publicada de um contêiner do Docker.

É altamente recomendável incluir a versão da ação que você está usando ao especificar um número de tag Docker, SHA ou ref do Git. Se você não especificar uma versão, ela poderá interromper seus fluxos de trabalho ou causar um comportamento inesperado quando o proprietário da ação publicar uma atualização.

• Usar o commit SHA de uma versão de ação lançada é a maneira mais garantida de obter estabilidade e segurança.
• Usar a versão principal da ação permite receber correções importantes e patches de segurança sem perder a compatibilidade. Fazer isso também garante o funcionamento contínuo do fluxo de trabalho.
• Usar o branch-padrão de uma ação pode ser conveniente, mas se alguém lançar uma nova versão principal com uma mudança significativa, seu fluxo de trabalho poderá ter problemas.

Algumas ações exigem entradas que precisam ser definidas com a palavra-chave with. Revise o arquivo README da ação para determinar as entradas obrigatórias.

runs:
  using: "composite"
  steps:
    # Reference a specific commit
    - uses: actions/checkout@a81bbbf8298c0fa03ea29cdc473d45769f953675
    # Reference the major version of a release
    - uses: actions/checkout@v3
    # Reference a specific version
    - uses: actions/checkout@v3.2.0
    # Reference a branch
    - uses: actions/checkout@main
    # References a subdirectory in a public GitHub repository at a specific branch, ref, or SHA
    - uses: actions/aws/ec2@main
    # References a local action
    - uses: ./.github/actions/my-action
    # References a docker public registry action
    - uses: docker://gcr.io/cloud-builders/gradle
    # Reference a docker image published on docker hub
    - uses: docker://alpine:3.8

runs.steps[*].with

Opcional Um map dos parâmetros de entrada definidos pela ação. Cada parâmetro de entrada é um par chave/valor. Para obter mais informações, confira Exemplo: como especificar entradas.

runs:
  using: "composite"
  steps:
    - name: My first step
      uses: actions/hello_world@main
      with:
        first_name: Mona
        middle_name: The
        last_name: Octocat

runs para ações de contêiner do Docker

Obrigatório Configura a imagem usada para a ação de contêiner do Docker.

Exemplo: Usando um arquivo do Dockerfile no seu repositório

runs:
  using: 'docker'
  image: 'Dockerfile'

Exemplo: Usando o contêiner de registro público do Docker

runs:
  using: 'docker'
  image: 'docker://debian:stretch-slim'

runs.using

Obrigatório Você precisa definir esse valor como 'docker'.

runs.pre-entrypoint

Opcional Permite que você execute um script antes do início da ação entrypoint. Por exemplo, você pode usar pre-entrypoint: para executar um script de configuração de pré-requisito. O GitHub Actions usa docker run para iniciar esta ação e executa o script dentro de um novo contêiner que usa a mesma imagem base. Isso significa que o estado de runtime é diferente do contêiner entrypoint principal, e todos os status que você exigir precisarão ser acessados no workspace, HOME, ou como uma variável STATE_. A ação pre-entrypoint: sempre é executada por padrão, mas você pode substituir isso usando runs.pre-if.

O runtime especificado com a sintaxe using executará esse arquivo.

Neste exemplo, a ação pre-entrypoint: executa um script chamado setup.sh:

runs:
  using: 'docker'
  image: 'Dockerfile'
  args:
    - 'bzz'
  pre-entrypoint: 'setup.sh'
  entrypoint: 'main.sh'

runs.image

Obrigatório A imagem do Docker a ser usada como o contêiner para executar a ação. O valor pode ser o nome da imagem base do Docker, um Dockerfile local no seu repositório ou uma imagem pública do Docker Hub ou de outro registro. Para referenciar um Dockerfile local no seu repositório, o arquivo precisa ser nomeado Dockerfile e você precisa usar um caminho relativo ao arquivo de metadados da ação. O aplicativo docker executará esse arquivo.

runs.env

Opcional Especifica um mapa de chave/valor das variáveis do ambiente a serem definidas no ambiente do contêiner.

runs.entrypoint

Opcional Substitui o ENTRYPOINT do Docker no Dockerfile ou define-o se ele ainda não foi especificado. Use entrypoint quando Dockerfile não especificar um ENTRYPOINT ou você desejar substituir a instrução ENTRYPOINT. Se você omitir entrypoint, os comandos especificados na instrução ENTRYPOINT do Docker serão executados. A instrução ENTRYPOINT do Docker tem um formulário de shell e um formulário de execução. A documentação de ENTRYPOINT do Docker recomenda o uso do formulário de execução da instrução ENTRYPOINT.

Para obter mais informações sobre como o entrypoint é executado, confira "Suporte do Dockerfile para o GitHub Actions".

runs.post-entrypoint

Opcional Permite executar um script de limpeza depois que a ação runs.entrypoint for concluída. O GitHub Actions usa docker run para iniciar esta ação. Como o GitHub Actions executa o script dentro de um novo contêiner usando a mesma imagem base, o estado do runtime é diferente do contêiner entrypoint principal. Você pode acessar qualquer estado necessário no workspace, em HOME ou como uma variável STATE_. A ação post-entrypoint: sempre é executada por padrão, mas você pode substituir isso usando runs.post-if.

runs:
  using: 'docker'
  image: 'Dockerfile'
  args:
    - 'bzz'
  entrypoint: 'main.sh'
  post-entrypoint: 'cleanup.sh'

runs.args

Opcional Uma matriz de cadeias de caracteres que define as entradas de um contêiner do Docker. As entradas podem incluir strings com codificação rígida. O GitHub transmite os args para o ENTRYPOINT do contêiner quando o contêiner é iniciado.

Os args são usados no lugar da instrução CMD em um Dockerfile. Se você usar CMD no Dockerfile, use as diretrizes ordenadas por preferência:

1. Documente os argumentos necessários no README da ação e omita-os da instrução CMD.
2. Use padrões que permitam o uso da ação sem a especificação de args.
3. Se a ação expuser um sinalizador --help ou algo semelhante, use-o para tornar a ação autodocumentada.

Se você precisar passar variáveis de ambiente para uma ação, certifique-se de que sua ação executa um shell de comando para realizar a substituição de variáveis. Por exemplo, se o atributo entrypoint estiver definido como "sh -c", args será executado em um shell de comando. Como alternativa, se o Dockerfile usar um ENTRYPOINT para executar o mesmo comando ("sh -c"), args será executado em um shell de comando.

Para obter mais informações sobre como usar a instrução CMD com o GitHub Actions, confira "Suporte do Dockerfile para o GitHub Actions".

Exemplo: Definir argumentos para o contêiner do Docker

runs:
  using: 'docker'
  image: 'Dockerfile'
  args:
    - ${{ inputs.greeting }}
    - 'foo'
    - 'bar'

branding

Opcional Você pode usar uma cor e um ícone de Pena para criar uma notificação para personalizar e distinguir sua ação. As notificações são mostradas ao lado do nome da ação no GitHub Marketplace.

Exemplo: Configurar a marca para uma ação

branding:
  icon: 'award'
  color: 'green'

branding.color

Cor de fundo do selo. Pode ser white, yellow, blue, green, orange, red, purple ou gray-dark.

branding.icon

O nome do ícone de Pena v4.28.0 a ser usado. Os ícones da marca são omitidos, assim como os itens seguintes:

café	colunas	divide-circle	divide-square
divide	frown	hexagon	chave
meh	mouse-pointer	smile	ferramenta
x-octagon

Aqui está uma lista taxativa de todos os ícones atualmente compatíveis:

activity	frequência de execução	alerta-círculo	alerta-octágono
alerta-triângulo	alinhar-centro	alinhar-justificar	alinhar-esquerda
alinhar-direita	âncora	abertura	arquivos
flecha-abaixo-círculo	flecha-abaixo-esquerda	flecha-abaixo-direita	flecha-abaixo
flecha-esquerda-círculo	flecha-esquerda	flecha-direita-círculo	flecha-direita
flecha-acima-círculo	flecha-acima-esquerda	flecha-acima-direita	arrow-up
arroba	prêmio	barra-quadro-2	barra-quadro
bateria-carregando	pilha	sino-desativado	sino
bluetooth	negrito	livro-aberto	agendar
indicador	box	pasta	calendário
câmera-desligada	câmera	Conversão	marcar-círculo
marcar-quadrado	marcar	chevron-abaixo	chevron-esquerda
chevron-direita	chevron-acima	chevrons-abaixo	chevrons-esquerda
chevrons-direita	chevrons-acima	circle	área de transferência
clock	nuvem-chuvisco	nuvem-relâmpago	nuvem-desativada
nuvem-chuva	nuvem-neve	nuvem	code
.	compass	copy	canto-abaixo-esquerda
canto-abaixo-direita	canto-esquerda-abaixo	canto-esquerda-acima	canto-direita-abaixo
canto-direita-acima	canto-acima-esquerda	canto-acima-direita	cpu
cartão-de-crédito	cortar	mira	Banco de Dados
excluir	disco	dólar-sinal	download-nuvem
download	gota	editar-2	editar-3
editar	link-externo	olho-fechado	olho
fast-forward	pena	arquivo-menos	arquivo-mais
arquivo-texto	file	filme	filtro
flag	pasta-menos	pasta-mais	folder
presente	git-branch	git-commit	git-merge
git-pull-request	globo	grade	disco-rígido
hash	fones-de-ouvido	coração	ajuda-círculo
inicial	image	caixa de entrada	informações
itálico	camadas	layout	boia salva-vidas
link-2	link	list	carregador
lock	log-in	log-out	mail
fixar-mapa	mapa	maximizar-2	maximizar
menu	mensagem-círculo	mensagem-quadrado	microfone-desligado
mic	minimizar-2	minimizar	menos-círculo
menos-quadrado	minus	monitor	lua
mais-horizontal	mais-vertical	move	music
navegação-2	navegação	octágono	pacote
clips de papel	pausa-círculo	pause	percent
chamada-telefônica	telefone-transferência	telefone-entrada	telefone-perdido
telefone-desligado	telefone-fora	phone	gráfico-pizza
reproduzir-círculo	jogar	mais-círculo	mais-quadrado
plus	bolso	potência	impressora
radio	atualizar-ccw	atualizar-cw	repeat
rewind	girar-ccw	girar-cw	rss
Salvar	tesoura	pequisa	Enviar
Servidor	configurações	compartilhar-2	compartilhar
escudo-desabilitado	escudo	sacola-de-compras	carrinho-de-compras
ordem aleatória	sidebar	pular-atrás	pular-frente
slash	controles deslizantes	smartphone	alto-falante
square	estrela	parar-círculo	sol
nascer-do-sol	pôr do sol	tablet	marcação
destino	terminal	termômetro	polegar-para-baixo
polegar-para-cima	alternar-esquerda	alternar-direita	lixeira-2
lixeira	tendência-baixa	tendência-alta	triangle
caminhão	tv	type	guarda-chuva
underline	desbloquear	carregar-nuvem	upload
usuário-marcar	usuário-menos	usuário-mais	usuário-x
usuário	users	vídeo-desligado	video
correio de voz	volume-1	volume-2	volume-x
volume	inspecionar	wifi-desligado	wifi
vento	x-círculo	x-quadrado	x
zapear-desligado	zap	aproximar	afastar