GitHub Actions

How to inject secrets from Hanzo KMS into GitHub Actions workflows using OIDC authentication

For syncing secrets from Hanzo KMS to GitHub (one-way sync to GitHub Secrets), use our GitHub Secret Syncs instead.

Concept

The KMS Secrets Action enables GitHub Actions workflows to fetch secrets from Hanzo KMS at runtime using OpenID Connect (OIDC) authentication with machine identities.

Instead of storing long-lived credentials in GitHub Secrets, workflows authenticate to Hanzo KMS using short-lived OIDC tokens issued by GitHub. This eliminates the need for static API keys or tokens while providing fine-grained access control based on repository, workflow, and execution context.

Secrets are fetched dynamically during workflow execution and exposed as environment variables, existing only for the lifetime of the job. This approach centralizes secret management in Hanzo KMS while maintaining security through identity-based authentication.

The short video below provides a guided overview of using Hanzo KMS with GitHub Actions and OIDC authentication, helping you build the right mental model before diving into the diagram and setup steps.

Diagram

The following sequence diagram illustrates the OIDC authentication workflow. The authentication flow is the same for all OIDC providers; for GitHub Actions, the client is a GitHub workflow and the identity provider is GitHub's OIDC service.

sequenceDiagram
  participant Client as GitHub Workflow
  participant Idp as GitHub OIDC Provider
  participant Infis as Hanzo KMS

  Client->>Idp: Step 1: Request identity token
  Idp-->>Client: Return JWT with verifiable claims

  Note over Client,Infis: Step 2: Login Operation
  Client->>Infis: Send signed JWT to /api/v1/auth/oidc-auth/login

  Note over Infis,Idp: Step 3: Query verification
  Infis->>Idp: Request JWT public key using OIDC Discovery
  Idp-->>Infis: Return public key

  Note over Infis: Step 4: JWT validation
  Infis->>Client: Return short-lived access token

  Note over Client,Infis: Step 5: Access Hanzo KMS API with Token
  Client->>Infis: Make authenticated requests using the short-lived access token

In GitHub Actions, the KMS Secrets Action handles steps 1-2 and 5, automatically fetching secrets after authentication and injecting them as environment variables into your workflow.

Workflow

A typical workflow for using Hanzo KMS with GitHub Actions consists of the following steps:

Create a machine identity in Hanzo KMS with OIDC authentication configured for your GitHub repository and workflow context.

Add the machine identity to your Hanzo KMS project with appropriate permissions to access the required secrets.

Configure your GitHub Actions workflow to use the KMS Secrets Action with OIDC authentication.

The workflow authenticates using GitHub's OIDC token, fetches secrets from Hanzo KMS, and exposes them as environment variables for the duration of the job.

How It Works

GitHub Actions uses OpenID Connect (OIDC) to authenticate workflows without storing long-lived credentials.

At a high level, the flow looks like this:

GitHub Issues an OIDC Token
When a workflow starts, GitHub issues a short-lived OIDC token containing identity claims about the repository, workflow, and execution context.

Workflow Presents Its Identity
The KMS Secrets Action sends this token to Hanzo KMS as proof of the workflow’s identity.

Hanzo KMS Verifies Trust
Hanzo KMS validates the token signature using GitHub’s OIDC provider and checks the token’s subject, audience, and claims against the configured machine identity.

Secrets Are Issued at Runtime
If the identity matches, Hanzo KMS issues a short-lived access token. The action then uses this token to fetch only the secrets the identity is authorized to access for the requested project and environment.

Secrets are exposed to the workflow as environment variables and exist only for the lifetime of the job.

Prerequisites

Before you begin, ensure you have:

An Hanzo KMS project (Hanzo KMS Cloud or self-hosted instance)

Secrets stored in your Hanzo KMS project

A GitHub repository with Actions enabled

Guide

In the following steps, we explore how to configure GitHub Actions to authenticate with Hanzo KMS using OIDC and fetch secrets at runtime.

Ensure the secrets your workflow needs are stored in your Hanzo KMS project and environment (e.g., dev, staging, prod).

For example, a pipeline that builds and pushes a Docker image might require:

DOCKER_USERNAME
DOCKER_PASSWORD

Secrets are scoped to an environment. Ensure they exist in the environment your workflow will access.

A machine identity represents a non-human workload (such as a CI/CD pipeline, server, or automated job) and defines what that workload is authorized to access without being tied to a user account.

To create a machine identity with OIDC authentication:

Navigate to your project in Hanzo KMS
Go to your project > Access Control > Machine Identities
Click Add Machine Identity to Project
Provide a name for the identity (e.g., github-actions-workflow)
Select an organization-level role that defines what the identity can access
Click Create

By default, the identity will be configured with Universal Auth. For CI/CD workflows, we want to avoid long-lived credentials, so we'll switch to OIDC authentication.

Click on your machine identity
Remove the default Universal Auth configuration
Click Add auth method and select OIDC Auth

Configure the following fields:

OIDC Discovery URL: https://token.actions.githubusercontent.com
Issuer: https://token.actions.githubusercontent.com
CA Certificate: Leave blank for GitHub Actions
Subject: The expected principal that is the subject of the JWT. The format is:
```
repo:<owner>/<repo>:<context>
```
For example:
- repo:octocat/example-repo:ref:refs/heads/main (specific branch)
- repo:octocat/example-repo:environment:production (specific environment)
- repo:octocat/example-repo:* (any context in the repository)
If you're unsure about the exact subject format, you can use github/actions-oidc-debugger to inspect the OIDC token claims from your workflow.
Audiences: A list of intended recipients. Set this to your GitHub organization URL, for example: https://github.com/octo-org
Claims: (Optional) Additional attributes that should be present in the JWT. Refer to GitHub's OIDC token documentation for supported claims.

Restrict access by configuring the Subject, Audiences, and Claims fields carefully. The Subject, Audiences, and Claims fields support glob pattern matching, but we highly recommend using hardcoded values whenever possible for better security.

Together, the Subject and Audience settings make the trust relationship explicit. Only workflows that match the repository, context, and audience you've defined will be able to authenticate and fetch secrets.

After configuring OIDC authentication, Hanzo KMS provides an Identity ID. This is what you'll reference in your GitHub Actions workflow.

Copy this value — you'll need it in the next step.

The Identity ID is not a secret. It's a public identifier that's safe to commit directly into your workflow YAML files.

Configure GitHub Actions Workflow

Now let's configure your GitHub Actions workflow to fetch secrets from Hanzo KMS.

Basic Workflow Example

Create or update a workflow file in .github/workflows/ (e.g., .github/workflows/kms-demo.yml):

name: Build and Push Docker Image

on:
  workflow_dispatch:  # Manual trigger for testing

permissions:
  id-token: write  # Required for OIDC authentication
  contents: read   # Required for checking out code

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Fetch secrets from Hanzo KMS
        uses: Hanzo KMS/secrets-action@v1.0.9
        with:
          method: "oidc"
          identity-id: "your-identity-id-here"  # From Step 4
          project-slug: "your-project-slug"      # Your Hanzo KMS project slug
          env-slug: "dev"                        # Your environment slug

      - name: Login to Docker Registry
        run: |
          echo "$DOCKER_PASSWORD" | docker login -u "$DOCKER_USERNAME" --password-stdin

      - name: Build and push Docker image
        run: |
          docker build -t my-image:latest .
          docker push my-image:latest

Key Configuration Points

Permissions Block: The id-token: write permission is required for OIDC authentication. Without it, GitHub won't issue an OIDC token for the workflow run.

KMS Secrets Action: The KMS Secrets Action step handles:

Requesting the OIDC token from GitHub

Authenticating with Hanzo KMS using OIDC

Fetching secrets for the specified project and environment

Injecting secrets as environment variables

Action Parameters:

method: "oidc" - Specifies OIDC authentication

identity-id - The machine identity ID from Hanzo KMS (safe to commit)

project-slug - Your Hanzo KMS project slug (found in project settings)

env-slug - The environment to fetch secrets from (e.g., dev, staging, prod)

This workflow uses OIDC authentication with short-lived tokens. The identity-id is a public identifier that can be safely committed to your repository. Authentication occurs at runtime using GitHub's OIDC token, eliminating the need to store long-lived credentials.

Using Secrets in Workflows

After the KMS Secrets Action completes, secrets are available as environment variables for subsequent steps in the job. Reference them using standard environment variable syntax:

- name: Run tests with database connection
  run: |
    npm run test -- --database-url="$DATABASE_URL"

Never print full secret values in workflow logs. GitHub Actions will mask secrets automatically, but avoid using echo $SECRET or similar commands that expose values.

Troubleshooting

Authentication Failures

If authentication fails, check:

Permissions: Ensure id-token: write is set in the workflow permissions

Subject Match: Verify the Subject in your machine identity matches the repository and context

Audience Match: Confirm the Audience matches your GitHub organization

Identity Scope: Ensure the identity has access to the project and environment you're requesting

Project Slug: Verify the project-slug matches your Hanzo KMS project slug exactly. You can find this in your project settings.

Environment Slug: Confirm the env-slug matches the exact environment name in Hanzo KMS (e.g., dev, staging, prod). Environment slugs are case-sensitive and must match exactly.

Debugging OIDC Tokens

To inspect OIDC token claims from your workflow, use GitHub's actions-oidc-debugger tool. This tool helps you verify that the token claims match your machine identity configuration.

For more detailed OIDC configuration options and troubleshooting, see OIDC Auth for GitHub Actions.

Alternative Approaches

GitHub Secret Syncs

If you prefer to push secrets from Hanzo KMS to GitHub (one-way sync), use GitHub Secret Syncs. This approach syncs secrets to GitHub at the organization-level, repository-level, or repository environment-level, making them available as GitHub Secrets.

Secret Syncs push secrets to GitHub, while this guide shows how to fetch secrets from Hanzo KMS at runtime. Choose the approach that best fits your security and operational requirements.

OIDC Auth for GitHub Actions - Detailed OIDC configuration guide

Machine Identities Overview - Understanding machine identities

GitHub Secret Syncs - Syncing secrets to GitHub

KMS Secrets Action - Official GitHub Action repository

On this page