사용자 지정 파일 훅을 사용하면 GitLab 소스 코드를 수정하지 않고 사용자 지정 통합을 추가할 수 있습니다.

파일 훅은 이벤트가 발생할 때마다 실행됩니다. 파일 훅 코드에서 이벤트나 프로젝트를 필터링할 수 있으며, 필요한 만큼 파일 훅을 만들 수 있습니다. 각 파일 훅은 이벤트가 발생하면 GitLab 이 비동기로 트리거합니다. 이벤트 목록은 시스템 훅 및 웹훅 문서를 참고합니다.

직접 파일 훅을 작성해 유지 관리하는 대신, GitLab 소스 코드를 직접 수정하고 업스트림에 기여할 수도 있습니다. 이 방식을 사용하면 버전이 바뀌어도 기능이 유지되고 테스트로 검증됩니다.

사용자 지정 파일 훅 설정#

파일 훅은 file_hooks 디렉터리에 있어야 합니다. 하위 디렉터리는 무시됩니다. 예시는 file_hooks 아래의 example 디렉터리에서 확인할 수 있습니다.

사용자 지정 훅을 설정하려면 다음을 수행합니다.

1. Sidekiq 구성 요소를 실행하는 GitLab 서버에서 플러그인 디렉터리를 찾습니다. 직접 컴파일한 설치에서는 경로가 보통 /home/git/gitlab/file_hooks/ 입니다. Linux 패키지 설치에서는 경로가 보통 /opt/gitlab/embedded/service/gitlab-rails/file_hooks 입니다.

   서버가 여러 대인 구성에서는 훅 파일이 각 GitLab 애플리케이션(Rails) 서버와 Sidekiq 서버에 모두 있어야 합니다.

2. file_hooks 디렉터리 안에 공백이나 특수 문자가 없는 이름으로 파일을 만듭니다.

3. 훅 파일을 실행 가능하게 만들고 소유자가 Git 사용자인지 확인합니다.

4. 파일 훅이 의도한 대로 동작하도록 코드를 작성합니다. 어떤 언어로도 작성할 수 있으며, 파일 맨 위의 'shebang' 이 해당 언어를 올바르게 나타내는지 확인합니다. 예를 들어 스크립트가 Ruby로 작성되었다면 shebang은 대체로 #!/usr/bin/env ruby 입니다.

5. 파일 훅에 전달되는 데이터는 STDIN에 JSON 형식으로 제공됩니다. 이는 시스템 훅과 완전히 동일합니다.

파일 훅 코드가 올바르게 구현되었다면 훅은 상황에 맞게 실행됩니다. 파일 훅 파일 목록은 이벤트마다 갱신됩니다. 새 파일 훅을 적용하기 위해 GitLab을 재시작할 필요는 없습니다.

파일 훅이 0 이 아닌 종료 코드로 실행되거나 실행에 실패하면 다음 위치에 메시지가 기록됩니다.

• 직접 컴파일한 설치는 log/file_hook.log.
• Linux 패키지 설치는 gitlab-rails/file_hook.log.

이 파일은 파일 훅이 0 이 아닌 코드로 종료된 경우에만 생성됩니다. 파일 훅이 실행되면 시작된 FileHookWorker 마다 Sidekiq 로그 gitlab/sidekiq/current에 항목이 추가됩니다. 이 항목에는 이벤트와 실행된 스크립트의 세부 정보가 담깁니다.

파일 훅 예시#

이 예시는 project_create 이벤트에만 반응하며, GitLab 인스턴스가 관리자에게 새 프로젝트가 생성되었음을 알립니다.

#!/opt/gitlab/embedded/bin/ruby
# By using the embedded ruby version we eliminate the possibility that our chosen language
# would be unavailable from
require 'json'
require 'mail'

# The incoming variables are in JSON format so we need to parse it first.
ARGS = JSON.parse($stdin.read)

# We only want to trigger this file hook on the event project_create
return unless ARGS['event_name'] == 'project_create'

# We will inform our admins of our gitlab instance that a new project is created
Mail.deliver do
  from    'info@gitlab_instance.com'
  to      'admin@gitlab_instance.com'
  subject "new project " + ARGS['name']
  body    ARGS['owner_name'] + 'created project ' + ARGS['name']
end

검증 예시#

직접 파일 훅을 작성하는 일은 까다로울 수 있으며, 시스템을 변경하지 않고 확인할 수 있다면 더 수월합니다. 이를 위해 Rake 태스크가 제공되므로, 운영 환경에 적용하기 전에 스테이징 환경에서 파일 훅을 테스트할 수 있습니다. 이 Rake 태스크는 샘플 데이터를 사용해 각 파일 훅을 실행합니다. 그 출력만으로도 시스템이 파일 훅을 인식하는지, 그리고 오류 없이 실행되었는지 판단할 수 있습니다.

# Omnibus installations
sudo gitlab-rake file_hooks:validate

# Installations from source
cd /home/git/gitlab
bundle exec rake file_hooks:validate RAILS_ENV=production

출력 예시입니다.

Validating file hooks from /file_hooks directory
* /home/git/gitlab/file_hooks/save_to_file.clj succeed (zero exit code)
* /home/git/gitlab/file_hooks/save_to_file.rb failure (non-zero exit code)

관련 주제#

• 서버 훅
• 시스템 훅