> ## Documentation Index
> Fetch the complete documentation index at: https://kubestarterkit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Updating 1st Party Applications

> Deploy changes to your 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

**1. Edit your service code**

Make changes to your application in `services/`:

```bash theme={null}
# Example: modify the go-backend service
vim services/go-backend/cmd/main.go
```

**2. Test locally**

Use the [local development environment](https://kubestarterkit.com/usage/getting-started/09-local-development-setup.md) to test:

```bash theme={null}
mise run //local:tilt-up
```

Tilt automatically rebuilds and redeploys when you save changes.

**3. Commit and push**

```bash theme={null}
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:

```yaml theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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

> [!NOTE]
>
> You can also create a release manually by pushing a tag:
>
> ```bash theme={null}
> 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:

```bash theme={null}
# 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:

> [tab] Build only
>
> Build and push an image without deploying:
>
> ```bash theme={null}
> gh workflow run ci-build-push.yml \
>   -f service=services/go-backend \
>   -f version=hotfix-123
> ```

> [tab] Deploy existing image
>
> Deploy an already-built image to an environment:
>
> ```bash theme={null}
> 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:

**1. Edit the configuration**

For Helm-based services, edit the values file:

```bash theme={null}
vim kubernetes/src/services/go-backend-helm/values.yaml
```

For Kustomize-based services, edit the overlay:

```bash theme={null}
vim kubernetes/src/services/go-backend/staging/kustomization.yaml
```

Example changes:

```yaml theme={null}
replicas: 3  # Increase replicas
resources:
  requests:
    memory: "256Mi"
    cpu: "250m"
```

**2. Render manifests**

```bash theme={null}
mise run //kubernetes/src/services:render-all "<CLUSTER>"
```

**3. Commit and push**

```bash theme={null}
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:

> [tab] Via GitOps
>
> Update the image tag to a previous version:
>
> ```bash theme={null}
> # 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
> ```

> [tab] Via ArgoCD
>
> > [!WARNING]
> >
> > 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.
>
> ```bash theme={null}
> # 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](https://kubestarterkit.com/usage/operations/03-updating-3rd-party-applications.md) - Update infrastructure components
* [Bootstrapping a New Service](https://kubestarterkit.com/usage/operations/04-bootstrapping-new-service.md) - Add a new application


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.