Observação: no momento, não há suporte para os executores hospedados no GitHub no GitHub Enterprise Server. Você pode ver mais informações sobre o suporte futuro planejado no GitHub public roadmap.
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 dos executores auto-hospedados, confira "Sobre executores auto-hospedados".
Aviso: ao criar fluxos de trabalho e ações, você sempre deve considerar se o 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, confira "Fortalecimento de segurança para o GitHub Actions".
Pré-requisitos
- Crie um repositório em GitHub e clone-o em sua estação de trabalho. Para obter mais informações, confira "Criar um repositório" e "Clonar um repositório."
- Se o repositório usar o Git LFS, você deverá incluir os objetos nos arquivos do repositório. Para obter mais informações, confira "Gerenciando objetos LFS do Git em arquivos do seu repositório".
- Pode ser útil ter um entendimento básico das variáveis do ambiente GitHub Actions e do sistema de arquivo do contêiner Docker. Para obter mais informações, confira "Armazenar informações em variáveis" e "Usar executores hospedados no GitHub."
Criar um arquivo Docker
No diretório hello-world-docker-action
, crie um arquivo Dockerfile
. Verifique se o seu nome de arquivo está em maiúsculas corretamente (use um D
maiúsculo, mas não um f
maiúsculo) se estiver tendo problemas. Para obter mais informações, confira "Suporte do arquivo Docker para GitHub Actions".
Dockerfile
# Container image that runs your code FROM alpine:3.10 # Copies your code file from your action repository to the filesystem path `/` of the container COPY entrypoint.sh /entrypoint.sh # Code file to execute when the docker container starts up (`entrypoint.sh`) ENTRYPOINT ["/entrypoint.sh"]
# Container image that runs your code
FROM alpine:3.10
# Copies your code file from your action repository to the filesystem path `/` of the container
COPY entrypoint.sh /entrypoint.sh
# Code file to execute when the docker container starts up (`entrypoint.sh`)
ENTRYPOINT ["/entrypoint.sh"]
Criar um arquivo de metadados de ação
Crie um arquivo action.yml
no diretório hello-world-docker-action
que você criou acima. Para obter mais informações, confira "Sintaxe de metadados para o 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 }}
# 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 transmitir entradas para o contêiner do Docker, você deve declarar a entrada usando inputs
e transmitir a entrada na palavra-chave args
. Tudo o que você inclui em args
é transmitido para o contêiner, mas para ter uma melhor capacidade de descoberta para os usuários da sua ação, recomendamos o uso de entradas.
O GitHub criará uma imagem com base no Dockerfile
e executará 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 "Olá, [quem deve ser saudado]" 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 o GitHub reconheça variáveis de saída, você deve gravá-las no arquivo de ambiente $GITHUB_OUTPUT
: echo "<output name>=<value>" >> $GITHUB_OUTPUT
. Para obter mais informações, confira "Comandos de fluxo de trabalho para o GitHub Actions".
-
Crie um 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 "time=$time" >> $GITHUB_OUTPUT
#!/bin/sh -l echo "Hello $1" time=$(date) echo "time=$time" >> $GITHUB_OUTPUT
Se
entrypoint.sh
for executado sem erros, 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, confira "Definindo códigos de saída para ações". -
Torne o arquivo
entrypoint.sh
executável. O Git fornece uma maneira de alterar explicitamente o modo de permissão de um arquivo para que ele não seja redefinido toda vez que houver um clone/fork.Shell git add entrypoint.sh git update-index --chmod=+x entrypoint.sh
git add entrypoint.sh git update-index --chmod=+x entrypoint.sh
-
Opcionalmente, para verificar o modo de permissão do arquivo no índice Git, execute o comando a seguir.
Shell git ls-files --stage entrypoint.sh
git ls-files --stage entrypoint.sh
Uma saída como
100755 e69de29bb2d1d6434b8b29ae775ad8c2e48c5391 0 entrypoint.sh
significa que o arquivo tem a permissão executável. Neste exemplo,755
denota a permissão executável.
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:
- Uma descrição detalhada do que a ação faz.
- Argumentos de entrada e saída obrigatórios.
- Argumentos de entrada e saída opcionais.
- Segredos usados pela ação.
- Variáveis de ambiente que a ação usa.
- Um exemplo de como usar sua ação em um fluxo de trabalho.
LEIAME.md
# Hello world docker action This action prints "Hello World" or "Hello" + the name of a person to greet to the log. ## Inputs ## `who-to-greet` **Required** The name of the person to greet. Default `"World"`. ## Outputs ## `time` The time we greeted you. ## Example usage uses: actions/hello-world-docker-action@v2 with: who-to-greet: 'Mona the Octocat'
# Hello world docker action
This action prints "Hello World" or "Hello" + the name of a person to greet to the log.
## Inputs
## `who-to-greet`
**Required** The name of the person to greet. Default `"World"`.
## Outputs
## `time`
The time we greeted you.
## Example usage
uses: actions/hello-world-docker-action@v2
with:
who-to-greet: 'Mona the Octocat'
Faça commit, tag e push da sua ação para GitHub Enterprise Server
No 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 o controle de versão da ação, confira "Sobre ações personalizadas".
git add action.yml entrypoint.sh Dockerfile README.md git commit -m "My first action is ready" git tag -a -m "My first action release" v1 git push --follow-tags
git add action.yml entrypoint.sh Dockerfile README.md
git commit -m "My first action is ready"
git tag -a -m "My first action release" 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, é possível controlar quem pode acessá-la. Para obter mais informações, confira "Gerenciando as configurações do GitHub Actions para um repositório". - Quando uma ação está em um repositório interno, é possível controlar quem pode acessá-la. Para saber mais, confira "Gerenciando as configurações do GitHub Actions para um repositório".
- As ações públicas podem ser usadas por fluxos de trabalho em qualquer repositório.
Observação: o GitHub Actions no sua instância do GitHub Enterprise Server pode ter acesso limitado às ações do GitHub.com ou do GitHub Marketplace. Para saber mais, confira "Gerenciar o acesso a ações do GitHub.com" e entre em contato com o administrador do site do GitHub Enterprise.
Exemplo usando uma ação pública
O código de fluxo de trabalho a seguir usa a ação hello world concluída no repositório público actions/hello-world-docker-action
. Copie o código de exemplo de fluxo de trabalho a seguir em um arquivo .github/workflows/main.yml
, mas substitua o actions/hello-world-docker-action
pelo nome do repositório e 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: - name: Hello world action step id: hello uses: actions/hello-world-docker-action@v2 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 }}"
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@v2
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 código de exemplo de fluxo de trabalho a seguir para 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@v4 - 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 }}"
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@v4
- 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 repositório, clique na guia Ações e selecione a execução mais recente do fluxo de trabalho. Em Trabalhos ou no grafo de visualização, clique em Um trabalho para dizer olá.
Clique em Etapa da ação Olá, mundo e você verá "Olá, Mona, o Octocat" ou o nome usado para a entrada who-to-greet
impresso no log. Para ver o carimbo de data/hora, clique em Obter a hora da saída.
Acessar arquivos criados por uma ação de contêiner
Quando uma ação de contêiner é executada, ela mapeia automaticamente o diretório de trabalho padrão (GITHUB_WORKSPACE
) no executor com o diretório /github/workspace
no contêiner. Todos os arquivos adicionados a esse diretório no contêiner estarão disponíveis para todas as etapas subsequentes no mesmo trabalho. Por exemplo, se você tiver uma ação de contêiner que compila seu projeto e quiser carregar a saída da compilação como um artefato, poderá usar as etapas a seguir.
workflow.yml
jobs: build: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v4 # Output build artifacts to /github/workspace on the container. - name: Containerized Build uses: ./.github/actions/my-container-action - name: Upload Build Artifacts uses: actions/upload-artifact@v3 with: name: workspace_artifacts path: ${{ github.workspace }}
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
# Output build artifacts to /github/workspace on the container.
- name: Containerized Build
uses: ./.github/actions/my-container-action
- name: Upload Build Artifacts
uses: actions/upload-artifact@v3
with:
name: workspace_artifacts
path: ${{ github.workspace }}
Para obter mais informações sobre como carregar a saída de compilação como um artefato, consulte "Armazenando e compartilhando dados de um fluxo de trabalho".
Exemplos de ações de contêiner do Docker no GitHub.com
Encontre muitos exemplos de ações de contêiner do Docker no GitHub.com.