Updating 1st Party Applications

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

Edit your service code

Make changes to your application in services/:

# Example: modify the go-backend service
vim services/go-backend/cmd/main.go

Test locally

Use the local development environment to test:

mise run //local:tilt-up

Tilt automatically rebuilds and redeploys when you save changes.

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):

Detects which services changed using path filters
Generates a version tag (e.g., 0.2.2-rc0029-g1234567)
Builds the Docker image
Pushes to ECR
Triggers the GitOps workflow

2. GitOps Update Workflow

The GitOps workflow (.github/workflows/gitops-update-manifests.yml):

Updates the image tag in values files (e.g., kubernetes/src/services/go-backend-helm/values.yaml)
Renders the Kubernetes manifests
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

Trigger	Tag Format	Example	Environment
Push to `main`	`X.Y.Z-rcNNNN-gSHA`	`0.2.2-rc0029-g1234567`	Staging
Release tag	`X.Y.Z`	`0.2.3`	Production
Manual workflow	User-specified	`hotfix-123`	User-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

Verify staging deployment

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

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:

A GitHub release is created with the new version tag
The CI workflow (.github/workflows/ci-build-push.yml) builds and pushes the production image
The GitOps workflow (.github/workflows/gitops-update-manifests.yml) updates production manifests
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"

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 only
Deploy existing image

Build and push an image without deploying:

gh workflow run ci-build-push.yml \
  -f service=services/go-backend \
  -f version=hotfix-123

Deploy an already-built image to an environment:

gh workflow run gitops-update-manifests.yml \
  -f service=services/go-backend \
  -f version=0.2.2-rc0029-g1234567 \
  -f environment=staging

Update Kubernetes Configuration

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

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"

Render manifests

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

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:

Via GitOps
Via ArgoCD

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

Because auto-sync is enabled by default for all ArgoCD Applications, you would need to disable auto-sync for the app-of-apps AND the corresponding Application for this change to not be reverted.

# View history
argocd app history go-backend-helm

# Rollback to previous revision
argocd app rollback go-backend-helm "<revision>"

Next Steps

Updating 3rd Party Applications - Update infrastructure components
Bootstrapping a New Service - Add a new application

About

Usage

Updating 1st Party Applications

Overview

Deployment Flow

Make Code Changes

What Happens After Push (Staging)

1. CI Build Workflow

2. GitOps Update Workflow

3. ArgoCD Sync

Version Tagging Strategy

Pre-release Versions (Staging)

Release Versions (Production)

Deploy to Production

Manual Deployment

Update Kubernetes Configuration

Rollback

Next Steps

​Overview

​Deployment Flow

​Make Code Changes

​What Happens After Push (Staging)

​1. CI Build Workflow

​2. GitOps Update Workflow

​3. ArgoCD Sync

​Version Tagging Strategy

​Pre-release Versions (Staging)

​Release Versions (Production)

​Deploy to Production

​Manual Deployment

​Update Kubernetes Configuration

​Rollback

​Next Steps

Overview

Deployment Flow

Make Code Changes

What Happens After Push (Staging)

1. CI Build Workflow

2. GitOps Update Workflow

3. ArgoCD Sync

Version Tagging Strategy

Pre-release Versions (Staging)

Release Versions (Production)

Deploy to Production

Manual Deployment

Update Kubernetes Configuration

Rollback

Next Steps