Observação: Executores hospedados em GitHub não são atualmente compatíveis com GitHub Enterprise Server. Você pode ver mais informações sobre suporte futuro planejado no Itinerário público do GitHub.
Introdução
Neste guia, você aprenderá os componentes básicos necessários para criar e usar uma ação do contêiner Docker empacotado. Para manter o foco deste guia nos componentes necessários para empacotar a ação, a funcionalidade do código da ação é mínima. A ação imprime "Olá, mundo" nos registros ou "Olá, [who-to-greet]", se você fornecer um nome personalizado.
Ao terminar esse projeto, você entenderá como criar sua própria ação de contêiner Docker e poderá testá-la em um fluxo de trabalho.
Executores auto-hospedados devem usar um sistema operacional Linux e ter o Docker instalado para executar as ações do contêiner Docker. Para obter mais informações sobre os requisitos de executores auto-hospedados, consulte "Sobre runners auto-hospedados."
Aviso: Ao criar fluxos de trabalho e ações, você sempre deve considerar se seu código pode executar entradas não confiáveis de possíveis invasores. Certos contextos devem ser tratados como entradas não confiáveis, uma vez que um invasor pode inserir seu próprio conteúdo malicioso. Para obter mais informações, consulte "Entender o risco de injeções de scripts".
Pré-requisitos
Pode ser útil ter um entendimento básico das variáveis do ambiente GitHub Actions e do sistema de arquivo do contêiner Docker:
Antes de começar, você deverá criar um repositório de GitHub.
-
Crie um repositório novo no your GitHub Enterprise Server instance. Você pode escolher qualquer nome para o repositório ou usar "hello-world-docker-action", como nesse exemplo. Para obter mais informações, consulte "Criar um repositório novo".
-
Clone o repositório para seu computador. Para obter mais informações, consulte "Clonar um repositório".
-
No seu terminal, mude os diretórios para seu novo repositório.
Shell cd hello-world-docker-action
Criar um arquivo Docker
Em seu novo diretório hello-world-docker-action
, crie um arquivo Dockerfile
. Certifique-se de que seu nome de arquivo esteja em maiúsculas corretamente (use um D
maiúsculo mas não um f
maiúsculo) se você tiver problemas. Para obter mais informações, consulte "Suporte do arquivo Docker para GitHub Actions".
arquivo Docker
# Imagem de contêiner que executa seu código
FROM alpine:3.10
# Copia o arquivo de código do repositório de ação para o caminho do sistema de arquivos `/` do contêiner
COPY entrypoint.sh /entrypoint.sh
# Arquivo de código a ser executado quando o contêiner do docker é iniciado (`entrypoint.sh`)
ENTRYPOINT ["/entrypoint.sh"]
Criar um arquivo de metadados de ação
Crie um novo arquivo action.yml
no diretório hello-world-docker-action
que você criou acima. Para obter mais informações, consulte "Sintaxe dos metadados para GitHub Actions}."
action.yml
# action.yml
name: 'Hello World'
description: 'Greet someone and record the time'
inputs:
who-to-greet: # id of input
description: 'Who to greet'
required: true
default: 'World'
outputs:
time: # id of output
description: 'The time we greeted you'
runs:
using: 'docker'
image: 'Dockerfile'
args:
- ${{ inputs.who-to-greet }}
Esses metadados definem uma entrada who-to-greet
e um parâmetro de saída time
. Para passar entradas para o contêiner do Docker, você deverá declarar a entrada usando entradas
e passar a entrada na palavra-chave args
. Tudo o que você incluir em args
é passado para o contêiner, mas para uma melhor descoberta para os usuários da sua ação, recomendamos o uso de entradas.
O GitHub criará uma imagem a partir do seu Dockerfile
e executará os comandos em um novo contêiner usando essa imagem.
Gravar um código de ação
Você pode escolher qualquer imagem Docker de base e, portanto, qualquer linguagem para sua ação. O exemplo de script de shell a seguir usa a variável de entrada who-to-greet
para imprimir "Hello [who-to-greet]" no arquivo de log.
Na sequência, o script obtém a hora atual e a configura como uma variável de saída que pode ser usada pelas ações executadas posteriormente em um trabalho. Para que GitHub reconheça as variáveis de saída, você deverá usar um comando do fluxo de trabalho em uma sintaxe específica: echo "::set-output name=<output name>::<value>"
. Para obter mais informações, consulte "Comandos do fluxo de trabalho para GitHub Actions".
-
Crie um novo arquivo
entrypoint.sh
no diretóriohello-world-docker-action
. -
Adicione o código a seguir ao arquivo
entrypoint.sh
.entrypoint.sh
Shell #!/bin/sh -l echo "Hello $1" time=$(date) echo "::set-output name=time::$time"
Se
entrypoint.sh
for executado sem qualquer erro, o status da ação será definido comosuccess
. Você também pode definir explicitamente códigos de saída no código de ação para fornecer o status de uma ação. Para obter mais informações, consulte "Definindo os códigos de saída para as ações". -
Torne seu arquivo executável
entrypoint.sh
executando o seguinte comando no seu sistema.Shell $ chmod +x entrypoint.sh
Criar README
Para que as pessoas saibam como usar sua ação, você pode criar um arquivo README. Um arquivo README é útil quando você planeja compartilhar publicamente sua ação, mas também é uma ótima maneira de lembrá-lo ou sua equipe sobre como usar a ação.
No diretório hello-world-docker-action
, crie um arquivo README.md
que especifica as seguintes informações:
- Descrição detalhada do que a ação faz;
- Argumentos obrigatórios de entrada e saída;
- Argumentos opcionais de entrada e saída;
- Segredos usados pela ação;
- Variáveis de ambiente usadas pela ação;
- Um exemplo de uso da ação no fluxo de trabalho.
README.md
# Hello world docker action
Esta ação imprime "Hello World" ou "Hello" + o nome de uma pessoa a ser cumprimentada no log.
## Inputs
## `who-to-greet`
**Required** The name of the person to greet. Padrão `"World"`.
## Outputs
## `time`
The time we greeted you.
## Exemplo de uso
uses: actions/hello-world-docker-action@v1
with:
who-to-greet: 'Mona the Octocat'
Faça commit, tag e push da sua ação para GitHub Enterprise Server
A partir do seu terminal, faça commit dos arquivos action.yml
, entrypoint.sh
, Dockerfile
e README.md
.
Adicionar uma tag da versão para versões da sua ação é considerada uma prática recomendada. Para obter mais informações sobre versões da sua ação, consulte "Sobre ações".
git add action.yml entrypoint.sh Dockerfile README.md
git commit -m "Minha primeira ação está pronta"
git tag -a -m "Versão da minha primeira ação" v1
git push --follow-tags
Testar sua ação em um fluxo de trabalho
Agora você está pronto para testar sua ação em um fluxo de trabalho. Quando uma ação está em um repositório privado, a ação somente pode ser usada em fluxos de trabalho no mesmo repositório. Ações públicas podem ser usadas por fluxos de trabalho em qualquer repositório.
Note: GitHub Actions on your GitHub Enterprise Server instance may have limited access to actions on GitHub.com or GitHub Marketplace. For more information, see "Managing access to actions from GitHub.com" and contact your GitHub Enterprise site administrator.
Exemplo usando uma ação pública
O código do fluxo de trabalho a seguir usa a ação completa hello world no repositório público actions/hello-world-docker-action
. Copie o exemplo de código de fluxo de trabalho a seguir em um arquivo .github/workflows/main.yml
, mas substitua actions/hello-world-docker-action
pelo nome de seu repositório e ação. Você também pode substituir a entrada who-to-greet
pelo seu nome.
.github/workflows/main.yml
on: [push]
jobs:
hello_world_job:
runs-on: ubuntu-latest
name: A job to say hello
steps:
- name: Hello world action step
id: hello
uses: actions/hello-world-docker-action@v1
with:
who-to-greet: 'Mona the Octocat'
# Use the output from the `hello` step
- name: Get the output time
run: echo "The time was ${{ steps.hello.outputs.time }}"
Exemplo usando uma ação privada
Copie o seguinte exemplo de código de fluxo de trabalho em um arquivo .github/workflows/main.yml
no repositório da ação. Você também pode substituir a entrada who-to-greet
pelo seu nome.
.github/workflows/main.yml
on: [push]
jobs:
hello_world_job:
runs-on: ubuntu-latest
name: A job to say hello
steps:
# To use this repository's private action,
# you must check out the repository
- name: Checkout
uses: actions/checkout@v2
- name: Hello world action step
uses: ./ # Uses an action in the root directory
id: hello
with:
who-to-greet: 'Mona the Octocat'
# Use the output from the `hello` step
- name: Get the output time
run: echo "The time was ${{ steps.hello.outputs.time }}"
No seu repositório, clique na aba Ações e selecione a última execução do fluxo de trabalho. Em Trabalhos ou no gráfico de visualização, clique em A job to say hello. Você deverá ver "Hello Mona the Octocat" ou o nome que você usou como entrada em who-to-greet
e o horário impresso no log.