105 - Issue 自動化 - Issue をピカピカに保つ

目的

Issue とラベルで日々の業務を管理し、特定のプロセスを定義していると、ラベルを正しい状態に保つのが難しい状況や場面があります。たとえば次のようなケースです。

ラベル衛生: プロセス全体を表すラベル（ABC）と、プロセス内の具体的なステップを表すスコープ付きラベル（ABC::1、ABC::2、ABC::3）が定義されている状況を考えてみてください。
このプロセスでは、チーム全員が「ABC」と、いずれかのスコープ付きラベル「ABC::x」を割り当てることが前提になっています。
しかし、人々はどちらかのラベルを付け忘れる可能性が高く、時間が経つにつれて、2つのラベルのうちどちらかが欠けた Issue が混在することになります。
ラベル衛生 Issue に割り当てられているかもしれない詳細なラベル群に基づいて Issue をサマライズしたいプロセスを考えてみてください。たとえば、10 個のスコープ付きラベル「ZYX::1、ZYX::2、ZYX::3、…ZYX::10」があり、それらを「ODD」と「EVEN」にまとめたい場合です。ZYX::2、4、6、8、10 はすべて「EVEN」、ZYX::1、3、5、7、9 はすべて「ODD」とラベル付けします。
ZYX::nnn ラベルに基づいて、適切な「ODD」/「EVEN」ラベルで Issue を更新するようチームに依頼することもできます。
ラベルを一括更新することもできます（すべての ZYX::1 の Issue を見つけて「ODD」ラベルを追加し、これを 9 回繰り返します）。どちらの場合も、人々が更新を忘れたり、何かが変更されたら間違ってしまったりするため、ODD/EVEN サマリーラベルはほとんどの場合不正確になります。

ほかにも、自動化が役立つ重要な場面があります。（実用例は下記を参照）

Issue を特定のプロジェクトに移動する - ある Issue または Issue グループを定期的に特定のプロジェクトに移動したい状況を考えてみてください。
Issue をエピックに昇格する - 再作成したい関連エピックのセットがある状況を考えてみてください。エピックを Issue テンプレートとして定義しておき、それらを自動的にエピックに昇格したい場合です。
Issue を非推奨化／削除する - 実質的に削除したい Issue があり、すべてのラベル、エピック、見積もり、マイルストーンなどを取り除きたい状況を考えてみてください。

自動化はこれらすべての状況に対応し、作業を効率化できます。

解決策 - ラベル衛生 / Triage Bot

以下を自動的に行うルールセットを定義します。

ラベルが欠けているときに追加する
ラベルが間違っているときに変更または削除する
コメントの追加、ユーザーのメンション、より詳細なコメントや /クイックアクションの実行

Triage Bot は GitLab のオープンプロジェクトで、多くの Issue やマージリクエストの衛生タスクを自動化し、プロジェクトが定義済みのプロセスにより一貫して従うことを可能にします。

Triage ポリシー / ルールの例

ここでは、Triage ポリシー / ルールがどのように更新と Issue 衛生を自動化できるかの例を 2 つ紹介します。

この例では、5 日以上経過しているがラベルが付いていない Issue を見つけ、Author に対して何かするようコメントを追加します。このポリシーは、チームメンバーにも Issue について通知します。

    - name: My policy
     conditions:
       date:
         attribute: updated_at
         condition: older_than
         interval_type: days
         interval: 5
       state: opened
       labels:
         - No Label
     limits:
       most_recent: 50
     actions:
       labels:
         - needs attention
       mention:
         - markglenfletcher
       comment: |
         {{author}} This issue is unlabeled after 5 days. It needs attention. Please take care of this before the end of #{2.days.from_now.strftime('%Y-%m-%d')}

Strategic marketing では、スコープ付きワークフローラベルが欠けている Strategic marketing リクエストを見つけるルールがあります。

      - name: sm_request (MISSING a scoped label and assign it as a New Reqeust)
        conditions:
          labels:
            - sm_request
          state: opened
          forbidden_labels:
            - sm_req::triage
            - sm_req::transfered
            - sm_req::new_request
            - sm_req::declined
            - sm_req::completed
            - sm_req::backlog
            - sm_req::assigned
        actions:
          labels:
            - sm_req::new_request
          comment: |
           SM TriageBot helping out here: This SM Request issue was not in the workflow, automatically adding it as a new request.

Triage Bot のセットアップ

TriageBot のセットアップは、シンプルな 2 ステップです。

CI/CD パイプラインを設定する
最初の Triage ポリシーをドラフトする
Triage ポリシーを定期的に実行する CI/CD スケジュールを設定する

ステップ 1: CI/CD パイプラインを初めて設定する

Triage Bot はスケジュール CI パイプラインジョブとして動作するため、プロジェクトで gitlab-ci.yml ファイルを定義する必要があります。gitlab-ci.yml ファイルはプロジェクトのルートディレクトリに保存します。
以下は Product and Solution Marketing パイプラインの例で、3 つのジョブが定義されています。手動ジョブが 2 つ、スケジュール ジョブが 1 つあります。2 つの手動ジョブは、ルール / ポリシーをテスト（dry-run）するか、実際にルール / ポリシーを適用（policy:run）します。1 つの スケジュール ジョブ（schedule:policyrun）は、実行されるとルール / ポリシーを実際に適用します。
```
>image: ruby:2.7
stages:
- triage
- run

dry-run:triage:
stage: triage
script:
   - gem install gitlab-triage
   - gitlab-triage --help
   - gitlab-triage --dry-run --token $API_TOKEN --source projects --source-id $CI_PROJECT_PATH
when: manual
except:
   - schedules

policy:run:
stage: run
script:
   - gem install gitlab-triage
   - gitlab-triage --token $API_TOKEN --source projects --source-id $CI_PROJECT_PATH
when: manual
except:
   - schedules

schedule:policyrun:
stage: run
script:
   - gem install gitlab-triage
   - gitlab-triage --token $API_TOKEN --source projects --source-id $CI_PROJECT_PATH
only:
   - schedules
```
TriageBot は GitLab プロジェクトにアクセスし、Issue を読み書きする権限を持つ必要があります。これは「トークン」と呼ばれ、「CI/CD 変数」を使って GitLab に保存されます。上のパイプライン例で見えている $API_TOKEN がそれです。

これらのジョブを実行するには、GitLab CI/CD 環境変数 $API_TOKEN を設定する必要があります。

その方法はこちらです。

2. CI-CD API トークン変数のセットアップ	画像
1. プロジェクトの左メニューから `Settings-->CI/CD` を選択します
2. 次に `Variables` セクションを展開します
3. 新しい行を追加します。 - Type= “Variable” - Key = “API_TOKEN” - Value = あなたの API キー - API キーはお持ちですよね？（短い手順は下記参照） - Masked を True に設定します。
4. 変数を保存します

3. API キーを取得する	画像
1. API キーはあなたのアカウントに紐付けられており、基本的に Bot にあなたを代理する権限を与えるものです。まず GitLab の個人設定のドロップダウンをクリックします。
2. `Access Tokens` を選択し、 - アクセストークンに名前を付けます - 有効期限は空のままにします（期限を設けたい場合を除く） - Scopes で「API」を選択します - Create personal access token をクリックします
3. パーソナルアクセストークンがページの上部に表示されます。
4. トークンをコピーして、CI/CD 変数設定の API_TOKEN Value に追加します。

ステップ 2: 最初の Triage ポリシーをセットアップする

Triage ポリシー / ルールは、プロジェクトのルートディレクトリに保存される .triage-policies.yml という YML ファイルに定義します。ルールとポリシーオプションの 詳細な 手順は、Triage Bot プロジェクトの README.md ファイルにある Defining a Policy セクションを読んでください。

ルートディレクトリに .triage-policies.yml という新規ファイルを作成します。

次のシンプルな最初のルールを貼り付けます。

  resource_rules:
    issues:
      rules:
        - name: find all open issues - any label (simple - should be lots)
          conditions:
          state: opened

変更をコミット＆マージします。

これによりパイプラインがトリガーされますが、ジョブはすべてスキップされるはずです。画面下部に次のように表示されます。

4. Dry-Run TriageBot	画像
1. Pipeline リンクをクリックして Pipeline 画面に行きます
2. 「Dry Run」パイプラインジョブを実行します。
3. ジョブをクリックして、実行を見守ります。
4. まずコンテナを作成し、ランナーを起動します（ここまで来たということは、CI ジョブが正しく定義されているということ）
5. 次に Triage Bot にヘルプ出力を表示するよう促します（これは動作しており、API キーが有効であることを意味します）
6. 続いてジョブが「Dry-Run」を実行し、Bot が動作している間の出力が見えます。ジョブは1つだけ - すべてのオープン Issue を見つけることなので、すぐに実行され 1,000 件以上の Issue を見つけます。ポリシー / ルールにフィルターやアクションがないため、ジョブは終了します。

これで、プロジェクトに必要な特定のポリシー / ルールを定義できます。

ステップ 3: ジョブのスケジュール

ジョブのスケジュール	画像
1. 左メニューの CI/CD–>Pipelines に移動します
2. Create New Schedule をクリックします
3. スケジュールを作成します。 - 名前 / 説明を記述 - インターバルパターンを選択（実行頻度。おそらく毎日） - `Target Branch` と `Variables` オプションはデフォルトのままに - Save Pipeline Schedule をクリックします。

その他の特定シナリオ

Issue を特定のプロジェクトに移動する

プロジェクトに、自動化 Bot に Issue 移動を指示するフラグとなるラベルを作成します。

ラベルは移動先プロジェクトに対して一意である必要があります。たとえば move--> project2Test

.triage-policies.yml を更新します。
次のルールを貼り付けます。

  resource_rules:
    issues:
      rules:
        - name: 1. Mooving an issue to another project based on the label - move to Test Project 2
          conditions:
            labels:
              - move--> project2Test
            state: opened
          actions:
            comment: |
             /move gitlab-com/marketing/strategic-marketing/testgroup-pmm-isights/testproject2

このルールは、すべての オープン な Issue から move--> project2Test ラベルを探し、クイックアクションを適用します。

/move .... Issue の移動先を指定します。

将来、まとめて Issue を別プロジェクトに移動したい場合は、move--> project2Test ラベルを追加するだけで済みます。

Issue をエピックに昇格する

プロジェクトに、自動化 Bot に Issue をエピックに昇格させるよう指示するフラグとなるラベルを作成します。

たとえば promote-me

.triage-policies.yml を更新します。
次のルールを貼り付けます。

  resource_rules:
    issues:
      rules:
      - name: 1.2 Promote Issues to epics
        conditions:
          labels:
            - promote-me
          state: opened
        actions:
          comment: |
           /promote

このルールは、すべての オープン な Issue から promote-me ラベルを探し、クイックアクションを適用します。

/promte Issue をエピックに昇格させます。

将来、まとめて Issue を昇格させたい場合は、promote-me ラベルを追加するだけで済みます。

Issue を非推奨化 / 削除する

Issue を実質的に削除（ラベル除去、エピックとマイルストーンからの除去、見積もり除去、クローズ）したい場合に。

プロジェクトに、自動化 Bot に Issue をエピックに昇格させるよう指示するフラグとなるラベルを作成します。

たとえば deprecate-me

.triage-policies.yml を更新します。
次のルールを貼り付けます。

  resource_rules:
    issues:
      rules:
      - name: 1.1 - Deprecate Issues Close and strip labels of deprecated issues
        conditions:
          labels:
            - deprecate-me
          state: opened
        actions:
          comment: |
           /remove_milestone
           /remove_epic
           /remove_estimate
           /unlabel
           /title Deprecated Issue
           /close

このルールは、すべての オープン な Issue から deprecate-me ラベルを探し、Issue を更新してクローズする一連のクイックアクションを適用します。

将来、まとめて Issue を削除・非推奨化したい場合は、deprecate-me ラベルを追加するだけで済みます。

成功と次のステップ

ここから、プロジェクト固有のポリシー / ルールを構築 / ドラフトできます。

最終更新 May 6, 2026: Merge pull request #100 from kyama0/fix/upload-images-tolerate-upstream-missing (70970e1a)

ページのソースコードを見る - ページの編集 - please contribute.