Start Building for Free
CircleCI.comアカデミーブログコミュニティサポート

環境変数

6 days ago1 min read
クラウド
Server v3.x
Server v2.x
Helpful Resources
このページの内容

概要

CircleCI の環境変数は、設定方法に応じて 優先順位に基づいて使用され、設定ファイルの各レベルで制御することができます。

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

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

コンテキストを使用すると、環境変数へのアクセスを更に制限することができます。 コンテキストの設定は、CircleCI Web アプリケーションの Organization Settings (組織設定) で行います。

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

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

シークレットのマスキングは、Project Settings や Web アプリの Contexts で設定される環境変数に適用されます。 環境変数は、アプリケーションにおいてきわめて重要な機能を担うプロジェクトのシークレットやキーを保持している場合があります。 シークレットのマスキングにより、echoprint の使用時にジョブの出力の環境変数を隠すことで、CircleCI のセキュリティが強化されます。

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

  • 環境変数の値が 4 文字未満
  • 環境変数の値が trueTruefalseFalse のいずれか

別の場所 (テスト結果やアーティファクトなど) に出力されるシークレットはマスキングされません。 SSH を使用してデバッグを行うユーザーは、環境変数の値にアクセスできます。

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

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 キーを使用して宣言された環境変数よりも優先されます。 コンテキストページで追加された環境変数はプロジェクト設定ページで追加されたものより優先して使われます。

環境変数の優先順位

環境変数の設定例

以下のような 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://circleci.com/developer/images/image/cimg/node
      - image: cimg/node:17.2.0
        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 ステップで変数を共有するときに、問題が発生する可能性があります。

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

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

ただし、 プライベートイメージのプルプロジェクトのプルのための環境変数の使用は例外となっています。

version: 2.1 の設定ファイルを使用すると、config.yml 全体の設定の一部を再利用できます。 parameters 宣言を使用することで、再利用可能な commandsjobsexecutors に値を渡すことができます。

version: 2.1

jobs:
  build:
    parameters:
      org_name:
        type: string
        default: my_org
      repo_name:
        type: string
        default: my_repo
    docker:
      - image: cimg/go:1.17.3
        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: Setup Environment Variables
      command: |
        echo 'export PATH="$GOPATH"/bin:"$PATH"' >> "$BASH_ENV"
        echo 'export GIT_SHA1="$CIRCLE_SHA1"' >> "$BASH_ENV"

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

Alpine Linux

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

bash で環境変数を使用するには、ジョブに shell キーと environment キーを追加します。

version: 2.1

jobs:
  build:
    shell: /bin/sh -leo pipefail
    environment:
      BASH_ENV: /etc/profile

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

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

設定内でスクリプトを実行すると、シークレット環境変数が公開される場合があります。 スクリプトのセキュアな活用方法については、 シェルスクリプトの使い方のページでご確認ください。

関連項目


ドキュメントの改善にご協力ください

このガイドは、CircleCI の他のドキュメントと同様にオープンソースであり、 GitHub でご利用いただけます。 ご協力いただき、ありがとうございます。

サポートが必要ですか

CircleCI のサポートエンジニアによる、サービスに関する問題、請求およびアカウントについての質問への対応、設定の構築に関する問題解決のサポートを行っています。 サポートチケットを送信して、CircleCI のサポートエンジニアにお問い合わせください。日本語でお問い合わせいただけます。

または、 サポートサイト から、サポート記事やコミュニティフォーラム、トレーニングリソースをご覧いただけます。