Skip to main content

Suporte do arquivo Docker para GitHub Actions

Ao criar um Dockerfile para uma ação do contêiner Docker, você deverá ter em mente como algumas instruções do Docker interagem com o GitHub Actions e com um arquivo de metadados da ação.

Sobre as instruções do arquivo Docker

Um Dockerfile contém instruções e argumentos que definem o conteúdo e o comportamento de inicialização de um contêiner do Docker. Para obter mais informações sobre as instruções às quais o Docker dá suporte, confira "Referência do Dockerfile" na documentação do Docker.

Instruções e substituições do arquivo Docker

Algumas instruções do Docker interagem com o GitHub Actions e um arquivo de metadados pode substituir algumas instruções do Docker. Certifique-se de que você esteja familiarizado com a forma como o arquivo Docker interage com GitHub Actions para evitar comportamento inesperado.

USER

As ações do Docker devem ser executadas pelo usuário-padrão do Docker (raiz). Não use a instrução USER no Dockerfile, porque você não poderá acessar o diretório GITHUB_WORKSPACE. Para obter mais informações, confira "Variáveis" e Referência de USER na documentação do Docker.

FROM

A primeira instrução no Dockerfile precisa ser FROM, que seleciona uma imagem base do Docker. Para obter mais informações, confira a Referência de FROM na documentação do Docker.

Estas são algumas melhores práticas ao definir o argumento FROM:

  • Recomendamos o uso de imagens oficiais do Docker. Por exemplo, python ou ruby.
  • Use uma tag da versão, se houver, preferencialmente com uma versão principal. Por exemplo, use node:10 ao invés de node:latest.
  • Recomendamos usar imagens do Docker com base no sistema operacional Debian.

WORKDIR

O GitHub define o caminho do diretório de trabalho na variável de ambiente GITHUB_WORKSPACE. Recomendamos não usar a instrução WORKDIR no Dockerfile. Antes da execução da ação, o GitHub montará o diretório GITHUB_WORKSPACE em qualquer item que estava naquele local na imagem do Docker e definirá GITHUB_WORKSPACE como o diretório de trabalho. Para obter mais informações, confira "Variáveis" e Referência de WORKDIR na documentação do Docker.

ENTRYPOINT

Se você definir entrypoint no arquivo de metadados de uma ação, ele substituirá o ENTRYPOINT definido no Dockerfile. Para obter mais informações, confira "Sintaxe de metadados para o GitHub Actions".

A instrução ENTRYPOINT do Docker tem um formulário de shell e um formulário de execução. A documentação de ENTRYPOINT do Docker recomenda o uso do formulário exec da instrução ENTRYPOINT. Para obter mais informações sobre os formulários exec e shell, confira a Referência de ENTRYPOINT na documentação do Docker.

Você não deve usar WORKDIR para especificar o ponto de entrada no Dockerfile. Em vez disso, você edverá usar um caminho absoluto. Para obter mais informações, confira WORKDIR.

Se você configurar o contêiner para usar o formulário exec da instrução ENTRYPOINT, os args configurados no arquivo de metadados da ação não serão executados em um shell de comando. Se os args da ação contiverem uma variável de ambiente, a variável não será substituída. Por exemplo, o uso do formato exec a seguir não imprimirá o valor armazenado em $GITHUB_SHA, mas imprimirá "$GITHUB_SHA".

ENTRYPOINT ["echo $GITHUB_SHA"]

Caso deseje fazer a substituição da variável, use o formulário shell ou execute um shell diretamente. Por exemplo, usando o formato exec a seguir, você pode executar um shell para imprimir o valor armazenado na variável de ambiente GITHUB_SHA.

ENTRYPOINT ["sh", "-c", "echo $GITHUB_SHA"]

Para fornecer os args definidos no arquivo de metadados da ação para um contêiner do Docker que usa o formulário exec, ENTRYPOINTrecomendamos criar um script de shell com o nome entrypoint.sh que é chamado por meio da instrução ENTRYPOINT:

Exemplo de Dockerfile

# Container image that runs your code
FROM debian:9.5-slim

# Copies your code file from your action repository to the filesystem path `/` of the container
COPY entrypoint.sh /entrypoint.sh

# Executes `entrypoint.sh` when the Docker container starts up
ENTRYPOINT ["/entrypoint.sh"]

Exemplo de arquivo entrypoint.sh

Usando o exemplo de Dockerfile acima, o GitHub enviará os args configurados no arquivo de metadados da ação como argumentos para entrypoint.sh. Adicione o shebang #!/bin/sh no início do arquivo entrypoint.sh para usar explicitamente o shell compatível com POSIX do sistema.

#!/bin/sh

# `$#` expands to the number of arguments and `$@` expands to the supplied `args`
printf '%d args:' "$#"
printf " '%s'" "$@"
printf '\n'

O seu código deve ser executável. Verifique se o arquivo entrypoint.sh tem as permissões execute antes de usá-lo em um fluxo de trabalho. Você pode modificar as permissões a partir do seu terminal usando este comando:

chmod +x entrypoint.sh

Quando um script de shell ENTRYPOINT não for executável, você receberá um erro semelhante a este:

Error response from daemon: OCI runtime create failed: container_linux.go:348: starting container process caused "exec: \"/entrypoint.sh\": permission denied": unknown

CMD

Se você definir args no arquivo de metadados da ação, args substituirá a instrução CMD especificada no Dockerfile. Para obter mais informações, confira "Sintaxe de metadados para o GitHub Actions".

Se você usar CMD no Dockerfile, siga estas diretrizes:

  1. Documente os argumentos necessários no README da ação e omita-os da instrução CMD.
  2. Use padrões que permitam o uso da ação sem a especificação de args.
  3. Se a ação expuser um sinalizador --help ou algo semelhante, use-o para tornar a ação autodocumentada.

Recursos compatíveis com o Linux

GitHub Actions suporta os recursos-padrão compatíveis com o Linux que são compatíveis com o Docker. Não é possível adicionar ou remover recursos. Para obter mais informações sobre as funcionalidades padrão do Linux compatíveis com o Docker, confira "Privilégio de runtime e funcionalidades do Linux" na documentação do Docker. Para saber mais sobre as funcionalidades do Linux, confira "Visão geral das funcionalidades do Linux" nas páginas do manual do Linux.