CIHubDocs
ProductDocsChangelog

Write your .cihub.yaml

Change the behavior of a queue or add queues with the .cihub.yaml file of the repository; write it by hand with the JSON Schema, or with an assistant.

Open the .mdEdit on GitHub

A queue works without a file: the first /cihub merge on the default branch creates its queue with the default settings. .cihub.yaml, at the root of the repository, changes the behavior of a queue, adds queues on other branches, and sets who goes first.

CIHub reads the file on the head of the target branch, never on a pull request: a pull request cannot loosen its own gate. A change of the file applies once it merges. The file can also be .cihub.yml, .cihub/config.yaml or .cihub/config.yml, but only one of them: with two, the configuration is in error.

Start the file

The first line declares the JSON Schema: your editor then completes each key and shows an error before you commit.

.cihub.yaml
# yaml-language-server: $schema=https://cihub.io/schema/config/v1.json
version: 1

Editors with a YAML language server, such as VS Code with its YAML extension, read this line.

A complete example

.cihub.yaml
# yaml-language-server: $schema=https://cihub.io/schema/config/v1.json
version: 1

# Settings and conditions of every queue, unless a queue sets its own.
defaults:
  queue_conditions:
    draft: false
    labels:
      none:
        - do-not-merge

queues:
  - branch: main
    strategy: batched
    batching:
      size: 3
      max_wait_minutes: 1
    # The checks that the test of the queue must pass, in addition to those of the rules of the branch.
    merge_conditions:
      checks:
        success:
          - Build Success
    # A kind of pull request with its own settings, in the same queue.
    profiles:
      - name: dependencies
        conditions:
          author: renovate[bot]
        batching:
          size: 10

  # Each release branch gets its own queue.
  - branch: release/*
    strategy: sequential

# The first rule that a pull request meets gives its priority; /cihub merge --priority wins.
priority_rules:
  - name: hotfixes
    conditions:
      labels:
        - hotfix
    priority: urgent
  - name: dependencies
    conditions:
      author: renovate[bot]
    priority: low
KeyWhat it does
queuesOne entry per branch, or per glob of branches (release/*): each branch that it matches has its own queue
strategyHow the queue tests the pull requests: Choose a strategy
queue_conditionsWhat a pull request must meet to enter the line, in addition to the rules of the branch
merge_conditionsThe checks that the test commit must pass, in addition to the required checks
profilesThe settings of a kind of pull request in the same queue, such as the updates of dependencies
priority_rulesWho goes first: urgent, high, medium, low, or 0 to 255
defaultsThe settings and the conditions of every queue that does not set its own

Write conditions

A condition is a YAML map: the key is an attribute of the pull request, and every key must hold.

queue_conditions:
  draft: false # a boolean
  base: main # a value, or a list of values (one of them)
  labels:
    none: # a list: all, any, none, or count
      - do-not-merge
  files:
    none_match: # globs
      - "migrations/**"
  approved_reviews_by:
    count:
      min: 2
  checks:
    success:
      - build

any:, all: and none: take a list of maps. The attributes cover the state of the pull request (draft, conflict, from_fork, behind_base), its reviews, its checks, its labels, its author, its files and its size, its base and its head, and its position and age in the queue. The JSON schema describes every attribute, and specs/CONFIGURATION.md gives their rules.

When a submitted pull request does not meet a condition, its comment names it: "the queue conditions labels: ready are not met".

Check the file

  • The schema line makes your editor check each key and each value.
  • An unknown key, a value out of range or two queues on one branch is an error, with its line.
  • The page of the queue in the dashboard shows the error of the file on the target branch. Until you fix it, the queue keeps the last valid file; a test that needs the file fails with "the configuration file is not valid".

Write it with an assistant

An assistant writes a valid file if it knows the rules of the file. Copy this prompt into it: it asks you the right questions first, then writes the file and explains each choice.

A coding agent reads the same rules from the schema and from this site in Markdown: Use CIHub with a coding agent.

Submit, cancel and restart a pull request

Submit a pull request to the queue from a comment, a label, the checkbox of CIHub, the command line or the dashboard; give it a priority; cancel it or restart its tests; pause a queue.

Choose a strategy

Sequential, pipelined or batched, how the queue tests the pull requests, and which strategy fits the length of your CI and the number of pull requests a day.

On this page

Start the fileA complete exampleWrite conditionsCheck the fileWrite it with an assistant
For agentsThis page as Markdown:/docs/configuration.md