AWS Parameter Store in the Build
Parameter Store in the build makes configuration explicit, but it raises hard questions about secrets and reproducibility.
AWS Parameter Store in the Build
$ gatsby build
success Building production JavaScript and CSS bundles - 42.108s
Done in 71.4s
$ grep -o "undefined/graphql" public/app-8f2c1a.js
undefined/graphql
GATSBY_API_URL wasn’t in process.env during the build. The build still went green, the artifact is deployable, and the empty value is baked into the shipped JavaScript – the first place it will show up is a user’s browser. No crash, no error message in the pipeline, just a static bundle that talks to nothing.
The concrete reason for writing this down is a small Gatsby plugin I built: gatsby-plugin-aws-parameter-store-environment. During the build, it pulls configuration values from AWS Systems Manager Parameter Store and provides them as environment variables. Fifty lines of code, a very manageable problem – and still a good opportunity to make visible an architecture question that is considerably bigger than the plugin itself.
The question isn’t “How do I get a value from an AWS service?” but “Where does the configuration of a static frontend belong, who owns it, and what does the answer cost me in operations?” This boundary is exactly where it is decided whether a deployment runs smoothly or every release remains a small manual feat of strength. A tiny plugin is often the most honest place to think through a decision like this, because nothing distracts from the actual question.
The problem: configuration in a static build#
Gatsby generates static HTML, CSS, and JavaScript at build time. That is the core of the JAMstack promise: fast, cache-friendly delivery without a server in the request path. The price for this is a shift that many underestimate – configuration isn’t read at runtime but baked in at build time. Whatever is in process.env during gatsby build ends up in the result. Whatever is missing stays missing until the next build runs.
In practice, a familiar pattern quickly grows out of this. Every environment – local, staging, production – gets its own .env file. Some values live in the CI system as secrets, others in the Git repository, a few only in the head of whoever deployed last. There is no single source, just scattering. And scattering creates drift: staging runs against a different API endpoint than intended, a feature flag is set differently in production than documented, a rotated access key was updated in three of four places.
That isn’t an exotic edge case. It is the most common source of friction between “the code is done” and “the change is live.” And it is expensive, because it doesn’t show up as an outage but as creeping uncertainty: nobody knows for sure anymore which configuration a particular build actually saw.
The idea: a single source for build configuration#
Parameter Store reverses this scattering. Instead of maintaining many .env files, I define the configuration hierarchically in one place in AWS, organized by application and environment:
# One source of truth, organized by app and environment
aws ssm put-parameter \
--name "/mikebild-dev/production/GATSBY_API_URL" \
--value "https://api.mikebild.com/graphql" \
--type "String"
aws ssm put-parameter \
--name "/mikebild-dev/production/CONTENTFUL_DELIVERY_TOKEN" \
--value "cda-xxxxxxxx" \
--type "SecureString" \
--key-id "alias/build-config"
The build then pulls the entire subtree of an environment and exports it as environment variables. In gatsby-config.js, this looks deliberately unspectacular:
module.exports = {
plugins: [
{
resolve: "gatsby-plugin-aws-parameter-store-environment",
options: {
// Pull the whole subtree for this environment
path: `/mikebild-dev/${process.env.DEPLOY_ENV}/`,
withDecryption: true,
},
},
],
};
The hierarchy is the real gain, not the API call. A path like /app/environment/KEY gives the configuration a structure that you can slice with an IAM policy: the production build may read /mikebild-dev/production/*, nothing else. Values of type SecureString are stored encrypted with KMS, and every access leaves a trace in CloudTrail. “There is a file somewhere” becomes “a named, versioned, access-controlled value with an audit trail.”
Architecture: build time versus runtime#
Before I use the plugin, I draw a line. It is the most important decision of the whole topic, and the plugin doesn’t make it for me.
flowchart LR PS["Parameter Store<br/>/app/env/*"] -->|build time| B["gatsby build"] B --> OUT["Static bundle<br/>HTML / JS / CSS"] OUT --> CDN["CDN / Browser"] RT["Runtime secrets<br/>never here"] -.->|not in bundle| OUT
Everything that moves into the static bundle at build time is public. Period. An API endpoint, a public content delivery key, a feature flag, an analytics ID – these may be in the shipped JavaScript, because they are visible to every browser anyway. Gatsby even makes this explicit through the GATSBY_ prefix convention: these variables are deliberately embedded in the client bundle.
Anything that is a real secret – write access to a database, a private API key, a signing key – never belongs in a build-time value for a frontend. Not because Parameter Store couldn’t protect it, but because the target is a static artifact that is delivered publicly. The most secure storage in the world doesn’t help if I then write the decrypted value into a file that ends up on a CDN.
Parameter Store is a little seductive here, and that is the hard question about secrets: because it offers SecureString and KMS, every value feels “secure.” But the security ends at the boundary of the build. That is why I sort every parameter in advance into exactly one of two drawers: “may be public” or “is a runtime secret.” The plugin may only touch the first drawer at all. Real runtime secrets belong in a serverless function or a backend that reads them from Parameter Store itself at runtime and never hands them to the client.
The second trade-off: reproducibility#
The second hard question is subtler and easily overlooked. The moment the build reads external configuration, it is no longer a pure function of the repository. The same Git commit no longer necessarily produces the same result – it produces the result that matches the external state of Parameter Store at build time.
That is a real loss. If someone changes a value in Parameter Store and doesn’t trigger a rebuild, the deployment and the declared configuration drift apart without any commit showing it. A rollback to an old commit may not restore the old configuration, because the parameter values have changed in the meantime. “Works on my machine” gets a new, unpleasant dimension: on my machine with yesterday’s parameters.
Parameter Store has a tool for this problem, and I consider it the decisive methodological lever: every parameter is versioned. I can reference a specific version – /app/prod/KEY:4 – instead of “whatever the current value is.” That makes the build more deterministic again: a commit plus a pinned set of parameters yields a reproducible artifact. The price is deliberate discipline, because someone has to bump the version and thereby treat the configuration change exactly like a code change: visible, traceable, rollback-capable. That is exactly the point where configuration stops being a sideshow and becomes part of the architecture.
What this measurably improves#
The effort pays off because it has a concrete effect in three places, not just elegance.
Shorter cycles: a new environment is a new path in Parameter Store, not a new ritual of .env files, copy and paste, and questions in the chat. A deploy no longer needs manual preparation, because the configuration lives where the build picks it up anyway. The path from “change the value” to “the value is live” shrinks to a parameter update plus a build.
Less friction: access is tied to environments via IAM, not to people with file access. A developer can set a staging configuration themselves without getting at a production secret. Self-service within clean boundaries replaces the bottleneck that otherwise consists of a single person who “knows the .env.”
Higher quality: config drift becomes structurally less likely, because there is only one source left. And if something does go wrong, there is an audit trail. CloudTrail answers the question “Who changed which value when?” – the question that, with a scattering of files and CI secrets, remains fundamentally unanswerable.
There is a fourth effect that is easily overlooked but saves a lot of friction day to day: the same mechanism works locally. A developer who is allowed to read the staging values runs their local build against exactly the same path in Parameter Store as the pipeline – no manual copying of an .env, no outdated local state, no discussion about why something behaves differently locally than in staging. That closes one of the most annoying gaps in the development cycle, namely the one between the configuration on the laptop and the configuration in CI. With that, the “works on my machine” from above loses one of its most common causes, because the laptop and the pipeline read from the same source. The boundary still matters here: locally, only the public, build-safe subtree may be visible, never a production runtime secret.
What I check before using it#
An idea only holds up once its failure path is described. Before I hook the plugin into a pipeline, I go through a few questions that all stay invisible in demo mode and decide things in operations.
What happens if Parameter Store isn’t reachable during the build or an expected value is missing? A build that silently runs through with an empty process.env.GATSBY_API_URL is more dangerous than one that aborts loudly – because it produces a broken but deployable artifact. Here I want a hard fail-fast, not an undefined that only shows up in the user’s browser.
Is access scoped narrowly enough? Via an IAM role, the build runner should be allowed to read exactly the one environment path, with withDecryption only for the values it really needs. Broad ssm:GetParametersByPath access across the entire hierarchy is convenient, and it is exactly the kind of convenience that makes a security review expensive later.
And the crucial question: is there accidentally a real secret in the path the build reads? That isn’t a technical mistake but a disciplinary one – and the most common one. That is why I separate the hierarchy right in the naming, so that build-public values and runtime secrets never end up in the same subtree in the first place, and access that is too broad doesn’t immediately mean a leak.
The typical mistake#
The most tempting mistake with this topic is confusing the tool with the solution. Parameter Store isn’t a configuration architecture, any more than encrypted storage is automatically a secrets strategy. It is a very good place to express a boundary – the boundary between build-public configuration and a runtime secret, between environments, between what a build may read and what it should never see. But I create this boundary, not the service.
That is exactly where the real value of this small plugin lies. It forces me to answer the question that the .env scattering successfully hid: what part of my frontend’s configuration is public, what is secret, and who owns each of these values across its lifecycle? As soon as that answer is in place, the technical rest – a path, a plugin, a GetParametersByPath – is almost trivial.
Closing#
Parameter Store in the build is a good example of how the interesting decision rarely lies in the tool’s name. The plugin fetches values from AWS – that is the easy half. The load-bearing half is the method behind it: make configuration explicit, keep it in exactly one place with clear access boundaries, enforce the separation of public and secret, and get reproducibility back through pinned versions.
If you draw these lines, you gain shorter deploy cycles, less friction with every environment, and fewer silent errors in operations. If you don’t, you end up with very secure storage from which secrets still seep into a public bundle. The difference isn’t in the service but in the decision it makes visible.
Revised and translated from German with the help of AI.