Esta versão do GitHub Enterprise foi descontinuada em 2021-09-23. Nenhum lançamento de patch será feito, mesmo para questões críticas de segurança. Para obter melhor desempenho, melhorar a segurança e novos recursos, upgrade to the latest version of GitHub Enterprise. Para ajuda com a atualização, contact GitHub Enterprise support.

Criar um script de hook pre-receive

Use os scripts de hooks pre-receive a fim de criar requisitos para aceitar ou rejeitar um push com base no conteúdo.

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.

ArgumentoDescriçã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ídaAção
0O push será aceito.
Diferente de zeroO 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

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

VariávelDescriçãoValor 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
$GIT_USER_AGENT
String de usuário-agente enviada pelo cliente Git que realizou push das alteraçõesgit/2.0.0
$GITHUB_REPO_NAME
Nome do repositório que está sendo atualizado no formato NAME/OWNERocto-org/hello-enterprise
$GITHUB_REPO_PUBLIC
Booleano público, que representa se o repositório está sendo atualizado
  • true: A visibilidade do repositório é pública
  • false: A visibilidade do repositório é privada ou interna
$GITHUB_USER_IP
Endereço IP do cliente que iniciou o push192.0.2.1
$GITHUB_USER_LOGIN
Nome de usuário para a conta que iniciou o pushoctocat

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.

ValorAçãoMais 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#save
Mudar para o conteúdo de um arquivo na interface web"Editando arquivos"
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ávelDescriçãoValor de exemplo
$GITHUB_PULL_REQUEST_AUTHOR_LOGIN
Nome de usuário da conta que criou o pull requestoctocat
$GITHUB_PULL_REQUEST_HEAD
O nome do branch de tópico do pull request, no formato USERNAME:BRANCHoctocat:fix-bug
$GITHUB_PULL_REQUEST_BASE
O nome do branch de base do pull request no formato USERNAME:BRANCHoctocat:main

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

VariávelDescriçãoValor de exemplo
$GITHUB_PUBLIC_KEY_FINGERPRINT
A impressão digital da chave pública para o usuário que fez push das alteraçõesa1: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.

  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