Soporte de Dockerfile para GitHub Actions

Cuando creas un Dockerfile para una acción de un contenedor de Docker, debes ser consciente de cómo interactúan algunas instrucciones de Docker con GitHub Actions y con el archivo de metadatos de la acción.

En este artículo

Acerca de las instrucciones de Dockerfile

Un elemento Dockerfile incluye instrucciones y argumentos que definen el contenido y comportamiento inicial de un contenedor Docker. Para obtener más información sobre las instrucciones compatibles con Docker, consulta Referencia de Dockerfile en la documentación de Docker.

Instrucciones e invalidaciones de Dockerfile

Algunas instrucciones de Docker interactúan con GitHub Actions, y un archivo de metadatos de la acción puede invalidar algunas instrucciones de Docker. Asegúrate de que estás familiarizado con la manera en que tu Dockerfile interactúa con GitHub Actions para prevenir cualquier comportamiento inesperado.

USER

Las acciones de Docker deben ejecutarse mediante el usuario predeterminado de Docker (root). No uses la instrucción USER en Dockerfile, porque no podrás acceder al directorio GITHUB_WORKSPACE. Para obtener más información, consulta Almacenamiento de información en variables y referencia USER en la documentación de Docker.

FROM

La primera instrucción de Dockerfile debe ser FROM, que selecciona una imagen base de Docker. Para obtener más información, vea la referencia FROM en la documentación de Docker.

Estos son algunos procedimientos recomendados al establecer el argumento FROM:

  • Se recomienda utilizar imágenes oficiales de Docker. Por ejemplo, python o ruby.
  • Utiliza una etiqueta de versión si es que existe, preferentemente con una versión mayor. Por ejemplo, use node:10 en lugar de node:latest.
  • Se recomienda usar imágenes de Docker basadas en el sistema operativo Debian.

WORKDIR

GitHub Enterprise Cloud establece la ruta de acceso del directorio de trabajo en la variable de entorno GITHUB_WORKSPACE. Se recomienda no usar la instrucción WORKDIR en Dockerfile. Antes de que se ejecute la acción, GitHub Enterprise Cloud montará el directorio GITHUB_WORKSPACE sobre todo lo que estuviera en esa ubicación en la imagen de Docker y se establecerá GITHUB_WORKSPACE como directorio de trabajo. Para obtener más información, consulta Almacenamiento de información en variables y la referencia WORKDIR en la documentación de Docker.

ENTRYPOINT

Si define entrypoint en el archivo de metadatos de una acción, invalidará el elemento ENTRYPOINT definido en Dockerfile. Para más información, consulta Sintaxis de metadatos para Acciones de GitHub.

La instrucción ENTRYPOINT de Docker tiene un formato shell y otro exec. En la documentación ENTRYPOINT de Docker se recomienda usar el formato exec de la instrucción ENTRYPOINT. Para obtener más información sobre los formatos exec y shell, vea la referencia ENTRYPOINT en la documentación de Docker.

No debe usar WORKDIR para especificar el entrypoint en el Dockerfile. En vez de esto, deberías utilizar una ruta absoluta. Para obtener más información, vea WORKDIR.

Si configura el contenedor para usar el formato exec de la instrucción ENTRYPOINT, el elemento args configurado en el archivo de metadatos de la acción no se ejecutará en un shell de comandos. Si el elemento args de la acción contiene una variable de entorno, esta no se sustituirá. Por ejemplo, el uso del siguiente formato exec no imprimirá el valor almacenado en $GITHUB_SHA, sino que en su lugar imprimirá "$GITHUB_SHA".

ENTRYPOINT ["echo $GITHUB_SHA"]

Si quiere la sustitución de variables, puede utilizar el formato shell o ejecutar un shell directamente. Por ejemplo, con el siguiente formato exec, puede ejecutar un shell para imprimir el valor almacenado en la variable de entorno GITHUB_SHA.

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

Para proporcionar args definidos en el archivo de metadatos de la acción a un contenedor de Docker que use el formato exec en ENTRYPOINT, se recomienda crear un script de shell denominado entrypoint.sh que llame desde la instrucción ENTRYPOINT:

Dockerfile de ejemplo

# 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"]

Archivo entrypoint.sh de ejemplo

Con el Dockerfile de ejemplo anterior, GitHub Enterprise Cloud enviará el elemento args configurado en el archivo de metadatos de la acción como argumentos a entrypoint.sh. Agregue el elemento #!/bin/sh shebang en la parte superior del archivo entrypoint.sh para usar explícitamente el shell compatible con POSIX del sistema.

#!/bin/sh

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

Tu código debe ser ejecutable. Asegúrese de que el archivo entrypoint.sh tiene permisos execute antes de usarlo en un flujo de trabajo. Puedes modificar los permisos de tu terminal si utilizas este comando:

chmod +x entrypoint.sh

Cuando un script de shell ENTRYPOINT no sea ejecutable, recibirá un error similar al siguiente:

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

CMD

Si define args en el archivo de metadatos de la acción, args invalidará la instrucción CMD especificada en Dockerfile. Para más información, consulta Sintaxis de metadatos para Acciones de GitHub.

Si usa CMD en Dockerfile, siga estas instrucciones:

  1. En el documento se necesitaban argumentos en el archivo Léame de la acción y omitirlos de la instrucción CMD.
  2. Use los valores predeterminados que permiten usar la acción sin especificar args.
  3. Si la acción expone una marca --help, o algo similar, úselo para que la acción se documente de forma automática.

Capacidades de Linux compatibles

GitHub Actions es compatible con las capacidades predeterminadas de Linux que acepta Docker. Estas capacidades no se pueden añadir ni eliminar. Para obtener más información acerca de las capacidades predeterminadas de Linux compatibles con Docker, consulta Capacidades de Linux y kernel en la documentación de Docker. Para obtener más información sobre las capacidades de Linux, consulta Información general sobre las capacidades de Linux en las páginas man de Linux.