docs: add ADC CI/CD guidance

[kayx23]

Summary

• Add a task-oriented guide for managing ADC configuration through CI/CD, covering ownership scopes, label selectors, protected credentials, plan artifacts, serialized non-atomic deploys, drift detection, and rollback.
• Document the pinned api7/adc container helper, including why the image entrypoint must be overridden, why the host user cannot be substituted, and that uid 65532 must be able to write diff.yaml.
• Correct adc validate availability: API7 Enterprise 3.9.10+, Apache APISIX only when /apisix/admin/configs/validate exists.
• State that ADC has no apply-plan command, that adc diff exits 0 when it finds differences, and that dumped files can include unscoped empty global_rules and plugin_metadata maps.
• Replace the workflow page's copy-pasteable lint && validate && diff && sync block with a pointer to the production model, and order the docs index as workflow → resource IDs → label selector → CI/CD.

Why

The existing workflow documentation explained individual commands but not a safe production delivery process. Operators need explicit guidance about destructive synchronization scope, credential exposure, plan/deploy consistency, concurrent jobs, partial failure, and recovery.

Local verification against ADC 0.29.0 and Apache APISIX 3.13 also showed that treating validate and a post-sync empty diff.yaml as universal steps is incorrect for many APISIX versions.

User impact

Readers now have one end-to-end operational model:

1. lint every proposed change without credentials
2. validate trusted changes when the backend supports it
3. preserve and review diff.yaml without applying that file
4. recalculate the plan immediately before an approved deployment
5. serialize deployments to the same ownership scope
6. detect drift only after a stable empty diff
7. roll back from version-controlled configuration without syncing unscoped dump keys

The guide supports both Apache APISIX and API7 Enterprise while retaining the warning that the APISIX backend is experimental and often normalizes defaults such as route priority and upstream hash_on.

Validation

• Inspected ADC 0.29.0 CLI, Docker image (WORKDIR=/home/nonroot, uid 65532, /home/nonroot mode 0700), label injection, non-atomic sync, and diff.yaml writer
• Ran Prettier-equivalent whitespace check (git diff --check) and verified relative documentation links
• Ran the documented lint, diff, sync, label-selector isolation, rollback, dump, and ping flow with api7/adc:0.29.0 against disposable Apache APISIX 3.13.0
• Confirmed adc validate fails on APISIX 3.13.0 (missing /apisix/admin/configs/validate) and that a minimal service/route does not round-trip to diff.yaml: [] because APISIX fills defaults
• Did not re-run a licensed API7 Enterprise backend in this pass

Summary by CodeRabbit

• Documentation
  • Added a comprehensive CI/CD guide covering validation, deployment planning, approvals, credential protection, drift detection, backups, and rollback.
  • Added a Get Started link to the CI/CD workflow guide.
  • Updated workflow guidance for pull-request checks, ownership scope, production safeguards, backend validation, and approved deployments.
  • Clarified that validation may be unavailable with older backend versions.

[coderabbitai]

Warning

Review limit reached

• Run on-demand review

_{On-demand reviews are free for the next 25 days. After that, they cost $0.25 per reviewed file.}

Or wait 50 minutes for your next included review.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: f9693d2c-8f07-4b57-97c0-7ca6d78f1b2e

📥 Commits

Reviewing files that changed from the base of the PR and between 6594ee9 and cdbf3ce.

📒 Files selected for processing (3)

• docs/README.md
• docs/guides/ci-cd.md
• docs/guides/workflow.md

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch agent/add-adc-ci-cd-docs

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}