Add stable exit-code contract and CI/CD documentation#182
Open
mkrueger wants to merge 11 commits into
Open
Conversation
Composite action that resolves a release, downloads the per-runtime CosmosDBShell package, verifies its SHA256 digest, extracts the self-contained executable, caches it in the runner tool cache, and adds cosmosdbshell to PATH. Supports latest or a pinned version across Linux, macOS, and Windows on x64/arm64. Adds a CI/CD guide (docs/ci.md) and links it from the README. Addresses #178
Introduce ShellExitCode with a stable, machine-readable process exit-code contract for non-interactive runs: 0 success, 1 general failure, 2 authentication/authorization failure, 3 connection/network error, 4 command/script syntax error. Program.cs now maps CLI parse errors, connect failures, and command/script results to these codes instead of always returning 1. Document the contract, GitHub Actions usage, authentication patterns (OIDC, managed identity, key/token), and failure-handling guidance in docs/ci.md. Add unit tests for the classifier and end-to-end process tests for the syntax exit code. Update CHANGELOG. Addresses #176
Code Coverage OverviewLanguages: C# C# / code-coverage/dotnetThe overall coverage in the Show a code coverage summary of the most impacted files.
Updated |
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a stable, machine-readable exit-code contract for non-interactive CosmosDBShell runs and introduces CI/CD-focused documentation and tooling (including an in-repo setup action) to make the shell easier to consume from automation.
Changes:
- Introduces
ShellExitCodeand wiresProgram.csto return stable exit codes for CLI parse errors, connection failures, and command/script execution results. - Adds a full CI/CD guide (GitHub Actions examples, auth patterns, retries, JSON parsing) and links it from the README and changelog.
- Adds a
setup-cosmosdb-shellcomposite GitHub Action plus unit/process tests for exit-code behavior.
Reviewed changes
Copilot reviewed 9 out of 9 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| README.md | Adds a docs link to the new CI/CD guide. |
| docs/ci.md | New CI/CD guide documenting installation, auth patterns, exit codes, and scripting guidance. |
| CosmosDBShell/Program.cs | Maps key non-interactive failure modes to stable exit codes via ShellExitCode. |
| CosmosDBShell/Azure.Data.Cosmos.Shell.Core/ShellExitCode.cs | Centralized exit-code contract and classifiers (FromException, FromCommandState). |
| CosmosDBShell.Tests/Runtime/ShellExitCodeTests.cs | Unit tests for exception/state-to-exit-code classification. |
| CosmosDBShell.Tests/Integration/ShellProcessTests.cs | Process-level assertions for syntax/argument exit-code behavior. |
| CHANGELOG.md | Documents the new exit-code contract and links to CI/CD guide. |
| .github/actions/setup-cosmosdb-shell/README.md | Documents usage and behavior of the composite setup action. |
| .github/actions/setup-cosmosdb-shell/action.yml | Implements the composite action to download/cache/install the shell from releases. |
- Map all CLI/argument validation failures (invalid --otel endpoint, mutually-exclusive -c/-k, invalid --mcp port) to the syntax exit code; classify MCP runtime failures via ShellExitCode.FromException. - Add a gh preflight check to the setup action with an actionable self-hosted-runner message. - Recommend pinning the action ref (tag/commit) in the action README and docs/ci.md. - Add a process test asserting a malformed --otel endpoint returns exit code 4.
- Pin actions/checkout to v4 in both docs/ci.md workflow examples. - Add a RequestFailedException 503/408/504 connection-error unit test for the exit-code classifier.
Reword the OIDC section so endpoint-only connection is clearly the only requirement and the --connect-* options are optional for deterministic startup.
- action.yml: use github.token fallback via expressions (input default cannot evaluate expressions); drop the warning when a release asset has no digest. - action README: soften SHA256 verification wording to reflect optional digest. - ShellExitCode: classify Cosmos-like OperationCanceledException timeouts as ConnectionError, with unit tests.
- docs/ci.md: clarify that only the -c/-k/stdin-free REPL always exits 0, and that -k preserves the initial command's exit code. - action README: document PowerShell and gh runner prerequisites for self-hosted runners.
Use CosmosShell.Tests.Runtime to match the other tests under CosmosDBShell.Tests/Runtime.
- Program.cs: set GeneralFailure exit code when the initial --connect is cancelled so CI detects aborted startup. - docs/ci.md: clarify REPL exits 0 only when reached and ending normally; startup failures still set non-zero codes. - action README: correct the token input default (empty) and document the github.token fallback.
Reference the COSMOSDB_SHELL_FORMAT env var and the per-command -f/--format option instead of the unrelated filter command.
4 tasks
Collaborator
Author
|
#173 already contains it. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Implements the exit-code contract and CI/CD documentation requested in #176, and includes the
setup-cosmosdb-shellGitHub Action from the earlier work on this branch.Exit-code contract (#176)
Non-interactive runs (
-c,-k, or a script piped on stdin) now return stable, machine-readable process exit codes instead of always returning1:012401/403, failed Entra credential)3503, request timeout)4ShellExitCodeclass centralizes the contract withFromExceptionandFromCommandStateclassifiers.Program.csmaps CLI parse errors, connect failures, and command/script results to these codes.0.Documentation
docs/ci.mdis expanded into a full CI/CD guide covering:azure/loginOIDCLinked from the README docs list.
Tests
ShellExitCodeTests— unit coverage for the classifier (auth, connection, syntax, general, nested exceptions, command-state mapping).ShellProcessTests— end-to-end assertions that an unterminated string and an unrecognized CLI argument both exit with code4.Also included on this branch
setup-cosmosdb-shellcomposite GitHub Action (.github/actions/setup-cosmosdb-shell/) that downloads, verifies, caches, and PATH-adds the shell across Linux/macOS/Windows runners.Validation
dotnet build CosmosDBShell.sln— 0 warnings, 0 errorsAddresses #176. Marketplace publishing under
azure/setup-cosmosdb-shell(a separate repo) is documented but out of scope for this repo.