Learn Semantic Release - GitOps and Release Automation

#Introduction

In episode 18 we monitored releases: version tags, release dashboards, and post-release validation. But there's one link in the chain that often breaks: the version ships automatically, while deployment to the cluster is still done manually by humans. This is where GitOps comes in. Its principle is simple but powerful — Git is the single source of truth, and changes that enter Git are automatically synchronized to the environment by an operator such as ArgoCD or Flux.

In this episode we cover:

1. The GitOps concept and the position of release automation within it.
2. Branch-based environment promotion from staging to production.
3. Two synchronization patterns: a manifest repo plus auto-sync, and an image updater.
4. Triggering a deploy workflow from a release tag.

#Main Discussion

#The GitOps Concept: Git as the Single Source of Truth

GitOps, a pattern popularized by Weaveworks and adopted by both ArgoCD and Flux, stands on three core principles:

1. The desired state is declared in Git. Application configuration, image tags, and replica counts are written as manifests — not as clicks on a dashboard.
2. An operator synchronizes. ArgoCD or Flux compares the state in Git with the state in the cluster, then adjusts until the two match.
3. All changes go through Git. No one can change production outside Git — an automatic audit trail, not a promise.

Semantic-release is a natural partner for GitOps. Release automation decides the version, GitOps decides where that version goes. Both work from the same source: Git.

#Aligning Release with Deployment

The complete flow becomes one straight line without human intervention:

1. A developer merges a PR to staging.
2. CI builds the image and tags it with the release candidate version.
3. semantic-release publishes tag v1.4.0-rc.1 on the staging branch.
4. GitOps synchronizes that image version to the staging environment.
5. After tests pass, the staging branch is merged to main.
6. semantic-release publishes tag v1.4.0, then the deployment to production runs.

The one key: the version semantic-release releases must be identical to the version of the deployed image. Don't let the deploy pick its own version different from the release tag. Tag the image exactly like the version tag:

docker build -t ghcr.io/acme/api:"${RELEASE_VERSION}" .
docker push ghcr.io/acme/api:"${RELEASE_VERSION}"

The RELEASE_VERSION variable is taken directly from semantic-release's output, not guessed. That way you can always trace "version X is running in the cluster" back to the exact commit and changelog.

#Branch-based Environment Promotion

The easiest-to-understand model: one branch for one environment.

Promotion isn't about copying artifacts; it's promoting an already-verified version. The code on staging has been tested, so merging staging to main only inherits a version that's already known to be good. semantic-release takes care of the version bumps:

• A new fix commit on staging → 1.4.0-rc.2.
• After the merge to main → stable 1.4.0 without a suffix.
• The next feat commit on staging → 1.5.0-rc.1.

#Pattern 1: Manifest Repo + Auto-sync

The most popular ArgoCD pattern: the target application is managed through a manifest repository (e.g. acme/deploy-configs) containing a kustomize or helm chart. The release workflow writes the new version into that manifest, then ArgoCD syncs it to the cluster.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: api
  namespace: argocd
spec:
  project: default
  destination:
    namespace: production
    server: https://kubernetes.default.svc
  source:
    repoURL: https://github.com/acme/deploy-configs
    targetRevision: production
    path: apps/api
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

The release workflow replaces the image tag in the manifest then pushes to that repository:

#!/usr/bin/env bash
set -euo pipefail
 
VERSION="${1:?tag versi wajib diisi}"
MANIFEST_REPO="git@github.com:acme/deploy-configs.git"
 
git clone --depth 1 --branch production "$MANIFEST_REPO" /tmp/deploy
cd /tmp/deploy
sed -i "s|image: ghcr.io/acme/api:.*|image: ghcr.io/acme/api:${VERSION}|" apps/api/deploy.yaml
git add apps/api/deploy.yaml
git commit -m "chore: promote api ${VERSION} ke production"
git push

The advantage of this pattern: every deployment change is a commit that can be reviewed and reverted. Rollback is just git revert v1.3.0 to the previous version — and ArgoCD automatically returns the cluster to that state.

#Pattern 2: An Image Updater That Monitors the Registry

The second pattern needs no extra workflow at all. ArgoCD Image Updater or Flux ImagePolicy monitors the container registry, finds new version tags that match the semver rules, then updates the manifest automatically.

apiVersion: image.toolkit.fluxcd.io/v1beta2
kind: ImagePolicy
metadata:
  name: api
spec:
  imageRepositoryRef:
    name: api
  filterTags:
    pattern: '^v(?P<semver>\d+\.\d+\.\d+)$'
  policy:
    semver:
      range: '>=1.0.0'

The policy above only picks up stable version tags without the rc suffix, so the image updater will never deploy a release candidate to production. You can verify the active policy with flux get imagepolicy api.

#Triggering a Deploy Workflow from a Release

How does the deployment know a release was just published? The two most common triggers:

1. The release event — runs when a GitHub Release is published by semantic-release.
2. The workflow_run trigger — runs when another release workflow finishes successfully.

An example release-event-based trigger:

name: Deploy Production
 
on:
  release:
    types: [published]
 
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout manifest repo
        uses: actions/checkout@v4
        with:
          repository: acme/deploy-configs
 
      - name: Promote to production
        run: ./promote.sh "${{ github.event.release.tag_name }}"

An example trigger based on another finished workflow:

name: Deploy Staging
 
on:
  workflow_run:
    workflows: ["Release Candidate"]
    types: [completed]
    branches: [staging]
 
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Get the version from the latest release
        run: |
          VERSION="${{ github.event.workflow_run.head_branch }}"
          echo "deploying the release result on branch $VERSION"

#Conclusion

In this episode we connected release automation with deployment automation:

• GitOps makes Git the single source of truth, and semantic-release provides a traceable version.
• Promotion from staging to production happens through branches: staging for rc, main for stable.
• ArgoCD and Flux sync changes through a manifest repo or an image updater.
• Deploy triggers use the release event or workflow_run — one trigger, not two.

Release and deployment now live in a single automatic flow. In episode 20 we'll make sure the whole team can follow this standard — through documentation, onboarding, and code review. See you there!