> For the complete documentation index, see [llms.txt](https://docs.keeper.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.keeper.io/keeperpam/jp/secrets-manager/integrations/github-actions.md).

# GitHub Actions

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

<figure><img src="https://859776093-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPL6k1aGsLiFiiJ3Y7zCl%2Fuploads%2FHSVuDBfNyxprJdpXZisy%2Fimage.png?alt=media&#x26;token=bcd1aed5-eb0e-4d7f-981a-9f274cf5d07f" alt=""><figcaption></figcaption></figure>

## 機能

* Keeperボルトからのシークレット取得と、環境変数・ステップ出力・ファイルへの設定
* 環境変数・ファイル・インライン値からのボルトへの書き戻し
* Keeperレコードへのファイルアップロード
* 保存時に必要に応じた新規レコードの作成

{% hint style="info" %}
Keeperシークレットマネージャーの機能一式については、[概要](https://docs.keeper.io/keeperpam/jp/secrets-manager/overview.md)をご参照ください。
{% endhint %}

## 動画デモ

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

{% embed url="<https://vimeo.com/672797748>" %}

## 要件

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

* Keeperシークレットマネージャーへのアクセス ([クイックスタートガイド](https://docs.keeper.io/keeperpam/jp/secrets-manager/quick-start-guide.md)をご参照ください)
  * Keeperアカウントでシークレットマネージャーアドオンが有効であること
  * シークレットマネージャーの適用ポリシーが有効なロールへの所属
* Keeperの[シークレットマネージャーアプリケーション](https://docs.keeper.io/keeperpam/jp/secrets-manager/about/terminology.md#application)にシークレットが共有されていること
  * アプリケーションの作成手順は、[クイックスタートガイド](https://docs.keeper.io/keeperpam/jp/secrets-manager/quick-start-guide.md)をご参照ください
* 初期化済みの[シークレットマネージャー構成](https://docs.keeper.io/keeperpam/jp/secrets-manager/about/secrets-manager-configuration.md)
  * GitHub Actions連携ではJSON形式およびBase64形式の構成を受け付けます

## 概要

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

## クイックスタート

### シークレットの取得

```yaml
- 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:${{ runner.temp }}/Certificate.crt
```

```yaml
- name: Use retrieved secrets
  env:
    LOGIN: ${{ steps.ksecrets.outputs.LOGIN }}
  run: ./deploy.sh --user "$LOGIN"
```

`DB_PASSWORD` は、以降のステップの環境変数にすでに設定されています。ステップ出力は、上記のとおり `env:` を通じてスクリプトに渡してください。`run:` スクリプト内に `${{ }}` 式を記述したり、シークレットの値を出力したりしないでください。

### シークレットの保存

```yaml
- name: Rotate database password
  uses: Keeper-Security/ksm-action@v1
  env:
    NEW_PASSWORD: ${{ steps.generate.outputs.NEW_PASSWORD }}
  with:
    keeper-secret-config: ${{ secrets.KSM_CONFIG }}
    secrets: |-
        uid123/field/password < env:NEW_PASSWORD
```

ランナーは、ステップのヘッダーに `env:` の値を表示します。`NEW_PASSWORD` を生成するステップでは、出力を書き込む前に、たとえば `echo "::add-mask::$VALUE"` でマスクしてください。

ファイルの内容を保存するには、`uid123/field/password < file:./new-password.txt` のように指定します。

レコードにファイルをアップロードするには、`uid456/file/renewed-cert.pem < file:./renewed-cert.pem` のように指定します。

{% hint style="warning" %}
既知の問題: ファイルをアップロードするステップは、アップロードの完了後も約5分間実行され続けることがあります。アップロード自体は数秒で完了し、テストではプロセスが約5分後に自動で終了しました。ランナーの稼働時間が余分にかかることを見込んでください。タイムアウトするとステップが失敗するため、このステップの `timeout-minutes` は7未満に設定しないでください。
{% endhint %}

### 取得と保存の併用

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

```yaml
- name: Read the old password and store the new one
  id: ksecrets
  uses: Keeper-Security/ksm-action@v1
  env:
    NEW_PASSWORD: ${{ steps.generate.outputs.NEW_PASSWORD }}
  with:
    keeper-secret-config: ${{ secrets.KSM_CONFIG }}
    secrets: |-
        uid123/field/password > OLD_PASSWORD
        uid123/field/password < env:NEW_PASSWORD
```

アクションは、リストの記述順に関係なく、すべての取得行を先に実行し、その後にすべての保存行を実行します。`OLD_PASSWORD` には、保存前の値が格納されます。取得に失敗した場合、保存は実行されません。

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

* [シークレットマネージャー構成](https://docs.keeper.io/keeperpam/jp/secrets-manager/about/secrets-manager-configuration.md)
  * JSON形式およびBase64形式の構成を利用可能
* [Keeper表記法](https://docs.keeper.io/keeperpam/jp/secrets-manager/about/keeper-notation.md)に基づくシークレット取得用のクエリ

## 入力値

### `keeper-secret-config`

シークレットの構成です。構成の作成方法については、[ドキュメント](https://docs.keeper.io/keeperpam/jp/secrets-manager/about/secrets-manager-configuration.md)をご参照ください。

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

**例:**

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

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

### `secrets`

`secrets` では、[Keeper表記法](https://docs.keeper.io/keeperpam/jp/secrets-manager/about/keeper-notation.md)により取得 (`>`) と保存 (`<`) を指定します。1行に1つの操作を記述してください。コメントはリストの外に記述してください。アクションはコメント行を操作として扱うため、ステップが失敗することがあります。

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

```
RecordUID/field/fieldname > DESTINATION
```

取得では、レコードUIDまたはレコードのタイトルを指定できます。

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

```
RecordUID/field/fieldname < SOURCE
```

保存とアップロードでは、レコードUIDが必要です。タイトルは使用できません。

**例:**

```yaml
secrets: |-
  uid123/field/password > env:DB_PASSWORD
  uid234/field/login > LOGIN
  uid321/file/Certificate.crt > file:${{ runner.temp }}/Certificate.crt
  uid456/field/secret < env:GENERATED_KEY
  uid789/file/renewed-cert.pem < file:./renewed-cert.pem
```

{% hint style="info" %}
シークレット内で複雑な値を参照する場合は、[Keeper表記法の述部](https://docs.keeper.io/keeperpam/jp/secrets-manager/about/keeper-notation.md#predicates)をご参照ください。

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

#### 取得先の指定

| セレクター                      | プレフィックスなし (ステップ出力) | `env:` (環境変数) | `file:` (ファイルパス) |
| -------------------------- | ------------------ | ------------- | ---------------- |
| `field` または `custom_field` | ステップ出力へ格納          | 環境変数へ格納       | 値をファイルへ書き込み      |
| `file`                     | 指定パスへダウンロード        | `file:` を使用   | 指定パスへダウンロード      |

`file` セレクターでは、`file:` を取得先に指定します。取得先のディレクトリは、あらかじめ存在している必要があります。

テキスト値は変更されずに書き込まれます。オブジェクトと配列はコンパクトなJSONとして書き込まれ、数値とブール値はJSONテキストとして書き込まれます。1つのフィールドに複数の値があり、表記にインデックスがない場合は、最初の値が返されます。すべての値をJSON配列として取得するには、`[]` インデックスを使用します。

#### 保存元の指定

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

他のステップから渡される値には、`env:` の使用を推奨します。インラインの値に含まれる2行目以降は別々の操作として扱われ、前後に対応する引用符がある場合は取り除かれ、先頭の `env:` や `file:` はプレフィックスとして解釈されます。

ファイルのアップロードには、ファイル名を指定した `file` セレクターを使います。例: `RecordUID/file/cert.pem < file:./cert.pem`。ファイルはローカルのファイル名のまま保存されます。アップロードでは新しい添付ファイルが追加され、同名の添付ファイルは置き換えられません。アップロード完了後もステップが実行され続ける問題については、「シークレットの保存」の既知の問題をご参照ください。

`file:` の保存元とファイルアップロードのパスは、ランナーのワークスペースディレクトリ内にある必要があります。それ以外のパスを指定すると、アクションは `File path must be within the workspace directory` エラーで失敗します。`out:` プレフィックスには対応していません。代わりに `env:` を使用するか、`${{ steps.id.outputs.name }}` などのGitHub Actions式を使用してください。

`file:` の保存元は、末尾の改行を含めて読み取ったとおりに保存されます。改行を追加したくない場合は、`printf '%s'` でファイルを書き出してください。

保存では、以下のフィールドタイプにテキスト値を書き込めます: `login`、`password`、`url`、`email`、`text`、`multiline`、`secret`、`note`、`pinCode`、`licenseNumber`、`databaseType`、`directoryType`。アクションはタイプでフィールドを探して値を置き換え、レコードに該当するフィールドがない場合は追加します。カスタムフィールドはラベルではなくタイプで照合されます。ファイル添付、パスキー、ワンタイムコード、レコードリンク、電話、氏名、住所、支払いカードなどの複数パーツのタイプを含め、それ以外のフィールドタイプは拒否されます。値は最大10,000文字で、`email` の値は有効なメールアドレスである必要があります。

### `create-if-missing`

`true` のとき、参照先のレコードUIDが見つからない場合、またはアプリケーションがそのレコードにアクセスできない場合に、保存処理で新規レコードを作成します。`folder-uid` が必要です。既定値は `false` です。

新規レコードのタイトルには表記の最初のセグメントが使われ、そのレコードに対する最初の保存行のみが書き込まれます。新規レコードには新しいUIDが割り当てられ、ログに `Created new record: <title> (UID: <uid>)` という行で表示されます。以降の実行では、このUIDを使用してください。元のセグメントのままにすると、次回の実行ではレコードが見つからず、別のレコードが再度作成されます。

### `folder-uid`

新規作成するレコードの配置先となる共有フォルダのUIDです。`create-if-missing` が `true` のときに必要です。サブフォルダではなく共有フォルダを指定し、そのフォルダを編集可能の権限でアプリケーションに共有する必要があります。既存レコードへの保存にも、編集可能の権限が必要です。

### `new-record-type`

新規作成するレコードのタイプです。既定値は `login` です。`create-if-missing` で作成されるレコードにのみ適用されます。

### `fail-on-store-error`

保存処理が失敗したときにアクション全体を失敗扱いにします。既定値は `true` です。`false` にすると、保存に失敗してもワークフローを続行できます。取得の失敗は、常にステップの失敗となります。1つのレコードを対象とする複数の保存行の一部で検証に失敗した場合、アクションは残りを保存したままステップを成功扱いにすることがあるため、ログでエラーを確認してください。

### `allow-empty-values`

空文字列をフィールドに保存することを許可します。既定値は `false` です。`false` のとき、アクションは空の値を警告とともにスキップし、ステップは失敗しません。設定されていない `env:` の保存元は、空として扱われます。

### `max-throttle-wait-seconds`

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

{% hint style="warning" %}
既知の問題: バージョン1.3.2および1.3.3では、アクションがスロットリングされたリクエストをリトライしないため、この入力値は機能しません。Keeperバックエンドはスロットリングされたリクエストに対してHTTP 429を返しますが、組み込みのSDKはHTTP 403の場合にのみリトライするため、ステップは即座に失敗します。修正版がリリースされるまでは、スロットリングが想定される場合、ワークフロー側でステップをリトライしてください。
{% endhint %}

### バージョン別の対応状況

`v1` タグは、最新の1.xリリースを指します。正確なバージョンを固定する場合は、以下の一覧をご参照ください。

* 1.2.0: Node 24ランタイム。セルフホストランナーには[Actions Runner v2.327.1](https://github.com/actions/runner/releases/tag/v2.327.1)以降が必要
* 1.3.0: 保存オペレーター、ファイルアップロード、`create-if-missing`、`folder-uid`、`new-record-type`、`fail-on-store-error`、`allow-empty-values`
* 1.3.2: `max-throttle-wait-seconds`

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

アクションは、取得した値と保存する値に対して、GitHub Actionsのマスキングを使用します。構造化された値では、最上位の各テキストプロパティもマスクされます。ダウンロードしたファイルの内容はマスクされません。マスキングは、完全に一致するテキストにのみ適用されます。

`secrets` リストに値をインラインで渡すと、それより前のステップで `::add-mask::` によりマスクしていない限り、ランナーのステップ入力ログにその値が表示されることがあります。ステップのデバッグログを有効にした場合も、アクションのデバッグ出力には、マスクされる前の `secrets` の各行が記述されたとおりに出力されます。値を `env:` で渡すと、デバッグ出力に含まれなくなります。ランナーはステップの `env:` の値をステップのヘッダーに表示するため、生成した値は、それを作成するステップで `::add-mask::` によりマスクしてください。

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

## ソースコード

KeeperシークレットマネージャーのGitHub Actionsプラグインのソースコードは、[GitHubリポジトリ](https://github.com/Keeper-Security/ksm-action)で確認できます。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.keeper.io/keeperpam/jp/secrets-manager/integrations/github-actions.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
