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

permissions:
  id-token: write
  contents: read

steps:
  - uses: actions/checkout@v4

  - uses: azure/login@v2
    with:
      client-id: $`{{ secrets.AZURE_CLIENT_ID }}`
      tenant-id: $`{{ secrets.AZURE_TENANT_ID }}`
      subscription-id: $`{{ secrets.AZURE_SUBSCRIPTION_ID }}`

  - uses: azure/setup-cosmosdb-shell@v1
    with:
      version: 1.0.213-preview

  - name: Seed and validate test data
    run: |
      cosmosdb-shell run ./scripts/seed.cosmos
      cosmosdb-shell run ./scripts/validate.cosmos

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

[sajeetharan]

Duplicate of #177