環境変数の使用

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

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

概要

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

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

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

Use Contexts to further restrict access to environment variables. CircleCI アプリケーションの [Organization Settings (組織設定)] で設定します。 For more information about controlling access to env vars with Contexts, refer to the Restricting a Context documentation.

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

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

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

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

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

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

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

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

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

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

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

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

優先順位

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

1. FOO=bar make install など、run ステップのシェル コマンドで宣言された環境変数
2. run ステップで environment キーを使用して宣言された環境変数
3. ジョブで environment キーを使用して設定された環境変数
4. このドキュメントの「CircleCI 定義済み環境変数」セクションで解説されている特別な CircleCI 環境変数
5. コンテキスト環境変数 (ユーザーがコンテキストへのアクセス権を持つ場合)。 手順については、コンテキストに関するドキュメントを参照してください。
6. [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: # basic units of work in a run
  build:
    docker: # use the Docker executor
      # CircleCI node images available at: https://hub.docker.com/r/circleci/node/
      - image: circleci/node:10.0-browsers
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
    steps: # steps that comprise the `build` job
      - checkout # check out source code to working directory
      # Run a step to setup an environment variable
      # Redirect MY_ENV_VAR into $BASH_ENV
      - run:
          name: "Setup custom environment variables"
          command: echo 'export MY_ENV_VAR="FOO"' >> $BASH_ENV
      - run: # print the name of the branch we're on
          name: "What branch am I on?"
          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

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

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

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 を使用して値をエクスポートします。

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

コンテキスト シークレットのマスキングによって環境変数を非公開に保つ (英語)

version: 2.1

jobs:
  build:
    docker:

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

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

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

1. CircleCI アプリケーションで、左のナビゲーションにあるリンクをクリックして、[Organization Settings (組織設定)] に移動します。

   

2. 環境変数を関連付けるコンテキストを選択するか、[Create Context (コンテキストを作成)] ボタンをクリックして新しいコンテキストを作成します。
3. [Add Environment Variable (環境変数を追加)] をクリックし、名前と値を入力します。
4. 以下のように .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

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

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

1. CircleCI アプリケーションで、プロジェクトを選択し [Pipelines (パイプライン)] ページにある歯車アイコンをクリックするか、他のページで 3 つの点をクリックして、プロジェクトの設定に移動します。

   

2. [Environment Variables (環境変数)] をクリックします。
3. [Add Variable (変数の追加)] ボタンをクリックして新しい変数を追加し、名前と値を入力します。
4. 以下のように .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 トークンです。

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

export param1="value1"
export param2="500"

POST API 呼び出しを使用して実行を開始します。 詳細については、API ドキュメントで新しいビルドのセクションを参照してください。 本体が空の POST は、指定されたブランチの新しい実行を開始します。

定義済み環境変数

以下の環境変数はビルドごとにエクスポートされ、より複雑なテストやデプロイに使用できます。

注: 定義済み環境変数を使用して別の環境変数を定義することはできません。 代わりに、run ステップを使用して、新しい環境変数を BASH_ENV でエクスポートする必要があります。

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

注: パイプライン値とパラメーターの一覧については、「パイプライン変数」を参照してください。

関連項目

Contexts Keep environment variables private with secret masking

---

Help make this document better

This guide, as well as the rest of our docs, are open-source and available on GitHub. We welcome your contributions.

• Suggest an edit to this page (please read the contributing guide first).
• To report a problem in the documentation, or to submit feedback and comments, please open an issue on GitHub.
• CircleCI is always seeking ways to improve your experience with our platform. If you would like to share feedback, please join our research community.

---

CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.