GitHub Actions

Inject Envshed secrets into your GitHub Actions workflows. Secrets are fetched from Envshed and exported as masked environment variables or written to a .env file.

Choose a credential

Credential	When to use it
OIDC (recommended)	The job proves which repository it runs in and gets a short-lived, read-only session. There is no token to store or rotate. It uses envshed run --oidc, not the action below.
Machine token	Use it with the action below. It reads one environment, optionally only certain keys, and is read-only.

Do not use a personal API token. It stops working after 30 days without use, so a workflow that runs rarely fails, and it acts with everything its owner can do.

With OIDC

yaml

permissions:
  id-token: write
  contents: read

steps:
  - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
  - run: npx envshed@0 run --oidc <policy-id> -- npm run deploy

Creating the trust policy is covered in GitHub Actions with OIDC.

Setup with a machine token

1. Create a machine token

In your organization, choose Hosted agents, then Connect a hosted agent, and pick the project and environment the workflow needs. Copy the token: it is shown once. See Machine Tokens.

2. Add the Token to GitHub Secrets

In your GitHub repository, go to Settings > Secrets and variables > Actions and add a new secret named ENVSHED_TOKEN with the machine token.

3. Add the Action to Your Workflow

yaml

steps:
  - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
  - uses: envshed/gh-setup-envshed@v1
    with:
      token: ${{ secrets.ENVSHED_TOKEN }}
      org: my-company
      project: backend
      environment: production
  - run: npm run deploy

Inputs

Input	Required	Default	Description
token	Yes	-	Envshed machine token
org	Yes	-	Organization slug
project	Yes	-	Project slug
environment	No	production	Environment slug
api-url	No	https://app.envshed.com	Envshed API URL
export-to	No	env	Where to export: env or file
file-path	No	.env	Path for .env file (only with export-to: file)

Examples

Environment Variables (Default)

Secrets are exported as environment variables, available to all subsequent steps in the job.

yaml

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
      - uses: envshed/gh-setup-envshed@v1
        with:
          token: ${{ secrets.ENVSHED_TOKEN }}
          org: my-company
          project: backend
          environment: production
      - run: npm run deploy

Write to a .env File

Useful for frameworks that read from .env files at build time.

yaml

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
      - uses: envshed/gh-setup-envshed@v1
        with:
          token: ${{ secrets.ENVSHED_TOKEN }}
          org: my-company
          project: frontend
          environment: production
          export-to: file
          file-path: .env.local
      - run: npm run build

Multi-Environment Deploy

Use a matrix strategy to deploy to multiple environments. A machine token reads one environment, so store one token per GitHub environment, each as ENVSHED_TOKEN.

yaml

jobs:
  deploy:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        env: [staging, production]
    environment: ${{ matrix.env }}
    steps:
      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
      - uses: envshed/gh-setup-envshed@v1
        with:
          token: ${{ secrets.ENVSHED_TOKEN }}
          org: my-company
          project: backend
          environment: ${{ matrix.env }}
      - run: npm run deploy

Docker Build

yaml

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
      - uses: envshed/gh-setup-envshed@v1
        with:
          token: ${{ secrets.ENVSHED_TOKEN }}
          org: my-company
          project: backend
          environment: production
          export-to: file
      - run: docker build -t my-app .

Security

• Never hardcode your token in workflow files. Always use GitHub encrypted secrets.
• All secret values are automatically masked in GitHub Actions logs via core.setSecret().
• Communication with the Envshed API is over HTTPS.

Troubleshooting

"Failed to fetch secrets (HTTP 401)"

Your token is invalid, revoked or expired. Create a new machine token under Hosted agents and update your GitHub secret.

"Failed to fetch secrets (HTTP 403)"

Your token does not have access to the specified organization, project, or environment. A machine token reads only the environment it was created for.

"Failed to fetch secrets (HTTP 404)"

The organization, project, or environment slug is incorrect. Double-check the slugs in your workflow file.

"No secrets found for the specified environment"

The environment exists but has no secrets. Add secrets via the dashboard or CLI before running the action.