Git 서버 후크

Tier: Free, Premium, Ultimate Offering: Self-Managed

Git 서버 후크(시스템 후크(system hooks) 또는 파일 후크(file hooks)와 혼동하지 마십시오)는 GitLab 서버에서 사용자 정의 로직을 실행합니다. 이를 사용하여 다음과 같은 Git 관련 작업을 수행할 수 있습니다.

  • 특정 커밋 정책 시행
  • 리포지터리 상태에 따라 작업 수행

Git 서버 후크는 pre-receive, post-receive, update 등을 사용합니다. Git 서버 측 후크를 사용합니다.

GitLab 관리자는 gitaly 명령을 사용하여 서버 후크를 구성할 수 있으며, 이를 통해 다음을 수행할 수도 있습니다.

  • Gitaly 서버 시작
  • 여러 하위 명령 제공
  • Gitaly gRPC API에 연결

gitaly 명령에 액세스할 수 없는 경우 서버 후크 대체로는 다음이 있습니다.

Geo는 서버 후크를 보조 노드로 복제하지 않습니다.

리포지터리에 서버 후크 설정

GitLab 15.11 이후
  • GitLab 15.11에서 소개됨, hooks set 명령어는 직접 파일 시스템 액세스를 대체합니다. 기존의 Git 후크는 hooks set 명령을 위해 이주할 필요가 없습니다.

전제 조건:

리포지터리에 서버 후크를 설정하려면:

  1. 사용자 정의 후크가 포함된 tarball을 생성합니다.
    1. 서버 후크가 예상대로 작동하도록 코드를 작성하세요. Git 서버 후크는 어떤 프로그래밍 언어로도 작성할 수 있습니다. 상단에 있는 shebang이 언어 유형을 반영하도록 합니다. 예를 들어, 스크립트가 루비로 되어 있다면 shebang는 아마도 #!/usr/bin/env ruby일 것입니다.

      • 단일 서버 후크를 생성하려면 후크 유형과 일치하는 이름으로 파일을 만듭니다. 예를 들어, pre-receive 서버 후크의 경우 파일 이름은 확장자 없이 pre-receive여야 합니다.
      • 여러 서버 후크를 만들려면 후크 유형과 일치하는 디렉터리를 만듭니다. 예를 들어, pre-receive 서버 후크의 경우 디렉터리 이름은 pre-receive.d여야 합니다. 해당 디렉터리에 후크 파일을 넣습니다.
    2. 서버 후크 파일이 실행 가능하도록 하고 백업 파일 패턴(*~)과 일치하지 않도록 합니다. 서버 후크는 tarball의 루트에 있는 custom_hooks 디렉터리에 있어야 합니다.
    3. tar 명령을 사용하여 사용자 정의 후크 아카이브를 만듭니다. 예를 들어, tar -cf custom_hooks.tar custom_hooks입니다.
  2. 필요한 옵션과 함께 hooks set 하위 명령어를 실행하여 리포지터리의 Git 후크를 설정합니다. 예를 들어, cat custom_hooks.tar | sudo /opt/gitlab/embedded/bin/gitaly hooks set --storage <storage> --repository <relative path> --config <config path>입니다.

    • 노드에 연결하려면 노드에 유효한 Gitaly 구성 파일의 경로가 필요하며 이는 --config 플래그로 제공되어야 합니다.
    • 사용자 지정 후크 tarball은 stdin을 통해 전달되어야 합니다. 예를 들어, cat custom_hooks.tar | sudo /opt/gitlab/embedded/bin/gitaly hooks set --storage <storage> --repository <relative path> --config <config path>입니다.
  3. Gitaly 클러스터를 사용 중인 경우 모든 Gitaly 노드에서 hooks set 하위 명령을 실행해야 합니다. 자세한 내용은 Gitaly 클러스터의 서버 후크를 참조하세요.

서버 후크 코드를 올바르게 구현한 경우, 다음으로 Git 후크가 트리거될 때 실행되어야 합니다.

GitLab 15.10 이하

리포지터리에 서버 후크를 생성하려면:

  1. 사이드바의 왼쪽 하단에서 관리 영역을 선택합니다.
  2. 개요 > 프로젝트로 이동하여 서버 후크를 추가하려는 프로젝트를 선택합니다.
  3. 나타나는 페이지에서 상대 경로 값을 찾습니다. 이 경로에 서버 후크를 위치시켜야 합니다.
    • 해시 저장를 사용 중이라면, 상대 경로 해석에 대한 정보는 해시 저장 경로 번역를 참조하세요.
    • 해시 저장를 사용 중이지 않으면:
      • 리눅스 패키지 설치의 경우 경로는 일반적으로 /var/opt/gitlab/git-data/repositories/<group>/<project>.git입니다.
      • 자체 컴파일 설치의 경우 경로는 일반적으로 /home/git/repositories/<group>/<project>.git입니다.
  4. 파일 시스템에서 올바른 위치에 custom_hooks라는 새 디렉터리를 만듭니다.
  5. custom_hooks 디렉터리에서:
    • 단일 서버 후크를 생성하려면 후크 유형과 일치하는 이름으로 파일을 만듭니다. 예를 들어, pre-receive 서버 후크의 경우 파일 이름은 확장자 없이 pre-receive여야 합니다.
    • 여러 서버 후크를 만들려면 후크 유형과 일치하는 디렉터리를 만듭니다. 예를 들어, pre-receive 서버 후크의 경우 디렉터리 이름은 pre-receive.d여야 합니다. 해당 디렉터리에 후크 파일을 넣습니다.
  6. 서버 후크 파일을 실행 가능하게 만들고 Git 사용자의 소유인지 확인하세요.
  7. 사용자 정의 후크가 예상대로 작동하도록 코드를 작성하세요. Git 서버 후크는 어떤 프로그래밍 언어로도 작성할 수 있습니다. 상단에 있는 shebang이 언어 유형을 반영하도록 합니다. 예를 들어, 스크립트가 루비로 되어 있다면 shebang는 아마도 #!/usr/bin/env ruby일 것입니다.
  8. 후크 파일이 백업 파일 패턴(*~)과 일치하지 않도록 확인하세요.
  9. Gitaly 클러스터를 사용 중이라면 모든 Gitaly 노드에서 이 프로세스를 반복해야 합니다. 자세한 내용은 Gitaly 클러스터의 서버 후크를 참조하세요.

서버 후크 코드를 올바르게 구현한 경우, 다음으로 Git 후크가 트리거될 때 실행되어야 합니다.

Gitaly 클러스터에서의 서버 후크

Gitaly 클러스터를 사용하는 경우, 개별 리포지터리는 Praefect에서 여러 Gitaly 리포지터리에 복제될 수 있습니다. 따라서 후크 스크립트를 해당 리포지터리의 모든 Gitaly 노드에 복사해야 합니다. 이를 위해 해당 버전의 사용자 정의 리포지터리 후크 설정 단계를 따라야 합니다.

스크립트를 복사해야 할 위치는 리포지터리가 저장되는 위치에 따라 다릅니다.

모든 리포지터리에 대한 글로벌 서버 후크 생성하기

모든 리포지터리에 적용되는 Git 후크를 만들려면 글로벌 서버 후크를 설정하세요. 글로벌 서버 후크는 또한 다음에도 적용됩니다:

  • 프로젝트 및 그룹 위키 리포지터리. 그들의 저장 디렉터리 이름은 <id>.wiki.git의 형식입니다.
  • 프로젝트 아래의 디자인 관리 리포지터리. 그들의 저장 디렉터리 이름은 <id>.design.git의 형식입니다.

서버 후크 디렉터리 선택하기

글로벌 서버 후크를 생성하기 전에 그것을 위한 디렉터리를 선택해야 합니다.

Linux 패키지 설치의 경우, 디렉터리는 gitlab.rbgitaly['configuration'][:hooks][:custom_hooks_dir]에서 설정됩니다. 다음 중 하나를 선택할 수 있습니다:

  • /var/opt/gitlab/gitaly/custom_hooks 디렉터리를 기본 제안으로 사용하려면 주석 처리를 해제하세요.
  • 나만의 설정을 추가하세요.

자체 컴파일된 설치의 경우:

  • 디렉터리는 [hooks] 섹션 아래의 gitaly/config.toml에 설정됩니다. 그러나, gitaly/config.toml의 값이 비어 있거나 존재하지 않으면, GitLab은 gitlab-shell/config.ymlcustom_hooks_dir 값을 존준합니다.
  • 기본 디렉터리는 /home/git/gitlab-shell/hooks입니다.

글로벌 서버 후크 생성하기

모든 리포지터리에 대한 글로벌 서버 후크를 만들려면 다음을 수행하세요:

  1. GitLab 서버에 가서 구성된 글로벌 서버 후크 디렉터리로 이동하세요.
  2. 구성된 글로벌 서버 후크 디렉터리에서 후크 타입에 맞는 디렉터리를 만드세요. 예를 들어 pre-receive 서버 후크의 경우, 디렉터리 이름은 pre-receive.d여야 합니다.
  3. 이 새로운 디렉터리 안에 서버 후크를 추가하세요. Git 서버 후크는 모든 프로그래밍 언어로 작성할 수 있습니다. 맨 위에 shebang가 해당 언어 유형을 반영하도록 하세요. 예를 들어, 스크립트가 루비로 되어 있다면, shebang는 아마도 #!/usr/bin/env ruby일 것입니다.
  4. 후크 파일을 실행 가능하도록 만들고, Git 사용자가 소유하도록 하며, 백업 파일 패턴(*~)과 일치하지 않도록 확인하세요.

서버 후크 코드가 올바르게 구현된 경우, Git 후크가 다음으로 트리거될 때 실행되어야 합니다. 후크는 후크 유형의 서브디렉터리 내의 파일 이름별로 알파벳순으로 실행됩니다.

리포지터리에 대한 서버 후크 제거하기

GitLab 15.11 및 이후
  • GitLab 15.11에서 도입hooks set 명령은 직접 파일 시스템 액세스를 대체합니다.

전제조건:

서버 후크를 제거하려면 빈 tarball을 hook set에 전달하여 리포지터리에 후크가 없어야 함을 나타내세요. 예를 들어:

cat empty_hooks.tar | sudo /opt/gitlab/embedded/bin/gitaly hooks set --storage <storage> --repository <relative path> --config <config path>
GitLab 15.10 이전

서버 후크를 제거하려면:

  1. 디스크상의 리포지터리 위치로 이동하세요.
  2. custom_hooks 디렉터리 내의 서버 후크를 삭제하세요.

연쇄 서버 후크

GitLab은 연쇄로 서버 후크를 실행할 수 있습니다. GitLab은 다음 순서대로 서버 후크를 찾아 실행합니다:

  • 내장 GitLab 서버 후크. 이러한 서버 후크는 사용자에 의해 사용자 정의되지 않습니다.
  • <project>.git/custom_hooks/<hook_name>: 프로젝트별 후크. 이 위치는 하위 호환성 유지를 위해 유지됩니다.
  • <project>.git/custom_hooks/<hook_name>.d/*: 프로젝트별 후크의 위치입니다.
  • <custom_hooks_dir>/<hook_name>.d/*: 편집기 백업 파일을 제외한 모든 실행 가능한 글로벌 후크 파일의 위치입니다.

서버 후크 디렉터리 내에서 후크는:

  • 알파벳 순으로 실행됩니다.
  • 후크가 0이 아닌 값으로 종료될 때 실행이 중지됩니다.

서버 후크에서 사용 가능한 환경 변수

서버 후크에 모든 환경 변수를 전달할 수 있지만, 지원되는 환경 변수에만 의존해야 합니다.

다음 GitLab 환경 변수는 모든 서버 후크에서 지원됩니다:

환경 변수 설명
GL_ID 푸시를 시작한 사용자 또는 SSH 키의 GitLab 식별자. 예: user-2234 또는 key-4.
GL_PROJECT_PATH GitLab 프로젝트 경로.
GL_PROTOCOL 이 변경에 사용된 프로토콜. http (HTTP를 사용한 Git push), ssh (SSH를 사용한 Git push), 또는 web (기타 모든 작업) 중 하나입니다.
GL_REPOSITORY id가 프로젝트의 ID인 project-<id>입니다.
GL_USERNAME 푸시를 시작한 사용자의 GitLab 사용자 이름.

다음 Git 환경 변수는 pre-receivepost-receive 서버 후크에서 지원됩니다:

환경 변수 설명
GIT_ALTERNATE_OBJECT_DIRECTORIES 격리 환경 내의 대체 개체 디렉터리. Git receive-pack 설명 참조.
GIT_OBJECT_DIRECTORY 격리 환경 내의 GitLab 프로젝트 경로. Git receive-pack 설명 참조.
GIT_PUSH_OPTION_COUNT 푸시 옵션의 개수. Git pre-receive 설명 참조.
GIT_PUSH_OPTION_<i> i0에서 GIT_PUSH_OPTION_COUNT - 1까지인 푸시 옵션의 값. Git pre-receive 설명 참조.

사용자 정의 오류 메시지

커밋이 거부되거나 Git 후크에서 오류가 발생할 때 GitLab UI에 사용자 정의 오류 메시지가 표시되도록 할 수 있습니다. 사용자 정의 오류 메시지를 표시하려면 스크립트가:

  • 각 메시지를 스크립트의 stdout 또는 stderr로 보내야 합니다.
  • 각 메시지를 GL-HOOK-ERR:로 접두사를 붙여야 하며, 접두사 앞에 문자가 없어야 합니다.

예를 들어:

#!/bin/sh
echo "GL-HOOK-ERR: My custom error message.";
exit 1