Создание скрипта перехватчика предварительного получения

Примеры перехватчиков предварительного получения для GitHub Enterprise Server можно просмотреть в репозитории github/platform-samples.

Написание скрипта перехватчика предварительного получения

Скрипт перехватчика предварительного получения выполняется в среде перехватчика предварительного получения на экземпляр GitHub Enterprise Server. При создании скрипта перехватчика предварительного получения учитывайте доступные входные и выходные данные, состояние выхода и переменные среды.

Входные данные (stdin)

После отправки и перед обновлением ссылок для удаленного репозитория git-receive-pack процесс экземпляр GitHub Enterprise Server вызывает скрипт перехватчика предварительного получения. Стандартные входные данные для скрипта stdin — это строка, содержащая строку для каждой обновляемой ссылки. Каждая строка содержит старое имя объекта для ссылки, новое имя объекта для ссылки и полное имя ссылки.

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

Эта строка представляет следующие аргументы.

Дополнительные сведения о процессе git-receive-pack см. в разделе git-receive-pack в документации Git. Дополнительные сведения о ссылках см. в разделе Ссылки Git в Pro Git.

Выходные данные (stdout)

Стандартные выходные данные для скрипта stdoutпередаются обратно в клиент. Все инструкции echo будут видны пользователю в командной строке или пользовательском интерфейсе.

Состояние выхода

Состояние выхода скрипта предварительного получения определяет, будет ли принята отправка.

Переменные среды

Помимо стандартных входных данных для скрипта перехватчика предварительного получения stdin GitHub Enterprise Server делает следующие переменные доступными в среде Bash для выполнения вашего скрипта. Дополнительные сведения о stdin для скрипта перехватчика предварительного получения см. в разделе Входные данные (stdin).

Для скрипта перехватчика предварительного получения доступны разные переменные, в зависимости от того, что запускает скрипт.

• Доступные всегда
• Доступные для отправок из веб-интерфейса или API
• Доступные для слияний запросов на вытягивание
• Доступные для отправок с использованием проверки подлинности SSH

Доступна всегда

Следующие переменные всегда доступны в среде перехватчика предварительного получения.

$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

Доступные для отправок из веб-интерфейса или API

Переменная $GITHUB_VIA доступна в среде перехватчика предварительного получения, когда обновление ссылки, активирующее перехватчик, происходит через веб-интерфейс или API для GitHub Enterprise Server. Значение описывает действие, которое обновило ссылку.

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

Доступные для слияний запросов на вытягивание

Следующие переменные доступны в среде перехватчика предварительного получения, когда отправка, которая активирует перехватчик, является отправкой вследствие слияния запроса на вытягивание.

$GITHUB_PULL_REQUEST_AUTHOR_LOGIN

$GITHUB_PULL_REQUEST_HEAD

$GITHUB_PULL_REQUEST_BASE

Доступные для отправок с использованием проверки подлинности SSH

$GITHUB_PUBLIC_KEY_FINGERPRINT

Задание разрешений и отправка перехватчика предварительного получения в GitHub Enterprise Server

Скрипт перехватчика предварительного получения содержится в репозитории в экземпляр GitHub Enterprise Server. Администратор сайта должен учитывать разрешения репозитория и обеспечить, чтобы доступ имелся только у соответствующих пользователей.

Рекомендуется объединить перехватчики в один репозиторий. Если консолидированный репозиторий перехватчиков является общедоступным, можно использовать README.md для объяснения применения политик. Кроме того, вклады можно принимать с помощью запросов на вытягивание. Однако перехватчики предварительного получения можно добавлять только из ветви по умолчанию. Для рабочего процесса тестирования следует использовать вилки репозитория с конфигурацией.

1. Для пользователей Mac убедитесь, что скрипты имеют разрешения на выполнение:

   $ sudo chmod +x SCRIPT_FILE.sh

   Для пользователей Windows убедитесь, что скрипты имеют разрешения на выполнение:

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

2. Фиксация и отправка в назначенный репозиторий для перехватчиков предварительного получения в экземпляр GitHub Enterprise Server.

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

3. Создайте перехватчик предварительного получения в экземпляре GitHub Enterprise Server.

Локальное тестирование скриптов предварительного получения

Вы можете протестировать скрипт перехватчика предварительного получения локально, прежде чем создавать или обновлять его в экземпляр GitHub Enterprise Server. Один из способов — создать локальную среду Docker для работы в качестве удаленного репозитория, который может выполнять перехватчик предварительного получения.

1. Убедитесь, что Docker установлен в локальной среде.

2. Создайте файл с именем Dockerfile.dev и следующим содержимым:

   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. Создайте тестовый скрипт предварительного получения с именем always_reject.sh. В этом примере скрипт отклоняет все отправки, что полезно для блокировки репозитория:

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

4. Убедитесь, что скрипты always_reject.sh имеют разрешения на выполнение:

   $ chmod +x always_reject.sh

5. Из каталога, содержащего Dockerfile.dev, создайте образ:

   $ 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. Запустите контейнер данных, содержащий созданный ключ SSH:

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

7. Скопируйте тестовый перехватчик предварительного получения always_reject.sh в контейнер данных:

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

8. Запустите контейнер приложения, который запускает sshd и выполняет перехватчик. Запишите возвращенный идентификатор контейнера:

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

9. Скопируйте созданный ключ SSH из контейнера данных на локальный компьютер:

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

10. Измените удаленный репозиторий тестов и отправьте его в репозиторий test.git в контейнере Docker. В этом примере используется git@github.com:octocat/Hello-World.git, но вы можете использовать любой подходящий репозиторий. В этом примере предполагается, что локальный компьютер (127.0.0.1) является портом привязки 52311, но вы можете использовать другой IP-адрес, если Docker работает на удаленном компьютере.

    $ 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'

    Обратите внимание, что отправка была отклонена после выполнения перехватчика предварительного получения и повторения выходных данных скрипта.

Дополнительные материалы

• Настройка Git — пример политики, применяемой Git на веб-сайте Pro Git