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.
Argumento | Descrição |
---|---|
<old-value> | Nome de objeto antigo armazenado na ref. Ao criar uma nova ref, o valor será 40 zeros. |
<new-value> | Novo nome de objeto a ser armazenado na ref. Ao excluir uma ref, o valor será 40 zeros. |
<ref-name> | O nome completo da ref. |
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.
Valor de status de saída | Ação |
---|---|
0 | O push será aceito. |
Diferente de zero | O push será rejeitado. |
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.
Variável | Descrição | Valor de exemplo |
---|---|---|
$GIT_DIR | Caminho para o repositório remoto na instância | /data/user/repositories/a/ab/ a1/b2/34/100001234/1234.git |
$GIT_PUSH_OPTION_COUNT | O número de opções de push enviadas pelo cliente com --push-option . Para obter mais informações, consulte "git-push" na documentação do Git. | 1 |
$GIT_PUSH_OPTION_N | Quando N for um número inteiro a partir de 0, esta variável vai conter a string de opção de push enviada pelo cliente. A primeira opção enviada é armazenada em GIT_PUSH_OPTION_0 , a segunda opção enviada é armazenada em GIT_PUSH_OPTION_1 , e assim por diante. Para obter mais informações sobre as opções de push, consulte "git-push" na documentação do Git. | abcd |
$GITHUB_REPO_NAME | Nome do repositório que está sendo atualizado no formato NAME/OWNER | octo-org/hello-enterprise |
$GITHUB_REPO_PUBLIC | Booleano público, que representa se o repositório está sendo atualizado |
|
$GITHUB_USER_IP | Endereço IP do cliente que iniciou o push | 192.0.2.1 |
$GITHUB_USER_LOGIN | Nome de usuário para a conta que iniciou o push | octocat |
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.
Valor | Ação | Mais informações |
---|---|---|
auto-merge deployment api | Merge automático do branch base através de uma implantação criada com a API | "Repositórios" na documentação da API REST |
blob edit | Mudar para o conteúdo de um arquivo na interface web | "Editar arquivos no repositório" |
branch merge api | Merge de um branch através da API | "Repositórios" na documentação da API REST |
branches page delete button | Exclusão de um branch na interface web | "Criar e excluir branches dentro do seu repositório" |
git refs create api | Criação de um ref através da API | "Banco de dados Git" na documentação da API REST |
git refs delete api | Exclusão de uma ref através da API | "Banco de dados Git" na documentação da API REST |
git refs update api | Atualização de um ref através da API | "Banco de dados Git" na documentação da API REST |
git repo contents api | Mudança no conteúdo de um arquivo através da API | "Repositórios" na documentação da API REST |
merge base into head | Atualizar o branch de tópico do branch de base quando o branch de base exigir verificações de status rigorosas (via Atualizar branch em um pull request, por exemplo) | "Sobre branches protegidos" |
pull request branch delete button | Exclusão de um branch de tópico de um pull request na interface web | "Excluindo e restaurando branches em uma pull request" |
pull request branch undo button | Restauração de um branch de tópico de um pull request na interface web | "Excluindo e restaurando branches em uma pull request" |
pull request merge api | Merge de um pull request através da API | "Pulls" na documentação da API REST |
pull request merge button | Merge de um pull request na interface web | "Fazer merge de uma pull request" |
pull request revert button | Reverter um pull request | "Reverter uma pull request" |
releases delete button | Exclusão de uma versão | "Gerenciar versões em um repositório" |
stafftools branch restore | Restauração de um branch do painel de administração do site | "Painel de administração do site" |
tag create api | Criação de uma tag através da API | "Banco de dados Git" na documentação da API REST |
slumlord (#SHA) | Commit por meio do Subversion | "Compatibilidade para clientes de Subversion" |
web branch create | Criação de um branch através da interface web | "Criar e excluir branches dentro do seu repositório" |
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.
Variável | Descrição | Valor de exemplo |
---|---|---|
$GITHUB_PULL_REQUEST_AUTHOR_LOGIN | Nome de usuário da conta que criou o pull request | octocat |
$GITHUB_PULL_REQUEST_HEAD | O nome do branch de tópico do pull request, no formato USERNAME:BRANCH | |
$GITHUB_PULL_REQUEST_BASE | O nome do branch de base do pull request no formato USERNAME:BRANCH | octocat:main |
Disponível para pushes que usam autenticação SSH
Variável | Descrição | Valor de exemplo |
---|---|---|
$GITHUB_PUBLIC_KEY_FINGERPRINT | A impressão digital da chave pública para o usuário que fez push das alterações | a1:b2:c3:d4:e5:f6:g7:h8:i9:j0:k1:l2:m3:n4:o5:p6 |
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.
-
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
-
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
-
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.
-
Garanta que o Docker está instalado localmente.
-
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"]
-
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
-
Certifique-se de que os scripts
always_reject.sh
têm permissões de execução:$ chmod +x always_reject.sh
-
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
-
Execute um contêiner de dados que contenha uma chave SSH gerada:
$ docker run --name data pre-receive.dev /bin/true
-
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
-
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
-
Copie a chave SSH gerada do contêiner de dados para a máquina local:
$ docker cp data:/home/git/.ssh/id_ed25519 .
-
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 ogit@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