Création d’un script de hook de pré-réception

Vous pouvez voir des exemples de hooks de pré-réception pour GitHub Enterprise Server dans le dépôt github/platform-samples.

Écriture d’un script de hook de pré-réception

Un script de hook de pré-réception s’exécute dans un environnement de hook de pré-réception sur votre instance GitHub Enterprise Server. Quand vous créez un script de hook de pré-réception, tenez compte des variables d’entrée, de sortie, d’état de sortie et d’environnement disponibles.

Entrée (stdin)

Après une poussée (push) et avant la mise à jour de toute référence pour le dépôt distant, le processus git-receive-pack sur votre instance GitHub Enterprise Server appelle le script de hook de pré-réception. L’entrée standard pour le script, stdin, est une chaîne contenant une ligne pour chaque référence à mettre à jour. Chaque ligne contient l’ancien nom d’objet et le nouveau nom d’objet pour la référence ainsi que le nom complet de la référence.

<old-value> SP <new-value> SP <ref-name> LF

Cette chaîne représente les arguments suivants.

Pour plus d’informations sur git-receive-pack, consultez « git-receive-pack » dans la documentation Git. Pour plus d’informations sur les références, consultez « Références Git » dans Pro Git.

Sortie (stdout)

La sortie standard du script, stdout, est retournée au client. Toutes les instructions echo seront visibles par l’utilisateur sur la ligne de commande ou dans l’interface utilisateur.

État de sortie

L’état de sortie d’un script de pré-réception détermine si la poussée sera acceptée.

Variables d'environnement

En plus de l’entrée standard de votre script de hook de pré-réception, stdin, GitHub Enterprise Server rend les variables suivantes disponibles dans l’environnement Bash pour l’exécution de votre script. Pour plus d’informations sur stdin pour votre script de hook de pré-réception, consultez « Entrée (stdin) ».

Différentes variables d’environnement sont disponibles pour votre script de hook de pré-réception selon ce qui déclenche l’exécution du script.

• Toujours disponible
• Disponible pour les poussées à partir de l’interface web ou de l’API
• Disponible pour les fusions de demandes de tirage (pull request)
• Disponible pour les poussées à l’aide de l’authentification SSH

Toujours disponible

Les variables suivantes sont toujours disponibles dans l’environnement de hook de pré-réception.

$GIT_DIR

$GIT_PUSH_OPTION_COUNT

$GIT_PUSH_OPTION_N

$GIT_USER_AGENT

$GITHUB_REPO_NAME

$GITHUB_REPO_PUBLIC

$GITHUB_USER_IP

$GITHUB_USER_LOGIN

Disponible pour les poussées à partir de l’interface web ou de l’API

La variable $GITHUB_VIA est disponible dans l’environnement de hook de pré-réception quand la mise à jour de la référence qui déclenche le hook s’effectue par le biais de l’interface web ou de l’API pour GitHub Enterprise Server. La valeur décrit l’action qui a mis à jour la référence.

auto-merge deployment api

blob#save

branch merge api

branches page delete button

git refs create api

git refs delete api

git refs update api

git repo contents api

merge base into head

pull request branch delete button

pull request branch undo button

pull request merge api

pull request merge button

pull request revert button

releases delete button

stafftools branch restore

tag create api

slumlord (#SHA)

web branch create

Disponible pour les fusions de demandes de tirage

Les variables suivantes sont disponibles dans l’environnement de hook de pré-réception quand la poussée qui déclenche le hook est due à la fusion d’une demande de tirage.

$GITHUB_PULL_REQUEST_AUTHOR_LOGIN

$GITHUB_PULL_REQUEST_HEAD

$GITHUB_PULL_REQUEST_BASE

Disponible pour les poussées à l’aide de l’authentification SSH

$GITHUB_PUBLIC_KEY_FINGERPRINT

Définition des autorisations et poussée d’un hook de pré-réception sur GitHub Enterprise Server

Un script de hook de pré-réception est contenu dans un dépôt sur votre instance GitHub Enterprise Server. Un administrateur de site doit prendre en compte les autorisations du dépôt et veiller à ce que seuls les utilisateurs appropriés y aient accès.

Nous vous recommandons de centraliser les hooks dans un dépôt unique. Si le dépôt dans lequel sont centralisés les hooks est public, README.md peut être utilisé pour expliquer les applications de stratégie. En outre, les contributions peuvent être acceptées par le biais de demandes de tirage. Toutefois, les hooks de pré-réception ne peuvent être ajoutés qu’à partir de la branche par défaut. Pour un workflow de test, des duplications (fork) du dépôt avec une configuration doivent être utilisées.

1. Pour les utilisateurs Mac, vérifiez que les scripts ont des autorisations d’exécution :

   sudo chmod +x SCRIPT_FILE.sh
   

   Pour les utilisateurs Windows, vérifiez que les scripts ont des autorisations d’exécution :

   git update-index --chmod=+x SCRIPT_FILE.sh
   

2. Commitez et poussez sur le dépôt désigné pour les hooks de pré-réception sur votre instance GitHub Enterprise Server.

   git commit -m "YOUR COMMIT MESSAGE"
   git push
   

3. Créez le hook de pré-réception sur l’instance GitHub Enterprise Server.

Test des scripts pré-réception localement

Vous pouvez tester un script de hook de pré-réception localement avant de le créer ou de le mettre à jour sur votre instance GitHub Enterprise Server. Vous pouvez, par exemple, créer un environnement Docker local qui jouera le rôle de dépôt distant pouvant exécuter le hook de pré-réception.

1. Vérifiez que Docker est installé localement.

2. Créez un fichier Dockerfile.dev contenant :

   FROM alpine:latest
   RUN \
     apk add --no-cache git openssh bash && \
     ssh-keygen -A && \
     sed -i "s/#AuthorizedKeysFile/AuthorizedKeysFile/g" /etc/ssh/sshd_config && \
     adduser git -D -G root -h /home/git -s /bin/bash && \
     passwd -d git && \
     su git -c "mkdir /home/git/.ssh && \
     ssh-keygen -t ed25519 -f /home/git/.ssh/id_ed25519 -P '' && \
     mv /home/git/.ssh/id_ed25519.pub /home/git/.ssh/authorized_keys && \
     mkdir /home/git/test.git && \
     git --bare init /home/git/test.git"
   
   VOLUME ["/home/git/.ssh", "/home/git/test.git/hooks"]
   WORKDIR /home/git
   
   CMD ["/usr/sbin/sshd", "-D"]
   

3. Créez un script de pré-réception de test nommé always_reject.sh. Cet exemple de script rejette toutes les poussées, ce qui est utile pour verrouiller un dépôt :

   #!/usr/bin/env bash
   
   echo "error: rejecting all pushes"
   exit 1
   

4. Vérifiez que les scripts always_reject.sh ont des autorisations d’exécution :

   chmod +x always_reject.sh
   

5. À partir du répertoire contenant Dockerfile.dev, générez une image :

   $ docker build -f Dockerfile.dev -t pre-receive.dev .
   [+] Building 4.5s (8/8) FINISHED
    => [internal] load build definition from Dockerfile.dev                                                                            0.0s
    => => transferring dockerfile: 641B                                                                                                0.0s
    => [internal] load .dockerignore                                                                                                   0.0s
    => transferring context: 2B                                                                                                     0.0s
    => [internal] load metadata for docker.io/library/alpine:latest                                                                    1.9s
    => [auth] library/alpine:pull token for registry-1.docker.io                                                                       0.0s
    => [1/3] FROM docker.io/library/alpine:latest@sha256:82d1e9d7ed48a7523bdebc18cf6290bdb97b82302a8a9c27d4fe885949ea94d1              0.0s
    => => resolve docker.io/library/alpine:latest@sha256:82d1e9d7ed48a7523bdebc18cf6290bdb97b82302a8a9c27d4fe885949ea94d1              0.0s
    => => sha256:82d1e9d7ed48a7523bdebc18cf6290bdb97b82302a8a9c27d4fe885949ea94d1 1.64kB / 1.64kB                                      0.0s
    => => sha256:25fad2a32ad1f6f510e528448ae1ec69a28ef81916a004d3629874104f8a7f70 528B / 528B                                          0.0s
    => => sha256:c1aabb73d2339c5ebaa3681de2e9d9c18d57485045a4e311d9f8004bec208d67 1.47kB / 1.47kB                                      0.0s
    => [2/3] RUN   apk add --no-cache git openssh bash &&   ssh-keygen -A &&   sed -i "s/#AuthorizedKeysFile/AuthorizedKeysFile/g" /e  2.3s
    => [3/3] WORKDIR /home/git                                                                                                         0.0s
    => exporting to image                                                                                                              0.1s
    => => exporting layers                                                                                                             0.1s
    => => writing image sha256:938447846e19a4328a85883fbd1ccf5eb919d97448cc7256efebf403d8b5a196                                        0.0s
    => => naming to docker.io/library/pre-receive.dev
   

6. Exécutez un conteneur de données qui contient une clé SSH générée :

   docker run --name data pre-receive.dev /bin/true
   

7. Copiez le hook de pré-réception de test always_reject.sh dans le conteneur de données :

   docker cp always_reject.sh data:/home/git/test.git/hooks/pre-receive
   

8. Exécutez un conteneur d’applications qui exécute sshd et exécute le hook. Notez l’ID de conteneur retourné :

   $ docker run -d -p 52311:22 --volumes-from data pre-receive.dev
   > 7f888bc700b8d23405dbcaf039e6c71d486793cad7d8ae4dd184f4a47000bc58
   

9. Copiez la clé SSH générée à partir du conteneur de données sur l’ordinateur local :

   docker cp data:/home/git/.ssh/id_ed25519 .
   

10. Modifiez le dépôt distant d’un dépôt de test et poussez sur le dépôt test.git dans le conteneur Docker. Cet exemple utilise git@github.com:octocat/Hello-World.git, mais vous pouvez utiliser n’importe quel dépôt. Cet exemple suppose que votre ordinateur local (127.0.0.1) lie le port 52311, mais vous pouvez utiliser une autre adresse IP si Docker s’exécute sur un ordinateur distant.

    $ git clone git@github.com:octocat/Hello-World.git
    $ cd Hello-World
    $ git remote add test git@127.0.0.1:test.git
    $ GIT_SSH_COMMAND="ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -p 52311 -i ../id_ed25519" git push -u test master
    > Warning: Permanently added '[127.0.0.1]:52311' (ECDSA) to the list of known hosts.
    > Counting objects: 7, done.
    > Delta compression using up to 4 threads.
    > Compressing objects: 100% (3/3), done.
    > Writing objects: 100% (7/7), 700 bytes | 0 bytes/s, done.
    > Total 7 (delta 0), reused 7 (delta 0)
    > remote: error: rejecting all pushes
    > To git@127.0.0.1:test.git
    >  ! [remote rejected] master -> master (pre-receive hook declined)
    > error: failed to push some refs to 'git@192.168.99.100:test.git'
    

    Notez que la poussée a été rejetée après l’exécution du hook de pré-réception et l’écho de la sortie du script.

Pour aller plus loin

• « Personnalisation de Git - Exemple de stratégie appliquée par Git » sur le site web Pro Git