CircleCIの環境変数の使い分け #Slack

こんにちは。
CircleCI カスタマーサクセスチームの Chisato です。
最近個人的に幸せだった出来事は、かぶの美味しさにあらためて気付けたことです。

今回は CircleCI の環境変数についてご紹介します。

環境変数

CircleCIでは環境変数が複数提供されています。
ユーザーが設定できるのは下記の３種類で、名前と値のペアで定義します。

インライン環境変数
プロジェクトでの環境変数
コンテキストでの環境変数

インライン環境変数

直接 config.yml ファイル（設定ファイル）に書き込む環境変数です。
ステップ（run ステップまたは deploy ステップ）、ジョブ、イメージと、小さい範囲で簡単に設定できます。
弊社のMakotoさんは、デプロイ先の設定などでよく使っているそうです。
ステップ、ジョブ、コンテナでの設定には、Environmentキーを用います。

Config.yml ファイルを見れば定義や値を確認できてしまうので、利用の際はご注意ください。
例えば下記に該当する場合は「使用しない」ほうが良いです。

モノレポ
秘匿情報
値の影響範囲が大きい

ステップでの設定

環境変数は設定したステップでのみ利用できるため、他のステップには引き継がれません。（ドキュメンテーション）

    steps:
      - checkout
      - run:
          name: こんにちは
          command: echo $SAY
          environment:
           SAY: Hello

ジョブでの設定

当該ジョブの中で実行されるすべてのステップで利用できます。あるステップで同じ環境変数名を定義すると、値が上書きされます。
（ドキュメンテーション）

jobs:
  build:
    docker:
      - image: cimg/base:stable
    environment:
      MY_ENV_VAR_1: my-value-1

イメージでの設定

dockerキーのイメージと合わせて設定します。
プライマリコンテナイメージ (最初にリストされたイメージ) とセカンダリサービスコンテナイメージにそれぞれ設定できます。
『CircleCI実践入門 CI/CDがもたらす開発速度と品質の両立』(p.102)では、下記のように使い分けることが推奨されています。

コンテナの中で動作するアプリケーション → イメージで定義
ステップ内で利用するもの → ステップで定義

jobs:
  build:
    docker:
      - image: cimg/base:stable
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD
        environment:
          MY_ENV_VAR_1: my-value-1

（ドキュメンテーション）

プロジェクトでの環境変数

プライベート、パブリックの両方のレポジトリにおいて、シークレットを安全に格納できます。
プロジェクトごとの設定なので、該当するプロジェクトでのみ利用したい環境変数の設定に便利です。

CircleCIのUIから、該当するプロジェクトを選択します。
[Project Settings]ページに移動し、[Environment Variables]をクリックします。
[Add Environment Variables]をクリックして、環境変数を追加します。

シークレットのマスキング

プロジェクトやコンテキストで設定される環境変数はマスキングされており、echoコマンドなどの出力結果にも表示されません。
ただし、次の場合はシークレットが閲覧できるので注意が必要です。

環境変数の値が４文字以下
値が次のどれか：true, True, false, False
別の場所に出力する場合（テスト結果やアーティファクト）
SSHを使用したデバッグ（これを実行するユーザーは、シークレットにアクセスできる）

コンテキストでの環境変数

コンテキストには「環境変数を保護し、プロジェクト間で共有する」役割があります。
複数のプロジェクト間で環境変数を共有したい時にたいへん便利です。
コンテキストの環境変数はジョブ単位の設定も可能です。

下記の手順で設定できます。

[Organization Settings] → [Context]と遷移し、[Create Context]をクリックします。

コンテキスト名を入力して、[Create Context]をクリックします。
次に、[Add Environment Variables]をクリックして環境変数を入力します。

今回はコンテキストを用いて、人気の Slack orb を試してみました。
こちらのページを参考に環境変数を設定します。
Slack API website から[Create New App]を選択して該当項目を埋めます。
SLACK_ACCESS_TOKENにはOAuth tokenを、SLACK_DEFAULT_CHANNELにはチャネルのIDをそれぞれ値として設定します。
（チャネルのURLのうち、/archives/の後の文字列がIDにあたります。）

これで、Slack_notify というコンテキストの環境変数が設定できました。
デフォルト設定のチャネル #general にSlack通知が届くか検証します。
下記は、Slack orbのページの例を引用しています。
（最下部のコンテキスト名は自分で設定したものに変更）

version: '2.1'
orbs:
  slack: circleci/slack@4.1
jobs:
  notify:
    docker:
      - image: 'cimg/base:stable'
    steps:
      - slack/notify:
          custom: |
            {
              "blocks": [
                {
                  "type": "section",
                  "fields": [
                    {
                      "type": "plain_text",
                      "text": "*This is a text notification*",
                      "emoji": true
                    }
                  ]
                }
              ]
            }
          event: always
workflows:
  send-notification:
    jobs:
      - notify:
          context: Slack_notify

実行してみると..

シュットトト（♪)

無事に通知を受け取ることができました。

制限付きコンテキスト

制限付きコンテキストを設定すると、指定したセキュリティグループに所属するメンバーのみ、該当するコンテキストにアクセスしたり、そのコンテキストを用いたワークフローを実行したりできます。
（グループに属さないメンバーが実行を試みると、"Unauthorized" でジョブが失敗します。）

下記方法で設定できます。
GitHubで [Your Organization] → [Teams]と遷移し、Team を作成します。

CircleCI で該当するコンテキストを開きます。デフォルトでは All members、つまりすべてのメンバーが登録されています。

[Add Security Group] をクリックして、追加したいグループを選択、追加します。

セキュリティグループを追加したら、合わせて All members の削除を行います。

セキュリティグループの指定が完了しました。

制限付きコンテキストは、スケジュール・パイプラインで設定や実行の管理者を制限したい場合などに便利です。

まとめ

今回ブログの執筆にあたり、Customer EngineeringチームのAaronさん、Naoyaさん、そしてMakotoさんにご指導いただきました。
今度お礼に八ヶ岳のかぶを差し上げたいと思います。

読者の皆さまには、環境変数を使いこなして、CircleCIを快適にご利用いただければ幸いです。
最後までお読みいただきありがとうございました。

技術的なご質問はこちら：サポートセンター

参考文献

浦井誠人, 大竹智也, 金洋国（2020）.『CircleCI実践入門 CI/CDがもたらす開発速度と品質の両立』.技術評論社
技術評論社書籍ページ

CircleCIドキュメンテーション
https://circleci.com/docs

Slack Orb
https://circleci.com/developer/orbs/orb/circleci/slack

Slack orb のセットアップ
https://github.com/CircleCI-Public/slack-orb/wiki/Setup