> 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/secrets-manager/integrations/github-actions.md).

# GitHub Actions

Keeper Secrets Manager integration into GitHub Actions for dynamic secrets retrieval

![](https://762006384-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJXOXEifAmpyvNVL1to%2F-MkdFl3JIXByC2lADPNH%2F-MkdFyUdRSxjKdJTdIPX%2Fgithub-actions-plugin-header.jpg?alt=media\&token=22669c6b-a368-4a05-afc6-68f5c86e3769)

## Features

* Retrieve secrets from the Keeper Vault and set them as environment variables, step outputs, or files
* Store values back to the Keeper Vault from environment variables, files, or inline values
* Upload files to Keeper records
* Create new records on demand during store operations

{% hint style="info" %}
For a complete list of Keeper Secrets Manager features see the [Overview](https://docs.keeper.io/keeperpam/secrets-manager/overview.md)
{% endhint %}

## Video Demo

The below overview video covers basic setup and ends with a basic GitHub Actions integration.

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

## Prerequisites

This page documents the Secrets Manager GitHub Actions integration. In order to utilize this integration, you will need:

* Keeper Secrets Manager access (See the [Quick Start Guide](https://docs.keeper.io/keeperpam/secrets-manager/quick-start-guide.md) for more details)
  * Secrets Manager addon enabled for your Keeper account
  * Membership in a Role with the Secrets Manager enforcement policy enabled
* A Keeper [Secrets Manager Application](https://docs.keeper.io/keeperpam/secrets-manager/about/terminology.md#application) with secrets shared to it
  * See the [Quick Start Guide](https://docs.keeper.io/keeperpam/secrets-manager/quick-start-guide.md) for instructions on creating an Application
* An initialized Keeper [Secrets Manager Configuration](https://docs.keeper.io/keeperpam/secrets-manager/about/secrets-manager-configuration.md)
  * The GitHub Actions integration accepts JSON and Base64 format configurations

## About

This action retrieves secrets from Keeper Vault and places them into environment variables, step outputs, or files on the GitHub Actions runner. It can also store values back to the vault. This is useful for secret rotation, certificate management, and two-way credential workflows.

## Quick Start

### Retrieving Secrets

```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` is already in the environment for later steps. Pass step outputs to scripts through `env:`, as shown. Do not put `${{ }}` expressions inside `run:` scripts, and do not print secret values.

### Storing Secrets

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

The runner prints a step's `env:` values in the step header. The step that creates `NEW_PASSWORD` must mask it before it writes the output, for example with `echo "::add-mask::$VALUE"`.

To store a value from a file, use `uid123/field/password < file:./new-password.txt`.

To upload a file to a record, use `uid456/file/renewed-cert.pem < file:./renewed-cert.pem`.

{% hint style="warning" %}
Known issue: a step that uploads a file can keep running for about five minutes after the upload finishes. The upload itself completes in seconds. In our testing the process ended on its own after about five minutes. Plan for the extra runner time, and do not set `timeout-minutes` below 7 on that step, because a timeout fails the step.
{% endhint %}

### Mixed Operations

Retrieve and store in the same step:

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

The action runs all retrieve lines first and then all store lines, whatever their order in the list. `OLD_PASSWORD` holds the value from before the store. If a retrieve fails, no store runs.

You will need to provide two inputs to utilize the GitHub Actions plugin:

* A [Keeper Secrets Manager configuration](https://docs.keeper.io/keeperpam/secrets-manager/about/secrets-manager-configuration.md)
  * GitHub Actions supports JSON and Base64 type configuration
* [Keeper Notation](https://docs.keeper.io/keeperpam/secrets-manager/about/keeper-notation.md) queries for secrets

## Inputs

### `keeper-secret-config`

Secrets configuration. See the [documentation](https://docs.keeper.io/keeperpam/secrets-manager/about/secrets-manager-configuration.md) for more information about creating a configuration.

JSON and Base64 type configuration is supported.

**Example:**

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

We recommend storing the configuration in a GitHub Actions secret and accessing it as a variable, as shown in the example above.

### `secrets`

A list of retrieve (`>`) and store (`<`) operations using [Keeper Notation](https://docs.keeper.io/keeperpam/secrets-manager/about/keeper-notation.md). Put one operation on each line. Keep comments outside the list, because the action treats a comment line as an operation and it can fail the step.

**Retrieve**: read a field from Keeper and place it into the runner:

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

A retrieve accepts a record UID or a record title.

**Store**: write a value from the runner back to Keeper:

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

A store or upload needs the record UID. A title does not work.

**Example:**

```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" %}
When referencing complex values in a secret, refer to the [Keeper Notation - Predicates](https://docs.keeper.io/keeperpam/secrets-manager/about/keeper-notation.md#predicates) documentation.

Use predicate notation when referencing values that are arrays, key-value pairs, or any other nested value.
{% endhint %}

#### Retrieve destinations

| Selector                  | No prefix (step output) | `env:` (env variable) | `file:` (file path)   |
| ------------------------- | ----------------------- | --------------------- | --------------------- |
| `field` or `custom_field` | Step output             | Environment variable  | Value written to file |
| `file`                    | Downloaded to path      | Use `file:`           | Downloaded to path    |

For the `file` selector, use a `file:` destination. The destination directory must already exist.

Text values are written unchanged. Objects and arrays are written as compact JSON, and numbers and booleans are written as JSON text. When a field holds several values and the notation has no index, the action returns the first value. Use the `[]` index to return all values as a JSON array.

#### Store sources

| Prefix   | Description                                         | Example                         |
| -------- | --------------------------------------------------- | ------------------------------- |
| *(none)* | Literal value or resolved GitHub Actions expression | `< ${{ steps.id.outputs.val }}` |
| `env:`   | Read from an environment variable                   | `< env:NEW_PASSWORD`            |
| `file:`  | Read contents from a file on the runner             | `< file:./secret.txt`           |

Prefer `env:` for values that come from other steps. The action treats each extra line of an inline value as a separate operation, removes matching outer quotes, and reads a leading `env:` or `file:` as a prefix.

File uploads use the `file` selector with the file name: `RecordUID/file/cert.pem < file:./cert.pem`. The file keeps its local name. An upload adds a new attachment. It does not replace an attachment with the same name. See the known issue under Storing Secrets about an upload step that keeps running after it finishes.

Paths for `file:` sources and file uploads must be inside the workspace directory of the runner. The action fails with the error `File path must be within the workspace directory` for any other path. The `out:` prefix is not supported. Use `env:` or a GitHub Actions expression such as `${{ steps.id.outputs.name }}` instead.

A `file:` source is stored exactly as read, including a trailing new line. Write the file with `printf '%s'` to avoid adding one.

A store writes text values to these field types: `login`, `password`, `url`, `email`, `text`, `multiline`, `secret`, `note`, `pinCode`, `licenseNumber`, `databaseType`, and `directoryType`. The action finds the field by type and replaces its value. It adds the field if the record has none. Custom fields match by type, not by label. The action rejects all other field types, including file attachments, passkeys, one-time codes, record links, and multi-part types such as phone, name, address, and payment card. A value can have at most 10,000 characters, and an `email` value must be a valid email address.

### `create-if-missing`

When `true`, a store operation creates a new record if the referenced record UID is not found or the Application cannot access it. Requires `folder-uid`. Default: `false`.

The new record gets the first segment of the notation as its title and holds only the first store line for that record. The new record has a new UID. The log shows it in a line that reads `Created new record: <title> (UID: <uid>)`. Use that UID in later runs. If you keep the original segment, the next run does not find the record and creates another one.

### `folder-uid`

The UID of the shared folder where new records are created. Required when `create-if-missing` is `true`. The folder must be a shared folder, not a subfolder, and it must be shared to the Application with the Can Edit permission. Stores to existing records also need Can Edit.

### `new-record-type`

The record type for newly created records. Default: `login`. This applies only to records that `create-if-missing` creates.

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

Fail the action if a store operation fails. Default: `true`. Set to `false` to continue the workflow even if a store fails. A failed retrieve always fails the step. When several store lines target one record and some of them fail validation, the action can save the others and still pass the step, so check the log for errors.

### `allow-empty-values`

Allow storing empty strings to fields. Default: `false`. When `false`, the action skips an empty value with a warning and the step does not fail. An `env:` source that is not set counts as empty.

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

Maximum number of seconds to wait for a single Keeper backend throttle retry before failing fast instead of blocking. Default: `60`. Must be a positive number. A value that is not a positive number fails the step.

{% hint style="warning" %}
Known issue: in versions 1.3.2 and 1.3.3 the action does not retry a throttled request, so this input has no effect. The Keeper backend answers a throttled request with HTTP 429, and the bundled SDK retries only on HTTP 403, so the step fails at once. Until a fixed release ships, retry the step in your workflow if you expect throttling.
{% endhint %}

### Availability by version

The `v1` tag points to the latest 1.x release. If you pin an exact version, use this list:

* 1.2.0: the Node 24 runtime. Self-hosted runners need [Actions Runner v2.327.1](https://github.com/actions/runner/releases/tag/v2.327.1) or later
* 1.3.0: the store operator, file upload, `create-if-missing`, `folder-uid`, `new-record-type`, `fail-on-store-error`, and `allow-empty-values`
* 1.3.2: `max-throttle-wait-seconds`

## Masking - Hiding Secrets from Logs

The action uses GitHub Actions masking for the values it retrieves and the values it stores. For structured values, it also masks each top-level text property. It does not mask the contents of files that it downloads. Masking matches exact text only.

If you pass a value inline in the `secrets` list, the runner can show that value in the step input log unless an earlier step masked it with `::add-mask::`. With step debug logging on, the action's debug output also prints each `secrets` line as written, before the value is masked. Passing values through `env:` keeps them out of that debug output. The runner prints a step's `env:` values in the step header, so mask any generated value with `::add-mask::` in the step that creates it.

This only obscures secrets from output logs. If someone has the ability to edit your workflows, then they are able to read and therefore write secrets to somewhere else just like normal GitHub Secrets.

## Source Code

Find the Keeper Secrets Manager GitHub Actions plugin source code in the [GitHub repository](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/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.
