🔨

Forgejo と Actions Runner を構築する

に公開
forgejo
tech

概要

Docker Compose を用いて Forgejo（Git サーバ）と Actions Runner の環境を構築します。Forgejo 本体は PostgreSQL をバックエンドに、Runner は Docker-in-Docker を利用した構成です。

環境

  • Proxmox VE 8.4 (ホスト)
  • Forgejo: Debian 12 Bookworm (LXC コンテナ, amd64)
  • Actions runners: Ubuntu 24.04 LTS (VM, amd64)

Forgejo

Forgejo のインストール

公式ドキュメント Installation with Docker を参考に Forgejo をインストールします。

  1. Docker をインストールします。

  2. Forgejo の compose.yml を作成します。

    networks:
  forgejo:
    external: false

services:
  server:
    image: codeberg.org/forgejo/forgejo:13
    container_name: forgejo
    environment:
      - USER_UID=1000
      - USER_GID=1000
      - FORGEJO__database__DB_TYPE=postgres
      - FORGEJO__database__HOST=db:5432
      - FORGEJO__database__NAME=forgejo
      - FORGEJO__database__USER=forgejo
      - FORGEJO__database__PASSWD=${FORGEJO_DB_PASSWORD}
    restart: always
    networks:
      - forgejo
    volumes:
      - ./forgejo:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "222:22"
    depends_on:
      - db

  db:
    image: postgres:14
    restart: always
    environment:
      - POSTGRES_USER=forgejo
      - POSTGRES_PASSWORD=${FORGEJO_DB_PASSWORD}
      - POSTGRES_DB=forgejo
    networks:
      - forgejo
    volumes:
      - ./postgres:/var/lib/postgresql/data

  3. Forgejo の .env を作成し DB のパスワードを指定します（Compose から参照されます）。

    FORGEJO_DB_PASSWORD=CHANGE_ME_TO_STRONG_PASSWORD

  4. Forgejo を起動します。

    docker compose up -d

  5. Forgejo の Web 画面 http://myserver:3000/ を開き初期設定をおこないます。

  6. 初期設定が終わったら Forgejo のトップ画面が表示されます。

Actions runners

Forgejo runner

Forgejo runner のインストール

公式ドキュメント OCI image installation を参考に Runner をインストールします。

  1. Docker をインストールします。

  2. 非 root 権限を持つ data ディレクトリを準備します（この例では 1001:1001 を選択します）。Runner は ./data に書き込みます。

    mkdir -p data/.cache
chown -R 1001:1001 data
chmod 775 data/.cache
chmod g+s data/.cache

  3. Runner の compose.yml を作成します。

    services:
  docker-in-docker:
    image: docker:dind
    container_name: "docker_dind"
    privileged: "true"
    command: ["dockerd", "-H", "tcp://0.0.0.0:2375", "--tls=false"]
    restart: "unless-stopped"

  runner:
    image: "data.forgejo.org/forgejo/runner:11"
    links:
      - docker-in-docker
    depends_on:
      docker-in-docker:
        condition: service_started
    container_name: "runner"
    environment:
      DOCKER_HOST: tcp://docker-in-docker:2375
    # User without root privileges, but with access to `./data`.
    user: 1001:1001
    volumes:
      - ./data:/data
    restart: "unless-stopped"

    command: '/bin/sh -c "while : ; do sleep 1 ; done ;"'

Forgejo runner の登録

公式ドキュメント Standard registration を参考に Runner を登録します。

  1. Runner を起動します。

    docker compose up -d

  2. docker exec を実行してコンテナ内でコマンドを実行できるようにします。

    docker exec -it runner /bin/sh

  3. forgejo-runner register を実行して Runner を登録します。

    ~ $ forgejo-runner register
INFO Registering runner, arch=amd64, os=linux, version=v11.3.1.
WARN Runner in user-mode.
INFO Enter the Forgejo instance URL (for example, https://next.forgejo.org/):
http://myserver:3000/
INFO Enter the runner token:
mytoken
INFO Enter the runner name (if set empty, use hostname: 795eb6641436):
test
INFO Enter the runner labels, leave blank to use the default labels (comma-separated, for example, ubuntu-20.04:docker://node:20-bookworm,ubuntu-18.04:docker://node:20-bookworm):

INFO Registering runner, name=test, instance=myserver:3000/, labels=[docker:docker://data.forgejo.org/oci/node:20-bullseye].
DEBU Successfully pinged the Forgejo instance server
INFO Runner registered successfully.
    • Enter the Forgejo instance URL: Forgejo サーバーの URL を指定します。
    • Enter the runner token: Forgejo の Web 画面で 設定 > Actions > ランナー > 新しいランナーを作成 から token を取得します。
    • Enter the runner name: 任意の Runner 名を指定します。
    • Enter the runner labels, leave blank to use the default labels: ジョブの runs-on と一致させるための識別子です。空欄のまま登録すると既定ラベル docker が付与されます。

  4. Runner のコンテナから抜けます。

    exit

  5. Runner を停止します。

    docker compose down

  6. Runner の compose.yml を修正します（登録完了後は daemon として常駐させます）。

    command: '/bin/sh -c "sleep 5; forgejo-runner daemon"'

  7. Runner を起動します。

    docker compose up -d

  8. Forgejo の Web 画面で 設定 > Actions > ランナー から Runner が登録されていることを確認します。

Workflow の追加

リポジトリに 最小 workflow を追加して動作確認します。

  1. .forgejo/workflows/ci.yml を作成します。

    on: [push]
jobs:
  test:
    runs-on: docker
    steps:
      - run: echo All good!

  2. .forgejo/workflows/ci.yml を commit & push します。

  3. Forgejo の Web 画面で Actions からワークフローの job test が成功していることを確認します。

Act runner

Windows ホスト上でワークフローを実行するための軽量ランナー（ホスト実行）を追加します。

Act runner のダウンロード

  1. act_runner からインストールするバージョンを選択します。

  2. 実行環境に合わせたファイルをダウンロードします。今回はバージョン 0.2.13 の act_runner-0.2.13-windows-amd64.exe をダウンロードします。

    act_runner の exe はコマンドライン(コマンドプロンプト/PowerShell)で実行します。

    C:\Users\myuser\Downloads>act_runner-0.2.13-windows-amd64.exe --version
act_runner version v0.2.13

Act runner の登録

  1. exe を実行して Runner を登録します。

    C:\Users\myuser\Downloads>act_runner-0.2.13-windows-amd64.exe register
level=info msg="Registering runner, arch=amd64, os=windows, version=v0.2.13."
level=warning msg="Runner in user-mode."
level=info msg="Enter the Gitea instance URL (for example, https://gitea.com/):"
myserver
level=info msg="Enter the runner token:"
mytoken
level=info msg="Enter the runner name (if set empty, use hostname: MY-DESKTOP):\n"
windows
level=info msg="Enter the runner labels, leave blank to use the default labels (comma-separated, for example, ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest):"
windows
level=info msg="Registering runner, name=windows, instance=myserver, labels=[windows]."
level=debug msg="Successfully pinged the Gitea instance server"
level=info msg="Runner registered successfully."
    • Enter the Forgejo instance URL: Forgejo サーバーの URL を指定します。
    • Enter the runner token: Forgejo の Web 画面で 設定 > Actions > ランナー > 新しいランナーを作成 から token を取得します。
    • Enter the runner name: 任意の Runner 名を指定します。
    • Enter the runner labels, leave blank to use the default labels: ジョブの runs-on と一致させるための識別子です。

  2. 登録完了後は daemon として常駐させます。

    C:\Users\myuser\Downloads>act_runner-0.2.13-windows-amd64.exe daemon
time="2025-12-19T15:19:14+09:00" level=info msg="Starting runner daemon"
time="2025-12-19T15:19:14+09:00" level=info msg="labels updated to: [windows:host]"
time="2025-12-19T15:19:14+09:00" level=info msg="runner: windows, with version: v0.2.13, with labels: [windows], declare successfully"

  3. Forgejo の Web 画面で 設定 > Actions > ランナー から Runner が登録されていることを確認します。

Workflow の追加

リポジトリに 最小 workflow を追加して動作確認します。

  1. .forgejo/workflows/ci.yml を作成します（runs-on は登録時に指定したラベルに合わせます。以下の例では windows）。

    on: [push]
jobs:
  windows:
    runs-on: windows
    steps:
      - run: echo All good!

  2. .forgejo/workflows/ci.yml を commit & push します。

  3. Forgejo の Web 画面で Actions からワークフローの job windows が成功していることを確認します。

    act_runner が Windows の実行ポリシー（Execution Policy）でブロックされた場合は次のコマンドを実行して回避することができます。

    Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

Discussion