Criar um script de hook pre-receive

Veja exemplos de hooks pre-receive para o GitHub Enterprise Server no repositório github/platform-samples.

Gravar um script de hook pre-receive

Um script de hook pre-receive é executado em um ambiente de hook pre-receive em sua instância do GitHub Enterprise Server. Ao criar um script de hook pre-receive, considere a entrada, saída, estado de saída e variáveis de ambiente disponíveis.

Entrada (stdin)

Depois que um push ocorrer e antes que qualquer ref seja atualizado para o repositório remoto, o processo git-receive-pack em sua instância do GitHub Enterprise Server irá invocar o script de do hook pre-receive. A entrada padrão para o script, stdin, é uma string que contém uma linha atualizar cada ref. Cada linha contém o nome antigo do objeto para ref, o novo nome do objeto para o ref e o nome completo do ref.

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

Essa frase representa os argumentos a seguir.

Para obter mais informações sobre git-receive-pack, consulte "git-receive-pack" na documentação do Git. Para obter mais informações sobre refs, consulte "Referências do Git" no Pro Git.

Saída (stdout)

A saída padrão do script, stdout, é remetida de volta para o cliente. Qualquer echo será visível para o usuário na linha de comando ou na interface do usuário.

Status de saída

O status de saída de um script pre-receive determina se o push será aceito.

Variáveis de ambiente

Além da entrada padrão para o seu script do hook pre-receive, stdin, GitHub Enterprise Server disponibiliza as variáveis a seguir no ambiente Bash para a execução do seu script. Para obter mais informações sobre stdin para o seu script de hook de pre-receive, consulte "Entrada (stdin)".

Diferentes variáveis de ambiente estão disponíveis para o seu script de hook pre-receive dependendo do que acionar o script.

• Sempre disponível
• Disponível para pushes a partir da interface web ou API
• Disponível para merge de pull request
• Disponível para pushes que usam autenticação SSH

Sempre disponível

As seguintes variáveis estão sempre disponíveis no ambiente de do hook pre-receive.

$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

Disponível para pushes a partir da interface web ou API

A variável $GITHUB_VIA está disponível no ambiente de pre-receive quando a atualização de ref que aciona o hook por meio da interface da web ou da API para GitHub Enterprise Server. O valor descreve a ação que atualizou o ref.

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

Disponível para merge de pull request

As variáveis a seguir estão disponíveis no ambiente de hook pre-receive quando o push que aciona o hook é um push devido ao merge de um pull request.

$GITHUB_PULL_REQUEST_AUTHOR_LOGIN

$GITHUB_PULL_REQUEST_HEAD

$GITHUB_PULL_REQUEST_BASE

Disponível para pushes que usam autenticação SSH

$GITHUB_PUBLIC_KEY_FINGERPRINT

Configurar permissões e fazer push de um hook pre-receive para o GitHub Enterprise Server

Um script de hook pre-receive está contido em um repositório em sua instância do GitHub Enterprise Server. O administrador do site deve considerar as permissões do repositório e garantir que somente os usuários adequados tenham acesso.

Recomendamos consolidar os hooks em um único repositório. Se o repositório consolidado do hook for público, será possível usar README.md para explicar a execução das políticas. Além disso, é possível aceitar contribuições via pull request. No entanto, os hooks pre-receive só podem ser adicionados pelo branch padrão. Em fluxos de trabalho de teste, devem ser usados forks do repositório com a devida configuração.

1. Para usuários de Mac, certifique-se de que os scripts tenham estas permissões de execução:

   $ sudo chmod +x SCRIPT_FILE.sh

   Para usuários de Windows, certifique-se de que os scripts tenham estas permissões de execução:

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

2. Faça o commit e push para o repositório designado para os hooks pre-receive em sua instância do GitHub Enterprise Server.

   $ git commit -m "YOUR COMMIT MESSAGE"
   $ git push

3. Crie o hook pre-receive na instância do GitHub Enterprise Server.

Testar scripts pre-receive no local

Você pode testar um script do hook pre-receive localmente antes de criá-lo ou atualizá-lo em sua instância do GitHub Enterprise Server. Uma forma de fazer isso é criar um ambiente Docker local para funcionar como repositório remoto que pode executar o hook pre-receive.

1. Garanta que o Docker está instalado localmente.

2. Crie um arquivo de nome Dockerfile.dev contendo:

   FROM gliderlabs/alpine:3.3
   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. Crie um script pre-receive de teste chamado always_reject.sh. Este exemplo de script rejeitará todos os pushes, o que é importante para bloquear um repositório:

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

4. Certifique-se de que os scripts always_reject.sh têm permissões de execução:

   $ chmod +x always_reject.sh

5. No diretório contendo Dockerfile.dev, crie uma imagem:

   $ docker build -f Dockerfile.dev -t pre-receive.dev .
   > Sending build context to Docker daemon 3.584 kB
   > Step 1 : FROM gliderlabs/alpine:3.3
   >  ---> 8944964f99f4
   > Step 2 : 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"
   >  ---> Running in e9d79ab3b92c
   > fetch http://alpine.gliderlabs.com/alpine/v3.3/main/x86_64/APKINDEX.tar.gz
   > fetch http://alpine.gliderlabs.com/alpine/v3.3/community/x86_64/APKINDEX.tar.gz
   ....truncated output....
   > OK: 34 MiB in 26 packages
   > ssh-keygen: generating new host keys: RSA DSA ECDSA ED25519
   > Password for git changed by root
   > Generating public/private ed25519 key pair.
   > Your identification has been saved in /home/git/.ssh/id_ed25519.
   > Your public key has been saved in /home/git/.ssh/id_ed25519.pub.
   ....saída truncada....
   > Initialized empty Git repository in /home/git/test.git/
   > Successfully built dd8610c24f82

6. Execute um contêiner de dados que contenha uma chave SSH gerada:

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

7. Copie o hook pre-receive de teste always_reject.sh no contêiner de dados:

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

8. Execute um contêiner de aplicativo que execute sshd e o hook. Anote o ID do contêiner:

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

9. Copie a chave SSH gerada do contêiner de dados para a máquina local:

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

10. Modifique o remote de um repositório de teste e faça push para o repo test.git no contêiner Docker. Este exemplo usa o git@github.com:octocat/Hello-World.git, mas você pode usar o repositório da sua preferência. Este exemplo pressupõe que a sua máquina local (127.0.0.1) está vinculando a porta 52311, mas você pode usar outro endereço IP se o docker estiver sendo executado em uma máquina remota.

    $ 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 main
    > Warning: Permanently added '[192.168.99.100]:52311' (ECDSA) to the list of known hosts.
    > Contando objetos: 7, concluído.
    > Delta compression using up to 4 threads.
    > Comprimindo objetos: 100% (3/3), concluído.
    > Gravando objetos: 100% (7/7), 700 bytes | 0 bytes/s, concluído.
    > Total 7 (delta 0), reused 7 (delta 0)
    > remote: error: rejecting all pushes
    > To git@192.168.99.100:test.git
    >  ! [remote rejected] master -> master (pre-receive hook declined)
    > error: failed to push some refs to 'git@192.168.99.100:test.git'

    Observe que o push foi rejeitado após a execução do hook pre-receive e o eco da saída do script.

Leia mais

• "Personalizar o Git - Um exemplo da aplicação da política do Git" no site do Pro Git