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

# AutoPilot for CI settings

> Turn AutoPilot for CI on or off, pause it, and set its policy, providers, runners and runner limits for the organization, a repository or a workflow, and narrow them in the workflow file.

AutoPilot for CI settings apply at three levels in CostGraph, plus the workflow
file:

1. The organization.
2. A repository (`owner/name`).
3. One workflow (`.github/workflows/ci.yml` in a repository).
4. The workflow file, through the [routing action's](https://docs.costgraph.ai/costgraph/autopilot/ci.md) inputs: `policy`, and `providers`, `max-cores`, `allowed-os`, `allowed-arch` (`x64` or `x86_64`, `arm64`) and `allow-gpu`, which can only narrow.

Enabled and pause are set in CostGraph only, for the organization, a repository or a workflow. Provider limits are set for the organization only.

## How the levels combine

| Setting | Rule |
| - | - |
| `policy` | The narrowest level that sets it wins: the workflow file, then the workflow, the repository and the organization. The default is `balanced`. |
| `allowed_providers` | Every level can only narrow it. A provider must be allowed at every level that sets a list, including the workflow file. |
| `enabled` | Turning AutoPilot off at any level stops routing below it. Turned off for the organization, nothing is routed and no level can turn it back on. |
| `paused_until` | The latest pause at any level applies. An organization pause cannot be lifted by a repository or workflow. |
| `release` | The narrowest level that sets it wins. Release jobs take the best runner without spreading and are never cancelled or re-run. |
| `max_cores` | The smallest value set at any level, including `max-cores` in the workflow file, applies. |
| `allowed_os`, `allowed_arch` | Like `allowed_providers`: every level, including `allowed-os` and `allowed-arch` in the workflow file, can only narrow the list. |
| `allow_gpu` | `false` at any level, including `allow-gpu` in the workflow file, keeps AutoPilot off runners with GPUs. |

The workflow file cannot turn AutoPilot on or off, pause it, set provider
limits, or allow a provider or runner shape the organization does not. A job whose default runner is
larger than these limits keeps its default runner.

When the workflow file sets `policy`, `providers` or a runner limit, the run's
routing decision is marked as set in Git.

## Read and change settings

```bash theme={null}
curl -s "https://api.costgraph.ai/api/v1/tenant/ci/autopilot/settings?repository=acme/api&workflow_path=.github/workflows/ci.yml" \
  -H "X-API-Key: $COSTGRAPH_API_KEY" -H "X-CostGraph-Tenant-ID: $TENANT_ID"
```

The answer has the settings set at that level (`own`), the settings in effect
(`effective`), and the level each effective value comes from
(`inherited_from`). Reading needs the `focus:read` scope or the Member role.
Changing settings with `PUT` on the same path is for organization owners and
admins signed in to CostGraph:

```json theme={null}
{"repository": "acme/api", "workflow_path": ".github/workflows/ci.yml", "policy": "cheapest", "allowed_providers": ["ubicloud", "blacksmith"]}
```

A field you leave `null` inherits from the wider level.

## Enabled and pause

`enabled` is on by default and routing runs. Turn it off for the organization,
a repository or a workflow and every job there keeps its own `runs-on` label
from the next routing request. Set `paused_until` to a time to do the same
until then. Neither can be set in the workflow file.

## Runners

`GET /api/v1/tenant/ci/autopilot/labels` lists every runner CostGraph knows for
you, grouped by provider: GitHub-hosted runners, runners of providers
integrated with CostGraph (connected, or whose runner jobs CostGraph reads
through your GitHub Actions connection), and labels you set. Pass `repository` and `workflow_path` to see a repository or workflow.
Each runner has its state there (`allowed`, `blocked`, `provider_off` when its
provider is not allowed, or `outside_limits` when the runner limits exclude
it), where it comes from, and the level its setting comes from.

To allow or block several runners at once, `PUT` a list for one level:

```json theme={null}
{"repository": "acme/api", "labels": [
  {"label": "warp-ubuntu-latest-x64-4x", "enabled": true},
  {"label": "ubicloud-standard-2", "enabled": false}
]}
```

An allow is inherited by narrower levels. A block at any level always wins, even
over an allow at a narrower level. CostGraph reads the provider, operating
system, architecture and vCPUs from each label; if it does not recognize one,
nothing is saved and the error names the label. Labels for macOS and Windows
runners work the same way. `DELETE` with `label`, and the same `repository` and
`workflow_path`, removes a setting so the runner inherits again.

## Provider limits

`/api/v1/tenant/ci/autopilot/providers` lists every provider AutoPilot can
route to, the labels proven for it, its limits and what routed jobs use now.
Provider limits are set for the organization. Set them per provider:

```json theme={null}
{"provider": "blacksmith", "max_concurrent": 20, "max_per_hour": 200, "daily_spend_cap": 50, "monthly_spend_cap": 800, "allow_secrets": true}
```

| Limit | Counts |
| - | - |
| `max_concurrent` | Routed jobs that have not finished, in the last 6 hours. |
| `max_per_hour` | Jobs routed to the provider in the last hour. |
| `daily_spend_cap` | Estimated cost of jobs routed today, including the next one. |
| `monthly_spend_cap` | Estimated cost of jobs routed this month, including the next one. |
| `allow_secrets` | `true` by default. `false` keeps jobs that use secrets off the provider; only jobs routed with `secrets: false` go there. |

A provider at a limit is skipped and the job takes the next best runner, or its
default. Limits are checked when a job is routed, from AutoPilot's own
estimates; they do not read the provider's bill and do not stop jobs that are
already running.

## Suggest a provider

If the runner provider you use is not listed, ask for it through the support
chat in the CostGraph dashboard.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.