> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qumo-deploy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CI/CD & Coding Agents

> Recipes and best practices for integrating qumod into GitHub Actions, GitLab CI, and AI agents.

# CI/CD & Coding Agents

`qumod` is engineered specifically for deterministic execution in automation pipelines and AI coding agent environments (such as Claude Code, Antigravity, and Cursor).

***

## Exit Codes

`qumod` enforces strictly standard process exit codes:

| Exit Code | Meaning                    | Agent Strategy                                                                                             |
| :-------- | :------------------------- | :--------------------------------------------------------------------------------------------------------- |
| `0`       | **Success**                | Parse stdout if `--json` was supplied.                                                                     |
| `1`       | **API or Runtime Error**   | Authentication failure, missing resources, or control plane error. Examine stderr or JSON payload `error`. |
| `2`       | **Usage / Argument Error** | Invalid flags, missing required positional arguments, or unknown subcommands.                              |

***

## GitHub Actions Integration

Use this recipe to deploy or manage projects in a GitHub Actions workflow:

```yaml .github/workflows/deploy.yml theme={null}
name: Qumo Deployment

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    name: Deploy to Qumo
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4

      - name: Install qumod CLI
        run: |
          curl -fsSL https://github.com/foalk-inc/qumo-deploy/releases/latest/download/qumod-linux-amd64 -o /usr/local/bin/qumod
          chmod +x /usr/local/bin/qumod

      - name: Verify CLI Authentication
        env:
          QUMO_TOKEN: ${{ secrets.QUMO_API_TOKEN }}
        run: |
          qumod whoami --json

      - name: Trigger Deployment
        env:
          QUMO_TOKEN: ${{ secrets.QUMO_API_TOKEN }}
        run: |
          qumod deploy --project "${{ secrets.QUMO_PROJECT_ID }}" --json
```

***

## GitLab CI Integration

```yaml .gitlab-ci.yml theme={null}
stages:
  - deploy

deploy_to_qumo:
  stage: deploy
  image: alpine:latest
  before_script:
    - apk add --no-cache curl
    - curl -fsSL https://github.com/foalk-inc/qumo-deploy/releases/latest/download/qumod-linux-amd64 -o /usr/local/bin/qumod
    - chmod +x /usr/local/bin/qumod
  script:
    - qumod whoami --json
    - qumod deploy --project "$QUMO_PROJECT_ID" --json
  only:
    - main
  variables:
    QUMO_TOKEN: "$QUMO_API_TOKEN"
```

***

## Coding Agent Recipes (Claude Code, Antigravity, Copilot)

When delegating commands to automated coding agents:

1. **Always enable `--json`**: Ensures deterministic parsability of responses.
2. **Handle API URL overrides**: When developing against local testbeds, pass `--api-url http://localhost:8080` or set `QUMO_API_URL`.
3. **Parse stdout and stderr separately**: Informational banners are logged to `stderr`, while pure JSON payloads are written cleanly to `stdout`.

### Agent Invocations

```bash theme={null}
# Query active organization and permissions
qumod whoami --json

# List available projects before initiating deployment
qumod project list --json

# Run deployment and assert success status
qumod deploy --project prj_live --json
```