CI/CD documentation: GitHub Actions workflow guidance and exit-code contract

[sajeetharan]

Feedback source

External user feedback (travel multi-agent workshop team).

Problem

There is no documentation or guidance for using CosmosDB Shell in CI/CD scenarios. Users are left to figure out authentication, installation caching, exit-code handling, and script integration on their own.

Proposed documentation

Add a CI/CD guide covering:

1. GitHub Actions workflow example

A ready-to-use workflow showing: checkout, azure/login with OIDC, setup-cosmosdb-shell action, and running seed/validate scripts.

2. Exit-code contract

Document stable, machine-readable exit codes:

• 0 = success
• 1 = general failure
• 2 = authentication failure
• 3 = connection/network error
• 4 = query/command syntax error

3. CI-oriented failure-handling guidance

• How to handle transient failures (retry patterns)
• How to parse JSON output in scripts
• How to use with azd post-provision hooks
• Caching strategies for the shell binary

4. Authentication patterns for CI

• Workload identity federation (OIDC)
• Service principal with federated credentials
• Managed identity (self-hosted runners)

Acceptance criteria

• Docs page published for CI/CD usage
• GitHub Actions example is copy-paste ready
• Exit-code contract is formally specified
• Linked from README and main docs landing page