Gitea Actions Runner 설정 경험담

1. 소개

Gitea와 Gitea Actions Runner란?

Gitea는 Go 언어로 작성된 경량 Git 서비스로, GitHub와 유사한 기능을 제공하는 오픈소스 프로젝트입니다. Gitea Actions는 GitHub Actions와 호환되는 CI/CD 기능을 제공하며, act_runner를 통해 워크플로우를 실행할 수 있습니다.

왜 GitLab이 아닌 Gitea를 선택했는가?

프로젝트 초기에 GitLab과 Gitea 중에서 고민했지만, 최종적으로 Gitea를 선택한 이유는 다음과 같습니다:

1. 가벼운 리소스 사용량

• GitLab은 최소 4GB RAM이 필요하지만, Gitea는 512MB 정도면 충분히 실행 가능
• Unraid NAS 환경에서 다른 서비스와 함께 구동하기에 적합

1. 빠른 설치와 설정

• 단일 바이너리 또는 Docker 컨테이너로 간단히 설치 가능
• 복잡한 설정 없이 몇 분 만에 Git 서버 구축 가능

1. GitHub Actions 호환성

• GitHub Actions와 동일한 워크플로우 문법 사용 가능
• 기존 GitHub Actions 경험을 그대로 활용 가능

1. Self-hosted 환경에 최적화

• Tailscale VPN과 결합하여 안전한 사설 Git 서버 구축
• 민감한 코드와 데이터를 외부에 노출하지 않고 관리 가능

1. Container Registry 내장

• Docker 이미지를 별도 레지스트리 없이 Gitea에서 직접 관리
• CI/CD 파이프라인과 통합이 용이

2. 설치

환경

• 호스트 OS: Unraid 7.2.0
• Gitea: Docker 컨테이너 (gitea/gitea:latest)
• Runner: Docker 컨테이너 (gitea/act_runner:latest)
• 네트워크: Tailscale VPN

2.1 Gitea 설치 (Unraid Docker)

Unraid의 Community Applications에서 Gitea를 검색하여 설치하거나, 수동으로 설정할 수 있습니다.

Docker 명령어 (터미널 사용 시)

docker run -d \
  --name=gitea \
  --restart=always \
  -p 3000:3000 \
  -p 222:22 \
  -v /mnt/user/appdata/gitea:/data \
  -e USER_UID=99 \
  -e USER_GID=100 \
  -e GITEA__actions__ENABLED=true \
  -e GITEA__actions__DEFAULT_ACTIONS_URL=https://github.com \
  gitea/gitea:latest

중요: Actions를 사용하려면 환경 변수 설정이 필수입니다:

문서 : 도커로 시작

문서만 보면 runner는 기본으로 시작되어야 하는데, unraid 에서 설치한 경우 설정이 없었습니다. 설치 후 /mnt/user/appdata/gitea/gitea/conf/app.ini 파일에 다음 설정이 있는지 확인하세요. 없다면 추가해줘야 합니다. 추가 후 재시작하세요.

[actions]
ENABLED = true
DEFAULT_ACTIONS_URL = https://github.com

2.2 Gitea 초기 설정

1. 웹 브라우저에서 http://<서버IP>:3000 접속
2. 초기 설정 화면에서 데이터베이스 및 관리자 계정 생성
3. Container Registry 활성화 (Site Administration → Configuration → Packages)

2.3 Gitea Actions Runner 설치

Step 1: Registration Token 생성

Gitea 웹 UI에서:

• Site Administration → Actions → Runners 메뉴 이동
• "Create new Runner" 버튼 클릭
• 표시되는 Registration Token을 복사

또는 저장소별로 등록하려면:

• Repository Settings → Actions → Runners에서 토큰 생성

그러나 여러개의 토큰을 이용해서 하는건 못해봤습니다. 아마 gitea-runner 를 여러개 띄운다면 각자 저장소에 따른 토큰을 사용해야 할 것으로 예상됩니다.

Step 2: Runner 컨테이너 실행

방법 A: Docker 명령어 (권장)

docker run -d \
  --name gitea-runner \
  --restart always \
  --network host \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /mnt/user/appdata/gitea-runner:/data \
  -e GITEA_INSTANCE_URL=주소:포트 \
  -e GITEA_RUNNER_REGISTRATION_TOKEN=여기에_토큰_붙여넣기 \
  gitea/act_runner:latest

방법 B: 수동 등록 (문제 발생 시)

# 1. 컨테이너만 먼저 실행
docker run -d \
  --name gitea-runner \
  --restart always \
  --network host \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /mnt/user/appdata/gitea-runner:/data \
  gitea/act_runner:latest sleep infinity

# 2. 대화형으로 등록
docker exec -it gitea-runner ./act_runner register

# 프롬프트에 따라 입력:
# - Gitea instance URL: http://주소:포트
# - Registration token: [복사한 토큰]
# - Runner name: [원하는 이름 또는 엔터]
# - Runner labels: [엔터 - 기본값 사용]

# 3. 등록 완료 후 재시작
docker restart gitea-runner

Step 3: 등록 확인

# 로그에서 등록 성공 메시지 확인
docker logs -f gitea-runner

성공적으로 등록되면 다음 메시지가 표시됩니다:

level=info msg="Runner registered successfully"
level=info msg="Listening for jobs"

Gitea 웹 UI의 Runners 페이지에서도 Runner가 "Idle" 상태로 표시됩니다.

3. 헤맸던 부분 요약

3.1 URL 끝 공백 문제

문제: Registration Token을 복사할 때 의도치 않게 URL 끝에 공백이 포함되어 401 Unauthorized 오류가 발생했습니다.

# ❌ 잘못된 예 (끝에 공백 포함)
"GITEA_INSTANCE_URL=http://192.168.219.101:3000 "

# ✅ 올바른 예
"GITEA_INSTANCE_URL=http://192.168.219.101:3000"

오류 메시지:

level=error msg="Cannot ping the Gitea instance server" error="unauthenticated: 401 Unauthorized"

해결 방법:

• 환경 변수 값 복사 시 앞뒤 공백 제거 확인
• 직접 타이핑하여 입력하거나, 텍스트 에디터에서 trim 후 복사

3.2 Actions 기능 미활성화

문제: Gitea 설치 시 Actions 기능이 기본적으로 비활성화되어 있어 Runner 등록이 불가능했습니다.

증상:

• Runner가 등록을 시도하지만 계속 401 Unauthorized 반환
• Site Administration에 Actions 메뉴가 보이지 않음

해결 방법:

방법 1: app.ini 수정

docker exec -it gitea bash
vi /data/gitea/conf/app.ini

# 다음 섹션 추가
[actions]
ENABLED = true
DEFAULT_ACTIONS_URL = https://github.com

# 저장 후 Gitea 재시작
exit
docker restart gitea

3.4 Runner 미등록 상태 확인 방법

Runner가 정상적으로 등록되었는지 확인하는 방법:

1. Gitea 웹 UI 확인

• Site Administration → Actions → Runners
• "Runners Management (Total: 0)" → 등록 안 됨
• "Runners Management (Total: 1)" → 정상 등록

1. Runner 로그 확인

   docker logs gitea-runner

   # 성공 시:
   # level=info msg="Runner registered successfully"
   # level=info msg="Listening for jobs"

   # 실패 시:
   # level=error msg="Cannot ping the Gitea instance server"

1. .runner 파일 확인

   docker exec gitea-runner ls -la /data/

   # .runner 파일이 존재하면 등록 완료
   # .runner 파일이 없으면 등록 실패

3.5 네트워크 연결 문제

문제: --network host 모드를 사용하지 않으면 Runner가 Gitea에 접근하지 못했습니다.

해결 방법:

• Docker 네트워크를 별도로 생성하여 Gitea와 Runner를 같은 네트워크에 배치
• 또는 --network host 사용 (간단하지만 보안상 주의 필요)

# 네트워크 생성 방법
docker network create gitea-network

# Gitea에 네트워크 연결
docker run -d \
  --name gitea \
  --network gitea-network \
  gitea/gitea:latest

# Runner에도 동일한 네트워크 사용
docker run -d \
  --name gitea-runner \
  --network gitea-network \
  -e GITEA_INSTANCE_URL=http://gitea:3000 \
  gitea/act_runner:latest

4. Repository Secrets 설정

CI/CD 워크플로우에서 민감한 정보를 사용하려면 Secrets 등록이 필요합니다.

Secrets 등록 방법

1. Repository → Settings → Secrets 이동
2. Add Secret 클릭
3. Secret 추가:

주의: Secret 이름은 GITEA_나 GITHUB_로 시작하면 안 됩니다 (예약어).

예시:

• REGISTRY_TOKEN: Container Registry 접근용 Personal Access Token

Personal Access Token 생성

Container Registry에 push하려면 PAT가 필요합니다:

1. User Settings → Applications → Manage Access Tokens
2. Generate New Token
3. 권한 선택:

• write:package (패키지 업로드)
• read:package (패키지 다운로드)

1. 생성된 토큰을 REGISTRY_TOKEN Secret으로 등록

5. 워크플로우 예시

프로젝트에서 사용 중인 CI/CD 워크플로우 예시:

name: CI/CD Pipeline

on:
  push:
    branches:
      - main
      - develop

jobs:
  build-and-push:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Login to Gitea Registry
        uses: docker/login-action@v3
        with:
          registry: 내서버주소:3000
          username: ${{ gitea.actor }}
          password: ${{ secrets.REGISTRY_TOKEN }}

      - name: Build and push Docker image
        uses: docker/build-push-action@v5
        with:
          context: ./backend
          push: true
          tags: |
            내서버주소:3000/myorg/myapp:latest
            내서버주소:3000/myorg/myapp:${{ github.sha }}

6. 트러블슈팅 체크리스트

Runner 등록이 안 될 때 순서대로 확인:

• [ ] Gitea에서 Actions가 활성화되어 있는가? (app.ini의 [actions] 섹션 확인)
• [ ] Registration Token이 정확한가? (공백, 특수문자 확인)
• [ ] 환경 변수에 따옴표가 이중으로 들어가지 않았는가?
• [ ] URL 끝에 불필요한 공백이 없는가?
• [ ] Gitea와 Runner가 같은 네트워크에 있는가?
• [ ] Gitea 컨테이너가 정상 실행 중인가? (docker ps)
• [ ] .runner 파일이 생성되었는가? (docker exec gitea-runner ls /data/)

7. 참고 자료

• Gitea 공식 문서
• Gitea Actions 가이드
• act_runner GitHub
• GitHub Actions 문법

8. 마치며

처음에는 환경 변수 설정과 네트워크 문제로 고생했지만, 근본 원인을 파악한 후에는 Gitea Actions를 안정적으로 사용할 수 있게 되었습니다.

특히 Self-hosted 환경에서 GitLab보다 훨씬 적은 리소스로 GitHub Actions와 유사한 CI/CD 환경을 구축할 수 있다는 점이 Gitea의 가장 큰 장점입니다. Tailscale과 결합하면 어디서든 안전하게 접근할 수 있는 사설 Git 서버를 운영할 수 있습니다.