Skip to main content

​
Overview

First-party applications are services you build and deploy, like the go-backend example in the kit. This page covers how to make changes and deploy them through the GitOps pipeline.

​
Deployment Flow

Changes flow through staging first, then to production after verification: 
┌────────────┐
│ STAGING    │  Merge to main -> Build -> Update manifests -> ArgoCD syncs ─┐
└────────────┘                                                              │
                ┌──────────────────── Verify Changes ───────────────────────┘
┌────────────┐  │
│ PRODUCTION │  └─> Merge Release PR -> Build -> Update manifests -> ArgoCD syncs
└────────────┘
Each step is detailed in the sections below.

​
Make Code Changes

1

Edit your service code

Make changes to your application in services/:
# Example: modify the go-backend service
vim services/go-backend/cmd/main.go
2

Test locally

Use the local development environment to test:
mise run //local:tilt-up
Tilt automatically rebuilds and redeploys when you save changes.
3

Commit and push

git add services/go-backend/
git commit -m "feat: add new endpoint for health checks"
git push origin main

​
What Happens After Push (Staging)

​
1. CI Build Workflow

The CI workflow (.github/workflows/ci-build-push.yml):
  1. Detects which services changed using path filters
  2. Generates a version tag (e.g., 0.2.2-rc0029-g1234567)
  3. Builds the Docker image
  4. Pushes to ECR
  5. Triggers the GitOps workflow

​
2. GitOps Update Workflow

The GitOps workflow (.github/workflows/gitops-update-manifests.yml):
  1. Updates the image tag in values files (e.g., kubernetes/src/services/go-backend-helm/values.yaml)
  2. Renders the Kubernetes manifests
  3. Commits and pushes to main
The image tag is identified by a comment marker: 
image:
  version: 0.2.2-rc0029-g1234567 # staging_services/go-backend

​
3. ArgoCD Sync

ArgoCD watches the repository and automatically syncs when manifests change. You can monitor the sync in the ArgoCD UI or CLI: 
argocd app get go-backend-helm
argocd app sync go-backend-helm

​
Version Tagging Strategy

TriggerTag FormatExampleEnvironment
Push to mainX.Y.Z-rcNNNN-gSHA0.2.2-rc0029-g1234567Staging
Release tagX.Y.Z0.2.3Production
Manual workflowUser-specifiedhotfix-123User-specified

​
Pre-release Versions (Staging)

When you push to main, the version is generated as:
  • Base: last release tag + 1 patch (e.g., 0.2.2 → 0.2.3)
  • Suffix: -rcNNNN-gSHA where NNNN is commits since last tag
This ensures every commit has a unique, sortable version.

​
Release Versions (Production)

To deploy to production, create a release tag: 
git tag "services/go-backend@0.2.3"
git push origin "services/go-backend@0.2.3"
This triggers the same build workflow but:
  • Uses the exact version from the tag (0.2.3)
  • Sets environment to production

​
Deploy to Production

1

Verify staging deployment

Ensure the change works correctly in staging before promoting to production.
2

Merge the Release Please PR

The Release Please workflow (.github/workflows/release-please.yml) automatically creates a release PR when changes are pushed to main. The PR:
  • Bumps the version based on conventional commit messages
  • Updates the CHANGELOG
  • Shows all changes since the last release
When you merge the release PR:
  1. A GitHub release is created with the new version tag
  2. The CI workflow (.github/workflows/ci-build-push.yml) builds and pushes the production image
  3. The GitOps workflow (.github/workflows/gitops-update-manifests.yml) updates production manifests
  4. ArgoCD syncs to the production cluster
You can also create a release manually by pushing a tag:
git tag "services/go-backend@0.2.3"
git push origin "services/go-backend@0.2.3"
3

Monitor the deployment

Watch the CI workflow and ArgoCD sync:
# Check workflow status
gh run list --workflow=ci-build-push.yml

# Check ArgoCD
argocd app get go-backend-helm --grpc-web

​
Manual Deployment

For debugging or hotfixes, you can trigger deployments manually:
Build and push an image without deploying:
gh workflow run ci-build-push.yml \
  -f service=services/go-backend \
  -f version=hotfix-123

​
Update Kubernetes Configuration

To change Kubernetes configuration (replicas, resources, etc.) without changing application code:
1

Edit the configuration

For Helm-based services, edit the values file:
vim kubernetes/src/services/go-backend-helm/values.yaml
For Kustomize-based services, edit the overlay:
vim kubernetes/src/services/go-backend/staging/kustomization.yaml
Example changes:
replicas: 3  # Increase replicas
resources:
  requests:
    memory: "256Mi"
    cpu: "250m"
2

Render manifests

mise run //kubernetes/src/services:render-all "<CLUSTER>"
3

Commit and push

git add kubernetes/
git commit -m "chore: increase go-backend replicas to 3"
git push origin main
ArgoCD syncs the new configuration without rebuilding the image.

​
Rollback

To rollback to a previous version:
Update the image tag to a previous version:
# Edit values.yaml
vim kubernetes/src/services/go-backend-helm/values.<STAGE>.yaml

# Change image version to previous tag
# image:
#   version: 0.2.2-rc0028-g98b8c55

# Render and push
mise run //kubernetes/src/services:render-all "<CLUSTER>"
git add . && git commit -m "fix: rollback go-backend to 0.2.2-rc0028"
git push origin main

​
Next Steps