【ITニュース解説】Gitea + Action Runner on Localhost: Full Setup Guide for Developers

システム開発の現場では、コードに変更が加えられた際に、自動でテストを行ったり、新しいバージョンのソフトウェアを公開したりする仕組みが非常に重要になる。この一連の自動化されたプロセスをCI/CD（継続的インテグレーション・継続的デリバリー）と呼ぶ。通常、多くの開発者はGitHub ActionsやGitLab CIといったクラウドサービスを利用してCI/CDパイプラインを構築するが、時には自分のパソコン、つまりローカル環境でこの仕組みを完全にコントロールしたいと考える場合がある。この記事では、Gitリポジトリ管理ツールであるGiteaと、そのCI/CDワークフローを実行するAction Runnerを、あなたのパソコン上に設定する方法を詳しく解説する。

ローカル環境でGiteaとAction Runnerを動かすことには、いくつかの大きなメリットがある。まず、クラウドサービスを利用する場合、コードをプッシュしてからワークフローが開始されるまでにネットワークの遅延が発生することがあるが、ローカル環境ではその待ち時間がほとんどなく、ワークフローが即座に実行される。これにより、開発中のフィードバックサイクルが大幅に短縮され、効率的に作業を進めることができる。次に、コードや認証情報といった機密性の高い情報を外部のクラウドサービスに置きたくない場合でも、ローカル環境ならばすべてのデータを自分のパソコン内で管理できるため、セキュリティ上の安心感が得られる。さらに、ローカルでしかアクセスできないサービス（例えば、自分で立てた開発用データベースやAPI）と連携してテストを行いたい場合や、VPNやトンネルを使わずにウェブフックの動作を確認したい場合など、特定のネットワーク環境が必要なケースでも、ローカル環境は非常に柔軟に対応できる。特に、Dockerレジストリを自分で構築して試したり、複数のマイクロサービスが連携するシステムを開発・テストしたりする際には、このローカルセットアップが非常に役立つだろう。

このセットアップを進めるために、まずいくつかの設定ファイルを用意する必要がある。一つ目は「token.txt」という名前の空のファイルだ。このファイルは、後でGiteaインスタンスから発行されるAction Runnerの登録トークンを保存するために使われる。このトークンは、GiteaがRunnerを認証し、安全に通信するための鍵となる情報だ。二つ目は「config.yml」というファイルで、その中にcontainer: network: hostという設定を記述する。この設定は、Action Runnerがあなたのパソコンのネットワーク（ホストネットワーク）を直接利用できるようにするために非常に重要だ。これにより、ワークフロー内で実行される処理が、あなたのパソコン上で動いている他のサービス（例: DockerレジストリやローカルAPI）とスムーズに連携できるようになる。

そして、最も中心となるのが「docker-compose.yml」ファイルだ。このファイルは、GiteaとAction Runnerという二つのサービスを、Dockerというコンテナ技術を使ってまとめて起動し、管理するための設定を記述する。Dockerは、アプリケーションとその実行に必要なすべての要素（コード、ランタイム、システムツール、ライブラリなど）を「コンテナ」と呼ばれる独立した環境にパッケージ化し、どんな環境でも同じように動作させることができる技術だ。Docker Composeは、複数の関連するDockerコンテナを定義し、一括で起動・停止・管理するためのツールである。

docker-compose.ymlの中身を見ると、まずgitea-networkという名前のプライベートネットワークが定義される。このネットワークを通じて、GiteaとAction Runnerは互いに通信する。giteaサービスは、gitea/gitea:1.24.6というDockerイメージを使ってコンテナを起動し、giteaというコンテナ名が付けられる。Giteaのデータが永続的に保存されるように、あなたのパソコン上の./data/giteaディレクトリをコンテナ内の/dataにマウントしている。また、パソコンのポート3000番をGiteaコンテナのポート3000番に接続することで、ウェブブラウザからhttp://localhost:3000にアクセスしてGiteaのウェブインターフェースを利用できるようになる。

次に、gitea-runnerサービスの設定だ。これはgitea/act_runner:0.2.13というイメージを使用し、gitea-runnerというコンテナ名で起動する。depends_on: giteaという設定により、Giteaサービスが完全に起動してからこのランナーサービスが開始される。ランナーもgitea-networkに参加する。ここでの重要なポイントはいくつかのボリュームマウントだ。最初に作成したtoken.txtとconfig.ymlをコンテナ内にマウントすることで、ランナーは登録トークンとネットワーク設定を利用できる。./data/act_runnerはランナー自身のデータ、./data/cacheはダウンロードされたアクションのキャッシュを保存するために使われ、これによりランナーを再起動しても状態が失われることはない。

特に重要なボリュームマウントは/var/run/docker.sock:/var/run/docker.sockだ。この設定は、ランナーコンテナがあなたのパソコンのDockerデーモン（Dockerの核となるプロセス）と直接通信できるようにする。これにより、ランナーはワークフローの中でDockerコマンド（例: Dockerイメージのビルドや新しいコンテナの起動）を実行できるようになり、あなたのパソコン上でDockerを活用した様々な処理が可能になる。環境変数として、CONFIG_FILEでconfig.ymlのパスを、GITEA_INSTANCE_URLでGiteaインスタンスのURLを、GITEA_RUNNER_REGISTRATION_TOKEN_FILEでtoken.txtのパスを指定することで、ランナーはGiteaと正しく連携し、ワークフローを実行できるようになる。

これらのファイルが準備できたら、コマンドラインツール（ターミナルやコマンドプロンプト）を開き、ファイルが保存されているディレクトリでdocker compose up -dコマンドを実行する。これにより、GiteaとAction Runnerのコンテナがバックグラウンドで起動する。次に、ウェブブラウザでhttp://localhost:3000にアクセスし、Giteaの初期設定を行い、新しいアカウントを作成する。Giteaの管理画面に進み、Action Runnerの登録ページで表示される登録トークンをコピーし、最初に作成したtoken.txtファイルの中に貼り付けて保存する。トークンを保存したら、docker compose restart gitea-runnerコマンドを実行してランナーコンテナを再起動する。これでランナーがGiteaに登録され、ワークフローを実行する準備が整う。ランナーが正しくGiteaに接続されたかを確認するには、docker logs gitea-runnerコマンドでランナーのログを確認すると良い。

セットアップが完了したら、実際にワークフローを動かして動作を確認してみよう。例として、簡単なDockerイメージをビルドするワークフローが提供されている。まず、Giteaリポジトリのルートディレクトリに「Dockerfile」というファイルを作成し、FROM busybox:1.36.1とCMD ["echo", "Hello world!"]という内容を記述する。これは、busyboxという非常に軽量なベースイメージを使い、「Hello world!」と出力するだけのシンプルなDockerイメージを定義している。

次に、Giteaリポジトリ内の.gitea/workflows/example.ymlというパスに、ワークフローの定義ファイルを作成する。このワークフローは、pushイベント（コードがリポジトリにプッシュされた時）が発生すると、Build and push imageという名前のジョブを実行するように設定されている。このジョブは複数のステップで構成される。Checkoutステップは、リポジトリのコードを作業ディレクトリに取得する。Setup QEMUとSetup Buildxは、Dockerイメージを様々なCPUアーキテクチャ向けにビルドするためのツールであるBuildxを設定するステップだ。特にBuildxではdriver-opts: network=hostが指定されており、これはランナーのconfig.ymlで設定したホストネットワークの利用を反映している。

Login to registryステップでは、docker/login-actionを使って、ローカルで動いているGiteaのコンテナレジストリ（http://localhost:3000）にログインする。ここで使用するusernameとpasswordは、あなたのGiteaのユーザー名と、Giteaの「アプリケーション」設定で発行されるアクセストークンを使用する。そして、Build and pushステップで、docker/build-push-actionを使って、先ほどのDockerfileからイメージをビルドし、ローカルのGiteaレジストリにプッシュする。tagsの部分では、localhost:3000/${{ gitea.repository }}:latestのように、リポジトリ名とlatestタグ、またはコミットのSHA値（コミットハッシュ）を使ってイメージにタグ付けしている。

これらのファイルをリポジトリに追加してGiteaにプッシュすると、Gitea Action Runnerが自動的にこのワークフローを検出し、あなたのパソコン上でDockerイメージのビルドとローカルレジストリへのプッシュを実行する。

この一連のセットアップにより、あなたは完全に機能するローカルのGitea + Action Runner環境を手に入れたことになる。これにより、コードをクラウドに送ることなく、ワークフローを即座にテストし、Buildxを使って様々なプラットフォーム向けのDockerイメージを柔軟にビルド・プッシュできる。また、自己ホスト型のCI/CDパイプラインを自由に試すことが可能になる。ここから、さらに多くのランナーを追加したり、外部のDockerレジストリと連携させたり、他のローカルサービスと統合したりと、この環境をあなたのニーズに合わせて拡張していくことができるだろう。