Gitea Actions で CI/CD を始める：ランナーの登録からワークフローの作成まで

コードを変更するたびに、テストを実行し、ビルドが通るかを確かめる。人の手で毎回これを行うのは大変で、忘れたり、省略したりしがちです。そこで使われるのが CI/CD と呼ばれる自動化の仕組みです。コードが push されたことをきっかけに、定められた作業を自動で実行し、結果を知らせます。

Gitea には、この仕組みが Gitea Actions として組み込まれています。GitHub Actions に近い書き方ができるため、すでに GitHub Actions に親しんでいる方には、取り組みやすい機能です。この記事では、仕組みの全体像から、ランナーの登録、最初のワークフローまでを説明します。確認した時点は2026年11月15日で、ドキュメントの最新の安定版は 28.3.0 です。

便利な自動化には、信頼の問題がついてくる

自動化は便利ですが、導入前に理解しておくべき点があります。Gitea Actions では、ジョブを実行するのは Gitea 本体ではありません。ドキュメントによれば、Gitea はジョブを自分では実行せず、ランナーという別のプログラムに任せます。つまり、ワークフローに書かれた内容は、ランナーが動いているマシンの上で実行されます。

この仕組みには、安全面の注意が付きます。ドキュメントは、次の点を明記しています。

• リポジトリ、組織、インスタンスに対して、信頼できないランナーを使わないでください。
• 信頼できないリポジトリ、組織、インスタンスに対して、ランナーを提供しないでください。
• gitea.com のような公開のインスタンスでは、ランナーの追加と利用に、特別な注意が必要です。

ワークフローは、プログラムをランナー上で動かすものです。そのため、ランナーが置かれた環境に、秘密の情報や、重要なシステムへの経路があれば、実行される内容の影響が及びます。ランナーを、専用の環境に分けて用意する、重要なサーバーとは別にする、といった工夫が重要です。導入の第一歩は、仕組みの理解と、信頼の範囲の確認です。

Gitea Actions の位置づけ

Gitea Actions は、バージョン 1.19 から利用できる、組み込みの CI/CD の機能です。ドキュメントは、これを「GitHub Actions に似ていて、ほぼ互換性がある」と説明しています。また、本番の利用に十分に安定していると述べ、Gitea プロジェクト自身も、自分たちの組織のすべてのリポジトリで使っているとしています。

ランナーは、Gitea Runner と呼ばれる、Go で作られた独立したプログラムです。ドキュメントによると、nektos/act を元にした、ハードフォークです。ジョブを実行するときに Docker を使う場合は、ランナーの環境に Docker が入っていて、デーモンが動いている必要があります。

互換性があるといっても、すべての機能が同一ではありません。ドキュメントは、違いの一覧を示していません。そのため、GitHub Actions 用に書かれたワークフローを持ち込む場合は、そのまま動くとは決めつけず、動作を確認する必要があります。たとえば、actions/checkout のようなアクションは、SHA256 のリポジトリや、Gitea をサブパスで動かしている場合に、正しく動作しないことがあると注意されています。

使い始めるための三つの準備

Gitea Actions を使うには、インスタンス、リポジトリ、ランナーの三つを準備します。

インスタンスで有効にする

Actions は、バージョン 1.21.0 から、標準で有効になっています。それより前のバージョンでは、設定ファイルに次の内容を書きます。

[actions]
ENABLED=true

28.3.0 を使っているなら、この設定は不要です。

リポジトリで有効にする

インスタンスで有効でも、リポジトリでは、標準で無効になっています。使いたいリポジトリで、設定の画面を開き、「Enable Repository Actions」を有効にします。この画面のアドレスは、<Gitea のアドレス>/<所有者>/<リポジトリ>/settings です。

ランナーを登録して起動する

ランナーは、実行ファイルを入手するか、Docker のイメージを使って用意します。登録は、次のコマンドで行います。

gitea-runner register --no-interactive --instance <インスタンスのアドレス> --token <トークン>

instance には、Gitea のアドレス（たとえば http://192.168.8.8:3000）を指定します。ここで重要なのは、127.0.0.1 や localhost のような、自分自身を指すアドレスを使わないことです。ドキュメントは、これを使うのは常に避けるべきだと明記しています。

トークンは、次のいずれかの画面で取得します。

どの範囲で登録するかは、先ほどの信頼の問題とつながります。インスタンス全体で共有するランナーは、すべてのリポジトリのジョブを実行します。特定の組織やリポジトリでだけ使うなら、その範囲で登録するほうが、影響を限定できます。

登録が終わると、.runner というファイルが作られます。ドキュメントは、このファイルを手で編集しないよう求めています。登録後は、次のコマンドでランナーを起動します。

gitea-runner daemon

最初のワークフローを書く

ワークフローは、リポジトリの .gitea/workflows/ ディレクトリに、.yaml の拡張子のファイルとして置きます。次は、最小の例です。

name: Gitea Actions Demo
on: [push]
jobs:
  Explore-Gitea-Actions:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository code
        uses: actions/checkout@v4
      - run: echo "Hello from Gitea Actions"

内容は、次のように読みます。

このファイルをリポジトリに追加して push すると、そのコミットをきっかけにジョブが動き、リポジトリの Actions のタブで、実行の状況を確認できます。うまく動かないときは、ランナーが登録されていて起動しているか、runs-on のラベルがランナーのラベルと合っているかを、順に確認します。

自動化を育てていく進め方

最初のワークフローが動いたら、実際の作業に合わせて、少しずつ内容を増やします。進め方の例を、次に示します。

1. まず、確認だけを自動にします。 テストの実行や、文法の確認など、リポジトリの状態を変えない作業から始めます。
2. 次に、プルリクエストと組み合わせます。 プルリクエストが出されたときに、自動で確認が動けば、レビューをする人は、結果を見て判断できます。
3. 最後に、配布を自動にします。 ビルドの成果物を、パッケージとして登録する、サーバーに反映するなど、外部へ影響する作業は、確認が安定してから加えます。

外部へ影響する作業ほど、認証の情報などの秘密を扱う場面が増えます。実行する環境と、ランナーを動かすマシンの信頼を、そのたびに見直してください。

また、Actions に関する権限は、チームの設定で管理できます。実行の承認や、取り消しを誰に許すのかも、あわせて決めておくと、運用が安定します。権限の考え方は、組織とチームで権限を設計するで整理しています。

ランナーを置く場所を考える

ランナーは、ジョブの内容を実際に実行するプログラムです。そのため、どのマシンに置くかによって、影響の範囲が変わります。ドキュメントが示す、信頼できないランナーを使わないという注意を、設計に落とし込むと、次のような考え方になります。

• 本体と、同じマシンに置かない選択肢を考えます。 Gitea 本体と、ランナーを同じマシンで動かすと、ジョブの内容が、本体のデータに近い場所で動きます。別のマシンに置けば、影響の範囲を分けられます。
• 専用のマシンや、使い捨てに近い環境を用意します。 ジョブで使う環境を、ほかの用途と分けておけば、後始末も単純です。
• 秘密の情報を、必要な範囲に限ります。 ランナーの環境に、不要な認証の情報を置かないようにします。
• 登録する範囲を、必要最小限にします。 インスタンス全体で共有するよりも、組織やリポジトリの単位で登録するほうが、影響を限定できます。

これらは、規模が小さいうちは負担に感じるかもしれません。それでも、最初に考え方を決めておけば、ランナーを増やすときにも、一貫した方針で対応できます。

動かないときの切り分け

ワークフローが期待どおりに動かないときは、原因を順に確認します。

1. ワークフローのファイルの場所を確認します。 .gitea/workflows/ の中に、.yaml の拡張子で置かれているかを見ます。
2. リポジトリで Actions が有効かを確認します。 リポジトリの設定の画面で、「Enable Repository Actions」が有効になっているかを見ます。標準では、リポジトリの Actions は無効です。
3. ランナーの登録と起動を確認します。 登録した範囲（インスタンス、組織、リポジトリ）が正しいか、gitea-runner daemon が動いているかを見ます。
4. ランナーのアドレスを確認します。 登録に使った Gitea のアドレスが、自分自身を指すものではなく、ランナーから到達できるものであるかを見ます。
5. ジョブのログを読みます。 リポジトリの Actions のタブで、失敗した場所と、出力されているメッセージを確認します。

ここまで確かめて解決しない場合は、ワークフローの内容を、最小の形まで削って、動くところから足していく方法が有効です。

GitHub Actions から持ち込むときの心構え

Gitea Actions は、GitHub Actions と、ほぼ互換だと説明されています。そのため、すでに書かれたワークフローを持ち込んで、試したくなるのは自然です。ただし、互換性があるという説明は、そのまま動くという保証ではありません。違いの一覧は示されていないため、持ち込む際は、次の進め方が安全です。

1. 小さなワークフローから、持ち込んで試します。
2. 使っているアクションが、動作するかを一つずつ確認します。
3. 動かないものは、代わりのアクションを探すか、シェルのコマンドで置き換えます。
4. 動作が確認できたものから、実際のリポジトリに移します。

特に、actions/checkout のような広く使われるアクションにも、SHA256 のリポジトリや、サブパスでの運用で正しく動作しない場合があると、ドキュメントに書かれています。自分の環境に当てはまるかを、あらかじめ確認しておきます。

ワークフローの結果を、日々のレビューにつなげる

自動化は、結果が人の判断に使われてこそ、意味を持ちます。ワークフローを動かしても、誰も結果を見ない状態では、手間が増えるだけです。そこで、チームの約束として、次のような取り決めを置くと、仕組みが生きてきます。

• 失敗したままの変更は、取り込まないと決めます。 テストが失敗しているプルリクエストは、直してから、確認を依頼します。
• 失敗の原因は、作者が最初に調べます。 ログを読み、自分の変更が原因かを確認してから、担当者に相談します。
• 不安定な確認は、放置せず直します。 ときどき失敗するテストを放置すると、本物の失敗が見逃されます。

こうした約束は、ツールの機能ではなく、チームの習慣です。ただし、リポジトリの画面に、結果がプルリクエストとともに表示されるため、約束を守りやすい環境が整っています。自動化は、人の注意力を節約するための仕組みであり、人の判断を置き換えるものではないという位置づけを、共有しておきます。

小さく始めて、確かめながら広げる

Gitea Actions は、リポジトリに組み込まれた自動化の仕組みとして、手軽に始められます。一方で、ジョブを実行するランナーの信頼が、運用の前提になります。導入するときは、次の順序で進めるのが無理がありません。

1. 試験用のリポジトリで、ランナーを一つ登録します。
2. 最小のワークフローで、動作を確かめます。
3. 実際のリポジトリで、確認の作業から自動にします。
4. 外部へ影響する作業は、環境の信頼を確かめてから加えます。

ランナーを置くサーバーと、重要な情報を持つサーバーを分けること、ランナーを登録する範囲を必要最小限にすること。この二点を意識するだけでも、安全面の負担は大きく下がります。この記事の内容は、2026年11月15日時点のドキュメントに基づいています。手順は、実際の環境で試したものではないため、導入の際は、試験用の環境で動作を確認してから、本番に反映していただくことをおすすめします。