Skip to content

GitOps Workflow

Before You Read

This guide assumes you understand ArgoCD & GitOps. For rollbacks see Rollbacks.

The Golden Rule

All changes to running services happen through Git. Never run kubectl apply or helm upgrade manually against staging or production.

ArgoCD watches the Git repository and applies changes automatically. Your only job is to get the right code into Git.

Deployment Flow

flowchart TD
    Code["1. Code change\n(microservice repo)"]
    PR["2. Open Pull Request\non Bitbucket"]
    CI["3. Bitbucket Pipelines\nBuild & push Docker image\nto Artifact Registry"]
    Merge["4. PR merged to\nmain/develop branch"]
    InfraRepo["5. Update image tag\nin infra repo\n(infrastructure-configuration)"]
    InfraPR["6. Open PR in infra repo\nUpdate values.yaml with new tag"]
    ArgoCD["7. ArgoCD detects change\nin infra repo"]
    Deploy["8. ArgoCD applies\nHelm chart to cluster"]
    Verify["9. Verify deployment\nArgoCD UI / kubectl"]

    Code --> PR --> CI --> Merge --> InfraRepo --> InfraPR --> ArgoCD --> Deploy --> Verify

Step-by-Step

1. Build Your Image

# In the microservice repository (e.g., microservice-identity)
git checkout -b feature/my-change
# ... make your code changes ...
git push origin feature/my-change

Bitbucket Pipelines automatically: - Builds the Docker image - Pushes to us-central1-docker.pkg.dev/orofi-dev-cloud/orofi/{service-name}:{commit-sha}

2. Update the Infra Repo

After your image is built, update the image tag in the infrastructure-configuration repo:

# In the infrastructure-configuration repo
cd projects/orofi/{environment}/{service-name}/helm/

[NEEDS TEAM INPUT: specify the exact file path and field to update for image tags. Is it values.yaml, values-dev.yaml, or a separate image tag file? Confirm the pattern — e.g.: 

image:
  repository: us-central1-docker.pkg.dev/orofi-dev-cloud/orofi/microservice-identity
  tag: "abc123def456"  ← update this
]

3. Open a PR in the Infra Repo

git checkout -b deploy/microservice-identity-v1.2.3
git add .
git commit -m "deploy: microservice-identity v1.2.3"
git push origin deploy/microservice-identity-v1.2.3
# Open PR on Bitbucket

4. ArgoCD Deploys After Merge

Once the PR is merged: 1. ArgoCD detects the change (poll interval: [NEEDS TEAM INPUT: default is 3 minutes]) 2. ArgoCD runs helm upgrade with the new values 3. Kubernetes rolls out new pods using the rolling update strategy

Watch the deployment: 

# Watch pod rollout
kubectl rollout status deployment/microservice-identity -n microservice-identity

# Watch in ArgoCD UI
# https://argocd.dev.orofi.xyz

5. Verify the Deployment

# Check pod status
kubectl get pods -n microservice-identity

# Check recent events
kubectl get events -n microservice-identity --sort-by='.lastTimestamp' | tail -20

# Check pod logs
kubectl logs -n microservice-identity -l app=microservice-identity --tail=50

# Verify the image tag is correct
kubectl get deployment microservice-identity -n microservice-identity \
  -o jsonpath='{.spec.template.spec.containers[0].image}'

In ArgoCD UI: the application should show status Synced and Healthy.

Deploying to Staging vs Dev

The workflow above applies to both environments. The difference: - Dev: Any engineer can deploy, fewer gates - Staging: [NEEDS TEAM INPUT: are there approvals required for staging deployments? Who reviews?] - Production: [NEEDS TEAM INPUT: describe the production deployment gate — approvals, time windows, required test results]

Manual Sync (Emergency Only)

If ArgoCD doesn't pick up a change automatically, you can trigger a manual sync:

# Via CLI
argocd app sync microservice-identity

# Via UI: click "Sync" button on the application page

Force sync

Only use argocd app sync --force if you understand what you're overriding. A force sync will discard local changes and reapply from Git — this can cause a brief rollout.

Canary Deployments

Services using ArgoCD Rollouts get canary promotion steps. After a Rollout is triggered:

# Check rollout status
kubectl argo rollouts get rollout microservice-identity -n microservice-identity --watch

# Promote to next canary step
kubectl argo rollouts promote microservice-identity -n microservice-identity

# Abort a canary (rolls back to stable)
kubectl argo rollouts abort microservice-identity -n microservice-identity

See Also