Skip to content

Platform Release Process

This document describes the release process for the Controller, Admin, and Ecommerce platforms.

Overview

All platforms follow a continuous deployment model where changes merged to main are automatically deployed through staging and preprod environments before requiring manual approval for production. The release system automates changelog generation, GitHub release creation, and Slack notifications.

Deployment Pipeline

Each platform has its own deploy pipeline workflow:

  • Controller: deploy_pipeline.yaml
  • Admin: deploy_pipeline_admin.yaml
  • Ecom: deploy_pipeline_ecom.yaml

Pipeline stages:

  1. Staging: Automatic deployment and testing
  2. Preprod: Automatic deployment and testing after staging succeeds
  3. Prod: Requires manual approval, then deploys and tests

Release Preparation

During the preprod stage of each deploy pipeline, the prepare-release action automatically creates a draft GitHub release with a changelog.

What It Does

  1. Finds the last published release for the platform
  2. Identifies all commits from pipeline runs since then
  3. Generates a changelog from associated PRs
  4. Creates a draft GitHub release
  5. Posts announcement to internal team Slack channel (if webhook is configured)

Release Tag Format

<platform>.<version>

Examples: controller.5, admin.12, ecom.27

Release Notes Format

Release notes include:

  • Changes: List of PRs with title, number, and author
  • Chores: PRs prefixed with chore: (case-insensitive) in title or description are grouped under a separate "Chores" section at the bottom
  • Deployment: Links to the deploy pipeline run and previous release

Example release notes:

## Changes

- #1551 - Add productTitle to merchandising fields (@author)
- #1546 - Add Lambda deployment monitoring (@author)

## Chores

- #1548 - chore: update dependencies (@author)

## Deployment

- [Deploy Pipeline Run](link)
- Previous release: [controller.4](link)
- [Full diff](link)

Slack Notifications

The release system sends Slack notifications at two points:

1. Draft Release (Internal Team)

When a draft release is created during preprod deployment, a notification is sent to the internal team channel. This requires the RELEASE_DRAFT_SLACK_WEBHOOK secret.

Format:

📢 Controller Platform Release: controller.5

  • 1551 - Add feature X (@author)

  • 1546 - Fix bug Y (@author)

Approve production deployment

2. Published Release (Company-Wide)

When a release is published (after production deployment succeeds), a notification is sent to the company-wide channel. This requires the RELEASE_SLACK_WEBHOOK secret.

Format:

📢 Controller Platform Release Published: controller.5

[Full release notes]

Required Secrets

Secret Description
RELEASE_DRAFT_SLACK_WEBHOOK Webhook URL for internal team channel (draft releases)
RELEASE_SLACK_WEBHOOK Webhook URL for company-wide channel (published releases)

Both secrets are optional. If not configured, the corresponding Slack notification is skipped.

Publishing a Release

  1. Review the draft release in GitHub Releases
  2. Approve the production deployment in the deploy pipeline workflow
  3. The publish-release action automatically publishes the release once prod deployment succeeds
  4. A company-wide Slack notification is sent

Rollbacks

To roll back a production deployment:

  1. Run the appropriate Deploy & Test workflow manually
  2. Select prod as the environment
  3. Enter the previous release tag as the ref input

Troubleshooting

No commits found

The workflow includes all commits from pipeline runs since the last release. If no deployments have occurred, the changelog will be empty.

PR not appearing in changelog

PRs only appear if:

  • The commit triggered a pipeline run
  • The commit was merged via a PR (direct pushes won't have associated PRs)

Chore not categorized

Ensure the PR title or description starts with chore: (case-insensitive). The prefix must be at the very beginning.