Promotion Pipeline Walkthrough

This guide walks you through the full lifecycle of the promotion pipeline — from first deploy through release, version bump, and hotfix — so you can see every workflow in action.

Prerequisites

Before starting, confirm:

• Your organization has 4 environments configured in Konstruct: dev, test, stage, prod
• A GitHub App is connected with access to your app and GitOps repositories
• AWS IAM OIDC trust policy includes main and hotfix-* branches
• ECR repositories exist for container images and Helm charts

Register the Application

1. Navigate to Applications in the Konstruct UI

2. Click Register Application

3. Select your target repository (must have a Dockerfile)

4. Choose the Promotion pipeline template:

   Field	Value
   Repository URL	https://github.com/konstructio/konstruct-templates
   Path	pipeline-templates/promotion
   Branch	main

5. Complete registration

Konstruct scaffolds your repository with 6 GitHub Actions workflows and a Helm chart under charts/.

First Deploy to Dev

Registration triggers a commit to main, which automatically runs the Publish Dev workflow.

1. Open your repository on GitHub and go to Actions
2. Watch the Publish Dev run — it builds the container, packages the chart as 0.1.0-rc.<sha>, and deploys to the dev environment
3. Verify the deployment in your dev environment — the app should return its chart version and image tag

tip

The Publish Dev workflow runs automatically on every push to main. You can also trigger it manually from the Actions tab via Run workflow.

Promote Through Environments

Each promotion reads the version currently deployed in the source environment and applies it to the next.

Promote to Test

1. Go to Actions > Promote Test
2. Click Run workflow
3. The workflow reads dev's deployed version and applies it to test
4. Verify the same version is now running in test

Promote to Stage

1. Go to Actions > Promote Staging
2. Click Run workflow
3. The workflow reads test's deployed version and applies it to stage
4. Verify the same version is now running in stage

Release to Production

1. Go to Actions > Release Prod

2. Click Run workflow

3. The workflow:

   • Reads the RC version from stage
   • Pulls the exact chart artifact from ECR
   • Re-tags it with clean semver (e.g., 0.1.0)
   • Publishes the release chart
   • Creates a GitHub release (v0.1.0)
   • Deploys to prod
   • Bumps Chart.yaml on main to 0.1.1
   • Triggers a new Publish Dev run for 0.1.1-rc.<sha>

4. After the run completes, check:

   • Production is running version 0.1.0
   • GitHub Releases has a v0.1.0 tag with generated notes
   • Dev is already running 0.1.1-rc.<sha> — the next development version

The stack is now set up for the next release cycle.

Manual Version Bump

If you need a minor or major version change (patch is handled automatically by release):

1. Go to Actions > Bump Version
2. Click Run workflow and select minor
3. Chart.yaml on main updates from 0.1.1 to 0.2.0
4. The push to main triggers Publish Dev — 0.2.0-rc.<sha> deploys to dev
5. Promote through test, stage, and release as before

Hotfix a Production Release

When you need to patch a production release without including unreleased work from main:

Create the Hotfix Branch

1. Go to Actions > Hotfix
2. Click Run workflow and enter the release tag (e.g., v0.1.0)
3. The workflow:
   • Creates a hotfix-0-1-1 branch from the v0.1.0 tag
   • Bumps the chart to 0.1.1
   • Opens a draft PR to main

Apply and Test the Fix

1. Push your fix to the hotfix-0-1-1 branch
2. The push triggers Publish Dev — the hotfix builds and deploys to dev as 0.1.1-rc.<sha>
3. Promote the hotfix through test and stage using the same promote workflows
4. Run Release Prod to release 0.1.1 to production

Merge Back to Main

1. Open the draft PR that was created automatically
2. Mark it ready for review and merge
3. This brings the hotfix into the main development track so it's included in the next planned release

Workflow Reference

Workflow	Trigger	What It Does
Publish Dev	Push to main or hotfix-*, or manual dispatch	Builds container and chart, deploys to dev
Promote Test	Manual dispatch	Reads version from dev, deploys to test
Promote Staging	Manual dispatch	Reads version from test, deploys to stage
Release Prod	Manual dispatch	Re-tags chart, creates release, deploys to prod, bumps main
Hotfix	Manual dispatch (input: release tag)	Creates hotfix branch and draft PR
Bump Version	Manual dispatch (input: patch/minor/major)	Bumps chart version on main