Releases

May 27, 2026 · View on GitHub

Release Steps

tl;dr:

  • AI-assisted local prep: use the shared release skill or @release-agent
  • Legacy manual fallback: make release

AI-Assisted Release Prep

The canonical release skill lives in .agents/skills/release/.

  • Claude Code: use the release skill from the repo root. Claude discovers it through the .claude/skills/release symlink and reads the project-level CLAUDE.md.
  • GitHub Copilot: use @release-agent in agent mode, or invoke it locally through Copilot CLI once available.

By default the shared skill and release agent only prepare local changes. They do not commit, push, tag, or open a PR unless explicitly asked.

Manual Release Helper

tl;dr Run: $ make release

Manual Steps

Overview:

  1. Create a new branch like release-ngrok-operator-<version>
  2. Update versions and changelogs
  3. Submit a PR to main
  4. Merge PR (triggers .github/workflows to publish the new release)

Determine:

  • The Helm Chart version: helm/ngrok-operator/Chart.yaml
  • The CRDs Helm Chart version: helm/ngrok-crds/Chart.yaml
  • The ngrok-operator App version: VERSION

Steps:

  • CRDs Helm Chart Version Bump (if CRDs have changed since last release)
    1. Update version in helm/ngrok-crds/Chart.yaml to new version
    2. Update appVersion in helm/ngrok-crds/Chart.yaml to match the new version
    3. Create or update helm/ngrok-crds/CHANGELOG.md with a new section (if it doesn't exist, create it following the same format as the operator changelog)
      • Note: Use the expected tag helm-chart-ngrok-crds-<VERSION> for the full changelog
  • App Version Bump
    1. Update VERSION to new version
    2. Write a new section in CHANGELOG
      • Note: Use the expected tag ngrok-operator-<VERSION> for the full changelog (this tag will be created for you when your release PR is merged)
      • Note: Find the new commits using a link, such as https://github.com/ngrok/ngrok-operator/compare/ngrok-operator-<version>...main
  • Helm Chart Version Bump
    1. If CRDs were updated: Update the ngrok-crds dependency version in helm/ngrok-operator/Chart.yaml to match the new CRDs version
    2. Update version to new version
    3. Update the appVersion to the desired VERSION
    4. Write a new section in helm/ngrok-operator/CHANGELOG
    5. Run $ make helm-update-snapshots helm-test

Artifacts

The ngrok Ingress Controller has 2 main artifacts, a docker image and a helm chart. While the helm chart is the recommended way to install the Ingress Controller, the docker image can be used to run the Ingress Controller in a Kubernetes cluster without helm.

Docker Image

The Docker image contains the ngrok Ingress Controller binary and is available on Docker Hub here. We currently support amd64 and arm64 architectures, with future plans to build for other architectures.

Helm Chart

The helm chart is packaged and published to its own helm repository and can be installed by following the instructions in the chart's README.

CRDs Helm Chart

The ngrok-crds helm chart contains the Custom Resource Definitions (CRDs) for the ngrok operator. This chart is published to the same helm repository as the main operator chart. It allows users to manage CRD lifecycle separately from the operator, which is useful for GitOps workflows and when multiple operators share the same CRDs.

Semantic Versioning

This project uses semantic versioning for both the the docker image and helm chart.

From the semver spec:

Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable.

That said, we will treat changes in "y" as major releases and changes in "z" as minor releases until version 1.0 is reached.

Release Process

The Docker Image and Helm chart are released independently since a feature or bug fix in one may not require a release in the other. Sometimes a change will require a version bump and release in both.

Tagging

There is a different git tag pattern for each artifact.

Helm Chart

Releases of the helm chart will be tagged with a prefix of helm-chart-. For example, version 1.2.0 of the helm chart will have a git tag of helm-chart-1.2.0 or helm-chart-ngrok-operator-1.2.0 which contains the code used to package and publish version 1.2.0 of the helm chart.

When changes are made to the helm chart's Chart.yaml file, a github workflow will trigger upon merging the PR to the main branch. The workflow will package and publish the helm chart for consumption. The workflow will also create a git tag as described above.

When changing version in the helm chart's Chart.yaml file, the version should be bumped according to the semantic versioning spec as described above.

CRDs Helm Chart

Releases of the CRDs helm chart will be tagged with a prefix of helm-chart-. For example, version 0.1.0 of the CRDs helm chart will have a git tag of helm-chart-ngrok-crds-0.1.0 which contains the code used to package and publish version 0.1.0 of the CRDs helm chart.

When changes are made to the CRDs helm chart's Chart.yaml file in helm/ngrok-crds/, a github workflow will trigger upon merging the PR to the main branch. The workflow will package and publish the CRDs helm chart for consumption. The workflow will also create a git tag as described above.

Controller

Releases of the controller will be tagged with a prefix of ngrok-operator-. For example, version 1.2.0 of the docker image will have a git tag of ngrok-oeprator-1.2.0 which contains the code used to build the docker image ngrok/ngrok-operator:1.2.0.

When changes that would affect the controller's docker image are pushed to main, a github workflow will trigger. The workflow will build and publish the ngrok/ngrok-operator:latest docker image.

If the VERSION file at the root of the repo is changed, the workflow will also create a git tag for the controller as described above and publish a tagged docker image. For instance when the VERSION is changed to 1.2.0, the workflow will create a git tag of ngrok-operator-1.2.0 and publish the docker image ngrok/ngrok-operator:1.2.0.