GitLab Runner 설치 및 설정 가이드

1. GitLab Runner 개요

GitLab Runner는 GitLab의 CI/CD 기능을 사용해 코드 빌드, 테스트, 배포를 자동화할 수 있는 도구다. 다양한 실행 환경을 지원해 여러 작업을 병렬로 처리할 수 있으며, 프로젝트 단위나 공유 Runner로 설정할 수 있어 유연하게 사용 가능하다.

2. GitLab Runner 설치 방법

Windows에서 설치

1. 설치 파일 다운로드 및 권한 설정
   • 공식 사이트에서 gitlab-runner-windows-amd64.exe 파일을 다운로드하고, C:\GitLab-Runner 폴더에 저장 후 이름을 gitlab-runner.exe로 변경한다.
2. 명령 프롬프트 실행: cmd를 관리자 권한으로 실행하여 다음 명령어를 입력한다
   • > gitlab-runner.exe install
   • > gitlab-runner.exe start
   • 이 명령어는 GitLab Runner를 Windows 서비스로 등록하고 시스템 부팅 시 자동으로 시작하게 한다.
3. 자동 실행 확인
   • services.msc를 통해 Windows 서비스 관리자에서 GitLab Runner가 정상 실행 중인지 확인한다.

Linux에서 설치

1. 설치 스크립트 다운로드 및 실행
   • 다음 명령어로 GitLab Runner를 설치한다.
   • # sudo curl -L --output /usr/local/bin/gitlab-runner https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-amd64 
   • # sudo chmod +x /usr/local/bin/gitlab-runner
2. 서비스 등록 및 실행
   • Runner를 시스템 서비스로 등록하고 시작하도록 설정한다.
   • # sudo gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner
   • # sudo gitlab-runner start  
   • 활용 팁: systemctl enable gitlab-runner 명령을 추가로 실행해 시스템 부팅 시 자동으로 실행되도록 설정할 수 있다.
3. 상태 확인
   • "sudo gitlab-runner status" 명령어로 Runner 상태를 확인한다.

Docker로 설치

Docker 이미지를 사용하여 Runner를 격리된 환경에서 실행할 수 있다.

docker run -d --name gitlab-runner --restart always \ -v /srv/gitlab-runner/config:/etc/gitlab-runner \ -v /var/run/docker.sock:/var/run/docker.sock \ gitlab/gitlab-runner:latest

• -v 옵션으로 설정 파일을 외부에 저장하여 유지 관리하기 쉽도록 한다.
• /var/run/docker.sock을 연결하여 Runner가 Docker 명령어를 사용할 수 있게 한다.

활용 팁

• Docker 환경에서는 Runner가 각 파이프라인 작업을 격리된 컨테이너에서 실행하므로 테스트 환경을 쉽게 구성할 수 있다.

3. GitLab Runner 등록 및 실행

GitLab에서 Runner 등록

1. 토큰 확인
   • GitLab에서 프로젝트의 Settings > CI/CD > Runners로 이동해 Register an instance runner를 클릭하여 토큰을 복사한다.
2. Runner 등록 시작
   • Runner 설치 후 gitlab-runner register 명령어를 실행한다. 아래와 같은 정보를 입력한다.
     • GitLab URL: GitLab 서버 URL (예: https://gitlab.com)
     • 토큰: GitLab에서 복사한 Runner 토큰
     • 설명 및 태그: Runner를 구분할 수 있는 설명과 태그를 입력한다.
     • Executor 선택: Docker, Shell, SSH 등 실행 환경을 선택한다.
3. Executor 세부 설정
   • Docker Executor
     • Docker 컨테이너를 통해 각 빌드를 독립적으로 실행할 수 있다. 기본 Docker 이미지를 설정하고, 파이프라인에서 추가로 필요한 이미지를 .gitlab-ci.yml 파일에 정의할 수 있다.
   • Shell Executor
     • 로컬 셸 환경에서 빌드를 실행하며, 개발 환경과 동일한 파일 시스템 및 네트워크를 공유한다.
4. config.toml 파일 편집
   • GitLab Runner의 설정 파일(/etc/gitlab-runner/config.toml)에서 동시 작업 수(concurrent)나 캐시 설정을 지정할 수 있다.

4. .gitlab-ci.yml 작성 및 파이프라인 설정

.gitlab-ci.yml 파일을 작성하여 빌드, 테스트, 배포 단계를 정의할 수 있다. 다음은 기본 예제다.

stages:
  - build
  - test
  - deploy

build-job:
  stage: build
  script:
    - echo "Building the project..."
    - ./build.sh

test-job:
  stage: test
  script:
    - echo "Running tests..."
    - ./test.sh

deploy-job:
  stage: deploy
  script:
    - echo "Deploying the project..."
    - ./deploy.sh

• stages: 각 단계(build, test, deploy)를 순서대로 정의.
• script: 각 단계에서 실행할 명령어 목록.
• tags: Runner를 지정하려면 tags 필드를 사용하여 특정 Runner에서만 실행되도록 할 수 있다.

활용 팁

• variables 필드를 통해 파이프라인 실행 중 사용할 환경 변수를 정의할 수 있다.

5. GitLab Runner 관리 및 삭제

1. Runner 삭제
   • GitLab 설정의 Settings > CI/CD > Runners에서 불필요한 Runner의 Unregister 버튼을 클릭해 삭제한다.
2. 명령어로 Runner 완전 삭제
   • 시스템에서 완전히 삭제하려면 다음 명령어를 실행한다
   • # sudo gitlab-runner uninstall
3. 재설치 및 재등록
   • 재설치가 필요한 경우, 위의 삭제 절차를 완료한 후 다시 설치하고 gitlab-runner register 명령어로 등록한다.

6. 자주 발생하는 문제 해결

• "Runner has not been connected yet" 오류
  • GitLab에서 Runner가 연결되지 않았음을 나타내는 오류다. 설정 파일의 URL과 토큰이 정확히 입력되었는지 확인하고, GitLab 웹 인터페이스에서 Runner가 활성화 상태인지 점검한다.
• Docker Executor 권한 문제
  • Docker 컨테이너 내에서 권한 문제가 발생할 때는 /var/run/docker.sock을 컨테이너에 연결하여 호스트 Docker 권한을 사용할 수 있게 설정하면 된다.
• 빌드 캐시 문제
  • 빌드 캐시가 제대로 설정되지 않을 경우 빌드 시간이 길어지거나 오류가 발생할 수 있다. config.toml 파일에서 cache 항목을 확인하고 빌드 시 필요한 경로가 캐싱되는지 점검한다.

추가 팁

• Runner 작업 로그
  • 작업이 실패할 경우 logs 디렉터리에서 로그 파일을 확인해 문제의 원인을 파악할 수 있다.
• 테스트용 Runner 설정
  • 실험적인 설정이나 새로운 파이프라인을 테스트할 때는 별도의 테스트용 Runner를 만들어 사용해볼 수 있다.

---

참조URL

https://assu10.github.io/dev/2020/10/08/gitlab-runner-1/
https://docs.gitlab.com/runner/register/index.html
https://microcode.tistory.com/4?category=779702
https://nakanara.tistory.com/240
https://nakanara.tistory.com/256
https://not-to-be-reset.tistory.com/326
https://stackoverflow.com/questions/67820925/gitlab-ci-cd-new-runner-has-not-been-connected-yet