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 do arquivo dos metadados deve 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 souber o que é YAML, consulte "Aprender a usar YAML em cinco minutos".

name

Necessário: O nome de sua ação. O GitHub exibe o nome na aba Ações para facilitar a identificação visual das ações em cada trabalho.

autor

Opcional: O nome do autor da ação.

descrição

Necessário: uma descrição curta da ação.

inputs

Opcional: parâmetros de entrada permitem que você especifique os dados que a ação espera usar no momento da execução. 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: numOctocats e octocatEyeColor. A entrada numOctocats não é necessária e assumirá o valor '1'. A entrada octocatEyeColor é necessária e não tem valor padrão. Arquivos de fluxo de trabalho que usam essa ação devem usar a palavra-chave with (com) para definir um valor de entrada para octocatEyeColor. Para obter mais informações sobre a sintaxe with (com), consulte "Sintaxe de fluxo de trabalho para o GitHub Actions".

inputs:
  numOctocats:
    description: 'Number of Octocats'
    required: false
    default: '1'
  octocatEyeColor:
    description: 'Eye color of the Octocats'
    required: true

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

Se a ação for escrita usando um composto, ela não receberá 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 do contêiner do Docker, você deverá passar 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, consulte "Criar uma ação de contêiner do Docker".

Por exemplo, se um fluxo de trabalho definiu as entradas numOctocats e octocatEyeColor, o código de ação poderia ler os valores das entradas usando as variáveis de ambiente do INPUT_NUMTOCATS e INPUT_OCTOCATEYECOLOR.

inputs.<input_id>

Necessário: um identificador string para associar à entrada. O valor de <input_id> é um mapa dos metadados da entrada. <input_id> deve ser um identificador único dentro do objeto inputs (entradas). <input_id> deve iniciar com uma letra ou _ e conter somente caracteres alfanuméricos, - ou _.

inputs.<input_id>.description

Necessário: descrição de string do parâmetro de entrada.

inputs.<input_id>.required

Necessário: um booleano para indicar se a ação exige o parâmetro de entrada. Defina para true quando o parâmetro for necessá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, esta string será registrada 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.

sapidas para o contêiner do Docker e ações do 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.

Outputs are Unicode strings, and can be a maximum of 1 MB. The total of all outputs in a workflow run can be a maximum of 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 a definição de saídas em uma ação, consulte "Comandos do fluxo de trabalho para GitHub Actions."

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

saídas:
  soma: número do ID da saída
    descrição: 'Soma das entradas'

outputs.<output_id>

Necessário: um identificador string para associar à saída. O valor de <output_id> é um mapa dos metadados de saída. <output_id> deve ser um identificador único dentro do objeto outputs (saídas). <output_id> deve iniciar com uma letra ou _ e conter somente caracteres alfanuméricos, - ou _.

outputs.<output_id>.description

Necessário: descrição de string do parâmetro de saída.

outputs para ações compostas

As saídas opcionais usam os mesmos parâmetros que outputs.<output_id> e outputs.<output_id>escription (consulte "saída para o contêiner do Docker e ações do JavaScript"), mas também inclui o token do valor.

Outputs are Unicode strings, and can be a maximum of 1 MB. The total of all outputs in a workflow run can be a maximum of 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 "::set-output name=random-id::$(echo $RANDOM)"
      shell: bash

outputs.<output_id>.value

Obrigatório O valor com o qual o parâmetro de saída será mapeado. Você pode defini-lo como uma string ou uma expressão com contexto. Por exemplo, você pode usar o contexto das etapas para definir o valor 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, consulte "Contextos".

runs

Obrigatório Especifica se esta é uma ação do 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 tempo de execução usado para executar o código.

Exemplo: Usando o Node.js v16

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

runs.using

Obrigatório O tempo de execução usado para executar o código especificado em principal.

• Use node12 para o Node.js v12.
• Use o node16 para o Node.js v16.

runs.main

Obrigatório O arquivo que contém o código da ação. O tempo de execução especificado em uso executa este arquivo.

runs.pre

Opcional Permite que você execute um script no início de um trabalho antes de a ação main: começar. Por exemplo, você pode usar pre: para executar um pré-requisito da configuração do script. O tempo de execução especificado com a sintaxe em uso irá executar este arquivo. A ação pre: sempre é executada por padrão, mas você pode substitui-la usando runs.pre-if.

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

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

runs.pre-if

Opcional Permite que você defina condições para a execução da ação pre:. A ação pre: será executada apenas se as condições em pre-if forem atendidas. Se não forem definidas, o padrão de pre-if será sempre(). Em pre-if, verifique as funções para avaliar com base no status do trabalho, não o status próprio da ação.

Observe que o contexto da etapa está indisponível, uma vez que nenhuma etapa foi executada ainda.

Neste exemplo, o cleanup.js é executado apenas nos executores baseados no Linux:

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

runs.post

Opcional Permite que você execute um script no final do trabalho, uma vez que a ação main: foi finalizada. Por exemplo, você pode usar post: para encerrar uns processos ou remover arquivos desnecessários. O tempo de execução especificado com a sintaxe em uso irá executar este 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: é executada sempre por padrão, mas você pode substituí-la usando post-if.

runs.post-if

Opcional Permite que você defina 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 não forem definidas, o padrão de post-if será sempre(). Em post-if, verifique as funções para avaliar com base no status do trabalho, não o status próprio da ação.

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

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

runs para ações compostas

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

runs.using

Obrigatório Você deve definir este valor como'composto'.

runs.steps

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

runs.steps[*].run

Optional O comando que você deseja executar. Isso pode ser inline ou um script no seu 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, consulte "github context".

runs.steps[*].shell

Opcional O shell onde você deseja executar o comando. Você pode usar qualquer um dos shells listados aqui. Obrigatório se run estiver configurado.

runs.steps[*].if

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

Quando você usa expressões em uma condicional if você pode omitir a sintaxe da expressão (${{ }}) porque GitHub calcula automaticamente a condição if como expressão. Para obter mais informações, consulte "Expressões".

Exemplo: Usando contextos

Essa etapa somente é executada quando o tipo de evento é uma pull_request e a ação do evento é unassigned (não atribuída).

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

A função my backup step somente é executada quando houver falha uma ação composta da etapa anterior do trabalho. Para obter mais informações, consulte "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 único para a etapa. Você pode usar id para fazer referência à etapa em contextos. Para obter mais informações, consulte "Contextos".

runs.steps[*].env

Opcional Define um mapa de variáveis de ambiente apenas para essa etapa. Se você deseja modificar a variável de ambiente armazenada no fluxo de trabalho, use eco "{name}={value}" >> $GITHUB_ENV em uma etapa composta.

runs.steps[*].working-directory

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

runs.steps[*].uses

Opcional Seleciona uma ação a ser executada como parte de uma etapa do seu trabalho. A ação é uma unidade reutilizável de código. Você pode usar uma ação definida no mesmo repositório que o fluxo de trabalho, um repositório público ou em uma imagem publicada de contêiner 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 requerem entradas que devem ser definidas com a palavra-chave com. 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 mapa dos parâmetros de entrada definidos pela ação. Cada parâmetro de entrada é um par chave/valor. Parâmetros de entrada são definidos como variáveis de ambiente. A variável é precedida por INPUT_ e convertida em letras maiúsculas.

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

runs.steps[*].continue-on-error

Optional Prevents the action from failing when a step fails. Set to true to allow the action to pass when this step fails.

runs par ações do contêiner do Docker

Obrigatório Configura a imagem usada para a ação do 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ê deve definir este valor como 'docker'.

runs.pre-entrypoint

Opcional Permite que você execute um script antes de a ação do entrypoint começar. Por exemplo, você pode usar o pre-entrypoint: para executar um pré-requisito do script da configuração. GitHub Actions usa a execução do docker para lançar esta ação e executa o script dentro de um novo contêiner que usa a mesma imagem-base. Isso significa que o momento de execução é diferente do contêiner principal do entrypoint e qualquer status de que você precisar devem ser acessado na área de trabalho, em HOME, ou como uma variável STATE_. A ação pre-entrypoint: sempre é executada por padrão, mas você pode substitui-la usando runs.pre-if.

O tempo de execução especificado com a sintaxe em uso irá executar este arquivo.

Neste exemplo, a ação pre-entrypoint: executa um script denominado 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 contêiner para executar a ação. O valor pode ser o nome da imagem de base do Docker, um arquivo Docker local no seu repositório u uma imagem pública no Docker Hub ou outro registro. Para fazer referência a um arquivo Docker local no seu repositório, o arquivo precisa ser denominado arquivo Docker e você precisa usar um caminho relativo ao seu arquivo de metadados de ação. O aplicativo do docker executará este arquivo.

runs.env

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

runs.entrypoint

Opcional Substitui o ENTRYPOINT do Docker no arquivo Docker ou o define, caso nenhum já tenha sido especificado. Use o entrypoint quando o arquivo Docker não especificar um ENTRYPOINT ou você desejar substituir a instrução doENTRYPOINT. Se você omitir o entrypoint, serão executados os comandos que você especificar na instrução do ENTRYPOINT do Docker. A instrução do ENTRYPOINT do Docker tem forma de shell e forma de exec. A documentação do ENTRYPOINT do docker recomenda o uso da forma exec da instrução do ENTRYPOINT.

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

post-entrypoint

OpcionalPermite que você execute um script de cleanup, uma vez finalizada a açãoruns.entrypoint. GitHub Actions usa a execução do docker para lançar esta ação. Porque GitHub Actions executa o script dentro de um novo contêiner usando a mesma imagem-base, o estado do momento da execução é diferente do contêiner principal do entrypoint. Você pode acessar qualquer estado que precisar na área de trabalho, em HOME ou como variável STATE_. A ação post-entrypoint: sempre é executada por padrão, mas você pode substitui-la usando runs.post-if.

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

runs.args

Opcional Um array de strings que define as entradas para um contêiner Docker. As entradas podem incluir strings com codificação rígida. O GitHub entrega os args ao ENTRYPOINT do contêiner quando o contêiner inicia.

args são usados em substituição à 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 das ações e omita-os da instrução CMD.
2. Use padrões que permitam o uso da ação sem especificação de args.
3. Se a ação expõe uma bandeira --help ou algo parecido, use isso para fazer sua ação se auto-documentar.

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 seu atributo entrypoint é definido como "sh -c", os args serão executados em um terminal de comando. Como alternativa, se o seu arquivo Docker usar um Entrypoint para executar o mesmo comando ("sh-c"), os Args serão executado em um shell de comando.

Para obter mais informações sobre o uso da instrução CMD com GitHub Actions, consulte "Suporte do arquivo Docker para GitHub Actions".

Exemplo: Definir argumentos para o contêiner do Docker

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

branding

Você pode usar uma cor e o ícone da Pena para criar um selo para personalizar e distinguir a sua ação. Os selos são exibidos ao lado do nome da sua ação em GitHub Marketplace.

Exemplo: Configurar a marca para uma ação

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

branding.color

Cor de fundo do selo. Pode ser: branco, amarelo, azul, verde, laranja, vermelho, roxo ou cinza-escuro.

branding.icon

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

coffee	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:

atividade	frequência de execução	alerta-círculo	alerta-octágono
alerta-triângulo	alinhar-centro	alinhar-justificar	alinhar-esquerda
alinhar-direita	âncora	abertura	arquivar
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	flecha-acima
arroba	prêmio	barra-quadro-2	barra-quadro
bateria-carregando	bateria	sino-desativado	sino
bluetooth	negrito	livro-aberto	livro
favorito	caixa	pasta	calendário
câmera-desligada	câmera	molde	marcar-círculo
marcar-quadrado	marcar	chevron-abaixo	chevron-esquerda
chevron-direita	chevron-acima	chevrons-abaixo	chevrons-esquerda
chevrons-direita	chevrons-acima	círculo	clipboard
relógio	nuvem-chuvisco	nuvem-relâmpago	nuvem-desativada
nuvem-chuva	nuvem-neve	nuvem	código
comando	bússula	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
delete	disco	dólar-sinal	download-nuvem
download	gota	editar-2	editar-3
edit	link-externo	olho-fechado	olho
facebook	fast-forward	pena	arquivo-menos
arquivo-mais	arquivo-texto	arquivo	filme
filtro	sinalizador	pasta-menos	pasta-mais
pasta	presente	git-branch	git-commit
git-merge	git-pull-request	globo	grade
disco-rígido	hash	fones-de-ouvido	coração
ajuda-círculo	casa	image	caixa de entrada
info	itálico	camadas	layout
boia salva-vidas	link-2	link	lista
carregador	bloquear	log-in	log-out
correio	fixar-mapa	map	maximizar-2
maximizar	menu	mensagem-círculo	mensagem-quadrado
microfone-desligado	microfone	minimizar-2	minimizar
menos-círculo	menos-quadrado	menos	monitor
lua	mais-horizontal	mais-vertical	mover
música	navegação-2	navegação	octágono
pacote	clips de papel	pausa-círculo	pausa
porcentagem	chamada-telefônica	telefone-transferência	telefone-entrada
telefone-perdido	telefone-desligado	telefone-fora	telefone
gráfico-pizza	reproduzir-círculo	reproduzir	mais-círculo
mais-quadrado	mais	bolso	energia
impressora	rádio	atualizar-ccw	atualizar-cw
repetir	retroceder	girar-ccw	girar-cw
rss	salvar	tesoura	pesquisar
enviar	servidor	settings	compartilhar-2
compartilhar	escudo-desabilitado	escudo	sacola-de-compras
carrinho-de-compras	aleatório	barra lateral	pular-atrás
pular-frente	barra	cursor	smartphone
alto-falante	quadrado	estrela	parar-círculo
sol	nascer-do-sol	pôr-do-sol	tablet
tag	target	terminal	termômetro
polegar-para-baixo	polegar-para-cima	alternar-esquerda	alternar-direita
lixeira-2	lixeira	tendência-baixa	tendência-alta
triângulo	caminhão	tv	tipo
guarda-chuva	sublinhar	desbloquear	carregar-nuvem
fazer upload	usuário-marcar	usuário-menos	usuário-mais
usuário-x	usuário	users	vídeo-desligado
vídeo	correio de voz	volume-1	volume-2
volume-x	volume	inspecionar	wifi-desligado
wifi	vento	x-círculo	x-quadrado
x	zapear-desligado	zapear	aproximar
afastar