GitHub Actions

GitHub Actionsへのシークレットマネージャー連携と動的なシークレット取得

機能

• Keeperボルトからのシークレット取得と、環境変数・ステップ出力・ファイルへの設定

• 環境変数・ファイル・インライン値からのボルトへの書き戻し

• Keeperレコードへのファイルアップロード

• 保存時に必要に応じた新規レコードの作成

Keeperシークレットマネージャーの機能一式については、概要をご参照ください。

動画デモ

以下の概要動画では、基本設定からGitHub Actionsとの連携までを扱っています。

要件

本ページではシークレットマネージャーのGitHub Actions連携について説明します。利用には以下が必要です。

• Keeperシークレットマネージャーへのアクセス (クイックスタートガイドをご参照ください)

  • Keeperアカウントでシークレットマネージャーアドオンが有効であること

  • シークレットマネージャーの適用ポリシーが有効なロールへの所属

• Keeperのシークレットマネージャーアプリケーションにシークレットが共有されていること

  • アプリケーションの作成手順は、クイックスタートガイドをご参照ください

• 初期化済みのシークレットマネージャー構成

  • GitHub Actions連携ではJSON形式およびBase64形式の構成を受け付けます

概要

このアクションを使うと、Keeperボルトからシークレットを取得し、GitHub Actionsランナーの環境変数・ステップ出力・ファイルへ渡せます。ボルトへの書き戻しにも対応し、シークレットのローテーション、証明書の管理、双方向の認証情報ワークフローに適しています。

クイックスタート

シークレットの取得

- name: Retrieve secrets from Keeper
  id: ksecrets
  uses: Keeper-Security/ksm-action@v1
  with:
    keeper-secret-config: ${{ secrets.KSM_CONFIG }}
    secrets: |-
        uid123/field/password > env:DB_PASSWORD
        uid234/field/login > LOGIN
        uid321/file/Certificate.crt > file:/tmp/Certificate.crt

- name: Use retrieved secrets
  run: |
    echo "DB password is set in env: ${{ env.DB_PASSWORD }}"
    echo "Login is in step output: ${{ steps.ksecrets.outputs.LOGIN }}"

シークレットの保存

- name: Rotate database password
  uses: Keeper-Security/ksm-action@v1
  with:
    keeper-secret-config: ${{ secrets.KSM_CONFIG }}
    secrets: |-
        # Store from a GitHub Actions expression
        uid123/field/password < ${{ steps.generate.outputs.NEW_PASSWORD }}
        # Or from an env var:  uid123/field/password < env:NEW_PASSWORD
        # Or from a file:      uid123/field/password < file:./new-password.txt

        # Upload a file to a record
        uid456/file < file:./renewed-cert.pem

取得と保存の併用

同一ステップで取得と保存を行う例です。

- name: Rotate and confirm
  id: ksecrets
  uses: Keeper-Security/ksm-action@v1
  with:
    keeper-secret-config: ${{ secrets.KSM_CONFIG }}
    secrets: |-
        uid123/field/password > OLD_PASSWORD
        uid123/field/password < ${{ steps.generate.outputs.NEW_PASSWORD }}

GitHub Actionsプラグインを利用するには、以下の2つの入力が必要です。

• シークレットマネージャー構成

  • JSON形式およびBase64形式の構成を利用可能

• Keeper表記法に基づくシークレット取得用のクエリ

入力値

keeper-secret-config

シークレットの構成です。構成の作成方法については、ドキュメントをご参照ください。

JSON形式およびBase64形式の構成に対応します。

例:

keeper-secret-config: ${{ secrets.KSM_CONFIG }}

構成はGitHub Actionsのシークレットに保存し、上記のように変数として参照することを推奨します。

secrets

secrets では、Keeper表記法により取得 (>) と保存 (<) を1行ずつ指定します。

取得 — Keeperからフィールドを読み取り、ランナーへ渡します。

RecordUID/field/fieldname > DESTINATION

保存 — ランナー側の値をKeeperへ書き込みます。

RecordUID/field/fieldname < SOURCE

例:

secrets: |-
  # Retrieve
  uid123/field/password > env:DB_PASSWORD
  uid234/field/login > LOGIN
  uid321/file/Certificate.crt > file:/tmp/Certificate.crt

  # Store
  uid123/field/password < ${{ steps.generate.outputs.NEW_PW }}
  uid456/field/apiKey < env:GENERATED_KEY
  uid789/file < file:./renewed-cert.pem

シークレット内で複雑な値を参照する場合は、Keeper表記法の述部をご参照ください。

配列、キーと値のペア、その他の入れ子構造の値は、述部記法で参照します。

取得先の指定

セレクター	プレフィックスなし (ステップ出力)	env: (環境変数)	file: (ファイルパス)
field または custom_field	ステップ出力へ格納	環境変数へ格納	不可
file	指定パスへダウンロード	指定パスへダウンロード	指定パスへダウンロード

保存元の指定

プレフィックス	説明	例
(なし)	リテラルまたはGitHub Actions式の解決結果	< ${{ steps.id.outputs.val }}
env:	環境変数から読み取り	< env:NEW_PASSWORD
file:	ランナー上のファイルから読み取り	< file:./secret.txt

ファイルのアップロードには file セレクターを使います。例: RecordUID/file < file:./cert.pem

create-if-missing

true のとき、参照先レコードが存在しない場合は保存処理で新規レコードを作成します。folder-uid が必要です。既定値は false です。

例:

- name: Store secret, create record if needed
  uses: Keeper-Security/ksm-action@v1
  with:
    keeper-secret-config: ${{ secrets.KSM_CONFIG }}
    create-if-missing: true
    folder-uid: XXXXXXXXXXXXXXXXXXXX
    secrets: |-
        MyApp/field/apiKey < ${{ steps.generate.outputs.API_KEY }}

folder-uid

新規作成するレコードの配置先となる共有フォルダのUIDです。create-if-missing が true のときに必要です。

new-record-type

新規作成するレコードのタイプです。既定値は login です。

fail-on-store-error

保存処理のいずれかが失敗したときにアクション全体を失敗扱いにします。既定値は true です。false にすると、保存に失敗してもワークフローを続行できます。

allow-empty-values

空文字列をフィールドに保存することを許可します。既定値は false です。false のとき、空の値は誤った上書きを防ぐため拒否されます。

max-throttle-wait-seconds

Keeperバックエンドによるスロットリングで1回のリトライを待機する際に、処理をブロックし続ける代わりに失敗として扱うまでの最大秒数です。既定値は 60 です。正の数を指定する必要があります。

Keeper SDKは、バックエンドからスロットリング待機が要求された場合に自動でリトライしますが、1回の待機時間自体には上限がありません。リトライで要求された待機時間がこの値を超えると、ランナー側のジョブタイムアウトによって無関係なエラーで強制終了されるのではなく、要求された待機時間と設定済みの上限を明示した THROTTLE_EXCEEDED エラーで即座に失敗します。この値を大きくすることで、失敗として即座に扱う代わりに、SDKのバックオフスケジュール全体 (最後の5回目の試行で最大約176秒) を実行させることができます。

例:

- name: Retrieve secrets, allow up to 3 minutes of throttle backoff
  uses: Keeper-Security/ksm-action@v1
  with:
    keeper-secret-config: ${{ secrets.KSM_CONFIG }}
    max-throttle-wait-seconds: 180
    secrets: |-
        uid123/field/password > env:DB_PASSWORD

マスキング (ログからシークレットを隠す)

GitHub Actions組み込みのマスキングにより、取得・保存した値はコンソール出力やログに自動でマスクされます。保存処理で扱う値も、デバッグログではマスクされます。

ログ上では値が見えなくなるだけです。ワークフローを編集できるユーザーは、通常のGitHubシークレットと同様に、シークレットの内容を読み取ったり他へ書き出したりできる場合があります。

ソースコード

KeeperシークレットマネージャーのGitHub Actionsプラグインのソースコードは、GitHubリポジトリで確認できます。