GitHub Environments & Promotion Pipeline

[73dward5]

GitHub Environments Opt-In & Force Regeneration

Overview

This adds optional flags to azd pipeline config to allow pushing environment variables/secrets to the GitHub environment instead of the repo level variables/secrets and federating the identity with that environment instead of the branch or PR.

Adds:

• --github-use-environments to generate a GitHub Actions workflow using GitHub Environments (single or matrix when multiple azd envs).
• --force-regenerate to overwrite the existing workflow unconditionally.

Also: migration heuristics, federated credential pruning, repo variable cleanup, updated snapshots, lint/spelling fixes.

Key Changes

• Flags: --github-use-environments, --force-regenerate
• Workflow template: conditional matrix, max-parallel: 1, secret/variable validation
• Auto-regeneration when env-mode mismatch detected
• Prunes legacy federated credentials (branch / PR subjects) for SP & MSI
• Removes redundant repo-level variables after migration
• Manager helpers: EnableGitHubEnvironments, ForceRegenerateWorkflow
• Snapshot & usage/help updates
• Typo fix: progess → progress
• All golangci-lint issues resolved

Behavior & Migration

Scenario	Result
Legacy workflow + opt-in	Regenerates with env matrix (if >1 env)
Env workflow + opt-out	Regenerates to legacy single
Any state + --force-regenerate	Always rewrites

Pruning Scope

Only deletes federated credentials with :pull_request or :ref:refs/heads/ (keeps :environment: subjects).

Testing

• Short tests pass
• Updated snapshots pass
• Functional failures unrelated (local env missing .NET 8, expired Azure auth token)
• Lint: clean

Risks & Mitigations

Risk	Mitigation
Unexpected overwrite	Requires explicit flag or mismatch
Over-pruning	Filters to known legacy subjects
Env var API limitations	Heuristic delete for known migrated names

Follow-Ups

• Docs for env vs legacy mode
• Release notes entry
• (Optional) cspell dictionary tuning

Checklist

• Flags
• Template logic
• Migration + pruning
• Tests & snapshots
• Lint/spelling
• Docs
• Release notes

Release Notes Blurb

Adds opt-in GitHub Environments workflow generation (--github-use-environments) and --force-regenerate to forcibly recreate workflows, with automatic migration and cleanup of

[73dward5]

• [5664] GitHub pipeline config: supports setting secrets & variables in a GitHub Environment named after the current azd environment (automatically created if needed) and adds a matching OIDC federated credential subject (repo:<owner>/<repo>:environment:<AZURE_ENV_NAME>). (Previously configurable via AZD_GITHUB_ENV; that variable is now ignored.) Fixes #5473.
• [5664] Added optional --github-use-environments flag to azd pipeline config to emit GitHub Environment (and matrix when multiple) blocks. Disabled by default; existing workflows remain unchanged unless flag is provided. Re-running with the flag toggled will migrate the existing workflow by adding or removing the environment/matrix section. Addresses matrix & multi‑environment ask in #2373 and community feedback in discussion #3585.
• [5664] Environment mode now migrates standard AZD pipeline variables to the GitHub Environment scope (removing repo-level duplicates) and generates only the environment federated credential subject. Related to #5473.
• [5664] Automatic pruning of legacy branch & pull_request federated identity credentials when switching to environment-only mode (service principal & MSI identities). Part of cleanup for #5473.

[73dward5]

@microsoft-github-policy-service agree

[73dward5]

I am fine with this PR being rejected, as long as you can derive some benefit from the code to implement GitHub environments.

[weikanglim]

Thanks @73dward5 for taking the time to submit this PR!

I do like inspirationally where this is going, and this does help illuminate certain design details upfront for some work we have in the backlog with #5329.

I'm curious to learn from your experience:

1. How was your experience with azd pipeline config looping through all environments? azd pipeline config traditionally targets a single environment. I could see a different implementation where azd pipeline config makes a YAML modification to the environment matrix, instead of regenerating it from scratch. But this may also introduce other potential drawbacks, cc: @vhvb1989 .
2. Was the generated matrix (run environment deployments in parallel) "good enough" for your use-case, or were you expecting some idea of promotion between environments, with perhaps a build stage that spawns deployment jobs?
3. Was it a good experience when using AZURE_ENV_NAME as the github environment name? This has come up in discussions in the past, because azd currently expects AZURE_ENV_NAME to be unique per subscription, so you may end up having something closer like myproject-dev rather than dev.

Thanks for taking the time to get this PR out and sharing your experience!

[73dward5]

1. How was your experience with azd pipeline config looping through all environments? azd pipeline config traditionally targets a single environment. I could see a different implementation where azd pipeline config makes a YAML modification to the environment matrix, instead of regenerating it from scratch. But this may also introduce other potential drawbacks, cc: @vhvb1989 .

• Having one pipeline for all environments does a couple of things. One, it helps keep the pipeline code DRY and free from duplication or misconfiguration between environments. Secondly, it allows for the environments to be promotable without having to orchestrate the environment promotions with separate pipelines. Or a branching strategy that ends up being closer to your deployment strategy, rather than staying true to your branching and contribution model.

3. Was the generated matrix (run environment deployments in parallel) "good enough" for your use-case, or were you expecting some idea of promotion between environments, with perhaps a build stage that spawns deployment jobs?

• The generated matrix works well as long as the max-parallel is 1, ensuring the environments do in fact stay promotable (e.g. Dev finishes, then Test, then Prod) instead of trying to run them all at the same time. In theory, the build should only need to run once before the deployment. However, it can be more challenging for some languages/tools to separate the environment variables from the build artifacts. For example, Terraform would need the tfvars for the plan, or a Node.js SPA might need the environment variables to be in the js. Other languages, like .NET, can be built, and then environment variables can be injected on the server (during the deployment) after the artifact is created.

5. Was it a good experience when using AZURE_ENV_NAME as the github environment name? This has come up in discussions in the past, because azd currently expects AZURE_ENV_NAME to be unique per subscription, so you may end up having something closer like myproject-dev rather than dev.

• I think AZURE_ENV_NAME as the github environment name works great to provide your current environment working context locally, but if you are building a promotable pipeline, you may want to know about all of your environments. In my opinion, if you are publishing a pipeline, you are essentially moving the build/deploy responsibility to CI/CD and no longer managing that process from your local machine. I do think that allowing custom environment names like myproject-dev rather than dev does contribute to developer flexibility and autonomy. With that flexibility, you do sort of run into some complexities in programmatically determining the promotion order, though.