# 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シークレットマネージャーの機能一式については、[概要](/keeperpam/jp/secrets-manager/overview.md)をご参照ください。
{% endhint %}

## 動画デモ

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

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

## 要件

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

* Keeperシークレットマネージャーへのアクセス ([クイックスタートガイド](/keeperpam/jp/secrets-manager/quick-start-guide.md)をご参照ください)
  * Keeperアカウントでシークレットマネージャーアドオンが有効であること
  * シークレットマネージャーの適用ポリシーが有効なロールへの所属
* Keeperの[シークレットマネージャーアプリケーション](/keeperpam/jp/secrets-manager/about/terminology.md#application)にシークレットが共有されていること
  * アプリケーションの作成手順は、[クイックスタートガイド](https://docs.keeper.io/keeperpam/jp/secrets-manager/integrations/pages/-MeRAVfQmDBzKQBC0f_c#2.-create-an-application)をご参照ください
* 初期化済みの[シークレットマネージャー構成](/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:/tmp/Certificate.crt
```

```yaml
- 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 }}"
```

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

```yaml
- 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
```

### 取得と保存の併用

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

```yaml
- 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つの入力が必要です。

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

## 入力値

### `keeper-secret-config`

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

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

**例:**

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

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

### `secrets`

`secrets` では、[Keeper表記法](/keeperpam/jp/secrets-manager/about/keeper-notation.md)により取得 (`>`) と保存 (`<`) を1行ずつ指定します。

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

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

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

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

**例:**

```yaml
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
```

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

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

#### 取得先の指定

| セレクター                      | プレフィックスなし (ステップ出力) | `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` です。

**例:**

```yaml
- 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` のとき、空の値は誤った上書きを防ぐため拒否されます。

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

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

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

## ソースコード

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


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

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

The question should be specific, self-contained, and written in natural language.
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.