Netlify Integration

Inject KeyEnv secrets into your Netlify builds using the KeyEnv CLI.

How It Works

The KeyEnv CLI pulls your secrets into a .env file before your build runs. Netlify automatically loads .env files during builds, making your secrets available as environment variables throughout the build process.

Setup

1. Add Your Service Token to Netlify

Go to your KeyEnv dashboard
Navigate to Settings > Service Tokens
Create a new token with:
- Scope: Select your project (recommended)
- Permissions: secrets:read
Add the token to Netlify:
- Go to Site settings > Environment variables
- Click Add a variable
- Key: KEYENV_TOKEN
- Value: Your service token
- Scopes: Select all (or specific contexts)

Also add KEYENV_PROJECT with your project ID if your token is not project-scoped.

2. Install the CLI During Build

Update your build command in netlify.toml to install the KeyEnv CLI and pull secrets before building:

# netlify.toml
[build]
  command = "curl -fsSL https://keyenv.dev/install.sh | bash && keyenv pull -e production -o .env && npm run build"
  publish = "dist"

That's it. The keyenv pull command writes a .env file that your build framework picks up automatically.

Examples

React / Vite

# netlify.toml
[build]
  command = "curl -fsSL https://keyenv.dev/install.sh | bash && keyenv pull -e production -o .env && npm run build"
  publish = "dist"

Next.js

# netlify.toml
[build]
  command = "curl -fsSL https://keyenv.dev/install.sh | bash && keyenv pull -e production -o .env && npm run build"
  publish = ".next"

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

Gatsby

# netlify.toml
[build]
  command = "curl -fsSL https://keyenv.dev/install.sh | bash && keyenv pull -e production -o .env && gatsby build"
  publish = "public"

Astro

# netlify.toml
[build]
  command = "curl -fsSL https://keyenv.dev/install.sh | bash && keyenv pull -e production -o .env && npm run build"
  publish = "dist"

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

Using a Build Script

For more control, create a build script:

#!/bin/bash
# scripts/netlify-build.sh
set -euo pipefail

# Install KeyEnv CLI
curl -fsSL https://keyenv.dev/install.sh | bash

# Pull secrets for the current environment
# Uses KEYENV_TOKEN and KEYENV_PROJECT from Netlify env vars
keyenv pull -e "${KEYENV_ENV:-production}" -o .env

echo "Loaded secrets from KeyEnv"

# Run the actual build
npm run build

Then reference it in netlify.toml:

[build]
  command = "bash scripts/netlify-build.sh"
  publish = "dist"

Environment-Specific Builds

Use Netlify's deploy context environment variables to pull the right KeyEnv environment:

# netlify.toml
[build]
  command = "curl -fsSL https://keyenv.dev/install.sh | bash && keyenv pull -e production -o .env && npm run build"
  publish = "dist"

# Override for deploy previews
[context.deploy-preview]
  command = "curl -fsSL https://keyenv.dev/install.sh | bash && keyenv pull -e staging -o .env && npm run build"

# Override for branch deploys
[context.branch-deploy]
  command = "curl -fsSL https://keyenv.dev/install.sh | bash && keyenv pull -e development -o .env && npm run build"

Or use a single command with a variable:

[build]
  command = "curl -fsSL https://keyenv.dev/install.sh | bash && keyenv pull -e $KEYENV_ENV -o .env && npm run build"

[context.production.environment]
  KEYENV_ENV = "production"

[context.deploy-preview.environment]
  KEYENV_ENV = "staging"

[context.branch-deploy.environment]
  KEYENV_ENV = "development"

Netlify Functions

Secrets pulled into .env are available to Netlify Functions at build time via process.env:

// netlify/functions/api.js
export async function handler(event, context) {
  const apiKey = process.env.API_KEY;

  const response = await fetch('https://api.example.com', {
    headers: { Authorization: `Bearer ${apiKey}` }
  });

  return {
    statusCode: 200,
    body: JSON.stringify(await response.json())
  };
}

Security

The service token is stored securely in Netlify's environment variables
Secrets are fetched over HTTPS
The .env file is only present during the build and is not deployed
Service tokens can be scoped to specific projects and environments

Troubleshooting

"Authentication failed"

Verify KEYENV_TOKEN is set in Netlify environment variables
Check the token has not expired
Ensure the token is available in the deploy context you are using

"Access denied"

The token may not have access to the specified project
The token may not have access to the target environment
Check token permissions in the KeyEnv dashboard

"Project or environment not found"

Verify the project ID is correct
Check that the environment name matches exactly (case-sensitive)
Ensure the environment exists in your KeyEnv project

Secrets not available during build

Make sure keyenv pull runs before your build command
Verify the .env file is being written to the project root
Check the build logs for errors from the keyenv pull command

Netlify

On this page