Goal: Enable automated integration testing without accidentally leaking our API keys and other secrets; at the same time permit anyone to automate their own tests without having to share their API keys and secrets.
masterbranch of StackExchange/dnscontrol.
Github Actions has a secure secrets storage system. Those secrets are available to Github Actions and are required for the integration tests to communicate with the various DNS providers that DNSControl supports.
For security reasons, those secrets are unavailable if the PR comes from outside the project (a forked repo). This is a good thing. If it didn’t work that way, a third-party could write a PR that leaks the secrets without the owners of the project knowing.
The docs (and many blog posts) describe this as forked repos don’t have access to secrets, and instead receive null strings. That’s not actually what’s happening.
Actually what happens is the secrets come from the forked repo. Or, more precisely, the secrets offered to a PR come from the repo that the PR came from. A PR from DNSControl’s owners gets secrets from github.com/StackExchange/dnscontrol’s secret store but a PR from a fork, such as https://github.com/TomOnTime/dnscontrol gets its secrets from TomOnTime’s secrets.
Our automated integration tests leverages this info to have tests only run if they have access to the secrets they will need.
Tests are executed if
*_DOMAIN exists. If the value is empty or
unset, the test is skipped. If a test doesn’t require secrets, the
*_DOMAIN variable is hardcoded. Otherwise, it is set by looking up
the secret. For example, if a provider is called
FANCYDNS, there must
be a secret called
This section describes how to add a provider to the testing system.
In this example, we will use a fictional DNS provider named “FANCYDNS”.
Step 1: Create a branch
Create a branch as you normally would to submit a PR to the project.
Step 2: Update
In this branch, edit
integration-testssection, add the name of your provider to the matrix of providers. Technically you are adding to the list at
matrix: provider: ... - DIGITALOCEAN - GANDI_V5 - FANCYDNS <<< NEW ITEM ADDED HERE - INWX
Locate the env section (technically this is
add all the env names that your provider sets in
Please replicate the formatting of the existing entries:
*_DOMAINvariable is first.
FANCYDNS_DOMAIN: $ FANCYDNS_KEY: $ FANCYDNS_USER: $
Let’s look at three examples:
BIND integration tests do not require any secrets because it
simply generates files locally.
The existence of
BIND_DOMAIN, and the fact that the value is
available to all, means these tests will run for everyone.
AZURE_DNS provider requires many settings. Since
AZURE_DNS_DOMAIN comes from GHA’s secrets storage, we can be assured
that the tests will skip if the PR does not have access to the
If you have a fork and want to automate the testing of
simply set the secrets named in
build.yml and the tests will
activate for your PRs.
AZURE_DNS_RESOURCE_GROUP is hardcoded to
this is not true for you, please feel free to submit a PR that turns
it into a secret.
AZURE_DNS_DOMAIN: $ AZURE_DNS_CLIENT_ID: $ AZURE_DNS_CLIENT_SECRET: $ AZURE_DNS_RESOURCE_GROUP: DNSControl AZURE_DNS_SUBSCRIPTION_ID: $ AZURE_DNS_TENANT_ID: $
The HEXONET integration tests require secrets, but HEXONET provides an Operational Test and Evaluation (OT&E) environment with some “fake” credentials which are known publicly.
Therefore, since there’s nothing secret about these particular
secrets, we hard-code them into the
build.yml file. Since
HEXONET_DOMAIN does not come from secret storage, everyone can run
these tests. (We are grateful to HEXONET for this public service!)
HEXONET_DOMAIN: a-b-c-movies.com HEXONET_ENTITY: OTE HEXONET_PW: test.passw0rd HEXONET_UID: test.user
NOTE: The above credentials are known to the public.
Sadly there is no locking to prevent two PRs from running the same test on the same domain at the same time. When that happens, both PRs running the tests fail. In the future we hope to add some locking.
Also, maintaining a fork requires keeping it up to date. That’s a bit more Git knowledge than I can describe here. (I’m not a Git expert by any stretch of the imagination!)