Gitea - 경량 Git 저장소 삽질 후기

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 환경에서 다른 서비스와 함께 구동하기에 적합

  2. 빠른 설치와 설정

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

  3. GitHub Actions 호환성

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

  4. Self-hosted 환경에 최적화

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

  5. 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 명령어 (터미널 사용 시)

1
2
3
4
5
6
7
8
9
10
11
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 파일에 다음 설정이 있는지 확인하세요.
없다면 추가해줘야 합니다.
추가 후 재시작하세요.

1
2
3
[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 명령어 (권장)

1
2
3
4
5
6
7
8
9
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
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# 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: 등록 확인

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

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

1
2
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 오류가 발생했습니다.

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

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

오류 메시지:

1
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 수정

1
2
3
4
5
6
7
8
9
10
11
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)” → 정상 등록

  2. Runner 로그 확인

    1
    2
    3
    4
    5
    6
    7
    8
    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"

  3. .runner 파일 확인

    1
    2
    3
    4
    docker exec gitea-runner ls -la /data/

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

3.5 네트워크 연결 문제

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

해결 방법:

  • Docker 네트워크를 별도로 생성하여 Gitea와 Runner를 같은 네트워크에 배치
  • 또는 --network host 사용 (간단하지만 보안상 주의 필요)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 네트워크 생성 방법
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 (패키지 다운로드)
  4. 생성된 토큰을 REGISTRY_TOKEN Secret으로 등록

5. 워크플로우 예시

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
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. 참고 자료

8. 마치며

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

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

#git, gitea, gitea-runner, ci/cd, docker
Gitea - 경량 Git 저장소 삽질 후기
https://kimjj81.github.io/2025/11/20/Gitea/
Author
김 정진
Posted on
November 20, 2025
Licensed under