【無料ユーザーでも使えます！】GitLabのCI/CD変数を完全に隠せる「Masked and hidden」機能を使ってみよう(GitLab 17.4以降)

はじめに

「GitLabって有料プランじゃないと大した機能使えないんでしょ?」と思っている方、実はそんなことありません。

GitLabにはCI/CDパイプラインの中でパスワードやAPIキーなどの秘密情報を扱うための「CI/CD変数」という仕組みがありますが、その中でも 「Masked and hidden(マスク&非表示)」 という設定は、Free(無料)プランのユーザーでも問題なく使うことができます。

この記事では、プロジェクト・グループの変数としてはGitLab 17.4で追加され、GitLab 17.6でGA(正式リリース)となった「Hide CI/CD variable values in the UI」という機能を中心に、無料ユーザーがもっとGitLabを使いこなせるように、わかりやすく解説していきます。

対象読者

GitLabのFreeプランを使っている方
CI/CDパイプラインでAPIキーやパスワードなどの秘密情報を扱っている方
「Masked」と「Hidden」の違いがよくわかっていない方

この機能の対応バージョンとプラン

まずバージョンとプランをはっきりさせておきます。ここは単位(プロジェクト/グループ/インスタンス)によって対応バージョンが異なるので注意してください。

導入バージョン(プロジェクト単位・グループ単位): GitLab 17.4(フィーチャーフラグ ci_hidden_variables 付き、デフォルトで有効)
GA(正式リリース)バージョン(プロジェクト単位・グループ単位): GitLab 17.6(フィーチャーフラグは削除済み)
導入バージョン(インスタンス単位/Admin領域): GitLab 19.0。Self-Managedで管理者がインスタンス全体の変数に対して「Masked and hidden」を使いたい場合は、19.0以降が必要です。
対応プラン: Free、Premium、Ultimateのすべて
対応環境: GitLab.com、GitLab Self-Managed、GitLab Dedicated

つまり、プロジェクトやグループの変数であればGitLab 17.6以降、無料ユーザーも含めて誰でも安心してこの機能を使えます。一方、インスタンス全体の変数として使いたい場合は、もう少し新しいバージョン(19.0以降)が必要になるので、Self-Managedを運用している方は自分のGitLabのバージョンを確認しておきましょう。

そもそもCI/CD変数とは

CI/CD変数は、.gitlab-ci.yml に値をハードコーディングせずに、ジョブやパイプラインの動作を制御したり、繰り返し使う値を保存したりするための仕組みです。

パスワードやトークンのような秘密情報は、.gitlab-ci.yml ファイルに直接書くのではなく、プロジェクトやグループの設定画面(UI)から登録するのが基本です。.gitlab-ci.yml に書いた変数はリポジトリにアクセスできる全員に見えてしまうため、機密情報の管理には向いていません。

「Masked(マスク)」だけでは不十分だった理由

これまでGitLabには、CI/CD変数の値をジョブログに表示させないための「Masked(マスク)」という設定がありました。マスクを設定すると、ジョブのログ出力で値が [MASKED] という文字列に置き換えられます。

ただし、このマスクにはひとつの弱点がありました。ジョブログには表示されなくなるものの、設定画面(UI)上では、権限を持つ人であればいつでも値を再表示できてしまうという点です。

つまり、「ログに出さない」ことはできても、「そもそも誰にも見せない」ということはできなかったわけです。

新機能「Hide(非表示)」でできること

GitLab 17.4で追加された機能によって、「Masked and hidden(マスクして、かつ非表示にする)」 という新しい可視性(Visibility)オプションが使えるようになりました。

このオプションを選ぶと、値を保存した後は、CI/CDの設定画面において、その値を今後誰も再表示できなくなります。管理者権限を持っていたとしても、一度保存された値は二度と画面上に表示されません。もちろん、パイプラインの実行時には環境変数として問題なく利用できます。

これによって、うっかり画面共有をしてしまった、あるいは退職者に一時的に見せてしまった、といったヒューマンエラーのリスクを大きく減らすことができます。

使い方

設定できるのはプロジェクト単位、グループ単位、インスタンス単位のいずれでも可能です(インスタンス単位はGitLab 19.0以降)。ここではプロジェクトの例で説明します。

上部の検索バーから対象のプロジェクトを開く
左サイドバーの「Settings」→「CI/CD」を選択
「Variables」セクションを展開
「Add variable」を選択し、以下を入力
- Key: 変数名(スペースなし、英数字と _ のみ)
- Value: 実際の値
- Visibility: 「Masked and hidden」を選択
「Add variable」を選択して保存

これだけで完了です。とても簡単ですね。

注意点

いくつか気をつけておきたいポイントがあります。

既存の変数を後から非表示にすることはできません。 非表示(Hidden)にできるのは、新規作成のタイミングのみです。既存の変数を非表示化したい場合は、いったん削除して新しく作り直す必要があります。
マスクの条件を満たす必要があります。 具体的には、値がスペースを含まない1行であること、8文字以上であること、既存の定義済み変数やカスタム変数の名前と一致しないことが求められます。この条件を満たさない値は非表示にできません。
値の文字数には注意。 Valueは通常10,000文字まで入力できますが、VisibilityをMaskedまたはMasked and hiddenにする場合は、使える文字種に追加の制限がかかります。
「Expand variable reference」のチェックは外しておくのがおすすめです。 これをオンにしたままだと、値に使える特殊文字がかなり限定されてしまいます(_、:、@、-、+、.、~、=、/のみ)。マスクや非表示を使う場合は基本的にオフのままにしておきましょう。
非表示にしても、絶対に安全というわけではありません。 GitLabの公式ドキュメントでも触れられていますが、マスクや非表示は悪意のあるユーザーによる不正アクセスを完全に防ぐことを保証するものではありません。本当に重要な秘密情報については、env や printenv のようなコマンドで値が出力されてしまうことを防ぐために、外部のシークレット管理サービスや、File型のCI/CD変数の利用も検討するとよいでしょう。

まとめ

「Masked and hidden」は、プロジェクト・グループの変数としてはGitLab 17.4で導入され、GitLab 17.6で正式リリースされた機能で、Freeプランのユーザーでも今日から使うことができます。

CI/CDのAPIキーやパスワードを扱っている方は、ぜひこの機会に「マスクするだけ」から「表示させない」へ一歩進んだ運用に切り替えてみてください。

無料プランでもこうした地道だけれど実用的なセキュリティ機能がどんどん追加されているのがGitLabの魅力のひとつです。この記事を読んで少しでも「GitLab、もっと使いこなせそう」と思っていただけたら幸いです。

参考

GitLab 17.4 リリースノート(https://about.gitlab.com/ja-jp/blog/gitlab-17-4-released/)
GitLab公式ドキュメント「CI/CD variables」