Integrations

Netlify Integration

@secr/netlify-plugin is a Netlify Build Plugin that pulls secrets from secr and injects them into process.env during the onPreBuild phase, before your site builds.

Quick Start

1. Install the plugin

npm install @secr/netlify-plugin

2. Create a CLI token

secr token create --name "netlify-prod"

3. Set the token in Netlify

In your Netlify site dashboard, go to Site configuration → Environment variables and add SECR_TOKEN with your token value.

4. Add the plugin to netlify.toml

netlify.toml

[[plugins]]
  package = "@secr/netlify-plugin"

  [plugins.inputs]
    org = "my-org"
    project = "my-project"
    environment = "production"

How It Works

Netlify triggers the build — When you push code or trigger a deploy, Netlify starts the build pipeline.
onPreBuild runs — The secr plugin runs in the onPreBuild phase, before your build command executes.
Read configuration — The plugin reads org, project, and environment from plugin inputs, falling back to environment variables if not set.
Pull secrets — Calls the secr API via the @secr/sdk to fetch all decrypted secrets for the resolved environment.
Inject into process.env — Each secret is set as a key-value pair on process.env, making it available to your build command and any framework that reads environment variables.
Status report — The plugin reports the number of injected secrets in the Netlify deploy summary.

Plugin Inputs

Inputs are set in [plugins.inputs] in your netlify.toml.

Option	Type	Required	Description
org	string	Yes	Organization slug in secr.
project	string	Yes	Project slug in secr.
environment	string	production	Environment slug to pull secrets from.

Environment Variables

Plugin inputs take priority. If an input is not set in netlify.toml, the plugin falls back to environment variables.

Variable	Required	Description
SECR_TOKEN	Yes	secr CLI token. Always required (no plugin input equivalent).
SECR_ORG	Fallback	Organization slug. Used if org input is not set.
SECR_PROJECT	Fallback	Project slug. Used if project input is not set.
SECR_ENVIRONMENT	Fallback	Environment slug. Used if environment input is not set.
SECR_API_URL	No	secr API base URL.

Multi-Environment Example

Use Netlify deploy contexts to pull different secrets for production, branch deploys, and deploy previews.

netlify.toml

# Default: production secrets
[[plugins]]
  package = "@secr/netlify-plugin"

  [plugins.inputs]
    org = "my-org"
    project = "my-project"
    environment = "production"

# Branch deploys: staging secrets
[context.branch-deploy.environment]
  SECR_ENVIRONMENT = "staging"

# Deploy previews: development secrets
[context.deploy-preview.environment]
  SECR_ENVIRONMENT = "development"

The SECR_ENVIRONMENT variable set in a deploy context overrides the plugin's environment input. This lets you use a single plugin block with context-specific overrides.

Troubleshooting

Error	Cause	Fix
SECR_TOKEN environment variable is required	The token is not set in Netlify site settings.	Add SECR_TOKEN in Site configuration > Environment variables.
org and project are required	Neither plugin inputs nor fallback env vars provide org/project.	Set org and project in [plugins.inputs] or as SECR_ORG/SECR_PROJECT env vars.
Secr API error: not_found	The org, project, or environment slug is incorrect.	Verify slugs with secr projects list. Check for typos in netlify.toml.
Build failed during onPreBuild	A network error or API timeout.	Verify your network allows outbound HTTPS to api.secr.dev from Netlify build containers.

Security Notes

•Token storage — Store the SECR_TOKEN as an environment variable in Netlify site settings (encrypted at rest). Never add the token to netlify.toml or commit it to your repository.
•In-memory only — Secrets are injected directly into process.env and never written to disk. They exist only for the duration of the build.
•Dedicated token — Create a separate token for Netlify builds. Revoke it without affecting other services if compromised.
•Context scoping — Use Netlify's deploy context environment variable scoping to restrict which tokens or environments are available to production vs. preview builds.
•Build logs — The plugin only logs the count of injected secrets, never the values. However, be careful with build commands that might echo environment variables.

Inject secrets into Netlify builds

npm install @secr/netlify-plugin

Create Free Account Back to Docs