Scenario:

• I use something like this repo to build docker images and push them to a registry. I do this in multiple app repos across my solution, and the PR merge creates a new image tag that's immutable, ready for deployment to servers. e.g. stable-<date>-<commit-sha>
• I might use Argo CD or Flux for GitOps, I might use Helm or Kustomize to define my environment values, or I might just use GHA itself to push a image change (in yaml, toml, json, etc.)

Problem:

• Our CI tools (in this case GHA, but could be Drone, CircleCI, Jenkins, Codefresh, etc.) build our image smartly with all the fancy tags and metadata, and push to our production registry and repo, but they stop there.
• Then our CD solution needs to change the image tag, first for staging, and then eventually promoting to prod. There are some tools like Argo CD Image Updater which will watch registries for new image tags (fitting a regex or date pattern) and update Kubernetes with that image, and optionally update a GitOps repo with the tag change, but this doesn't fit all workflows. For one, updating Git after a cluster change isn't fully GitOps IMO.
• This "CI to CD" gap requires humans to merge their PR, and then go find what image tag was built (which could be 10+ minutes later since it's creating a new image from the new merge commit), and paste the correct tag into a different repo where their IaC/GitOps is stored.

Proposed solution:

• Assuming in this case we're using GHA for CI, it knows when that image is pushed to the "final" registry and what the tag is. It should "bridge the gap" with a helpful commit or PR to our IaC/GitOps repos based on our human workflow requirements.
• All this solution needs to be is a final GHA Job after a default_branch commit or PR merge. It links the CI run to an environment deployment. Bonus points for adding a notification (Slack, etc.) that the IaC/GitOps repo has a new image ready for PR merge.

In the current reusable workflow, it'll push to either Docker Hub, GHCR, or both. It'll push all tags to both registries every build. This isn't typically how more complex setups work. We should provide workflows and docs to support an additional process:

1. Image is only pushed to a single registry/repo while a PR is open. Assume this is the "Dev" registry/repo. There are multiple tags, including datetime, PR number, GHA run ID, etc.
2. Once PR is merged, a true "promotion" of that PR isn't possible (AFAIK) because the merge is really a GitHub push event. GHA can't correlate the PR merging and the push event. The image must be built again (but can lean on the layer cache of BuildKit, so it shouldn't need to rebuild any layers if the Dockerfile is designed properly).
3. Once that image is rebuilt, push the image to both registries, but only the tags we prefer for "promoted" images.

Proposal:

1. Add a new step using docker/build-push-action, but with different inputs for tags and labels. That step needs an if key to only fire on push (and if a promotion input is enabled.)
2. Change the current id: build_image step to only fire on pull_rest if the promotion input is enabled.

This should allow the calling workflow to opt-in to a promotion multi-build setup, and choose different image names and tags. Note, the image names for the promotion build will determine which registries and repos to push to.