公式のGitLabリポジトリを使用してGitLab Runnerをインストールする

GitLab Runnerをインストールするには、GitLabリポジトリのパッケージを使用できます。

サポートされているディストリビューション

GitLabでは、Packagecloudでサポートされている以下のバージョンのLinuxディストリビューションのパッケージを提供しています。新しいOSディストリビューションリリースに対応する新しいRunner debまたはrpmパッケージは、Packagecloudでサポートされている場合、自動的に追加されます。

Debベースのディストリビューション

RPMベースのディストリビューション

セットアップによっては、他のDebianまたはRPMベースのディストリビューションもサポートされている場合があります。これは、サポートされているGitLab Runnerディストリビューションからの派生であり、互換性のあるパッケージリポジトリを持つディストリビューションを指します。たとえば、DeepinはDebianの派生ディストリビューションです。そのため、RunnerのdebパッケージはDeepinにインストールして実行できるはずです。他のLinuxディストリビューションでもGitLab Runnerをバイナリとしてインストールできる場合があります。

GitLab Runnerをインストールする

GitLab Runnerをインストールするには、次の手順に従います。

1. 公式GitLabリポジトリを追加します。

   Debian/Ubuntu/Mint

   1. リポジトリ設定スクリプトをダウンロードします:

      curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" -o script.deb.sh

   2. 実行する前にスクリプトを検査します:

      less script.deb.sh

   3. スクリプトを実行します:

      sudo bash script.deb.sh

   RHEL/CentOS/Fedora/Amazon Linux

   1. リポジトリ設定スクリプトをダウンロードします:

      curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.rpm.sh" -o script.rpm.sh

   2. 実行する前にスクリプトを検査します:

      less script.rpm.sh

   3. スクリプトを実行します:

      sudo bash script.rpm.sh

2. 最新バージョンのGitLab Runnerをインストールするか、次のステップに進んで特定のバージョンをインストールします。

   No such file or directoryジョブの失敗を防ぐために、skelディレクトリの使用はデフォルトで無効になっています。

   Debian/Ubuntu/Mint

   sudo apt install gitlab-runner

   RHEL/CentOS/Fedora/Amazon Linux

   sudo yum install gitlab-runner
   
   or
   
   sudo dnf install gitlab-runner

   RHELディストリビューション向けに、FIPS 140-2準拠バージョンのGitLab Runnerが利用可能です。このバージョンをインストールするには、パッケージ名としてgitlab-runnerの代わりにgitlab-runner-fipsを使用します。

3. 特定のバージョンのGitLab Runnerをインストールするには、次のようにします。

   Debian/Ubuntu/Mint

   gitlab-runnerバージョンv17.7.1の時点では、最新バージョンではない特定のバージョンのgitlab-runnerをインストールする場合、そのバージョンに必要なgitlab-runner-helper-packagesを明示的にインストールする必要があります。この要件は、apt/apt-getの制限により存在しています。

   apt-cache madison gitlab-runner
   sudo apt install gitlab-runner=17.7.1-1 gitlab-runner-helper-images=17.7.1-1

   特定バージョンのgitlab-runnerをインストールするときに、同じバージョンのgitlab-runner-helper-imagesをインストールしないと、次のようなエラーが発生する可能性があります。

   sudo apt install gitlab-runner=17.7.1-1
   ...
   The following packages have unmet dependencies:
    gitlab-runner : Depends: gitlab-runner-helper-images (= 17.7.1-1) but 17.8.3-1 is to be installed
   E: Unable to correct problems, you have held broken packages.

   RHEL/CentOS/Fedora/Amazon Linux

   yum list gitlab-runner --showduplicates | sort -r
   sudo yum install gitlab-runner-17.2.0-1

4. Runnerを登録します。

上記の手順を完了すると、Runnerを起動してプロジェクトで使用できるようになります。

FAQセクションを参照してください。このセクションでは、GitLab Runnerに関する最も一般的な問題について説明しています。

ヘルパーイメージパッケージ

gitlab-runner-helper-imagesパッケージには、GitLab Runnerがジョブの実行中に使用する、構築済みのヘルパーコンテナイメージが含まれています。これらのイメージは、リポジトリのクローンを作成し、アーティファクトをアップロードし、キャッシュを管理するために必要なツールとユーティリティを提供します。

gitlab-runner-helper-imagesパッケージには、次のオペレーティングシステムとアーキテクチャ用のヘルパーイメージが含まれています:

Alpineベースのイメージ（最新）:

• alpine-arm
• alpine-arm64
• alpine-riscv64
• alpine-s390x
• alpine-x86_64
• alpine-x86_64-pwsh

Ubuntuベースのイメージ（24.04）:

• ubuntu-arm
• ubuntu-arm64
• ubuntu-ppc64le
• ubuntu-s390x
• ubuntu-x86_64
• ubuntu-x86_64-pwsh

ヘルパーイメージの自動ダウンロード

特定のオペレーティングシステムとアーキテクチャの組み合わせ用のヘルパーイメージがホストシステムで使用できない場合、GitLab Runnerは必要に応じて必要なイメージを自動的にダウンロードします。gitlab-runner-helper-images packageに含まれていないアーキテクチャの場合、手動インストールは必要ありません。この自動ダウンロードにより、runnerは、手動での介入や個別のパッケージインストールを必要とせずに、追加のアーキテクチャ（loong64など）をサポートできます。

GitLab Runnerをアップグレードする

最新バージョンのGitLab Runnerをインストールするには、次のようにします。

sudo apt update
sudo apt install gitlab-runner

sudo yum update
sudo yum install gitlab-runner

PackageインストールのGPG署名

GitLab Runnerプロジェクトは、パッケージインストール方法に対して2種類のGPG署名を提供しています。

• リポジトリメタデータの署名
• パッケージの署名

リポジトリメタデータの署名

リモートリポジトリからダウンロードしたパッケージ情報が信頼できるものであることを検証するために、パッケージマネージャーはリポジトリメタデータの署名を使用します。

この署名は、apt-get updateなどのコマンドを使用するときに検証されます。このため、パッケージのダウンロードとインストールが行われる前に、利用可能なパッケージに関する情報が更新されます。検証に失敗した場合、パッケージマネージャーはメタデータを拒否します。つまり、署名の不一致の原因となった問題が見つかって解決されるまで、リポジトリからパッケージをダウンロードしてインストールすることはできません。

パッケージメタデータ署名の検証に使用されるGPG公開キーは、上記の手順で最初に行われたインストール時に自動的にインストールされます。今後のキーの更新では、既存のユーザーが新しいキーを手動でダウンロードしてインストールする必要があります。

https://packages.gitlab.comでホストされているすべてのプロジェクトに対して1つのキーを使用します。使用されているキーの詳細は、Linuxパッケージのドキュメントで確認できます。このドキュメントページには、過去に使用されたすべてのキーも記載されています。

パッケージの署名

リポジトリメタデータの署名は、ダウンロードされたバージョン情報がhttps://packages.gitlab.comからのものであることを証明します。パッケージ自体の整合性を証明するものではありません。リポジトリからユーザーへのメタデータ転送が影響を受けていない限り、https://packages.gitlab.comにアップロードされたものはすべて、承認されているかどうかにかかわらず、適切に検証されます。

パッケージ署名では、各パッケージがそのビルド時に署名されます。ビルド環境と使用されているGPGキーの機密性を信頼できるようになるまで、パッケージの信頼性を検証できません。パッケージの有効な署名は、その出所が認証されており、その整合性が侵害されていないことを証明します。

パッケージ署名検証は、Debian/RPMベースのディストリビューションの一部でのみデフォルトで有効になっています。このタイプの検証を使用するには、設定の調整が必要になる場合があります。

https://packages.gitlab.comでホストされているリポジトリごとに、パッケージ署名検証に使用されるGPGキーが異なる場合があります。GitLab Runnerプロジェクトでは、このタイプの署名に独自のキーペアを使用します。

RPMベースのディストリビューション

RPM形式には、GPG署名機能の完全な実装が含まれており、この形式に基づくパッケージマネージャーと完全に統合されています。

Linuxパッケージのドキュメントに、RPMベースのディストリビューションのパッケージ署名検証を設定する方法に関する技術的な説明があります。GitLab Runnerでの違いは次のとおりです。

• インストールする必要がある公開キーパッケージの名前はgpg-pubkey-35dfa027-60ba0235です。
• RPMベースのディストリビューションのリポジトリファイルの名前は、/etc/yum.repos.d/runner_gitlab-runner.repo（安定版リリースの場合）または/etc/yum.repos.d/runner_unstable.repo（不安定版リリースの場合）です。
• パッケージ署名公開キーは、https://packages.gitlab.com/runner/gitlab-runner/gpgkey/runner-gitlab-runner-49F16C5CC3A0F81F.pub.gpgからインポートできます。

Debianベースのディストリビューション

deb形式は、公式にはパッケージ署名機能をデフォルトで備えていません。GitLab Runnerプロジェクトでは、パッケージの署名と検証にdpkg-sigツールを使用します。この方法では、パッケージの手動検証のみがサポートされています。

debパッケージを検証するには、次の手順に従います。

1. dpkg-sigをインストールします。

   apt update && apt install dpkg-sig

2. パッケージ署名公開キーをダウンロードしてインポートします。

   curl -JLO "https://packages.gitlab.com/runner/gitlab-runner/gpgkey/runner-gitlab-runner-49F16C5CC3A0F81F.pub.gpg"
   gpg --import runner-gitlab-runner-49F16C5CC3A0F81F.pub.gpg

3. dpkg-sigでダウンロードしたパッケージを検証します。

   dpkg-sig --verify gitlab-runner_amd64.deb
   Processing gitlab-runner_amd64.deb...
   GOODSIG _gpgbuilder 931DA69CFA3AFEBBC97DAA8C6C57C29C6BA75A4E 1623755049

   パッケージの署名が無効であるか、無効なキー（失効したキーなど）で署名されている場合、出力は次のようになります。

   dpkg-sig --verify gitlab-runner_amd64.deb
   Processing gitlab-runner_amd64.deb...
   BADSIG _gpgbuilder

   キーがユーザーのキーリングに存在しない場合、出力は次のようになります。

   dpkg-sig --verify gitlab-runner_amd64.v13.1.0.deb
   Processing gitlab-runner_amd64.v13.1.0.deb...
   UNKNOWNSIG _gpgbuilder 880721D4

現在のGPG公開キー

https://packages.gitlab.com/runner/gitlab-runner/gpgkey/runner-gitlab-runner-49F16C5CC3A0F81F.pub.gpgからパッケージ署名に使用される現在の公開GPGキーをダウンロードできます。

過去のGPG公開キー

過去に使用されたキーを以下の表に示します。

失効したキーは、パッケージ署名検証設定から削除することを強くお勧めします。

次のキーによって作成された署名は、信頼すべきではありません。

トラブルシューティング

GitLab Runnerのインストール時に発生する問題のトラブルシューティングと解決のためのヒントを以下に示します。

エラー: No such file or directoryジョブの失敗

デフォルトのスケルトン（skel）ディレクトリが原因でGitLab Runnerで問題が発生し、ジョブの実行に失敗することがあります。イシュー4449とイシュー1379を参照してください。

これを回避するために、GitLab Runnerをインストールすると、gitlab-runnerユーザーが作成され、デフォルトでは、ホームディレクトリはスケルトンなしで作成されます。skelの使用によってホームディレクトリに追加されるShell設定は、ジョブの実行を妨げる可能性があります。この設定は、前述のような予期しない問題を引き起こす可能性があります。

skelの回避がデフォルトの動作になる前にRunnerを作成していた場合は、次のドットファイルを削除してみてください。

sudo rm /home/gitlab-runner/.profile
sudo rm /home/gitlab-runner/.bashrc
sudo rm /home/gitlab-runner/.bash_logout

skelディレクトリを使用して、新しく作成された$HOMEディレクトリにデータを入力する必要がある場合は、Runnerをインストールする前に、GITLAB_RUNNER_DISABLE_SKEL変数を明示的にfalseに設定する必要があります。

export GITLAB_RUNNER_DISABLE_SKEL=false; sudo -E apt-get install gitlab-runner

export GITLAB_RUNNER_DISABLE_SKEL=false; sudo -E yum install gitlab-runner