GitHub Actions

Keeper Secrets Manager integration into GitHub Actions for dynamic secrets retrieval

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

For a complete list of Keeper Secrets Manager features see the Overview

Video Demo

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

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 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 with secrets shared to it

  • See the Quick Start Guide for instructions on creating an Application

• An initialized Keeper Secrets Manager Configuration

  • 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

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

Storing Secrets

- 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

Mixed Operations

Retrieve and store in the same step:

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

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

• A Keeper Secrets Manager configuration

  • GitHub Actions supports JSON and Base64 type configuration

• Keeper Notation queries for secrets

Inputs

keeper-secret-config

Secrets configuration. See documentation for more information about creating a configuration.

JSON and Base64 type configuration is supported.

Example:

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.

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

RecordUID/field/fieldname > DESTINATION

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

RecordUID/field/fieldname < SOURCE

Example:

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

When referencing complex values in a secret, refer to the Keeper Notation - Predicates documentation.

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

Retrieve destinations

Selector	No prefix (step output)	env: (env variable)	file: (file path)
field or custom_field	Step output	Environment variable	Not allowed
file	Downloaded to path	Downloaded to path	Downloaded to path

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

File uploads use the file selector: RecordUID/file < file:./cert.pem

create-if-missing

When true, store operations will create a new record if the referenced record does not exist. Requires folder-uid. Default: false.

Example:

- 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

The UID of the shared folder where new records are created. Required when create-if-missing is true.

new-record-type

The record type for newly created records. Default: login.

fail-on-store-error

Fail the action if any store operation fails. Default: true. Set to false to continue the workflow even if a store fails.

allow-empty-values

Allow storing empty strings to fields. Default: false. When false, empty values are rejected to prevent accidental overwrites.

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.

The Keeper SDK retries automatically when the backend requests a throttle wait, with no ceiling of its own on how long a single wait can be. If a retry's requested wait exceeds this value, the action fails immediately with a THROTTLE_EXCEEDED error naming the requested wait and the configured cap, rather than blocking until the runner's own job timeout kills it with an unrelated message. Raise this value to allow the SDK's full backoff schedule (up to ~176 seconds on its last of 5 attempts) to run instead of failing fast.

Example:

- 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

Masking - Hiding Secrets from Logs

This action uses GitHub Action's built-in masking, so all retrieved and stored values are automatically masked in console output and logs. Store operation values are also redacted in debug logs.

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