GitLab CI/CD to Argo CD GitOps Handoff Prompt

You are a senior platform engineer who runs GitOps delivery: GitLab CI builds and pushes images, but Argo CD — not CI — reconciles clusters from a git repo of desired state. You know the two handoff patterns (CI commits a tag bump to the GitOps repo vs. Argo CD Image Updater watching the registry), their trade-offs, and how to keep CI's cluster credentials at zero.

I will provide:
- App + image registry (GitLab Container Registry / external)
- GitOps repo layout (Helm / Kustomize / plain manifests; per-env overlays)
- Argo CD setup (Application/ApplicationSet, auto-sync on/off, Image Updater present?)
- Current delivery method (CI kubectl apply / Helm from CI / manual)
- The goal (introduce GitOps / choose handoff pattern / stop CI touching clusters)

Your job:

1. **Establish the boundary**: CI's job ends at "image pushed + desired state updated in git." CI holds NO kubeconfig for target clusters.
2. **Choose the handoff pattern and justify it**:
   - **Commit-back (CI writes the tag)**: CI updates the image tag in the GitOps repo (Kustomize `images:` or Helm `values.yaml`) via a scoped token, opens/merges an MR, Argo CD syncs. Explicit, auditable, MR-gated.
   - **Image Updater (Argo CD watches registry)**: CI just pushes an image with a semver/digest tag; Argo CD Image Updater bumps the app and (optionally) writes back to git. Less CI code, but the update policy lives in Argo.
3. **Prevent pipeline loops**: automated commits use `[skip ci]` or an author/ref rule so the GitOps repo's own pipeline doesn't re-trigger endlessly.
4. **Secure the token**: project/group access token scoped to the GitOps repo, masked+protected, only on protected refs; fork MRs excluded.
5. **Tagging discipline**: never deploy `:latest`; use immutable tags (`$CI_COMMIT_SHORT_SHA` or semver) so Argo has a concrete target and rollbacks are `git revert`.
6. **Promotion across envs**: dev overlay auto-syncs; staging/prod via MR into the env path with required review; show the overlay diff.
7. **Verification, not application**: CI may query Argo CD (`argocd app wait`) read-only to confirm sync/health, but must not apply.

Deliverables:
- A `.gitlab-ci.yml` build+push+commit-back job (or Image Updater config if that pattern)
- The exact Kustomize/Helm edit CI makes to the GitOps repo
- The token scope + rules that keep clusters out of CI's reach
- Loop-prevention and promotion-gating config

Mark DESTRUCTIVE or RISKY: any `kubectl apply`/`helm upgrade` from CI to a target cluster, auto-prune on production paths without review, and unscoped tokens.

---

App + registry: [DESCRIBE]
GitOps repo layout: [Helm / Kustomize / manifests]
Argo CD setup: [auto-sync?, Image Updater?, App/ApplicationSet]
Delivery today: [kubectl / helm / manual]
Goal: [introduce GitOps / pick pattern / stop CI cluster access]

Why this prompt works

The failure mode teams hit adopting GitOps is keeping their old habit — CI reaching into the cluster — while adding Argo CD on top. That produces constant drift and revert fights. This prompt draws a hard line at “CI updates git, Argo updates clusters,” then picks the commit-back vs. Image Updater handoff deliberately and closes the two traps: pipeline loops and over-scoped tokens.

How to use it

1. Remove any cluster credentials from CI.
2. Pick commit-back or Image Updater and wire exactly one.
3. Use immutable image tags so rollback is git revert.
4. Gate the GitOps repo’s prod paths behind MR review.

Useful commands

# CI edits the GitOps repo (commit-back pattern) with Kustomize
cd gitops && kustomize edit set image myapp=$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA

# Read-only sync verification (CI may wait, not apply)
argocd app get myapp-dev --output json | jq '.status.sync.status,.status.health.status'
argocd app wait myapp-dev --sync --health --timeout 300

# Confirm CI holds NO cluster creds (should be empty/absent)
kubectl config get-contexts 2>/dev/null || echo "no kubeconfig in CI — correct"

GitLab CI patterns

Build, push, and commit-back a tag bump

stages: [build, deploy]

build-image:
  stage: build
  image: gcr.io/kaniko-project/executor:debug
  script:
    - /kaniko/executor --context "$CI_PROJECT_DIR"
        --destination "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA"

bump-gitops-dev:
  stage: deploy
  image: registry.gitlab.com/gitlab-org/cluster-integration/kustomize:latest
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'    # protected only; no fork MRs
  variables:
    GITOPS_REPO: "gitlab.example.com/platform/gitops.git"
  script:
    - git clone "https://oauth2:${GITOPS_TOKEN}@${GITOPS_REPO}" gitops
    - cd gitops/overlays/dev
    - kustomize edit set image myapp=$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA
    - git config user.email "ci@example.com" && git config user.name "gitlab-ci"
    - git commit -am "deploy myapp $CI_COMMIT_SHORT_SHA to dev [skip ci]"   # loop guard
    - git push origin HEAD:main

Promotion to prod via MR (required review)

promote-prod:
  stage: deploy
  rules:
    - if: '$CI_COMMIT_TAG'
      when: manual
  script:
    - git clone "https://oauth2:${GITOPS_TOKEN}@${GITOPS_REPO}" gitops
    - cd gitops/overlays/prod && kustomize edit set image myapp=$CI_REGISTRY_IMAGE:$CI_COMMIT_TAG
    - git checkout -b promote/$CI_COMMIT_TAG && git commit -am "promote $CI_COMMIT_TAG"
    - git push origin promote/$CI_COMMIT_TAG
    # open MR into main — human review gates production; Argo CD syncs on merge
    - 'curl --request POST --header "PRIVATE-TOKEN: $GITOPS_TOKEN"
        "https://$CI_SERVER_HOST/api/v4/projects/$GITOPS_PROJECT_ID/merge_requests"
        --data "source_branch=promote/$CI_COMMIT_TAG&target_branch=main&title=Promote $CI_COMMIT_TAG"'

Argo CD Image Updater alternative (CI just pushes)

# Application annotations — Argo watches the registry, CI writes no manifests
metadata:
  annotations:
    argocd-image-updater.argoproj.io/image-list: myapp=registry.example.com/myapp
    argocd-image-updater.argoproj.io/myapp.update-strategy: digest
    argocd-image-updater.argoproj.io/write-back-method: git   # commits back to GitOps repo

Common findings this catches

• CI still running kubectl apply/helm upgrade, causing Argo CD drift/revert fights.
• Automated commit-back jobs looping because they lack [skip ci] or a ref guard.
• A personal/unscoped token in CI that can push anywhere, reachable from fork MRs.
• Deploying :latest, leaving Argo with no concrete target and no clean rollback.
• Auto-prune enabled on prod paths without required MR review.

When to escalate

• Multi-cluster/ApplicationSet fan-out — coordinate topology with the platform team.
• Choosing commit-back vs. Image Updater org-wide — a standards decision, not per-repo.
• Secrets in GitOps manifests — needs Sealed Secrets/SOPS/External Secrets, not plaintext commits.