GitHub Actions

Concept

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

Instead of storing long-lived credentials in GitHub Secrets, workflows authenticate to Infisical 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 Infisical while maintaining security through identity-based authentication.

The short video below provides a guided overview of using Infisical 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 Infisical

  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 Infisical API with Token
  Client->>Infis: Make authenticated requests using the short-lived access token

Workflow

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

1. Create a machine identity in Infisical with OIDC authentication configured for your GitHub repository and workflow context.
2. Add the machine identity to your Infisical project with appropriate permissions to access the required secrets.
3. Configure your GitHub Actions workflow to use the Infisical Secrets Action with OIDC authentication.
4. The workflow authenticates using GitHub's OIDC token, fetches secrets from Infisical, 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:

1. 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.

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

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

4. Secrets Are Issued at Runtime
   If the identity matches, Infisical 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 Infisical project (Infisical Cloud or self-hosted instance)
• Secrets stored in your Infisical project
• A GitHub repository with Actions enabled

Guide

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

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

- `DOCKER_USERNAME`
- `DOCKER_PASSWORD`

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

To create a machine identity with OIDC authentication:

1. Navigate to your project in Infisical
2. Go to your project > **Access Control** > **Machine Identities**
3. Click **Add Machine Identity to Project**
4. Provide a name for the identity (e.g., `github-actions-workflow`)
5. Select an organization-level role that defines what the identity can access
6. Click **Create**

By default, the identity will be configured with [Universal Auth](/documentation/platform/identities/universal-auth). For CI/CD workflows, we want to avoid long-lived credentials, so we'll switch to OIDC authentication.

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)
  
  <Tip>
    If you're unsure about the exact subject format, you can use [github/actions-oidc-debugger](https://github.com/github/actions-oidc-debugger) to inspect the OIDC token claims from your workflow.
  </Tip>

- **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](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#understanding-the-oidc-token) for supported claims.

<Warning>
  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.
</Warning>

<Info>
  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.
</Info>

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

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

Configure GitHub Actions Workflow

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

Basic Workflow Example

Create or update a workflow file in .github/workflows/ (e.g., .github/workflows/infisical-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 Infisical
        uses: Infisical/[email protected]
        with:
          method: "oidc"
          identity-id: "your-identity-id-here"  # From Step 4
          project-slug: "your-project-slug"      # Your Infisical 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.

Infisical Secrets Action: The Infisical Secrets Action step handles:

• Requesting the OIDC token from GitHub
• Authenticating with Infisical 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 Infisical (safe to commit)
• project-slug - Your Infisical project slug (found in project settings)
• env-slug - The environment to fetch secrets from (e.g., dev, staging, prod)

Using Secrets in Workflows

After the Infisical 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"

Troubleshooting

Authentication Failures

If authentication fails, check:

1. Permissions: Ensure id-token: write is set in the workflow permissions
2. Subject Match: Verify the Subject in your machine identity matches the repository and context
3. Audience Match: Confirm the Audience matches your GitHub organization
4. Identity Scope: Ensure the identity has access to the project and environment you're requesting
5. Project Slug: Verify the project-slug matches your Infisical project slug exactly. You can find this in your project settings.
6. Environment Slug: Confirm the env-slug matches the exact environment name in Infisical (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.

Alternative Approaches

GitHub Secret Syncs

If you prefer to push secrets from Infisical 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.

Related Documentation

• OIDC Auth for GitHub Actions - Detailed OIDC configuration guide
• Machine Identities Overview - Understanding machine identities
• GitHub Secret Syncs - Syncing secrets to GitHub
• Infisical Secrets Action - Official GitHub Action repository