Prise en charge des fichiers Dockerfile pour GitHub Actions

Lors de la création d’une Dockerfile pour une action de conteneur Docker, vous devez savoir comment certaines instructions Docker interagissent avec GitHub Actions et le fichier de métadonnées d’une action.

Dans cet article

À propos des instructions Dockerfile

Un Dockerfile contient des instructions et des arguments qui définissent le contenu et le comportement de démarrage d’un conteneur Docker. Pour plus d’informations sur les instructions que Docker prend en charge, consultez « Dockerfile reference » dans la documentation Docker.

Instructions Dockerfile et remplacement des instructions

Certaines instructions Docker interagissent avec GitHub Actions, et le fichier de métadonnées d’une action peut remplacer certaines instructions Docker. Vous devez savoir comment votre fichier Dockerfile interagit avec GitHub Actions pour éviter tout comportement inattendu.

Utilisateur

Les actions Docker doivent être exécutées par l’utilisateur Docker par défaut (racine). N’utilisez pas l’instruction USER dans votre Dockerfile, car vous ne pouvez pas accéder au répertoire GITHUB_WORKSPACE. Pour plus d’informations, consultez « Stocker des informations dans des variables » et USER reference dans la documentation Docker.

FROM

La première instruction du fichier Dockerfile doit être FROM, qui sélectionne une image de base Docker. Pour plus d’informations, consultez FROM reference dans la documentation Docker.

Voici quelques bonnes pratiques concernant la définition de l’argument FROM :

  • Il est recommandé d’utiliser des images Docker officielles. Par exemple, python ou ruby.
  • Utilisez une étiquette de version s’il en existe une, de préférence avec une version principale. Par exemple, utilisez node:10 au lieu de node:latest.
  • Il est recommandé d’utiliser des images Docker basées sur le système d’exploitation Debian.

WORKDIR

GitHub définit le chemin du répertoire de travail dans la variable d’environnement GITHUB_WORKSPACE. Il est recommandé de ne pas utiliser l’instruction WORKDIR dans votre Dockerfile. Avant l’exécution de l’action, GitHub monte le répertoire GITHUB_WORKSPACE sur tout ce qui se trouvait à cet emplacement dans l’image Docker, puis il définit GITHUB_WORKSPACE comme répertoire de travail. Pour plus d’informations, consultez « Stocker des informations dans des variables » et WORKDIR reference dans la documentation Docker.

ENTRYPOINT

Si vous définissez entrypoint dans le fichier de métadonnées d’une action, cela remplacera le fichier ENTRYPOINT défini dans le Dockerfile. Pour plus d’informations, consultez « Metadata syntax for GitHub Actions ».

L’instruction Docker ENTRYPOINT peut avoir un format shell ou un format exec. La documentation Docker ENTRYPOINT recommande d’utiliser le format exec de l’instruction ENTRYPOINT. Pour plus d’informations sur les formats exec et shell, consultez la ENTRYPOINT reference dans la documentation Docker.

Vous ne devez pas utiliser WORKDIR pour spécifier votre point d’entrée dans le Dockerfile. Au lieu de cela, vous devez utiliser un chemin absolu. Pour plus d’informations, consultez WORKDIR.

Si vous configurez votre conteneur pour utiliser le format exec de l’instruction ENTRYPOINT, les args configurés dans le fichier de métadonnées de l’action ne s’exécuteront pas dans un interpréteur de commandes. Si les args de l’action contiennent une variable d’environnement, celle-ci ne sera pas substituée. Par exemple, l’utilisation du format exec suivant n’affiche pas la valeur stockée dans $GITHUB_SHA, mais affiche "$GITHUB_SHA" à la place.

ENTRYPOINT ["echo $GITHUB_SHA"]

Si vous souhaitez une substitution de variable, utilisez le format shell ou exécutez directement un interpréteur de commandes. Par exemple, à l’aide du format exec suivant, vous pouvez exécuter un interpréteur de commandes pour afficher la valeur stockée dans la variable d’environnement GITHUB_SHA.

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

Pour fournir les args définis dans le fichier de métadonnées de l’action à un conteneur Docker qui utilise le format exec dans ENTRYPOINT, nous vous recommandons de créer un script shell nommé entrypoint.sh que vous appellerez à partir de l’instruction ENTRYPOINT :

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

Exemple de fichier entrypoint.sh

À l’aide de l’exemple de Dockerfile ci-dessus, GitHub envoie les args configurés dans le fichier de métadonnées de l’action en tant qu’arguments à entrypoint.sh. Ajoutez le #!/bin/sh shebang en haut du fichier entrypoint.sh pour utiliser explicitement l’interpréteur de commandes compatible POSIX du système.

#!/bin/sh

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

Votre code doit être exécutable. Vérifiez que le fichier entrypoint.sh dispose d’autorisations execute avant de l’utiliser dans un workflow. Vous pouvez modifier l’autorisation à partir de votre terminal à l’aide de cette commande :

chmod +x entrypoint.sh

Lorsqu’un script shell ENTRYPOINT n’est pas exécutable, vous recevez une erreur similaire à celle-ci :

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

CMD

Si vous définissez args dans le fichier de métadonnées de l’action, args remplacera l’instruction CMD spécifiée dans le fichier de métadonnées de l’action Dockerfile. Pour plus d’informations, consultez « Metadata syntax for GitHub Actions ».

Si vous utilisez CMD dans votre Dockerfileapplication, suivez les instructions suivantes :

  1. Documentez les arguments requis dans le fichier README de l’action et omettez-les de l’instruction CMD.
  2. Utilisez les valeurs par défaut qui autorisent l’utilisation de l’action sans spécifier aucune valeur args.
  3. Si l’action expose un indicateur --help, ou quelque chose de similaire, utilisez-le pour rendre votre action auto-documentée.

Fonctionnalités Linux prises en charge

GitHub Actions prend en charge les fonctionnalités Linux par défaut qui sont prises en charge par Docker. Il n’est pas possible d’ajouter ni de supprimer des fonctionnalités. Pour plus d’informations sur les fonctionnalités Linux par défaut qui sont prises en charge par Docker, consultez « Capacités du noyau Linux » dans la documentation Docker. Pour en savoir plus sur les fonctionnalités Linux, consultez « Overview of Linux capabilities » dans les pages de manuel Linux.