Criando uma ação de contêiner do Docker

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".

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".

1. Crie um arquivo entrypoint.sh no diretório hello-world-docker-action.

2. 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
   
   

   Se entrypoint.sh for executado sem erros, o status da ação será definido como success. 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".

3. 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
   

4. 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
   

   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

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".

• As ações públicas podem ser usadas por fluxos de trabalho em qualquer repositório.

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. As ações públicas podem ser usadas mesmo se não forem publicadas em GitHub Marketplace. Para obter mais informações, confira "Publicar ações no GitHub Marketplace".

.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. Esta ação privada não pode ser publicada em GitHub Marketplace, e só pode ser usada neste repositório.

.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@v4
        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@v4
        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.

• github/issue-metrics
• microsoft/infersharpaction
• microsoft/ps-docs