GitOps

Every deployment in Lucity is a Git commit. Your entire deployment state is version-controlled, auditable, and reversible. No "what's running in production?" mystery. git log tells you.

Understand the Two-Repository Model

Lucity maintains a clean separation between two repositories:

• Source repo (your code, on GitHub): read-only to the platform. Lucity clones it to build images but never writes to it. Not a commit, not a file, not a config.
• GitOps repo (deployment config, on Soft-serve): managed entirely by the platform. Contains Helm values that define what's deployed, where, and how.

This separation is intentional. Your source code stays clean. No .lucity.yaml, no Procfile, no platform-specific artifacts. Your deployment configuration lives in its own repo where it can be versioned, diffed, and reverted independently.

Explore the GitOps Repo Structure

gitops/{project}/
├── base/
│   ├── Chart.yaml              # Depends on lucity-app chart
│   └── values.yaml             # Shared: services, databases, base config
└── environments/
    ├── development/
    │   └── values.yaml         # Overrides: image tag, debug settings
    ├── staging/
    │   └── values.yaml         # Overrides: promoted image tag
    ├── production/
    │   └── values.yaml         # Overrides: replicas, resources, HA config
    └── pr-142/
        └── values.yaml         # Ephemeral: minimal resources, PR-specific tag

Base holds shared service definitions: what services exist, what databases are provisioned, what the default configuration looks like. Environments override what's different, usually just the image tag, replica count, and resource limits.

This structure means a promotion from development to staging is just copying an image tag from one values.yaml to another. No rebuild, no repackaging, no "works on my machine."

Read the Commit Messages

Every commit to the GitOps repo follows a semantic format:

git log becomes a readable deployment history. Who deployed what, when, and to which environment, all in the commit log. No separate audit system needed, no dashboard-only history that vanishes when you eject.

Use Labels for Discovery

All Lucity-managed Kubernetes resources use the lucity.dev/ label prefix:

These are standard Kubernetes labels. Query them with kubectl:

# All namespaces for a project
kubectl get ns -l lucity.dev/project=myapp

# All ephemeral (PR) environments
kubectl get ns -l lucity.dev/ephemeral=true

# Everything in production
kubectl get all -n myapp-production

No special CLI, no proprietary API. The tools you already know work out of the box.

Integrate with ArgoCD

Lucity creates one ArgoCD Application per project per environment. Each Application points to the corresponding directory in the GitOps repo:

• myapp-development watches gitops/myapp/environments/development/
• myapp-production watches gitops/myapp/environments/production/
• myapp-pr-142 watches gitops/myapp/environments/pr-142/

When the packager commits a new image tag, ArgoCD detects the change and syncs the new manifests to Kubernetes automatically. The deployer reports sync status and rollout health back to the dashboard. No direct cluster polling. ArgoCD handles reconciliation, and the platform observes the result.

Know Why GitOps

The GitOps model gives you properties that are hard to get any other way:

• Traceability: every change is a commit with an author, timestamp, and diff. git blame works on your infrastructure.
• Rollbacks: reverting a bad deployment is git revert. The previous state is applied automatically by ArgoCD.
• Reproducibility: the entire deployment state is in the repo. Clone it, and you can reconstruct the full environment.
• Auditability: compliance teams love Git logs. Every change is signed, timestamped, and attributable.
• Ejectability: because it's all in Git with standard Helm values, it survives ejection perfectly. Point your own ArgoCD at the repo and everything keeps running.

Git was already the best version control system. Turns out it's a pretty good deployment system too.