Omniscio

GitHub Branch Creation from MC Items

GitHub branch creation from MC items makes the branch for a piece of board work without leaving Omniscio: it names the branch from the item, cuts it from the repository's default branch, and links the result back onto the item so the work has a place to start from.

On this page

What it is

GitHub branch creation from MC items is the "start the work" action on a board item. Given an item and a project folder that is linked to a GitHub repository, it creates a new branch on GitHub and records the branch as a link on the item.

The branch name comes from the item's own name, slugified for git, behind a prefix you can choose (default feat). The branch is cut from the repository's current default branch, so it starts from the same place a person's git checkout -b would.

Two entry points reach the same code: the in-app action on the item, and a CLI action an agent can request through an approval card. Both call one service function, so an approved card creates exactly the branch the button would.

The switch is githubMcBranchCreationEnabled, off by default and listed in Settings → Lab; it also follows the board checklist's GitHub answer.

Where to find it

  • A board item's action menu carries "create a branch", where you pick the project and optionally the branch prefix.
  • Settings → Lab → GitHub branch creation from MC items is the on/off switch.
  • The item's Links tab lists the branch once it exists, with its name and a link to the branch on GitHub.
  • Settings → GitHub holds the account used for the call, and the project list decides which repositories are offered.

How it behaves

From an item to a branch

  1. The item is read and the project is resolved (the one you picked, or the first GitHub-connected project).
  2. GitHub is asked for the repository's default branch, then for that branch's current commit.
  3. The branch name is assembled from the prefix and the item's slugified name — the prefix is itself made ref-safe first, falling back to feat if nothing usable survives.
  4. The new ref is created from that commit.
  5. A github_branch link is written onto the item and the item's links are pushed to any open board.

Names, collisions and limits

A branch whose name already exists is retried with a numeric suffix — -2, -3, -4 — up to three retries, and if all collide the call fails with a message saying the name is taken rather than creating a second branch silently. Because the prefix is sanitised before the name is assembled, a 422 from GitHub can only mean a real collision, not an invalid ref.

Only one branch creation per item can be in flight at a time; a second request while one is running is refused with "Branch creation already in progress for this item."

Failure handling

The call is not retried in the background: a person is watching it, so a failure is surfaced instead of stalling. The messages name the actionable cause — no GitHub account connected (connect in Settings → GitHub), repository not found, no access to the repository, project not linked to a git remote, or GitHub unreachable. The git lookup for the project's remote runs through the app's owned-child primitive, so the child is contained and reaped like every other git run.

Boards and items are described in mission-control.md; the pull requests and commits that then reference those items are in github-pr-linking.md. Every other page in this library is listed in INDEX.md.

Last verified 2026-11-10