GitOps Beta

GitOps is a Git-authored workflow for platform operators who want to manage LyftData deployment desired state from files reviewed in source control.

Note

GitOps is currently a controlled beta for platform-admin/operator workflows. The CLI and API perform validation, planning, apply, promotion, rollback, run history, and event inspection. The Deployments UI provides status and drift visibility, run history/detail/events, and governed promotion/rollback by selecting server-stored successful GitOps runs. The UI is not a Git authoring surface and does not apply arbitrary browser-uploaded bundles.

Supported scope

Use GitOps when you want to:

• validate desired state from a manifest before applying it,
• reconcile one tenant and one environment at a time,
• promote a reviewed revision from a source environment such as dev to a target environment such as prod,
• require explicit approval evidence for promotion and rollback,
• list runs and inspect run events for audit trails,
• compare environment status and drift from the Deployments UI,
• perform UI-governed promotion or rollback by selecting a stored successful GitOps run and supplying approval evidence.

The beta scope does not include in-server Git checkout, branch management, UI-based first apply, arbitrary browser desired-state authoring, arbitrary browser bundle upload, or broad tenant-admin self-service across all Deployment Manager operations. Keep checkout, branch policy, pull requests, and CI approval gates in your normal source-control and release tooling.

Prerequisites

• A licensed LyftData server with Deployments enabled.
• The lyftdata CLI installed on the operator machine or CI runner.
• A platform-admin account or API identity authorized to manage GitOps desired state.
• Desired-state files stored in a Git repository or another reviewed change-control system.
• Environment names such as dev and prod agreed by the platform team.

Authenticate the CLI before running GitOps commands:

lyftdata --url https://lyftdata.example.com/ login admin

If your server still uses a self-signed certificate during evaluation, add --tls-insecure or set LYFTDATA_TLS_INSECURE=true until you install a trusted certificate.

Validate the beta path locally

When you are validating a source checkout, release candidate, or upgrade proof, use the repeatable proof lane before relying on the CLI-first beta path:

cargo xtask gitops-proof

The proof starts a clean licensed dev stack with the gitops-cli-proof profile, runs the example desired-state pack, writes JSON evidence under tmp/gitops-proof/<timestamp>/, and stops the stack when complete.

Useful options:

cargo xtask gitops-proof --keep-alive
cargo xtask gitops-proof --reuse
cargo xtask gitops-proof --json-dir tmp/gitops-proof/manual
cargo xtask gitops-proof --ports-offset 320

The proof covers validation, planning, apply to dev, run status/events, run listing, environment status and drift, promotion to prod with approval evidence, rollback with approval evidence, and final status/drift.

Use the Deployments UI console

Open Deployments > GitOps environments to inspect the selected tenant’s GitOps state. The direct route is /deployments?tab=gitops; if your session can access more than one tenant, select the tenant scope in the page before the console loads GitOps runs.

The console includes:

• Overview status and deterministic drift comparison,
• recent Runs with detail and event timelines,
• governed promotion from a stored successful run reference,
• governed rollback to a stored successful run reference.

Promote and Rollback only select successful write runs that have stored canonical bundles. Plan-only, validate, failed, blocked, and older pre-bundle rows remain audit history, but they are not selectable for browser-governed promotion or rollback.

Stored bundles preserve the canonical Git-authored desired state used by successful write runs so the server can perform referenced promotion and rollback without browser bundle upload. Do not put raw secrets in GitOps desired-state files; use managed credential, variable, or secret references.

Configure source profiles

Open Settings > GitOps to configure source profiles for a tenant. A profile records the repository URL, default ref, manifest path, target environments, default environment, approval defaults, and optional managed credential reference. The Settings page also shows generated lyftdata git-ops validate, plan, apply, and promote-plan commands for the selected profile.

Source profiles make the product discoverable for operators and CI maintainers. They do not move desired-state authoring into the browser: desired-state files still live in Git, LyftData still receives declarative bundles through the CLI/API flow, and raw secret material should remain in managed credential, variable, or secret references.

Automation can manage the same tenant-scoped source-profile registry through the CLI:

lyftdata git-ops source-profiles list --tenant default --json
lyftdata git-ops source-profiles put --tenant default --json-body @profiles.json --json

Use the UI, guarded API, or CLI for configuration. Do not write directly to the Settings DB.

Manifest shape

A GitOps manifest points LyftData at the desired-state files for a tenant. Git metadata is recorded as provenance; LyftData does not pull from Git itself.

schema_version: v1
source:
  repo: [email protected]:acme/lyftdata-config.git
  ref: refs/heads/main
  commit_sha: 0000000000000000000000000000000000000000
  generated_by: ci
  ci_run_id: build-123
scope:
  tenant_id: default
includes:
  - kind: workflow
    paths:
      - workflows/telemetry-cost-control.workflow.yaml
  - kind: worker_group
    paths:
      - worker-groups/default-workers.yaml
  - kind: deployment
    paths:
      - deployments/telemetry-cost-control.deployment.yaml

Supported beta resources include workflows, library jobs, deployments, worker groups, worker settings, and contexts. Secrets should stay reference-only; do not commit raw secret values into GitOps manifests or included files.

Validate and plan

Run validation before producing a plan:

lyftdata git-ops validate \
  --manifest lyftdata-gitops.yaml \
  --tenant default \
  --environment dev

Then generate a plan. The optional --out file is useful for review records in CI:

lyftdata git-ops plan \
  --manifest lyftdata-gitops.yaml \
  --tenant default \
  --environment dev \
  --out artifacts/gitops-dev-plan.json

For a quick operator review, use diff:

lyftdata git-ops diff \
  --manifest lyftdata-gitops.yaml \
  --tenant default \
  --environment dev

Apply to an environment

Apply only after validation and review pass:

lyftdata git-ops apply \
  --manifest lyftdata-gitops.yaml \
  --tenant default \
  --environment dev

apply creates or updates managed artifacts for the selected tenant/environment. Deletions require --prune and are scoped to resources already owned by the same GitOps source identity. Taking over existing managed resources requires an explicit --adopt-managed decision.

Promote to production

Promotion reuses the reviewed desired-state source revision and records approval evidence. First plan the promotion:

lyftdata git-ops promote-plan \
  --manifest lyftdata-gitops.yaml \
  --tenant default \
  --source-revision refs/heads/main \
  --source-environment dev \
  --target-environment prod

Then apply it with approval evidence:

lyftdata git-ops promote-apply \
  --manifest lyftdata-gitops.yaml \
  --tenant default \
  --source-revision refs/heads/main \
  --source-environment dev \
  --target-environment prod \
  --approval ops-lead:change-123 \
  --min-approvals 1

Use repeated --approval APPROVER[:EVIDENCE] flags when your release policy requires more than one approval.

Inspect runs and events

List recent runs:

lyftdata git-ops runs \
  --tenant default \
  --environment prod \
  --limit 10

Inspect a run and include its events:

lyftdata git-ops run-status \
  --run-id <run-id> \
  --events

Record the run IDs, bundle hash, approvals, and final status in your change-management system.

Evidence expectations

Every proof, release-acceptance run, or production change record should include:

• command or automation lane used,
• server URL or profile,
• source commit or build identifier,
• bundle hash,
• validate, plan, dev apply, promotion, and rollback run IDs where applicable,
• approval evidence for promotion or rollback,
• final status and drift result,
• known warnings or intentionally skipped surfaces.

Roll back

Rollback submits the desired-state bundle from a prior successful apply run back to the target environment.

Plan the rollback:

lyftdata git-ops rollback-plan \
  --manifest lyftdata-gitops.yaml \
  --tenant default \
  --environment prod \
  --to-run-id <prior-successful-prod-run-id>

Apply it with approval evidence:

lyftdata git-ops rollback-apply \
  --manifest lyftdata-gitops.yaml \
  --tenant default \
  --environment prod \
  --to-run-id <prior-successful-prod-run-id> \
  --approval ops-lead:rollback-123 \
  --min-approvals 1

After rollback, inspect the rollback run, check the Deployments UI for environment status/drift, and confirm workloads converge.

CI checklist

• Manifest and included desired-state files are reviewed in source control.
• CI runs validate, plan, or diff for pull requests.
• Apply to dev is recorded with run ID and bundle hash.
• Promotion to prod requires approval evidence.
• Rollback target run IDs are easy to find from release records.
• Change records include final status/drift evidence.
• Operators inspect run events and environment drift after apply, promotion, or rollback.

Related docs

• Deployment Manager
• Workflows
• CI/CD automation for jobs
• CLI reference