環境変数の使用

以下のセクションに沿って、CircleCI で環境変数を使用する方法について説明します。

シークレットのマスキング
組織とリポジトリの名前変更
環境変数の使用オプション
シェルコマンドでの環境変数の設定
ステップでの環境変数の設定
ジョブでの環境変数の設定
コンテキストでの環境変数の設定
プロジェクトでの環境変数の設定
コンテナでの環境変数の設定
API v2 を使用した環境変数の挿入
API v1 を使用した環境変数の挿入
定義済み環境変数

概要

CircleCI では、スコープや認証レベルに幅を持たせるために、環境変数の使用方法を複数提供しています。環境変数は、その設定方法によって優先順位に基づいて使用され、構成において各レベルで制御することができます。

プライベートプロジェクト全体で使用するプライベートキーまたはシークレット環境変数を追加するには、CircleCI アプリケーションで [Project Settings (プロジェクト設定)] の [Environment Variables (環境変数)] ページに移動します。設定された後の変数の値は、アプリで読み取ることも編集することもできません。環境変数の値を変更するには、現在の変数を削除し、新しい値を設定して再度追加します。

プライベート環境変数を使用すると、プロジェクトがパブリックの場合でもシークレットを安全に格納できます。関連する設定情報については、「オープンソースプロジェクトの構築」ページを参照してください。

コンテキストを使用して環境変数へのアクセスを制御する方法について、詳細は「コンテキストの制限」を参照してください。 CircleCI アプリケーションの [Organization Settings (組織設定)] で設定します。コンテキストを使用して環境変数へのアクセスを制御する方法について、詳細は「コンテキストの制限」を参照してください。

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

シークレットのマスキングは、オンプレミス版である CircleCI Server では現在サポートされていません。

シークレットのマスキングは、[Project Settings (プロジェクト設定)] または [Contexts (コンテキスト)] で設定されている環境変数に適用されます。環境変数は、プロジェクトのシークレットやキーを保持します。シークレットやキーはアプリケーションにとってきわめて重要なものです。シークレットのマスキングは、echo や print が使用される際にジョブ出力における環境変数を不明瞭にすることで、CircleCI のセキュリティを強化します。

以下の場合、環境変数の値はビルドの出力でマスキングされません。

環境変数の値が 4 文字未満
環境変数の値が true、True、false、False のいずれか

注: シークレットのマスキングは、ビルドの出力で環境変数の値が表示されないようにするだけの機能です。環境変数の値には、SSH を使用したデバッグを行うユーザーがアクセスできます。

組織とリポジトリの名前変更

過去に CircleCI に接続した組織やリポジトリの名前を変更する場合は、以下の手順を参考にしてください。

VCS で組織またはリポジトリの名前を変更します。
新しい組織またはリポジトリの名前を使用して CircleCI アプリケーションにアクセスします (例: app.circleci.com/pipelines/<VCS>/<new-org-name>/<project-name>)。
プラン、プロジェクト、設定が正常に転送されたことを確認します。
これで、必要に応じて VCS の古い名前で新しい組織やリポジトリを作成できます。

注: この手順を実行しないと、環境変数やコンテキストなど、組織またはリポジトリの設定にアクセスできなくなる可能性があります。

環境変数の使用オプション

CircleCI は Bash を使用しますが、ここでは POSIX 命名規則に従った環境変数が使用されます。有効な文字は、アルファベット (大文字と小文字)、数字、およびアンダースコアです。環境変数の最初の文字はアルファベットにする必要があります。

優先順位

環境変数は、以下に示す優先順位に従って使用されます。

FOO=bar make install など、run ステップのシェルコマンドで宣言された環境変数
run ステップで environment キーを使用して宣言された環境変数
ジョブで environment キーを使用して設定された環境変数
このドキュメントの「CircleCI 定義済み環境変数」セクションで解説されている特別な CircleCI 環境変数
コンテキスト環境変数 (ユーザーがコンテキストへのアクセス権を持つ場合)。手順については、コンテキストに関するドキュメントを参照してください。
[Project Settings (プロジェクト設定)] ページで設定されたプロジェクトレベルの環境変数

FOO=bar make install のように、run ステップのシェルコマンドで宣言された環境変数は、environment キーおよび contexts キーを使用して宣言された環境変数よりも優先されます。 [Contexts (コンテキスト)] ページで追加された環境変数は、[Project Settings (プロジェクト設定)] ページで追加された変数よりも優先されます。

環境変数の優先順位

セキュリティに関する注意事項

.circleci/config.yml ファイル内にシークレットやキーを追加しないでください。 CircleCI 上のプロジェクトにアクセスできる開発者には、config.yml の全文が表示されます。シークレットやキーは、CircleCI アプリケーションのプロジェクト設定またはコンテキスト設定に格納してください。詳細については、セキュリティに関するドキュメントの「暗号化」セクションを参照してください。

構成内でスクリプトを実行すると、シークレット環境変数が公開される場合があります。安全なスクリプトのベストプラクティスについては、「シェルスクリプトの使用」を参照してください。

環境変数の構成例

以下のような config.yml を例に考えてみましょう。

version: 2.1

jobs: # 1 回の実行の基本作業単位
  build: 
    docker: # Docker Executor を使用
      # CircleCI ノード イメージは https://hub.docker.com/r/circleci/node/ で入手できます

      - image: circleci/node:10.0-browsers
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # コンテキスト/プロジェクト UI 環境変数の参照
    steps: # `build` ジョブを構成するステップ
      - checkout # ソースコードを作業ディレクトリにチェックアウトします
      # 環境変数をセットアップするステップを実行します
      # MY_ENV_VAR を $BASH_ENV にリダイレクトします
      - run: 
          name: "カスタム環境変数のセットアップ"
          command: echo 'export MY_ENV_VAR="FOO"' >> $BASH_ENV
      - run: # 現在のブランチの名前を表示
          name: "今いるブランチを表示"
          command: echo ${CIRCLE_BRANCH}
      # 上と同様に、別のステップを実行します
      # 中かっこなしで環境変数を呼び出せることに注意してください
      - run:
          name: "今いるブランチを表示"
          command: echo $CIRCLE_BRANCH
      - run:
          name: "設定したカスタム環境変数を表示"
          command: echo ${MY_ENV_VAR}
      - run:
          name: "プロジェクトに格納されている環境変数を表示"
          command: echo ${PROJECT_ENV_VAR}
      - run:
          name: "コンテキストに格納されている環境変数を表示"
          command: echo ${CONTEXT_ENV_VAR}

workflows: # build という単一のジョブを持つ単一のワークフロー
  build:
    jobs:

      - build:
          context: Testing-Env-Vars
          command: echo ${CIRCLE_BRANCH}
      # Run another step, the same as above; note that you can
      # invoke environment variable without curly braces.
      - run:
          name: "What branch am I on now?"
          command: echo $CIRCLE_BRANCH
      - run:
          name: "What was my custom environment variable?"
          command: echo ${MY_ENV_VAR}
      - run:
          name: "Print an env var stored in the Project"
          command: echo ${PROJECT_ENV_VAR}
      - run:
          name: "Print an env var stored in a Context"
          command: echo ${CONTEXT_ENV_VAR}

workflows: # a single workflow with a single job called build
  build:
    jobs:
      - build:
          context: Testing-Env-Vars

この config.yml では以下が行われます。

カスタム環境変数の設定
CircleCI が提供する定義済み環境変数 (CIRCLE_BRANCH) の読み取り
config.yml での変数の使用 (または挿入)
プロジェクトまたはコンテキストで設定される環境変数に適用されるシークレットのマスキング

この設定ファイルを実行すると、下図のように出力されます。プロジェクトに格納されている環境変数がマスキングされ、**** と表示されていることに注目してください。

環境変数の挿入例

上の設定ファイルと出力には、「今いるブランチを表示」という 2 つの類似するステップが含まれています。これらのステップは、環境変数を読み取るための 2 つの方法を示しています。なお、${VAR} 構文と $VAR 構文のどちらもサポートされています。シェルパラメーターの展開については、Bash のドキュメントを参照してください。

パラメーターと Bash 環境の使用

原則として、CircleCI はビルド構成への環境変数の挿入をサポートしていません。使用する値はリテラルとして扱われます。そのため、working_directory を定義するときや、PATH を変更するとき、複数の run ステップで変数を共有するときに、問題が発生する可能性があります。

ただし、プライベートイメージをサポートするため、Docker イメージセクションは例外となっています。

以下の例では、$ORGNAME と $REPONAME に挿入は行われません。

working_directory: /go/src/github.com/$ORGNAME/$REPONAME

version: 2.1 の設定ファイルを使用すると、config.yml 全体の構成の一部を再利用できます。以下のように parameters 宣言を使用することで、再利用可能な commands jobs や executors に挿入を行う (値を渡す) ことができます。

version: 2.1

jobs:
  build:
    parameters:
      org_name:
        type: string
        default: my_org
      repo_name:
        type: string
        default: my_repo
    docker:

      - image: circleci/go:1.15.0
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # コンテキスト/プロジェクト UI 環境変数の参照
    steps:
      - run: echo "project directory is go/src/github.com/<< parameters.org_name >>/<< parameters.repo_name >>"

workflows:
  my_workflow:
    jobs:

      - build:
          org_name: my_organization
          repo_name: project1

      - build:
          org_name: my_organization
          repo_name: project2

詳細については、「parameters 宣言の使用」を参照してください。

設定ファイルに値を挿入する方法として、以下のように、run ステップを使用して環境変数を BASH_ENV にエクスポートすることもできます。

steps:
  - run:
      name: 環境変数のセットアップ
      command: |
        echo "export PATH=$GOPATH/bin:$PATH" >> $BASH_ENV
        echo "export GIT_SHA1=$CIRCLE_SHA1" >> $BASH_ENV

各ステップで、CircleCI は bash を使用して BASH_ENV を取得します。つまり、BASH_ENV が自動的にロードおよび実行されることで、挿入を使用して複数の run ステップで環境変数を共有できるようになります。

注: この $BASH_ENV による回避策は bash でのみ機能します。他のシェルではおそらく機能しません。

Alpine Linux

Alpine Linux ベースのイメージ (Docker など) は ash シェルを使用します。

以下の 2 つのパラメーターをジョブに追加するだけで、bash で環境変数を使用できます。

version: 2.1

jobs:
  build:    
    shell: /bin/sh -leo pipefail
    environment:

      - BASH_ENV: /etc/profile

シェルコマンドでの環境変数の設定

CircleCI は環境変数の設定時の挿入をサポートしませんが、BASH_ENV を使用して、現在のシェルに変数を設定することは可能です。これは、PATH を変更するときや、他の変数を参照する環境変数を設定するときに便利です。

version: 2.1 

jobs:
  build:
    docker:

      - image: smaant/lein-flyway:2.7.1-4.0.3
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # コンテキスト/プロジェクト UI 環境変数の参照
    steps:
      - run:
          name: PATH の更新および実行時の環境変数の定義
          command: |
            echo 'export PATH=/path/to/foo/bin:$PATH' >> $BASH_ENV
            echo 'export VERY_IMPORTANT=$(cat important_value)' >> $BASH_ENV
            source $BASH_ENV

注: シェルによっては、~/.tcshrc や ~/.zshrc などのシェルスタートアップファイルに新しい変数を付加しなければならない場合があります。

詳細については、シェルのドキュメントで環境変数の設定方法を参照してください。

ステップでの環境変数の設定

1 つのステップで環境変数を設定するには、environment キーを使用します。

version: 2.1

jobs:
  build:
    docker:

      - image: smaant/lein-flyway:2.7.1-4.0.3
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # コンテキスト/プロジェクト UI 環境変数の参照
    steps:
      - checkout
      - run:
          name: 移行の実行
          command: sql/docker-entrypoint.sh sql
          # 単一のコマンド シェル用の環境変数
          environment:
            DATABASE_URL: postgres://conductor:@localhost:5432/conductor_test

注: 各 run ステップは新しいシェルなので、環境変数はステップ間で共有されません。複数のステップで環境変数にアクセスできるようにする必要がある場合は、BASH_ENV を使用して値をエクスポートします。

ジョブでの環境変数の設定

1 つのジョブで環境変数を設定するには、environment キーを使用します。

version: 2.1

jobs:
  build:
    docker:

      - image: buildpack-deps:trusty
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # コンテキスト/プロジェクト UI 環境変数の参照
    environment:
      FOO: bar

注: 7 桁以上の整数は指数表記に変換されます。これを回避するには、整数を文字列として格納してください (例: “1234567”)。

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

CircleCI アプリケーションで、左のナビゲーションにあるリンクをクリックして、[Organization Settings (組織設定)] に移動します。
環境変数を関連付けるコンテキストを選択するか、[Create Context (コンテキストを作成)] ボタンをクリックして新しいコンテキストを作成します。
[Add Environment Variable (環境変数を追加)] をクリックし、名前と値を入力します。
以下のように .circleci/config.yml ファイルで、workflows キーの下にコンテキストを追加してから、新しい環境変数を使用します。

version: 2.1

workflows:
  test-env-vars:
    jobs:

      - build:
          context: my_context_name # MY_ENV_VAR という名前の環境変数を持つ

jobs:
  build:
    docker:

      - image: cimg/base:2020.01
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # コンテキスト/プロジェクト UI 環境変数の参照
    steps:
      - checkout
      - run: 
          name: "コンテキストに含まれる環境変数を出力"
          command: |
            echo $MY_ENV_VAR

コンテキストを作成すると、複数のプロジェクト間で環境変数を共有すると共に、アクセス可能なユーザーを制御できるようになります。詳細については、コンテキストに関するドキュメントを参照してください。

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

CircleCI アプリケーションで、プロジェクトを選択し [Pipelines (パイプライン)] ページにある歯車アイコンをクリックするか、他のページで 3 つの点をクリックして、プロジェクトの設定に移動します。
[Environment Variables (環境変数)] をクリックします。
[Add Variable (変数の追加)] ボタンをクリックして新しい変数を追加し、名前と値を入力します。
以下のように .circleci/config.yml で、新しい環境変数を使用します。

version: 2.1

workflows:
  test-env-vars:
    jobs:

      - build

jobs:
  build:
    docker:

      - image: cimg/base:2020.01
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # コンテキスト/プロジェクト UI 環境変数の参照
    steps:
      - checkout
      - run: 
          name: "プロジェクトに含まれる環境変数を出力"
          command: |
            echo $MY_ENV_VAR # この環境変数はプロジェクト内で設定が必要

作成された環境変数は、アプリケーションに表示されず、編集することはできません。環境変数を変更するには、削除して作成し直すしかありません。

コンテナでの環境変数の設定

環境変数は Docker コンテナにも設定することができます。設定するには、environment キーを使用します。

注:: この方法で設定する環境変数は、コンテナ内で実行されるステップでは使用できません。これらを使用できるのは、コンテナによって実行されるエントリポイントとコマンドのみです。 CircleCI のデフォルトでは、ジョブのプライマリコンテナのエントリポイントは無視されます。プライマリコンテナの環境変数を利用可能にするには、エントリポイントを保持する必要があります。 For more information, see the adding an entrypoint section of the Custom Images guide.

version: 2.1

jobs:
  build:
    docker:

      - image: <image>:<tag>
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # コンテキスト/プロジェクト UI 環境変数の参照
        # 環境変数は Docker コンテナによって実行されるエントリポイント/コマンドに使用可能
        environment:
          MY_ENV_VAR_1: my-value-1
          MY_ENV_VAR_2: my-value-2

以下に、プライマリコンテナイメージ (最初にリストされたイメージ) とセカンダリ (サービス) コンテナイメージに、別々の環境変数を設定する例を示します。

version: 2.1

jobs:
  build:
    docker:

      - image: <image>:<tag>
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # コンテキスト/プロジェクト UI 環境変数の参照
        environment:
          MY_ENV_VAR_1: my-value-1
          MY_ENV_VAR_2: my-value-2
      - image: <image>:<tag>
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # コンテキスト/プロジェクト UI 環境変数の参照
        environment:
          MY_ENV_VAR_3: my-value-3
          MY_ENV_VAR_4: my-value-4

複数行にわたる環境変数のエンコード

複数行の環境変数を追加する際に問題が発生した場合は、base64 を使用してエンコードします。

$ echo "foobar" | base64 --wrap=0
Zm9vYmFyCg==

結果の値を CircleCI 環境変数に格納します。

$ echo $MYVAR
Zm9vYmFyCg==

その変数を使用するコマンド内で変数をデコードします。

$ echo $MYVAR | base64 --decode | docker login -u my_docker_user --password-stdin
Login Succeeded

注: すべてのコマンドラインプログラムが docker と同じ方法で認証情報を受け取るわけではありません。

API v2 を使用した環境変数の挿入

CircleCI API v2 を使用すると、パイプラインパラメーターから変数を渡すことができます。

パイプラインをトリガーする API v2`` エンドポイントを使用すると、特定のパラメーターの値でパイプラインをトリガーすることができます。これを実行するには、POST 本体の JSON パケット内で parameters キーを渡します。

下の例では、上記の設定ファイルの例で説明したパラメーターを使用して、パイプラインをトリガーしています (注: API からパイプラインをトリガーするときにパラメーターを渡すには、設定ファイルでパラメーターを宣言している必要があります)。

curl -u ${CIRCLECI_TOKEN}: -X POST --header "Content-Type: application/json" -d '{
  "parameters": {
    "workingdir": "./myspecialdir",
    "image-tag": "4.8.2"
  }
}' https://circleci.com/api/v2/project/:project_slug/pipeline

重要: パイプラインパラメーターは機密データとして扱われないため、機密の値 (シークレット) には使用しないでください。シークレットは、プロジェクト設定ページとコンテキストページで確認できます。

詳細については、「パイプライン変数」を参照してください。

API v1 を使用した環境変数の挿入

ビルドパラメーターは環境変数であるため、以下の条件に従って名前を付けます。

使用できるのは ASCII 文字、数字、アンダースコア文字のみです
先頭に数字を使用することはできません
少なくとも 1 文字を含む必要があります

環境変数の通常の制限以外には、値自体への制限はなく、単純な文字列として扱われます。ビルドパラメーターがロードされる順序は保証されないため、ビルドパラメーターに値を挿入して別のビルドパラメーターに渡すことは避けてください。ベストプラクティスとして、独立した環境変数から成る順不同のリストとしてビルドパラメーターを設定することをお勧めします。

重要: ビルドパラメーターは機密データとして扱われないため、機密の値 (シークレット) には使用しないでください。シークレットは、プロジェクト設定ページとコンテキストページで確認できます。

たとえば、以下のパラメーターを渡すとします。

{
  "build_parameters": {
    "foo": "bar",
    "baz": 5,
    "qux": {"quux": 1},
    "list": ["a", "list", "of", "strings"]
  }
}

このビルドは、以下の環境変数を受け取ります。

export foo="bar"
export baz="5"
export qux="{\"quux\": 1}"
export list="[\"a\", \"list\", \"of\", \"strings\"]"

ビルドパラメーターは、ジョブのコンテナ内の環境変数としてエクスポートされ、config.yml 内のスクリプトまたはプログラム、コマンドで使用できます。挿入された環境変数を使用して、ジョブの中で実行されるステップに影響を与えることができます。挿入された環境変数よりも config.yml やプロジェクト設定で定義された値が優先されるので、注意が重要です。

build_parameters キーを使用して環境変数を挿入することで、実行のたびに異なるターゲットに対して機能テストをビルドできます。たとえば、ステージング環境へのデプロイステップを持つ実行で、さまざまなホストに対する機能テストをビルドするとします。 bash と curl を使用した以下の例のように、JSON 本体を Content-type: application/json で送信することで、build_parameters を使用できます (ただし、選択した言語の HTTP ライブラリを使用することも可能です)。

{
  "build_parameters": {
    "param1": "value1",
    "param2": 500
  }
}

たとえば、以下のように curl を使用します。

curl \
  --header "Content-Type: application/json" \
  --header "Circle-Token: $CIRCLE_TOKEN" \
  --data '{"build_parameters": {"param1": "value1", "param2": 500}}' \
  --request POST \
  https://circleci.com/api/v1.1/project/github/circleci/mongofinil/tree/master

上の例の $CIRCLE_TOKEN はパーソナル API トークンです。