Remarque : Les exécuteurs hébergés sur GitHub ne sont pas pris en charge sur GitHub Enterprise Server. Vous pouvez voir plus d’informations sur le support futur planifié dans la GitHub public roadmap.
Introduction
Dans ce guide, vous allez découvrir les composants de base qui sont nécessaires pour créer et utiliser une action de conteneur Docker empaquetée. Afin de nous concentrer sur les composants nécessaires à l’empaquetage de l’action, nous avons réduit la fonctionnalité du code de l’action à son strict minimum. L’action affiche « Hello World » dans les journaux ou « Hello [who-to-greet] » si vous fournissez un nom personnalisé.
Une fois que vous aurez terminé ce projet, vous saurez comment créer votre propre action de conteneur Docker et la tester dans un workflow.
Les exécuteurs autohébergés doivent utiliser un système d’exploitation Linux et disposer de Docker pour exécuter les actions de conteneur Docker. Pour plus d’informations sur les impératifs des exécuteurs autohébergés, consultez « À propos des exécuteurs auto-hébergés ».
Avertissement : Au moment de la création de workflows et d’actions, vous devez toujours déterminer si votre code peut exécuter une entrée non fiable provenant d’attaquants potentiels. Certains contextes doivent être traités comme des entrées non fiables, car un attaquant peut insérer son propre contenu malveillant. Pour plus d’informations, consultez « Durcissement de la sécurité pour GitHub Actions ».
Prérequis
- Vous devez créer un dépôt sur GitHub et le cloner sur votre station de travail. Pour plus d’informations, consultez « Création d’un dépôt » et « Clonage d’un dépôt ».
- Si votre référentiel utilise Git LFS, vous devez inclure les objets dans les archives de votre dépôt. Pour plus d’informations, consultez « Gestion des objets Git LFS dans les archives de votre dépôt ».
- Il peut être utile d'avoir des connaissances de base sur GitHub Actions, les variables d'environnement et le système de fichiers du conteneur Docker. Pour plus d’informations, consultez « Stocker des informations dans des variables » et « Utilisation des exécuteurs hébergés par GitHub ».
Création d’un Dockerfile
Dans le nouveau répertoire hello-world-docker-action
, créez un fichier Dockerfile
. Vérifiez que le nom de votre fichier est bien en majuscules (utilisez un D
majuscule et non un f
majuscule) si vous rencontrez des problèmes. Pour plus d’informations, consultez « Prise en charge des fichiers Dockerfile pour 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"]
Création d’un fichier de métadonnées d’action
Créez un fichier action.yml
dans le répertoire hello-world-docker-action
que vous avez créé ci-dessus. Pour plus d’informations, consultez « Metadata syntax for 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 }}
Ces métadonnées définissent une entrée who-to-greet
et un paramètre de sortie time
. Pour passer des entrées au conteneur Docker, vous devez déclarer les entrées à l’aide de inputs
et les passer dans le mot clé args
. Tout ce que vous incluez dans args
est passé au conteneur. Toutefois, pour que les utilisateurs puissent mieux découvrir votre action, nous vous recommandons d’utiliser des entrées.
GitHub crée une image à partir de votre Dockerfile
et exécute les commandes dans un nouveau conteneur à l’aide de cette image.
Écriture du code d’action
Vous pouvez choisir n’importe quelle image Docker de base et, donc, n’importe quel langage pour votre action. L’exemple de script shell suivant utilise la variable d’entrée who-to-greet
pour afficher « Hello [who-to-greet] » dans le fichier journal.
Ensuite, le script obtient l’heure actuelle et la définit comme une variable de sortie que pourront utiliser les prochaines actions d’un travail. Pour que GitHub reconnaisse les variables de sortie, vous devez les écrire dans le fichier d’environnement $GITHUB_OUTPUT
: echo "<output name>=<value>" >> $GITHUB_OUTPUT
. Pour plus d’informations, consultez « Workflow commands for GitHub Actions ».
-
Dans le répertoire
hello-world-docker-action
, créez un fichierentrypoint.sh
. -
Ajoutez le code suivant à votre fichier
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
Si
entrypoint.sh
s’exécute sans erreur, l’état de l’action est défini sursuccess
. Pour indiquer l’état d’une action, vous pouvez définir explicitement des codes de sortie dans le code de l’action. Pour plus d’informations, consultez « Setting exit codes for actions ». -
Rendez votre fichier
entrypoint.sh
exécutable. Git permet de modifier explicitement le mode d’autorisation d’un fichier afin qu’il ne soit pas réinitialisé chaque fois qu’il existe un clone/une duplication.Shell git add entrypoint.sh git update-index --chmod=+x entrypoint.sh
git add entrypoint.sh git update-index --chmod=+x entrypoint.sh
-
Si vous le souhaitez, pour vérifier le mode d’autorisation du fichier dans l’index git, exécutez la commande suivante.
Shell git ls-files --stage entrypoint.sh
git ls-files --stage entrypoint.sh
Une sortie comme
100755 e69de29bb2d1d6434b8b29ae775ad8c2e48c5391 0 entrypoint.sh
signifie que le fichier dispose de l’autorisation exécutable. Dans cet exemple,755
indique l’autorisation exécutable.
Création d’un fichier README
Pour expliquer aux utilisateurs comment utiliser votre action, vous pouvez créer un fichier README. Un fichier README est très utile si vous prévoyez de partager votre action publiquement, mais c’est aussi un excellent moyen de vous rappeler comment utiliser l’action.
Dans votre répertoire hello-world-docker-action
, créez un fichier README.md
qui spécifie les informations suivantes :
- Une description détaillée de ce que fait l’action.
- Les arguments d’entrée et de sortie obligatoires.
- Les arguments d’entrée et de sortie facultatifs.
- Les secrets utilisés par l’action.
- Les variables d’environnement utilisées par l’action.
- Un exemple d’utilisation de votre action dans un workflow.
README.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'
Commiter, étiqueter et pousser votre action vers GitHub Enterprise Server
À partir de votre terminal, commitez vos fichiers action.yml
, entrypoint.sh
, Dockerfile
et README.md
.
Il est recommandé d’ajouter également une étiquette de version pour les versions de votre action. Pour plus d’informations sur le versioning de votre action, consultez « À propos des actions personnalisées ».
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
Tester votre action dans un workflow
Vous êtes maintenant prêt à tester votre action dans un workflow.
- Lorsqu’une action se trouve dans un référentiel privé, vous pouvez contrôler qui peut y accéder. Pour plus d’informations, consultez « Gestion des paramètres de GitHub Actions pour un dépôt ». - Lorsqu’une action se trouve dans un référentiel interne, vous pouvez contrôler qui peut y accéder. Pour plus d’informations, consultez « Gestion des paramètres de GitHub Actions pour un dépôt ».
- Les actions publiques peuvent être utilisées par les workflows dans n’importe quel dépôt.
Remarque : GitHub Actions sur peut avoir un accès limité aux actions sur GitHub.com ou GitHub Marketplace. Pour plus d’informations, consultez « Gestion de l’accès aux actions de GitHub.com » et contactez votre administrateur de site GitHub Enterprise.
Exemple utilisant une action publique
Le code du workflow suivant utilise l’action hello world terminée dans le dépôt public actions/hello-world-docker-action
. Copiez l’exemple de code de workflow suivant dans un fichier .github/workflows/main.yml
, en remplaçant actions/hello-world-docker-action
par le nom de votre dépôt et le nom de votre action. Vous pouvez également remplacer l’entrée who-to-greet
par votre nom.
.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 }}"
Exemple utilisant une action privée
Copiez le code de l’exemple de workflow suivant dans un fichier .github/workflows/main.yml
du dépôt de votre action. Vous pouvez également remplacer l’entrée who-to-greet
par votre nom.
.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 }}"
Dans votre dépôt, cliquez sur l’onglet Actions, puis sélectionnez la dernière exécution du workflow. Sous Travaux ou dans le graphe de visualisation, cliquez sur A job to say hello.
Cliquez sur Hello world action step et vous devriez voir « Hello Mona the Octocat » ou le nom que vous avez utilisé pour l’entrée who-to-greet
imprimée dans le journal. Pour voir l’horodatage, cliquez sur Obtenir l’heure de la sortie.
Accès aux fichiers créés par une action de conteneur
Quand une action de conteneur s’exécute, elle mappe automatiquement le répertoire de travail par défaut (GITHUB_WORKSPACE
) sur l’exécuteur avec l’annuaire /github/workspace
du conteneur. Tous les fichiers ajoutés à cet annuaire sur le conteneur seront disponibles pour toutes les étapes suivantes du même projet. Par exemple, si vous disposez d’une action de conteneur qui génère votre projet et que vous souhaitez télécharger la sortie du build en tant qu’artefact, vous pouvez utiliser les étapes suivantes.
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 }}
Pour plus d’informations sur le chargement de la sortie du build en tant qu’artefact, consultez « Stockage et partage des données d’un workflow ».
Exemples d’actions de conteneur Docker sur GitHub.com
Vous pouvez trouver de nombreux exemples d’actions de conteneur Docker sur GitHub.com.