Runner グループ - チームリソース

このページの目的は、Runner グループの日々の業務に必要なリソースをドキュメント化することです。

概要

このページの目的は、Runner グループの日々の業務に必要なリソースをドキュメント化することです。

おすすめのブックマーク

私たちがメンテナンスするプロジェクト

チームとして複数のプロジェクトをメンテナンスしています。https://gitlab.com/gitlab-com/runner-maintainers グループは各プロジェクトにメンテナー権限で追加されています。また、各プロジェクト間でツールとバージョンを統一するよう努めています。

プロダクトプロジェクト

Runner コンポーネントプロジェクト

CI Steps プロジェクト

ヘルパープロジェクト

Runner の公開 API に依存する GitLab プロジェクト

以下のプロジェクトは Runner の公開 API に依存しており、公開 API への変更・廃止を行う際にはその範囲として考慮する必要があります:

プロジェクトAPI
GitLab Terraform プロバイダーREST API
GitLab CLIREST API

セキュリティプロセス（CVE 脆弱性報告 Issue の管理）

CVE 脆弱性 Issue の管理は、GitLab の脆弱性管理の取り組み (1、 2)の一部であり、 GitLab FedRAMP 認証を維持するための重要な要素です。

container-scanners プロジェクトを使用して、GitLab は私たちが生成するすべてのイメージをスキャンし、CVE 脆弱性を検出します。これらのスキャンから、 vulnmapper プロジェクトが脆弱なイメージを作成したプロジェクトに Issue を作成し、遵守すべき SLA を含みます。 週次チームタスクで Support & Security Responder の役割を担当する Runner チームメンバーが CVE のリストをトリアージし、レビューして、適切に Issue に対処する必要があります:

  • Critical（重大）の severity の Issue は即座に対処する必要があります。
  • High（高）、Medium（中）、Low（低）の severity の Issue は、修正 SLA の優先順位に従って対処する必要があります。

CVE Issue への対処手順は次のとおりです:

アクティブな脆弱性報告の表示

  • 次のいずれかを使用して、チームに割り当てられたアクティブな CVE Issue を表示します:

    • Issue 検索

    • gitlab-dashboard cves コマンド

    • cver imageVulns コマンド

      多くの Issue が同じ CVE 脆弱性報告を参照しています。同じ脆弱性報告の Issue をグループ化してまとめて対処するのが最善です。

  • CVE 報告を優先順位に従って対処し、critical、high、medium の severity を最初に処理します。以下の手順に従ってください:
    1. 共通 / 関連する Issue のグループごとに、関連する CVE がまだ有効かどうかを確認します。これは、 trivy や grype などのツールで Issue に示された画像の latest バージョンをスキャンし、trivy や grype のスキャンに Issue で参照されている CVE が現れるかどうかを確認することで行えます。
    2. 関連する画像の trivy または grype スキャンで脆弱性が報告されなくなった場合、Issue をクローズできます。上記の cver 内部ツールはこのタスクをほぼ自動化しており、関連する Issue のクローズも含まれます（ドキュメントを参照）。
    3. 関連する画像に脆弱性がまだ存在する場合は対処する必要があります。

gitlab-runner または gitlab-runner-helper 画像の ubi-fips フレーバーを参照する Issue は、他の画像フレーバー（alpine や ubuntu など）よりも優先されます。これは GitLab FedRAMP 認証が ubi-fips 画像のみに依存しているためです。

アクティブな脆弱性報告への対処

脆弱性は通常、以下の 3 つのタイプのいずれか（発生頻度の高い順）で現れます:

  • サードパーティ OS パッケージ（git や git-lfs など）に脆弱性が存在する
  • gitlab-runner の依存関係に脆弱性が存在する
  • gitlab-runner の私たちが書いたコードに脆弱性が存在する

サードパーティ OS パッケージ

この場合、脆弱性は:

  • アップストリームで修正されていない
  • アップストリームで修正されているが、修正を含む OS パッケージがまだ作成・公開されていない
  • アップストリームで修正されない予定

主な対処方針は、deviation request issue を作成することです（ https://handbook.gitlab.com/handbook/security/security-assurance/security-compliance/poam-deviation-request-procedure/ を参照）。一般に、問題のあるソフトウェアモジュール（例: git-lfs や libcurl）ごとに 1 つの deviation request Issue を作成します。Issue を作成する際は、必ず operational_requirement_template をテンプレートとして選択し、以下のセクションを記入してください:

  • 影響を受けるイメージ
  • 脆弱性の詳細（関連する CVE 報告ごとに 1 行）
  • 関連する vulnmapper Issue
  • 理由

deviation request Issue が作成されたら、次を追加してください:

  • 関連するすべての gitlab-runner Issue への deviation request Issue へのメモ

  • ラベル FedRAMP::DR Status::Open

  • このリストから最も関連性の高いラベル:

    • Vulnerability::Vendor Base Container::Fix Unavailable
    • Vulnerability::Vendor Base Container::Will Not Be Fixed
    • Vulnerability::Vendor Package::Fix Unavailable
    • Vulnerability::Vendor Package::Will Not Be Fixed

最終的に、問題のあるパッケージの修正が OS パッケージマネージャーに反映されると、gitlab-runner と deviation request 両方の Issue をクローズできます。

gitlab-runner の依存関係

ここで最もシンプルな対処方針は、依存関係を最新の互換バージョン（または少なくとも脆弱性に対処したバージョン）に更新することです。依存関係の更新を含む MR がマージされると、gitlab-runner の Issue をクローズできます。

依存関係が脆弱性に対処しない場合、考えられる対処方針は:

  • 脆弱性に対処した依存関係のフォークが存在する場合、Go モジュールの replace ディレクティブで使用します。この場合、アップストリームの依存関係で脆弱性が対処された際に元に戻すタスクを必ず作成してください。
  • 可能であれば、その依存関係を使用しないか、別の同様の依存関係に置き換えることを検討します。
  • deviation request Issueを作成します。

gitlab-runner のソースコード

ここでの唯一の対処方針は、脆弱なコードを修正することです。修正が単純でなく実装に時間がかかる場合（CVE の SLA を満たせない可能性がある場合）、deviation request Issueの作成が必要になる場合があります。

セキュリティフォークを使用した作業

Issue が機密扱いになっている場合、Issue を修正する MR はプロジェクトのセキュリティフォークで作成する必要があります（security-forksを参照）。一般的にプロセスは正規プロジェクトリポジトリでの MR 作成・マージと同じですが、いくつかの重要な相違点があります。

セキュリティリポジトリの MR は、Runner コードオーナーに加えて、セキュリティの対応者によるレビュー / 承認が必須であることに注意してください。

以下の例は GitLab Runner プロジェクトを対象としていますが、セキュリティフォークを持つすべての Runner 関連プロジェクトにも同様に適用されます。

セキュリティフォークを正規リポジトリと同期する

セキュリティフォークは正規リポジトリと自動的に同期するよう設定されていますが、セキュリティフォークの main ブランチに正規リポジトリの main ブランチに存在しない変更がある場合、無効になることがあります。これは通常、セキュリティ MR がセキュリティフォークの main にマージされたが、正規リポジトリの main にはマージされていない場合に発生します。この場合、セキュリティフォークを正規リポジトリと手動で同期させる必要があります。

チェックアウト済みの正規リポジトリから:

git fetch # 正規リポジトリの最新変更があることを確認します
git remote add security [email protected]:gitlab-org/security/gitlab-runner.git # セキュリティリポジトリをリモートとして追加します。git URL を使用してください
git fetch security # セキュリティフォークのリポジトリ参照をフェッチします
git checkout -b security-main security/main # セキュリティフォークの main ブランチをチェックアウトします
git rebase --rebase-merges origin/main # 正規の main をセキュリティの main にリベースします
git log --color --topo-order --oneline # 結果の履歴が正常であることを確認します
git push --force # 結果のローカル security main ブランチをセキュリティリモートリポジトリにプッシュします

注意:

  1. これらの手順では、セキュリティリポジトリと正規リポジトリを双方向に完全同期させません。正規リポジトリにのみ存在する変更をセキュリティリポジトリに取り込むだけです。逆方向の同期は以下で説明します。
  2. セキュリティリポジトリは main ブランチに force-push ブランチ保護を持つべきではありませんが、作業中のものに保護がある場合は、最後のステップを実行できるように一時的に無効にしてください。
  3. セキュリティフォーク main ブランチが正規リポジトリ main ブランチと大幅に乖離した場合（特にセキュリティリポジトリのみに存在する変更について）、正規リポジトリをセキュリティフォークにリベースする際にマージの競合が発生する可能性があります。それらを解決する必要があります。

セキュリティ MR を正規リポジトリにマージバック

セキュリティリポジトリで作成された MR がマージされると（セキュリティリポジトリの main ブランチへ）、セキュリティリポジトリと正規リポジトリは非同期になります。セキュリティフォークから正規リポジトリへの MR のマージは手動プロセスです。開発者が正規リポジトリに取り込みたいセキュリティリポジトリの各 MR は、正規リポジトリへの新しい MR を通じて手動で行う必要があります。この手順が手動なのは、開発者がこれらのマージをいつ行うか制御できるようにするためです。

セキュリティフォークの main ブランチにすでにマージされた MR を正規リポジトリにマージするには、次の手順に従ってください:

チェックアウト済みの正規リポジトリから:

git fetch # 正規リポジトリの最新変更があることを確認します
git remote add security [email protected]:gitlab-org/security/gitlab-runner.git # セキュリティリポジトリをリモートとして追加します。git URL を使用してください
git fetch security # セキュリティフォークのリポジトリ参照をフェッチします
git checkout -b name-of-working-branch origin/main # セキュリティリポジトリからコミットをチェリーピックするための新しいブランチを作成します
git cherry-pick sha-of-commit-in-security-repo # セキュリティリポジトリから関連 MR のすべてのコミットをブランチにチェリーピックします

最後のステップを関連 MR のすべてのコミットについて、トポロジカル順に、マージコミットを除いて繰り返します。MR のマージコミットをチェリーピックされたコミットに含めないでください。

最後に、このブランチから通常どおり正規リポジトリに MR を作成します。

注意:

  1. セキュリティフォークが正規リポジトリと大幅に乖離した場合、コミットのチェリーピック時にマージの競合が発生する可能性があります。それらを解決する必要があります。
  2. MR が正規の main にマージされた直後に、上記のようにセキュリティリポジトリを手動で同期させる必要があります。
  3. これらの手順の目的は、セキュリティリポジトリと正規リポジトリを双方向に完全同期させることではありません。完全な同期は、セキュリティリポジトリからすべての MR を正規リポジトリにマージする副産物として発生します。各 MR についていつこれが行われるかは開発者の裁量に委ねられています。

メトリクスとログ

  • ダッシュボード

runner-dashboards

  • メトリクス
  • ログ
    • Runner ログ（シャードでフィルタリング）
    • シャードのリストはサービスダッシュボードのトップバーのドロップダウンにあります:

runner-shards

内部ツール

マージリクエストボット

gitlab-org/gitlab-runner には、マージリクエストボットが有効になっており、 コミュニティコントリビューションにコメントを投稿します。 これはマージリクエスト Webhook イベントを通じて設定されています。

Windows での開発 / テスト

Windows の開発ドキュメントでは Vagrant と Virtualbox の使用を推奨しています。 ただし、最も簡単な方法は Google Compute Engine の Windows インスタンスを作成して RDP 接続することです。 この特別なイメージからインスタンスを作成してください。

サポート対象バージョン

LTSCであるため、かなり古いバージョンの Windows をサポートしています。

サードパーティインフラ

IBM Z/OS でのテスト

s390x アーキテクチャのアーティファクトのテストを容易にするため、 GitLab チームメンバーが利用できる Z/OS VM があります。

ログイン

  1. 1Password の Verify ボールトで、zOS login - gitlabkey02.pem ファイルをダウンロードします。

  2. 同じボールトの zOS login エントリから、user と address フィールドを確認します。

  3. Z/OS VM に SSH 接続します:

    ssh -i "zOS login - gitlabkey02.pem" <user>@<address>

    注意: .pem ファイルのロック解除にパスワードが求められます。zOS login - gitlabkey02.pem エントリに付属のパスワードを入力してください。

ヘルパーイメージのテスト

CI/CD パイプラインで生成された prebuilt-s390x.tar.xz イメージをテストしたい場合、かつ前の手順の .pem ファイルをすでに持っている場合、手順は次のとおりです:

  1. prebuilt-s390x.tar.xz ファイルを Z/OS VM にコピーします:

    scp -i "zOS login - gitlabkey02.pem" prebuilt-s390x.tar.xz <user>@<address>:/home/ubuntu/

    注意: .pem ファイルのロック解除にパスワードが求められます。zOS login - gitlabkey02.pem エントリに付属のパスワードを入力してください。

  2. VM に SSH 接続します:

    ssh -i "zOS login - gitlabkey02.pem" <user>@<address>

  3. イメージをインポートして実行します:

    sudo docker import ./prebuilt-s390x.tar.xz gitlab/gitlab-runner-helper:s390x-dev
sudo docker run -it gitlab/gitlab-runner-helper:s390x-dev bash
gitlab-runner-helper help

Mac Runner AWS 環境へのアクセス

GitLab SaaS Mac Runners は AWS 上で稼働しています。 本番、ステージング、チームサンドボックス、個人サンドボックスの環境があります。 個人サンドボックスは [Hackystack(https://gitlabsandbox.cloud/cloud)] から作成できます。 コスト削減のために未使用リソースには注意してください。oh-my-cost が役立ちます。 Hackystack には チームサンドボックスもあり、Mac ジョブイメージビルダーインスタンスのホストに使用されています。 チームサンドボックスへのアクセスはアクセスリクエストで取得できます。 チームサンドボックス内には、ステージングと本番の Mac 環境にアクセスできるロールもあります。

Mac Runner ステージングへのアクセス

チームサンドボックスから、アカウント ID 251165465090（ステージング）の eng_dev_verify_runner というロールを有効化します。

Mac Runner 本番へのアクセス

チームサンドボックスから、アカウント ID 215928322474（本番）の eng_dev_verify_runner というロールを有効化します。

負荷テスト

グループ gitlab-runner-stress には GitLab と Runner インスタンスのストレステスト用ツール一式があります。 Mac Runners の標準ベンチマークは XcodeBenchmark（私たちのフォーク）です。

Runner ベンディングマシン（AWS Cloud Formation テンプレート）

Partner Solution グループは、AWS での Runner デプロイ用の厳選された AWS Cloud Formation テンプレートのコレクションを “Runner Vending Machine” として管理しています。 Runner の動作やデプロイ方法を変更する際はループに入れて、これらのテンプレートを最新の状態に保てるよう連絡してください。 担当者は DarwinJS です。

シークレット

Runner のシークレットをどのように管理し、適切な場所に格納するかについては詳細なドキュメントが必要です。 ドキュメント化が必要: https://gitlab.com/gitlab-org/gitlab-runner/-/issues/29823

最終更新 May 6, 2026: Merge pull request #100 from kyama0/fix/upload-images-tolerate-upstream-missing (70970e1a)
ページのソースコードを見る - ページの編集 - please contribute. Creative Commons License