> ## Documentation Index > Fetch the complete documentation index at: https://paper.brimble.io/llms.txt > Use this file to discover all available pages before exploring further. # Create a CI runner > Creates the runner for one GitHub organization. Each organization can have one runner. The Brimble GitHub App must be installed on the organization, and the installation must be connected to your account. A runner in `reuse` mode is created disabled and turns on when a sandbox is attached. A runner in `per_job` mode is created enabled. **API key scope:** `ci_runner.create` **Team role permission:** `ci_runner.create` ## OpenAPI ````yaml api-reference/core.openapi.yaml POST /v1/ci-runners openapi: 3.0.3 info: title: Brimble API version: 1.0.0 description: > The Brimble API lets you deploy and manage projects, databases, domains, sandboxes, object storage and more. ## Base URL All endpoints are relative to `https://api.brimble.io/core`, for example `GET https://api.brimble.io/core/v1/projects`. ## Authentication Create an API key in the dashboard under **Settings → API keys** and send it in the `x-brimble-key` header: ``` x-brimble-key: ``` Each API key carries permission scopes such as `project.read` or `project.deploy`. Every endpoint lists the scope it needs; a key without that scope gets `403`. Dashboard session tokens (`Authorization: Bearer `) are also accepted, but integrations should use API keys. ## Teams Endpoints act on your personal workspace unless you pass a team. Most endpoints accept `teamId` (as a query parameter, or in the body for writes). API keys created for a team act in that team. Inside a team, your team role must also allow the action; each endpoint lists the team permission it checks. ## Responses Successful responses are JSON with this shape: ```json { "message": "Projects fetched", "data": { } } ``` Errors return a `message`: ```json { "message": "Project not found", "data": {} } ``` Requests that fail validation return `400` with every invalid field: ```json { "errors": [{ "type": "field", "msg": "Project name should be provided", "path": "name", "location": "body" }] } ``` ## Rate limits Requests made with an API key are rate limited. Responses include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Bucket`. Command execution and file transfer endpoints use separate buckets. ## Idempotency Endpoints that accept an `Idempotency-Key` header return the original result when retried with the same key and body, instead of repeating the operation. ## Streaming Command execution endpoints can stream output as Server-Sent Events (`text/event-stream`). Each event is `data: ` where the JSON has a `type` of `stdout`, `stderr`, `done` or `error`. ## Webhooks To receive events instead of polling, configure a webhook with `PATCH /v1/webhooks`. See the [Webhooks guide](/webhooks/overview) and the [Webhook events reference](/webhooks/events) for every payload. contact: name: Brimble url: https://brimble.io servers: - url: https://api.brimble.io/core description: Production security: - ApiKeyAuth: [] - BearerAuth: [] tags: - name: Projects description: Create, deploy, configure and manage projects. - name: Deployments and Logs description: Deployment history, build logs and request logs. - name: Environments description: Project environments (production, staging, previews) and their variables. - name: Secrets description: >- Secrets (environment variables) set on a single project. Not to be confused with Environments, which group projects into production, staging and preview. Secret values are encrypted at rest and returned encrypted; use `POST /v1/decrypt` to read them. - name: Webhooks description: >- Receive events from Brimble at your own endpoint (or a Discord or Slack channel). Configure the destination and events with `PATCH /v1/webhooks`; use `*` to receive every event. See the [Webhooks guide](/webhooks/overview) for setup, and the [Webhook events reference](/webhooks/events) for the payload each event delivers. | Event | Sent when | | --- | --- | | `project.created` | A project is created | | `project.updated` | A project is updated | | `project.deleted` | A project is deleted | | `project.domain.updated` | A project domain changes | | `deployment.created` | A deployment is queued | | `deployment.started` | A deployment starts | | `deployment.success` | A deployment succeeds | | `deployment.failed` | A deployment fails | | `environment.variables.added` | Environment variables are added | | `environment.variables.updated` | Environment variables are updated | | `environment.variables.deleted` | Environment variables are deleted | | `domain.created` | A domain is added | | `domain.purchased` | A domain is purchased | | `domain.renewed` | A domain is renewed | | `domain.expired` | A domain expires | | `dns.record.created` | A DNS record is created | | `dns.record.updated` | A DNS record is updated | | `dns.record.deleted` | A DNS record is deleted | | `database.created` | A database is created | | `database.backup.completed` | A database backup completes | | `autoscaling.group.created` | An autoscaling rule is created | | `autoscaling.group.updated` | An autoscaling rule is updated | | `autoscaling.group.deleted` | An autoscaling rule is deleted | | `payment.successful` | A payment succeeds | | `payment.failed` | A payment fails | Test deliveries sent with `POST /v1/webhooks/test` include the header `X-Brimble-Test: true`. - name: Git Providers description: Connected git accounts, repositories and linking repositories to projects. - name: Domains description: Custom domains, DNS records and domain registration. - name: Databases description: 'Managed databases: provisioning, backups, users and linking to projects.' - name: Log Drains description: Stream logs to external destinations. - name: Sandboxes description: Isolated sandboxes for running code, with files and snapshots. - name: CI Runners description: Run GitHub Actions jobs for an organization on Brimble sandboxes. - name: Object Storage description: S3-compatible buckets, objects and credentials. - name: Scaling and Networking description: Autoscaling rules, networking and CDN cache, and rate limits. - name: Teams description: Teams, members, invitations and roles. - name: Tags description: Label projects with tags and filter by them. - name: Catalog description: Regions, frameworks and plans. No authentication required. paths: /v1/ci-runners: post: tags: - CI Runners summary: Create a CI runner description: >- Creates the runner for one GitHub organization. Each organization can have one runner. The Brimble GitHub App must be installed on the organization, and the installation must be connected to your account. A runner in `reuse` mode is created disabled and turns on when a sandbox is attached. A runner in `per_job` mode is created enabled. **API key scope:** `ci_runner.create` **Team role permission:** `ci_runner.create` operationId: createCiRunner requestBody: required: true content: application/json: schema: type: object required: - name - installationId - mode properties: name: type: string minLength: 1 maxLength: 64 description: Name of the runner, up to 64 characters. teamId: type: string pattern: ^[a-fA-F0-9]{24}$ description: Team to act in. Omit for your personal workspace. installationId: type: integer minimum: 1 description: >- ID of the Brimble GitHub App installation on the organization. See `GET /v1/accounts/{git}`. mode: type: string enum: - reuse - per_job description: >- `reuse` runs jobs on sandboxes you attach, which stay running between jobs. `per_job` starts a new sandbox for each job and destroys it when the job ends. size: type: string description: >- Sandbox size for each job, for example `sbx.small`. Required when `mode` is `per_job`. region: type: string pattern: ^[a-fA-F0-9]{24}$ description: >- ID of the sandbox region to run jobs in. Required when `mode` is `per_job`. maxConcurrency: type: integer minimum: 1 maximum: 20 description: >- Most sandboxes to run at once in `per_job` mode. Defaults to 2. responses: '201': description: CI runner created content: application/json: schema: type: object required: - message - data properties: message: type: string description: Human-readable result of the request. example: CI runner created data: $ref: '#/components/schemas/CiRunner' '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': description: The organization already has a CI runner content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': $ref: '#/components/responses/ServerError' components: schemas: CiRunner: type: object properties: id: type: string description: ID of the CI runner. name: type: string description: Name of the runner. team: type: string nullable: true description: ID of the team that owns the runner. `null` in a personal workspace. provider: type: string enum: - GITHUB description: Where the jobs come from. installation_id: type: number description: ID of the Brimble GitHub App installation on the organization. account_login: type: string description: Login of the GitHub organization, for example `acme`. mode: type: string enum: - reuse - per_job description: >- `reuse` runs jobs on attached sandboxes. `per_job` starts a new sandbox for each job. size: type: string nullable: true description: Sandbox size for each job in `per_job` mode. `null` in `reuse` mode. region: type: string nullable: true description: ID of the sandbox region for `per_job` mode. `null` in `reuse` mode. max_concurrency: type: number description: Most sandboxes that run at once in `per_job` mode. enabled: type: boolean description: >- Whether the runner picks up jobs. A `reuse` runner is enabled only while a sandbox is attached. created_at: type: string format: date-time description: When the runner was created. updated_at: type: string format: date-time description: When the runner was last changed. required: - id - name - team - provider - installation_id - account_login - mode - size - region - max_concurrency - enabled - created_at - updated_at ErrorResponse: type: object required: - message properties: message: type: string description: Human-readable error message. example: Project not found data: type: object description: Always empty on errors. example: {} ValidationErrorResponse: type: object required: - errors properties: errors: type: array description: One entry per invalid field. items: type: object properties: type: type: string description: Always `field`. example: field value: description: Value that was sent. msg: type: string description: What is wrong with the value. example: Invalid value path: type: string description: >- Name of the invalid field. Nested fields use dots, for example `repo.branch`. example: name location: type: string description: Part of the request the field was in. enum: - body - query - params - headers - cookies responses: ValidationError: description: Request validation failed content: application/json: schema: $ref: '#/components/schemas/ValidationErrorResponse' Unauthorized: description: Missing, invalid or expired credentials content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Forbidden: description: >- The API key lacks the required scope, your team role lacks the permission, or the feature is not available on your account content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' ServerError: description: Unexpected server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-brimble-key description: >- API key created in the dashboard under Settings → API keys. Each key carries permission scopes; every endpoint lists the scope it needs. BearerAuth: type: http scheme: bearer bearerFormat: JWT description: Dashboard session token. Use an API key for integrations. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.