Skip to main content

Esta versão do GitHub Enterprise será descontinuada em 2022-10-12. Nenhum lançamento de patch será feito, mesmo para questões críticas de segurança. Para obter melhor desempenho, segurança aprimorada e novos recursos, atualize para a última versão do GitHub Enterprise. Para obter ajuda com a atualização, entre em contato com o suporte do GitHub Enterprise.

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 ganchos de pré-recebimento do 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 your GitHub Enterprise Server instance. 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 referência seja atualizada para o repositório remoto, o processo git-receive-pack no your GitHub Enterprise Server instance invocará o script do gancho de pré-recebimento. A entrada padrão para o script, stdin, é uma cadeia de caracteres que contém uma linha para cada referência a ser atualizada. 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 do objeto antigo armazenado na referência.
Quando você cria uma referência, o valor é 40 zeros.
<new-value>Novo nome de objeto a ser armazenado na referência.
Quando você exclui uma referência, o valor é 40 zeros.
<ref-name>O nome completo da ref.

Para obter mais informações sobre git-receive-pack, confira "git-receive-pack" na documentação do Git. Para obter mais informações sobre as referências, confira "Referências do Git" em Pro Git.

Saída (stdout)

A saída padrão do script, stdout, é transmitida novamente para o cliente. As instruções echo ficarão visíveis para o usuário na linha de comando ou na interface do usuário.

Status da 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 script de gancho de pré-recebimento, stdin, o GitHub Enterprise Server disponibiliza as variáveis a seguir no ambiente do Bash para a execução do script. Para obter mais informações sobre o stdin do script de gancho de pré-recebimento, confira "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, confira "git-push" na documentação do Git.1
$GIT_PUSH_OPTION_N
Quando N for um número inteiro que começa no 0, essa variável conterá a cadeia de caracteres da 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 etc. Para obter mais informações sobre as opções de push, confira "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 NOME/PROPRIETÁRIOocto-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 ficará disponível no ambiente do gancho de pré-recebimento quando for feita a atualização de referência que dispara o gancho por meio da interface da Web ou da API do 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"Criar uma implantação" na documentação da API REST
blob#save
Mudar para o conteúdo de um arquivo na interface web"Como editar arquivos"
branch merge api
Merge de um branch através da API"Mesclar um branch" na documentação da API REST
branches page delete button
Exclusão de um branch na interface web"Como criar e excluir branches no seu repositório"
git refs create api
Criação de um ref através da API"Banco de dados do Git" na documentação da API REST
git refs delete api
Exclusão de uma ref através da API"Banco de dados do Git" na documentação da API REST
git refs update api
Atualização de um ref através da API"Banco de dados do Git" na documentação da API REST
git repo contents api
Mudança no conteúdo de um arquivo através da API"Criar ou atualizar o conteúdo do arquivo" na documentação da API REST

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 do tópico da solicitação de pull, no formato USERNAME:BRANCHoctocat:fix-bug
$GITHUB_PULL_REQUEST_BASE
O nome do branch base da solicitação de pull, 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 your GitHub Enterprise Server instance. 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 do gancho consolidado for público, o README.md poderá ser usado para explicar a imposiçã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 your GitHub Enterprise Server instance.

    $ git commit -m "YOUR COMMIT MESSAGE"
    $ git push
  3. Crie o gancho de pré-recebimento 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 your GitHub Enterprise Server instance. Uma forma de fazer isso é criar um ambiente Docker local para funcionar como repositório remoto que pode executar o hook pre-receive.

  1. Verifique se o Docker está instalado localmente.

  2. Crie um arquivo chamado 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 de pré-recebimento 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. Verifique se os scripts always_reject.sh têm permissões de execução:

    $ chmod +x always_reject.sh
  5. No diretório que contém Dockerfile.dev, compile 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.
    ....truncated output....
    > 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 gancho de pré-recebimento de teste always_reject.sh para o 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 executa sshd e executa o gancho. 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 repositório remoto de um repositório de teste e efetue push para o repositório test.git no contêiner do Docker. Este exemplo usa git@github.com:octocat/Hello-World.git, mas você poderá usar qualquer repositório que desejar. 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.
    > 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@192.168.99.100:test.git
    >  ! [remote rejected] main -> main (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.

Leitura adicional