About

The Conventional Branch specification was inspired by Conventional Commits.

AI Agent Source Prefixes

As AI coding agents increasingly open their own pull requests, Conventional Branch maintains a registry of their branch prefixes so tools and teams can recognize them consistently. This registry is the machine-readable source of truth — the table below is generated from data/agents.yaml.

Giving each agent a documented prefix (or using the vendor-neutral ai/) lets teams do more than just eyeball who opened a PR:

• Apply review policy by source — require an extra human approval on agent-generated branches, or auto-assign a reviewer to them.
• Route CI differently — run a heavier security, license, or lint suite on ai/, copilot/, claude/, … branches before they reach a human reviewer.
• Attribute activity and cost — measure how much work each agent produces by filtering branches and PRs on their prefix.
• Automate housekeeping — auto-label PRs, apply branch-protection rules, or trigger notifications based on the prefix.

Building an agent that opens PRs? Register its prefix so reviewers and tooling recognize it out of the box.

Tooling for Conventional Branch

Conventional Branch can be adopted with local checks, CI validation, and agent skills:

• commit-check: Commit Check supports checking commit messages, branch naming, committer name/email, commit signoff, customizing error messages, suggested commands and more.
• commit-check-action: A GitHub Action for checking commit message formatting, branch naming, committer name, email, commit signoff and more.
• Conventional Branch Skill: Agent skill for AI coding assistants.

Install the skill with:

npx skills add conventional-branch/conventional-branch --skill conventional-branch

Projects Using Conventional Branch

Roughly ordered by how widely recognized the organization is, so the list is useful to skim.

• gchq/Bailo: Machine learning lifecycle management, by GCHQ, the UK’s intelligence, security and cyber agency.
• ORNLSlicer/ORNLSlicer: Toolpath planning and slicing for additive manufacturing, developed at Oak Ridge National Laboratory.
• ByteDance-Seed/cryofm: Generative foundation model for cryo-EM density maps, by ByteDance Seed.
• bcgov/nr-pies: Natural Resource Permitting Information Exchange by the Government of British Columbia.
• amagovpt/udata-pt: Portugal’s open data platform, by ARTE, the state agency for technological reform.
• TexasInstruments/processor-sdk-doc: Texas Instruments Processor SDK documentation.
• Enedis-OSS/tic4eebus: EEBUS OPEV use case by Enedis, France’s largest electricity distributor.
• BerriAI/litellm: A high-performance LLM proxy supporting 100+ models with spending tracking and guardrails.
• ansible/metrics-utility: Standalone utility for github.com/ansible/awx.
• sanity-io/sdk: Sanity App SDK.
• cuga-project/cuga-agent: CUGA, an open-source generalist agent harness for the enterprise.
• TailGrids/tailgrids: Open-source React UI library built with Tailwind CSS.
• lightonai/lighton-python-sdk: Python SDK for the LightOn API.
• ippontech/iroco2: IroCO2, a tool for estimating and reducing the carbon footprint of cloud infrastructure, by Ippon Technologies.
• Technica-Engineering/FLYNC: Flexible YAML-based vehicle network configuration, by Technica Engineering.
• stellio-hub/stellio-context-broker: Stellio, an NGSI-LD compatible context broker.
• Curiosum: Building apps for innovators.
• ZeusAutomacao/DFe.NET: Biblioteca em C# para emissão e impressão de NFe, NFCe, MDF-e e CT-e.
• commit-check: A free, powerful tool that enforces commit metadata, branch naming, and more.
• fau-advanced-separations/CADET-Process: A framework for modelling and optimizing advanced chromatographic processes, by Advanced Separations @ FAU.
• devsoc-unsw/structs.sh: An educational data structures and algorithms platform, by the UNSW Software Development Society.
• CSES-Open-Source/TritonScript: Open source project by the Computer Science and Engineering Society at UC San Diego.
• RLinf/RLinf: Reinforcement Learning Infrastructure for Agentic AI.
• soma-smart/framefox: Python web framework built on FastAPI, MVC and SQLModel.
• keyteki/keyteki: The engine behind The Crucible Online, for playing KeyForge in the browser.
• karol-broda/snitch: A prettier way to inspect network connections.
• jal-co/shieldcn: Beautiful README badges inspired by shadcn/ui.
• dunossauro/fastapi-do-zero: Curso básico de FastAPI em português.
• … and more projects using Conventional Branch.

Want your project on this list? Send a pull request.

CI/CD Integration

Because the branch name already encodes its purpose, CI/CD pipelines can key their behavior off the prefix directly, without any extra metadata or configuration lookup. In GitHub Actions, that means an if: startsWith(...) condition per job:

jobs:
  test:
    if: startsWith(github.head_ref, 'feature/') || startsWith(github.head_ref, 'bugfix/')
    runs-on: ubuntu-latest
    steps:
      - run: npm test

  security-review:
    if: startsWith(github.head_ref, 'hotfix/')
    runs-on: ubuntu-latest
    steps:
      - run: ./scripts/security-scan.sh

  release-candidate:
    if: startsWith(github.head_ref, 'release/')
    runs-on: ubuntu-latest
    steps:
      - run: ./scripts/build-release-candidate.sh

A common mapping of prefixes to pipeline behavior:

Other CI/CD platforms support the same pattern using their own equivalent of a branch-name condition (e.g., GitLab CI’s rules: - if:, or a shell check against $CI_COMMIT_REF_NAME). Conventional Branch only standardizes the branch name — the mapping above is a starting point to adapt to your own pipeline.

How to Adopt

1. Communicate the convention to your team and add it to your contributing guidelines.

2. Enforce it automatically using one of the tools listed above.

3. Add the badge to your repository README to signal adoption:

   

   [![Conventional Branch](https://conventionalbranch.org/badge.svg)](https://conventionalbranch.org/)
   

   Or in HTML:

   <a href="https://conventionalbranch.org/">
     <img alt="Conventional Branch 1.1.0" src="https://conventionalbranch.org/badge.svg">
   </a>
   

   Prefer to generate it yourself, or want a different shape? The shields.io equivalent carries the same colors and version, and takes &style=flat-square, &style=plastic or &style=for-the-badge:

   [![Conventional Branch](https://img.shields.io/badge/Conventional%20Branch-1.1.0-6699CC)](https://conventionalbranch.org/)
   

4. Configure your CI/CD to trigger different workflows based on branch prefix (e.g., auto-deploy on release/ branches) — see CI/CD Integration above.