direnv action

Provides environment variables via direnv

This action provides environment variables via direnv, evaluates the target .envrc, and exports the resulting environment variables to subsequent workflow steps.

Documentation site: https://hatsunemiku3939.github.io/direnv-action/

Who uses this action

How it works

The action performs the following steps:

Installs the requested direnv version from the GitHub release assets or a cache. Cold installs verify the downloaded binary's SHA-256 digest before execution or caching.
Runs direnv allow for the configured path.
Runs direnv export json in the configured path.
Logs the exported environment variable names without printing their values.
Optionally verifies that required environment variable names were exported.
Exports the resulting variables to the GitHub Actions environment.
Appends PATH entries through core.addPath() when PATH is present in the exported values.
Masks configured secret values with the GitHub Actions masking API.

Inputs

direnvVersion: The direnv version to use. Default: 2.37.1.
direnvChecksum: Optional SHA-256 checksum for the downloaded direnv binary. Default: ''.
masks: A comma-separated list of environment variable names to mask. Default: ''.
required: A newline-delimited list of environment variable names that must be exported. Default: ''.
path: The directory where direnv allow and direnv export json are executed. Default: ..

Outputs

No outputs

Example usage

Examples below pin the current release, v1.4.6. If you prefer compatible updates within the current major line, use the moving major tag @v1.

uses: HatsuneMiku3939/direnv-action@v1.4.6
with:
  direnvVersion: 2.37.1
  masks: SECRET1, SECRET2

This loads the .envrc file from the repository root.

By default, cold installs verify the downloaded direnv binary against the GitHub Release API asset digest. To pin an expected digest yourself, set direnvChecksum to either a plain SHA-256 hex digest or a sha256:<digest> value:

uses: HatsuneMiku3939/direnv-action@v1.4.6
with:
  direnvVersion: 2.37.1
  direnvChecksum: sha256:1f1b93dd6f38523fde26dfac96151ef9d31a374e3005cd3345fb93555ae0c9b5

To evaluate the .envrc in a subdirectory, set path explicitly:

uses: HatsuneMiku3939/direnv-action@v1.4.6
with:
  path: child
  masks: SECRET1, SECRET2

To fail early when expected variables are not exported, set required:

uses: HatsuneMiku3939/direnv-action@v1.4.6
with:
  required: |
    AWS_REGION
    DATABASE_URL
    NODE_AUTH_TOKEN

For the most predictable builds, pin an exact version tag such as @v1.4.6. Use @v1 only when you want to receive the latest compatible v1.x.y release automatically.

Behavior notes

masks accepts environment variable names, not raw secret values.
required accepts environment variable names, not raw values, and fails when any listed name is absent from the exported environment.
When .envrc exports PATH, the action appends it to the job PATH instead of overwriting the entire value.
Variables exported by direnv export json are available to later workflow steps in the same job.
The action logs exported variable names for debugging, but it does not print environment variable values.
The action does not define custom outputs; consumers should read exported environment variables directly.
Cold installs verify the downloaded direnv binary before marking it executable or saving it to any cache.
When direnvChecksum is provided, the action cache key includes that checksum so different pins do not share cache entries.

Security considerations

This action evaluates .envrc, which means repository code can influence the shell commands executed by direnv. Treat .envrc as executable code, especially in workflows that can access repository secrets, cloud credentials, deployment tokens, or production infrastructure.

Only use this action with trusted repositories and trusted .envrc contents.
Avoid evaluating untrusted fork contents from pull_request_target workflows. If you use pull_request_target, do not check out and run a fork-provided .envrc in a job that has access to secrets.
Prefer running secret-bearing jobs only on trusted refs, protected branches, or reviewed tags. For fork PR validation, use pull_request with minimal permissions and without repository secrets unless the .envrc contents are trusted.
Use the required input to fail early when expected exported variables are missing. This helps prevent downstream steps from running with incomplete configuration, but it is not a sandbox or a secret-protection boundary.
Keep workflow permissions: as narrow as possible and avoid passing long-lived credentials into jobs that evaluate changing .envrc files.
Treat masking as a log redaction aid, not a complete secret protection boundary.
Keep sensitive logic inside trusted workflow contexts whenever possible.
Download verification uses the GitHub Release API asset digest by default. This protects against corrupted or swapped download bytes relative to GitHub's release metadata. For a stronger independent pin, provide direnvChecksum.

Development

Run the local quality checks before packaging or releasing changes:

npm run lint
npm test

For release preparation, use the full gate so the generated dist/ artifacts stay in sync:

npm run all

The Vitest unit tests cover binary URL selection, downloaded binary checksum verification, tool installation cache branches, environment export behavior, required variable validation, secret masking, and the main action flow with mocked GitHub Actions APIs.