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

プラン: Free、Premium、Ultimate
提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated

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

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

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

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

ディストリビューション	サポート対象バージョン
Debian	Duke, Forky, Trixie, Bookworm, Bullseye
LinuxMint	Xia, Wilma, Virginia, Victoria, Vera, Vanessa
Raspbian	Duke, Forky, Trixie, Bookworm, Bullseye
Ubuntu	Questing, Noble, Jammy, Focal, Bionic

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

ディストリビューション	サポート対象バージョン
Amazon Linux	2025, 2023, 2
Red Hat Enterprise Linux	10、9、8、7
Fedora	43, 42
Oracle Linux	10、9、8、7
openSUSE	16.0、15.6
SUSE Linux Enterprise Server	15.7、15.6、15.5、15.4、12.5

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

リストにないディストリビューションのパッケージは、当社のパッケージリポジトリからは入手できません。これらは、S3バケットからRPMまたはDEBパッケージをダウンロードして、手動でインストールできます。

GitLab Runnerをインストールする

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

公式GitLabリポジトリを追加します:
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
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
最新バージョンのGitLab Runnerをインストールするか、次のステップに進んで特定のバージョンをインストールします:
sudo apt install gitlab-runner
sudo yum install gitlab-runner or sudo dnf install gitlab-runner

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

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.

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

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

パッケージインストールの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パッケージを検証するには、次の手順に従います:

dpkg-sigをインストールします:
```
apt update && apt install dpkg-sig
```

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

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

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キーをダウンロードできます。

キーの属性	値
名前	`GitLab, Inc.`
メール	`support@gitlab.com`
フィンガープリント	`931D A69C FA3A FEBB C97D AA8C 6C57 C29C 6BA7 5A4E`
有効期限	`2026-04-28`

GitLab Runnerプロジェクトでは、<https://gitlab-runner-downloads.s3.dualstack.us-east-1.amazonaws.com>バケットで利用可能なS3リリース用のrelease.sha256ファイルに署名するために、同じキーを使用します。

過去のGPG公開キー

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

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

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

シリアル番号	キーのフィンガープリント	状態	有効期限	ダウンロード（失効したキーのみ）
1	`3018 3AC2 C4E2 3A40 9EFB E705 9CE4 5ABC 8807 21D4`	`revoked`	`2021-06-08`	失効したキー
2	`09E5 7083 F34C CA94 D541 BC58 A674 BF81 35DF A027`	`revoked`	`2023-04-26`	失効したキー

トラブルシューティング

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

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

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

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

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

GitLab Runnerをインストールする

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

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

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

パッケージインストールのGPG署名

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

パッケージの署名

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

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

現在のGPG公開キー

過去のGPG公開キー

トラブルシューティング

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

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