Explain intended usage of storing secrets in environment and making them available to deployment workflow

[DocMoebiuz]

Details

Ok, I tried to put the main question in the title. The docs are a little bit confusing about this.

Current situation: I have three github environments defined, and every environment holds the respective secrets and env-variables. Lets say they are called "dev,test,prod". Every environment holds a secret, e.g. MY_SECRET.

I have now set up the branch-deploy action so that I can deploy to these three environments.

Deployment is associated correctly, but the subsequent workflow steps won't be able to access "MY_SECRET".

Is that correct?

You are mentioning, that we should use an additional environment, e.g. dev-secrets, test-secrets and prod-secrets which serve as the environments that now provide the secrets for us through the standard property "environment" on job level.

I haven't tried that yet, but I would assume that:

• I have to dynamically determine the value in my workflow so that deployment environment and secrets environment are the corresponding ones, or is this solved by branch-deploy?
• I would end up with two actual deployments in my list (e.g. on the repo home page) for every deloyment that I trigger through branch-deploy

Please help me confirm my understanding.

[DocMoebiuz]

I can confirm that the -secrets environments show on the repo home page too.

I understand, it is Github that automatically creates a deployment object as soon as a job is using environment-property. And it also updates it when the workflow job then is done. That's why the branch-deploy deployment is marked as inactive.

Idea💡- One potential solution could be to have branch-deploy update the same deployment instance which was created by github instead of creating its own? Behavior could be controlled by a property to make it backward-compatible.

[DocMoebiuz]

This issue is discussing the Github default behavior with requests to not automatically create a deployment when using environment https://github.com/actions/runner/issues/2120

[DocMoebiuz]

Here are my findings:

• branch-deploy action creates deployments programmatically using the Github API.
  • The deployment is created by the action and when using deploy/noop trigger.
  • During the post-action the deployment object is then finalized. The post-action is running at the end of the current job.
  • The deployment is associated with the environment and the correct branch
  • In this scenario, the workflow job/steps don't run in the context of a environment
  • branch protection rules from environment are not enforced
  • environment vars and secrets are not accessible
• GitHub has a very opinionated handling of environments
  • The environmentattribute is defined on job level.
  • For such jobs a individual deployment is always created
  • branch protection rules are applied
  • environment vars and secrets are accessible
  • deployment status is finialized at the end of the job run.
  • if multiple jobs in same workflow use environment, multiple deployments will be created and finished

Because of these facts, the expected way of deploying a branch to an environment using respective environment secrets & vars` does not work.

If one naively uses environment name for deploy and uses the environment name with the github job attribute, the deployment by branch-deploy will show as inactive (no green rocket) whereas the deployment done by GitHub will be displayed as active but showing that it used the main branch for the deployment.

It is a pity that this is not possible at the moment.

Possible workarounds:

• additional secret-environments - this is explained in the branch-deploy docs. Your workflow then has access to these secrets, but the environment has to have a different name from the environment that is used by branch-deploy, e.g. production and production-secrets. A deployment will be created for both environments and only one deployment actually deserves that name. One environment was created by the branch-deploy action, and the other deployment by GitHub's default environment
• repository secrets with environment prefix/suffix - instead of defining the vars and secrets on environment level they are now defined on repository level. Variable and secret names would use a environment name as part of their name, e.g., production-secret01, production-var01 vs development-secret01, development-var01. This requires that all jobs and steps know the current environment that branch-deploy action is using. This can be achieved by using the output environment which is provided by branch-deploy.

Both workarounds don't really allow to leverage other environment features like branch protection. This is due to the fact that GitHub itself is not aware that an environment context is used because this is handled internally by the branch-deploy action.

Maybe I am just stating the obvious but for me it was not obvious at all and I hope somebody might find this summary useful.

[GrantBirki]

@DocMoebiuz First of all, thank you for writing all this up! It is really great to have this all in writing in a place that is searchable and for others to find in the future. You did a great job doing a deep-dive into how this Action works and how GitHub environments are wired up.

The two possible workarounds are both valid and cover the vast majority of use cases for folks using this Action to facilitate their deployments. You did a great job explaining both the concept of using secret-environments and plain-old repository secrets.

For most folks, the ultimate deciding factor on "which one to use" for storing secrets often boils down to their risk tolerance. With environment secrets, you can actually them down to which branch can access them. Since all issue_comment: types: [created] workflow events are fired from the default branch (most often main / master), this means that you can lock secrets down really well when using this Action. For example, a bad actor would not be able to alter the workflow to on: pull_request and exfiltrate the secrets since the environment protection rules only allow them to be sourced from workflow that are related to the branch which you designated.

In contrast, if you used plain-old repository secrets, this is now of concern as you don't have the ability to lock them down with the same type of protection rules.

Here is an example of locking down environment secrets with a branch protection rule (from a repo using github/branch-deploy):

That being said, using environment-secrets isn't the cleanest look and can be confusing to contributors when they see a little green rocket and deployed to production-secrets on the homepage of a repo:

Some orgs might have great security controls in-place and have the risk tolerance to just use repo secrets and that's fine too. It all comes down to what works best for you, and how you want to protection your secrets at the end of the day 😃

---

P.S. thank you for linking https://github.com/actions/runner/issues/2120! I'm going to poke around internally at GitHub and try to figure out more about this request. I personally think it would be great if we could use an environment just for the secrets it store and not for a full on deployment in a workflow.

Thanks!