Security of netlify.toml contents

We need a way to remove or encrypt secrets present in netlify.toml.

Currently, if you only build on a master branch (or you build on non-master branches too but your secrets don’t differ by branch), you can set up sensitive env vars in the Netlify UI and non-sensitive env vars in netlify.toml and everything works fine.

However if you use branch builds and some of your secrets differ by branch, there is no way to provide env vars other than in netlify.toml (in a [context.ENVNAME.environment] section). The Netlify UI does not have a way to define env vars per context / branch.

Checking secrets (passwords, tokens etc.) into source code control is generally bad. I understand that everything else about a build comes through a git clone, so it’s convenient to have that info right there in the toml file. But the security implications of that are too negative.

I see three possible solutions:

(1) separate env vars for each build context in the Netlify UI
– overall env vars that apply unless overridden by the context
– env vars entered separately for each selected branch / context
– continue to have netlify.toml values override UI values for the same env var & context – user responsible to not overlap keys

(2) continue using netlify.toml but with a way to encrypt env vars
– e.g. TOML sections named like [secure.environment] and [secure.ENVNAME.environment] that parallel the existing [context.environment] and [context.ENVNAME.environment]
– for each site (or better: each context) Netlify would generate a encryption key and a decryption key, and provide the encryption key to the user – the user would push each secret through an encryption / base64 encoding tool and embed the base64 value in the netlify.toml file, e.g. something like:

password = ‘BASE64-ENCODED-VALUE’

– the Netlify build process would decode and unencrypt that value, after which is could be used like any other env var in the build cycle

(3) Provide an alternate channel for a separate netlify-secrets.toml file. Before pushing a commit that would still include netlify.toml but without secrets in it, the user would push netlify-secrets.toml to a separate git repo, or a SFTP server, or an S3 bucket, or upload it using the Netlify API. Many options here – I think you could use any mechanism you want as long as (1) the secrets file is not in the main repo, and (2) the secrets file can be provided per context.

Hi @chris-activewrite! I hear you about the difficulty of storing context-specific env vars securely. Your three possible solutions all make sense to me, and there are a couple of build plugins that might help with the first two.

For #1, you might want to try I haven’t tried it yet, but it was recently submitted to the Netlify plugins repository. It automatically prefixes (or suffixes) your env vars with the current deploy context, so you can add those different-context variables in the UI without having to jump through extra hoops in your code to account for them.

For #2, you could use to encrypt the files (and combine that with the contextual-env plugin for context-specific encryption keys :exploding_head:). Of course, we don’t have that [secure.environment] section you suggest, so you’d have to get the env vars into the toml file by other means.

In the end, #1 sounds easier. :slight_smile: If you end up trying one of these, I’d love to hear how it goes!


thanks for sharing those resources, @verythorough!

I’ll try those. Thanks for the great suggestions.