暗号化されたシークレット

暗号化されたシークレットについて

シークレットは、組織、リポジトリ、またはリポジトリ環境内に作成する、暗号化された環境変数です。 作成したシークレットは、GitHub Actionsワークフローで利用できます。 GitHub はシークレットが GitHub に到達する前に暗号化され、ワークフローで使用されるまで暗号化されたままになっていることを確実にするのを助けるために libsodium シールド ボックスを使います。

Organizationレベルで保存されたシークレットについては、アクセスポリシーを使ってどのリポジトリがOrganizationのシークレットを利用できる化を制御できます。 Organizationレベルのシークレットを利用すると、複数のリポジトリ間でシークレットを共有できるので、重複してシークレットを作成する必要が軽減されます。 一カ所でOrganizationシークレットを更新すれば、そのシークレットを使うすべてのリポジトリワークフローにその変更が有効になることを保証できます。

環境レベルで保存されたシークレットについては、それらへのアクセスを制御するために必� �のレビュー担当者を有効化することができます。 必� �の承認者によって許可されるまで、ワークフローのジョブは環境のシークレットにアクセスできません。

シークレットに名前を付ける

シークレットの名前には次のルールが適用されます。

• シークレット名には、英数字 ([a-z]、[A-Z]、[0-9]) またはアンダースコア (_) のみを含めることができます。 スペースは使用できません。

• シークレット名の最初を GITHUB_ プレフィックスにすることはできません。

• シークレット名の最初を数字にすることはできません。

• シークレット名は大文字と小文字を区別しません。

• シークレット名は、作成されたレベルで一意である必要があります。

  たとえば、環境のレベルで作成されたシークレットはその環境内でユニークな名前になっていなければならず、リポジトリのレベルで作成されたシークレットはそのリポジトリ内でユニークな名前になっていなければならず、組織のレベルで作成されたシークレットはそのレベルでユニークな名前になっていなければなりません。

  複数のレベルで同じ名前のシークレットが存在する� �合、最も低いレベルのシークレットが優先されます。 たとえば、Organization レベルのシークレット名がリポジトリレベルのシークレット名と同じ� �合、リポジトリレベルのシークレット名が優先されます。 同様に、組織、リポジトリ、環境がすべて同じ名前のシークレットを持つ� �合、環境レベルのシークレットが優先されます。

GitHub がログのシークレットを確実に削除するよう、シークレットの値として構� 化データを使用しないでく� さい。 たとえば、JSONやエンコードされたGit blobを含むシークレットは作成しないでく� さい。

シークレットにアクセスする

シークレットをアクションが使用できるようにするには、ワークフローファイルでシークレットを入力または環境変数に設定する必要があります。 アクションに必要な入力および環境変数については、アクションのREADMEファイルを確認します。 詳細については、GitHub Actions のワークフロー構文に関するページを参照してく� さい。

ワークフローファイルを編集するアクセス権を持っていれば、ワークフローファイル中の暗号化されたシークレットを使い、読み取ることができます。 詳細については、「GitHub 上のアクセス権限」を参照してく� さい。

Organization及びリポジトリのシークレットはワークフローの実行がキューイングされた時点で読まれ、環境のシークレットは環境を参照しているジョブが開始された時点で読まれます。

REST API を使用してシークレットを管理することもできます。 詳細については、「シークレット」を参照してく� さい。

認証情� �のアクセス許可を制限する

認証情� �を生成する際には、可能な限り最小限の権限� けを許可することをおすすめします。 たとえば、個人の資� �情� �を使用する代わりに、デプロイ キーまたはサービス アカウントを使用します。 必要なのが読み取り� けであれば、読み取りのみの権限を許可すること、そしてアクセスをできるかぎり限定することを考慮してく� さい。 personal access token を生成するときは、必要最小限のスコープを選びます。

リポジトリに暗号化されたシークレットを作成する

個人アカウントのリポジトリにシークレットを作成するには、そのリポジトリのオーナーでなければなりません。 組織リポジトリのシークレットを作成するには、admin アクセス権が必要です。

gh secret set SECRET_NAME

gh secret set SECRET_NAME < secret.txt

環境の暗号化されたシークレットの生成

個人アカウントのリポジトリの環境でシークレットを作成するには、リポジトリの所有者である必要があります。 組織リポジトリに環境のシークレットを作成するには、admin アクセス権が必要です。

gh secret set --env ENV_NAME SECRET_NAME

gh secret list --env ENV_NAME

Organizationの暗号化されたシークレットの作成

Organizationでシークレットを作成する� �合、ポリシーを使用して、そのシークレットにアクセスできるリポジトリを制限できます。 たとえば、すべてのリポジトリにアクセスを許可したり、プライベート リポジトリまたは指定したリポジトリ のリストのみにアクセスを制限したりできます。

組織レベルでシークレットを作成するには、admin アクセス権が必要です。

gh auth login --scopes "admin:org"

gh secret set --org ORG_NAME SECRET_NAME

gh secret set --org ORG_NAME SECRET_NAME --visibility all

gh secret set --org ORG_NAME SECRET_NAME --repos REPO-NAME-1, REPO-NAME-2"

gh secret list --org ORG_NAME

Organizationレベルのシークレットへのアクセスの確認

Organization内のシークレットに適用されているアクセス ポリシーを確認できます。

1. で、Organization のメイン ページへ移動します。 1. Organization 名の下で、 [設定] をクリックします。
2. 左側のサイドバーで、 [シークレット] をクリックします。
3. シークレットのリストには、設定済みのアクセス許可とポリシーが含まれます。 次に例を示します。
4. 各シークレットに構成されているアクセス許可の詳細については、 [更新] をクリックします。

暗号化されたシークレットのワークフロー内での利用

アクションに入力あるいは環境変数としてシークレットを提供するには、リポジトリ内に作成したシークレットにアクセスする secrets コンテキストを使うことができます。 詳細については、「コンテキスト」および「GitHub Actions のワークフロー構文」を参照してく� さい。

steps:
  - name: Hello world action
    with: # Set the secret as an input
      super_secret: ${{ secrets.SuperSecret }}
    env: # Or as an environment variable
      super_secret: ${{ secrets.SuperSecret }}

if: 条件でシークレットを直接参照することはできません。 代わりに、シークレットをジョブ レベルの環境変数として設定し、ジョブのステップを条件付きで実行するために環境変数を参照することを検討してく� さい。 詳細については、「コンテキストの可用性」と jobs.<job_id>.steps[*].if を参照してく� さい。

シークレットが設定されていない� �合、シークレットを参照する式の戻り値 (例では ${{ secrets.SuperSecret }} など) は空の文字列になります。

可能であれば、コマンドラインからプロセス間でシークレットを渡すのは避けてく� さい。 コマンドライン プロセスは、他のユーザーに表示される (ps コマンドを使用)、またはセキュリティ監査イベントによってキャプチャされる可能性もあります。 シークレットの保護のために、環境変数、STDIN、またはターゲットのプロセスがサポートしている他のメカニズ� の利用を検討してく� さい。

コマンドラインからシークレットを渡さなければならない� �合は、それらを適切なルールでクオート内に収めてく� さい。 シークレットは、意図せずシェルに影響するかもしれない特殊なキャラクターをしばしば含みます。 それらの特殊なキャラクターをエスケープするには、環境変数をクオートで囲ってく� さい。 次に例を示します。

Bashの利用例

steps:
  - shell: bash
    env:
      SUPER_SECRET: ${{ secrets.SuperSecret }}
    run: |
      example-command "$SUPER_SECRET"

PowerShellの利用例

steps:
  - shell: pwsh
    env:
      SUPER_SECRET: ${{ secrets.SuperSecret }}
    run: |
      example-command "$env:SUPER_SECRET"

Cmd.exeの利用例

steps:
  - shell: cmd
    env:
      SUPER_SECRET: ${{ secrets.SuperSecret }}
    run: |
      example-command "%SUPER_SECRET%"

シークレットの制限

最大 1,000 個の組織シークレット、100 個のリポジトリ シークレット、100 個の環境シークレットを� �納できます。

リポジトリに作成されたワークフローは、次の数のシークレットにアクセスできます。

• 100 個のリポジトリ シークレットすべて。
• 100 を超える組織シークレットへのアクセスがリポジトリに割り当てられている� �合、ワークフローでは最初の 100 個の組織シークレットのみを使用できます (シークレット名のアルファベット� �に並べ替えられます)。
• 100 個の環境シークレットすべて。

シークレットの容量は最大64 KBです。 より大きなシークレットを� �納するには、以下の「大きなシークレットを� �納する」の回避策を参照してく� さい。

大きなシークレットを� �納する

64 KB より大きなシークレットを使うには、暗号化されたシークレットをリポジトリ内に保存して、復号化パスフレーズを GitHub のシークレットとして保存するという回避策を使用できます。 たとえば、GitHub のリポジトリに暗号化されたファイルをチェックインする前に、gpg を使ってシークレットを含むファイルをローカルで暗号化できます。 詳細については、「gpg manpage」を参照してく� さい。

1. ターミナルから次のコマンドを実行し、gpg と AES256 暗号アルゴリズ� を使用してシークレットを含むファイルを暗号化します。 この例では、my_secret.json はシークレットを含むファイルです。

   gpg --symmetric --cipher-algo AES256 my_secret.json
   

2. パスフレーズを入力するよう求められます。 このパスフレーズを覚えておいてく� さい。GitHubで、このパスフレーズを値として用いる新しいシークレットを作成するために必要になります。

3. パスフレーズを含む新しいシークレットを作成します。 たとえば、LARGE_SECRET_PASSPHRASE という名前で新しいシークレットを作成し、シークレットの値を上記のステップで使用したパスフレーズに設定します。

4. 暗号化したファイルをリポジトリ内のパスにコピーして、コミットします。 この例では、暗号化したファイルは my_secret.json.gpg です。

   警告: 暗号化されていない my_secret.json ファイル ではなく、.gpg ファイル拡張子で終わる暗号化された my_secret.json.gpg ファイルを必ずコピーしてく� さい。

   git add my_secret.json.gpg
   git commit -m "Add new encrypted secret JSON file"
   

5. リポジトリ内にシェル スクリプトを作成して、シークレット ファイルの暗号化を解除します。 この例では、スクリプトの名前は decrypt_secret.sh です。

   #!/bin/sh
   
   # Decrypt the file
   mkdir $HOME/secrets
   # --batch to prevent interactive command
   # --yes to assume "yes" for questions
   gpg --quiet --batch --yes --decrypt --passphrase="$LARGE_SECRET_PASSPHRASE" \
   --output $HOME/secrets/my_secret.json my_secret.json.gpg
   

6. リポジトリにチェックインする前に、シェルスクリプトが実行可能であることを確かめてく� さい。

   chmod +x decrypt_secret.sh
   git add decrypt_secret.sh
   git commit -m "Add new decryption script"
   git push
   

7. GitHub Actions ワークフローで、step を使ってシェル スクリプトを呼び出し、シークレットの暗号化を解除します。 ワークフローが実行されている環境でリポジトリのコピーを作成するには、actions/checkout アクションを使用する必要があります。 リポジトリのルートを基準として run コマンドを使用し、シェル スクリプトを参照します。

   name: Workflows with large secrets
   
   on: push
   
   jobs:
     my-job:
       name: My Job
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v2
         - name: Decrypt large secret
           run: ./decrypt_secret.sh
           env:
             LARGE_SECRET_PASSPHRASE: ${{ secrets.LARGE_SECRET_PASSPHRASE }}
         # This command is just an example to show your secret being printed
         # Ensure you remove any print statements of your secrets. GitHub does
         # not hide secrets that use this workaround.
         - name: Test printing your secret (Remove this step in production)
           run: cat $HOME/secrets/my_secret.json
   

Base64 バイナリ BLOB をシークレットとして� �納する

Base64 エンコードを使用して、小さなバイナリ BLOB をシークレットとして� �納できます。 その後、ワークフロー内のシークレットを参照し、ランナーで使用するためにデコードできます。 サイズの制限については、「シークレットの制限」を参照してく� さい。

1. ファイルを Base64 文字列にエンコードするために base64 を使用します。 次に例を示します。

   $ base64 -i cert.der -o cert.base64
   

2. Base64 文字列を含むシークレットを作成します。 次に例を示します。

   $ gh secret set CERTIFICATE_BASE64 < cert.base64
   ✓ Set secret CERTIFICATE_BASE64 for octocat/octorepo
   

3. ランナーから Base64 文字列にアクセスするには、シークレットを base64 --decode にパイプします。 次に例を示します。

   name: Retrieve Base64 secret
   on:
     push:
       branches: [ octo-branch ]
   jobs:
     decode-secret:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v2
         - name: Retrieve the secret and decode it to a file
           env:
             CERTIFICATE_BASE64: ${{ secrets.CERTIFICATE_BASE64 }}
           run: |
             echo $CERTIFICATE_BASE64 | base64 --decode > cert.der
         - name: Show certificate information
           run: |
             openssl x509 -in cert.der -inform DER -text -noout