# GitHub Actions ![](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/en/keeperpam/secrets-manager/overview) {% endhint %} ## Video Demo The below overview video covers basic setup and ends with a basic Github Actions integration. {% embed url="" %} ## 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/en/keeperpam/secrets-manager/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](https://docs.keeper.io/en/keeperpam/about/terminology#application) with secrets shared to it * See the [Quick Start Guide](https://docs.keeper.io/en/keeperpam/quick-start-guide#2.-create-an-application) for instructions on creating an Application * An initialized Keeper [Secrets Manager Configuration](https://docs.keeper.io/en/keeperpam/secrets-manager/about/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 ```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 }}" ``` ### Storing Secrets ```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 ``` ### Mixed Operations Retrieve and store in the same step: ```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 }} ``` You will need to provide two inputs to utilize the Github Actions plugin: * A [Keeper Secrets Manager configuration](https://sites.gitbook.com/preview/site_h4H2v/keeperpam-and-secrets-manager/~/revisions/bIpy8il3H28oAxHfF8v2/secrets-manager/about/secrets-manager-configuration) * Github Actions supports JSON and Base64 type configuration * [Keeper Notation](https://sites.gitbook.com/preview/site_h4H2v/keeperpam-and-secrets-manager/~/revisions/bIpy8il3H28oAxHfF8v2/secrets-manager/about/keeper-notation) queries for secrets ## Inputs ### `keeper-secret-config` Secrets configuration. See[ documentation](https://docs.keeper.io/en/keeperpam/secrets-manager/about/secrets-manager-configuration) 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://sites.gitbook.com/preview/site_h4H2v/keeperpam-and-secrets-manager/~/revisions/bIpy8il3H28oAxHfF8v2/secrets-manager/about/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:** ```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" %} When referencing complex values in a secret, refer to the [Keeper Notation - Predicates](https://sites.gitbook.com/preview/site_h4H2v/keeperpam-and-secrets-manager/~/revisions/bIpy8il3H28oAxHfF8v2/about/keeper-notation#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 | 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:** ```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` 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. ## 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](https://github.com/Keeper-Security/ksm-action)