How to Inject Environment Variables Into Builds

A build can pass on your laptop and fail in CI because one variable is missing or named differently. To inject environment variables into the build process safely, first decide when the value is needed, then pass it only to the tool or job that needs it.

We analyzed 44 comments and questions from Reddit, YouTube and Quora about environment variable injection in builds and found that 27% mentioned the difference between build time and runtime injection.

Keep public build settings separate from secrets. Docker’s guidance adds a useful warning: build arguments and image environment settings aren’t safe places for credentials.

Step 1: Identify Which Variables the Build Needs

Start with a list of every value the build reads. An environment variable is a key-value setting supplied outside your application code. It can tell a build which API base URL to use, which mode to run, or how to reach a service.

Write the key names in a checked-in .env.example file, with safe placeholder values. Keep actual local values in .env or another local-only file, and add those files to .gitignore before adding secrets. Use uppercase names with underscores, such as DATABASE_URL. Keep the spelling and letter case the same in your app and deployment settings.

Mark each variable as public or secret. A browser app’s public API address may be embedded in its JavaScript during the build. A database password must stay on the server. Any variable exposed to client code through a framework prefix can become visible to users, so never put private credentials in those values.

Then mark the stage that needs each value: build time, application startup, or both. Static-site generation may need a database URL while creating pages, even if the running server also needs that value later. A local script might need it only for a migration or seed command.

Use the smallest useful scope. A global value can affect many projects; a project or environment value limits the reach. EnvManager can keep team .env values in one encrypted, role-based system and inject selected values into a command. Its CLI command for running with injected secrets supports limiting what the command can access.

Milestone: You should have a variable inventory, a safe example file, and a clear answer for when each value is needed.

Step 2: Set Variables for a Local Build

For local work, store development values in a file your framework or command can load. Keep real credentials out of Git. Add the file to .gitignore, then commit a matching example file that lists required keys without usable secrets.

Frameworks don’t all load files the same way. Some read .env files automatically; a standalone script may need a command-line flag or a loader. For a Node.js script, for example, you can run node --env-file=.env app.js when your Node version supports that option. If a package script needs a variable across Windows and macOS, a cross-platform helper such as cross-env can set it in the script command.

For example, a build mode can change what Eleventy includes. Set ELEVENTY_ENV=dev for local work, then set it to prod for the production build. The Eleventy config can read that value and ignore documentation files only in production. The variable changes the build’s behavior; it doesn’t need to be a secret.

For a containerized development workspace, keep the env file outside source control and point the container setup at it. Use the full file path if the setup requires one. Treat this file as local configuration, not as a safe way to share team credentials.

Managed build services have their own settings. Most let you set variables through a UI, CLI, API, or configuration file, though secrets belong in protected settings rather than a committed config file.

EnvManager can also sync a team’s encrypted .env values to local machines, so developers don’t have to pass secrets around in chat or copy them by hand. Pull the values you need, then run the local build in the same shell context that can read them.

Milestone: Run the local build once with the intended file or shell environment, then confirm it reads the expected mode.

Step 3: Add Variables to Your CI/CD Build Environment

CI jobs start in clean environments. Don’t rely on a shell profile or a file from your laptop. Add each value to the CI platform’s protected settings, then scope it to the job or environment that needs it.

In GitHub Actions, store credentials as secrets and refer to them from a workflow step. Keep ordinary values, such as a public API address or build mode, separate from secrets. GitHub documents secret use in workflows and notes that secrets aren’t passed to workflows triggered by pull requests from forks. That protects credentials from untrusted code, but it can also explain why a forked pull request fails where a trusted branch succeeds.

For non-secret text that must be hidden in logs, GitHub Actions supports the ::add-mask:: workflow command. Masking is a log safeguard, not secret storage. Don’t print credentials to test whether they loaded.

Jenkins users can configure job-level injection with the Environment Injector plugin. The common setup flow is to enable injection, provide a properties file or inline values, set the variables for the job, and mask passwords in logs. If the job checks out source code first, place injection after checkout when the properties file lives in the workspace. If the job needs a value before checkout, use a source that’s available earlier, such as a managed credential or job setting.

Vercel has separate Development, Preview, and Production scopes. Check the scope as well as the key name. After changing a value, trigger a fresh build so the new setting reaches the output. A variable that works locally but fails in Preview may simply be assigned to the wrong target.

With Maven on Windows, system environment settings can provide values to a build process. Set the variable in Windows’ Environment Variables settings, then reopen the command prompt or IDE before running Maven. For project-only values, use the build runner’s supported configuration instead of changing every user’s machine.

EnvManager supports syncing secrets to CI/CD pipelines. Keep credentials restricted to the specific job that uses them, and keep the checked-in workflow file free of actual secret values. For platform-specific guidance, see the CI/CD variables and secrets guide.

Milestone: Run one CI build and check that the required key names are present without exposing their values in logs.

Step 4: Pass Variables Into the Build Tool or Container

Once the value is stored, make sure the actual build command can read it. A variable set in a dashboard won’t help if the build runs in another job, service, or container. Pass only the keys that process needs.

For a Node script, the process reads values from its environment. For Vite, client-facing values need the expected VITE_ prefix. Other frameworks use their own rules. Check the framework’s naming and loading behavior before changing a key, because a correctly set value can still appear undefined when the app expects a different name.

Bundlers such as esbuild need a clear path from the environment into the code they compile. Don’t assume every bundler replaces arbitrary environment names automatically. Use its supported definition or substitution settings for public build-time values, and verify what ends up in the output bundle. Never use that route for a private credential.

Docker’s distinction is especially important. Use ARG for non-secret build inputs such as a version or build flag. Use ENV for safe defaults that should persist in the image or running container. But Docker warns that build arguments and environment variables are inappropriate for build secrets because values may appear in image metadata, provenance records, or image history. Use dedicated secret or SSH mounts for credentials instead. Read Docker’s build variable guidance before passing a secret to a Docker build.

For a runtime container, pass configuration when the container starts rather than baking a production password into its image. That lets the same image run in more than one environment without embedding each environment’s credentials in the build output.

EnvManager’s command wrapper can inject only selected values into the child process. For example, run envmanager run --only STRIPE_KEY -- npm run seed to make that key available to the seed command. The value is supplied to the process rather than written into the command itself. For more guidance on keeping credentials out of outputs, use this guide to preventing secrets from leaking into build artifacts.

Milestone: The build tool receives the required values, while the image and browser bundle contain only data meant to be public.

Step 5: Verify the Build and Protect the Values

Test the build in the same stage where it will run. A local success doesn’t prove that CI has the same key, scope, or framework settings. Make the application fail early with the missing key’s name, but never include the value in the error.

When a build fails, check the basics in order:

• Confirm the variable exists in the platform or local file.
• Compare spelling and letter case with the code and .env.example.
• Check whether the value is scoped to Development, Preview, Production, or the right CI job.
• Find out whether the app reads it at build time or when the process starts.
• After a platform change, rebuild or restart the process that needs the new value.

If a variable is undefined, check whether the framework loads the file but a separate tool does not. A framework may read .env.local while a migration or seed script launched beside it does not. Pass the file to that script or load it explicitly. Also check quotes, spaces, line breaks, and special characters if a value looks truncated.

Never dump the whole process environment to debug a build. Logs can outlive a job and be visible to more people than the secret store. Check presence instead, such as printing a message that says a required key is set. GitHub Actions’ masking command can help protect log output, but avoid echoing secrets in the first place.

Use role-based access control (RBAC) to limit who can change or retrieve sensitive values. EnvManager centralizes encrypted .env files with role-based access, so teams can sync values to local machines and CI/CD without relying on manual copy-paste. Grant access by need, then review who can edit production values.

If a secret reaches Git history, a log, or a build artifact, treat it as exposed. Remove the leaked copy where possible, then rotate or revoke the credential. Deleting the visible text alone doesn’t make the old key safe again.

Milestone: The build passes in its target environment, logs show no secret values, and each credential has a clear owner and scope.

FAQ

Should I put environment variables in a .env file?

Yes, a local .env file can hold development settings, but keep real credentials out of source control. Add the file to .gitignore before storing secrets in it. Commit a .env.example file with the required key names and safe placeholders so teammates can set up their own values.

Are Docker build arguments safe for secrets?

No, Docker advises against using build arguments or Dockerfile environment settings for secrets. Values can persist in image metadata, provenance records, or image history. Use a dedicated secret mount or SSH mount when a build needs credentials, and inject deployment-specific values when the container starts.

Why does an environment variable work locally but fail in CI?

The CI job may not have the key, may use a different spelling, or may have the wrong environment scope. Check whether the workflow can access secrets for its trigger type, especially for pull requests from forks. Then confirm the build step runs after the variable is made available.

How can I check that a secret reached the build?

Check whether the key is present without printing its value. Add a validation step that reports a missing variable by name, then fails the build. Also verify that the build runs in the intended environment and that the framework reads the variable at the stage where you set it.

Conclusion

Set each variable at the stage that needs it, and keep credentials out of source files, browser bundles, and Docker build arguments. Start by listing the required keys in .env.example, then run one build in CI and verify its scope and logs. For shared secrets, use a controlled injection path such as EnvManager instead of copying values between machines.