Sobre sintaxe YAML para o GitHub Actions
Ações Docker e JavaScript requerem 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, as saídas e o ponto de entrada principal 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: nome de sua ação. O GitHub exibe o name
(nome) na aba Actions (Ações) para facilitar a identificação visual das ações em cada trabalho.
autor
Opcional: 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
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 para uma ação 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 altera os nomes de entrada para letras maiúsculas e substitui espaços por caracteres _
.
Por exemplo, se um fluxo de trabalho definiu as entradas numOctocats e octocatEyeColor, o código da ação lê os valores das entradas usando as variáveis de ambiente INPUT_NUMOCTOCATS
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 boolean
(booleano) para indicar se a ação requer 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.
outputs (saídas)
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.
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
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 em etapas de execução compostas
As saídas opcionais
usam os mesmos parâmetros que outputs.<output_id>
e outputs.<output_id>.description
(veja "saídas
para GitHub Actions"), mas também inclui o token do valor
.
Exemplo
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 e expressão, consulte "Sintaxe de contexto e expressão para GitHub Actions".
runs
para ações de JavaScript
Obrigatório Configura o caminho para o código da ação e o aplicativo usado para executar o código.
Exemplo usando Node.js
executa:
using: 'node12'
main: 'main.js'
runs.using
Obrigatório O aplicativo usado para executar o código especificado em principal
.
runs.main
Obrigatório O arquivo que contém o código da ação. O aplicativo especificado em usando
executa este arquivo.
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 aplicativo especificado com a sintaxe using
executará esse arquivo. A ação pre:
é sempre executada como padrão, mas você pode substituí-la usando pre-if
.
Neste exemplo, a ação pre:
executa um script denominado setup.js.
:
executa:
using: 'node12'
pre: 'setup.js'
main: 'index.js'
post: 'cleanup.js'
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()
. 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'
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 aplicativo especificado com a sintaxe using
executará esse arquivo.
Neste exemplo, a ação post:
executa um script chamado cleanup.js
:
executa:
using: 'node12'
main: 'index.js'
post: 'cleanup.js'
A ação post:
é executada sempre por padrão, mas você pode substituí-la usando post-if
.
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()
.
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 em etapas de execução compostas
Obrigatório Configura o caminho para a ação composta, e o aplicativo usado para executar o código.
runs.using
Obrigatório Para usar uma ação de etapas de execução compostas, defina como "composite"
.
runs.steps
Obrigatório As etapas de execução que você planeja executar nesta ação.
runs.steps[*].run
Obrigatório 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
Obrigatório O shell onde você quer executar o comando. Você pode usar qualquer um dos shells listados aqui.
runs.steps[*].name
Opcional O nome da etapa de execução 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 "Contexto e sintaxe de expressão para GitHub Actions".
runs.steps[*].env
Opcional Define um mapa
de variáveis de ambiente apenas para essa etapa. Se você quiser modificar a variável de ambiente armazenada no fluxo de trabalho, use echo "{name}={value}" >> $GITHUB_ENV
em uma etapa de execução composta.
runs.steps[*].working-directory
Opcional Especifica o diretório de trabalho onde o comando é executado.
runs
para ações do Docker
Obrigatório Configura a imagem usada para a ação Docker.
Exemplos de uso do arquivo Docker no repositório
runs:
using: 'docker'
image: 'Dockerfile'
Exemplo usando um contêiner de registro Docker público
runs:
using: 'docker'
image: 'docker://debian:stretch-slim'
runs.using
Obrigatório Você deve definir este valor como 'docker'
.
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 doentrypoint e quaisquer status que você precisar devem ser acessados 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 substituí-la usando pre-if
.
O aplicativo especificado com a sintaxe using
executará esse arquivo.
Neste exemplo, a ação pre-entrypoint:
executa um script denominado setup.sh
:
executa:
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
no seu repositório, use um caminho relativo ao seu arquivo de metadados da 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 substituí-la usando post-if
.
executa:
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:
- Documente os argumentos necessários no LEIAME das ações e omita-os da instrução
CMD
. - Use padrões que permitam o uso da ação sem especificação de
args
. - 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
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
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
Nome do ícone Feather (pena) para usar.
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 |
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 |