Git branch naming convention validator
Give a branch name and your naming template: feature/ABC-123-add-login against type/ticket-description passes and splits into type feature, ticket ABC and description 123-add-login. A name that misses the pattern fails with a message quoting both. Free in your browser.
- Free
- Runs in your browser
- No sign-up
- Your data stays on your device
Run — free
Worked example
- Branch
- feature/ABC-123-add-login
- Convention
- type/ticket-description
- Component names
- type, ticket, description
- Component count
- 3
Teams that share a monorepo or a long-lived product repository usually agree on a branch naming convention so review bots, release scripts, and ticket links can parse every ref without human guessing. A typical pattern looks like type slash ticket hyphen description—for example feature/ABC-123-add-login—but every organisation invents its own separators and component order. This git branch naming convention validator accepts the live branch string and your convention template, checks that the entire name matches from start to end, and returns each named component so CI, hooks, and dashboards can enforce policy without brittle one-off regexes.
How the convention pattern works and what gets extracted
A convention is a short template string made of placeholder names and literal separators. Placeholders are ordinary identifiers: they start with a letter or underscore and continue with letters, digits, or underscores. Everything else in the template is a separator that must appear literally in the branch name.
The classic example type/ticket-description therefore means three components—type, ticket, and description—joined by a slash and then a hyphen. When you submit branch feature/ABC-add-login with that convention, the validator returns type equal to feature, ticket equal to ABC, and description equal to add-login. The final component is allowed to contain the same characters as earlier separators so multi-word slugs such as add-user-login stay inside description rather than being truncated at the first hyphen.
Component names inside one convention must be unique; the pattern must start and end with a placeholder; placeholders and separators must alternate. Those rules keep the compiled matcher deterministic and avoid ambiguous captures.
What you can do with it
CI gate for pull requests
Reject PR branches that do not match type/ticket-description before expensive build and test jobs run.
Pre-commit and onboarding hooks
Teach developers the house naming pattern locally with the same pure matcher the server uses.
Ticket and changelog automation
Extract ticket and type components from the branch name to update trackers and choose changelog sections.
FAQ
How do I validate a git branch against a naming convention?
Send branch (for example feature/ABC-add-login) and convention (for example type/ticket-description).
What happens if the branch name is empty?
An empty or whitespace-only branch name is never accepted and is not billed.
Can the description part contain hyphens?
Yes. The final placeholder captures the remaining suffix, so add-user-login stays inside the last component when the separator before it is a single hyphen.
Does the validator enforce a fixed list of branch types?
No. It checks structure and extracts components. Apply your own allow-list on the type component if you only accept feature, fix, chore, and similar labels.
Why does the ticket part come out as ABC and not ABC-123?
In type/ticket-description the ticket ends at the first hyphen, because that hyphen is the separator before the description. Everything after it, 123-add-login, belongs to the last part, which may contain hyphens of its own.
Related tools
For developers — API access
Everything on this page is available programmatically. This section is for teams who want to wire it into their own systems; everyone else can just use the tool above.
API endpoint
Prefer to automate it? One authenticated POST creates the task; the result comes back by webhook or a signed link. The same capability also runs here on the web, by email and from Telegram — and soon from our app too.
Call it from your stack
curl -X POST https://api.kit.forhosting.com/dev/git-branch-name-validate \
-H "Authorization: Bearer $KIT_KEY" \
-H "Content-Type: application/json" \
-d '{"branch":"feature/ABC-123-add-login","convention":"type/ticket-description"}'const res = await fetch("https://api.kit.forhosting.com/dev/git-branch-name-validate", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.KIT_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"branch": "feature/ABC-123-add-login",
"convention": "type/ticket-description"
})
});
const { task_id } = await res.json();import os, requests
res = requests.post(
"https://api.kit.forhosting.com/dev/git-branch-name-validate",
headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
json={
"branch": "feature/ABC-123-add-login",
"convention": "type/ticket-description"
},
)
task_id = res.json()["task_id"]<?php
$res = file_get_contents("https://api.kit.forhosting.com/dev/git-branch-name-validate", false, stream_context_create([
"http" => [
"method" => "POST",
"header" => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
"content" => '{"branch":"feature/ABC-123-add-login","convention":"type/ticket-description"}',
],
]));
$task = json_decode($res, true);body := bytes.NewBufferString(`{"branch":"feature/ABC-123-add-login","convention":"type/ticket-description"}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/dev/git-branch-name-validate", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)Example request
{
"branch": "feature/ABC-123-add-login",
"convention": "type/ticket-description"
}Example response
{
"task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
"type": "dev.git_branch_name_validate",
"status": "queued",
"_links": {
"result": "/tasks/tsk_…/result"
}
}The API is asynchronous: the call returns a task_id immediately and the result arrives by webhook. Polling is capped at 1 req/s per task.
Pricing
Published price — no tokens, no invented credits. A failed task is never charged.
Errors
| HTTP | Code | Meaning |
|---|---|---|
401 | unauthorized | Missing or invalid API key. |
402 | insufficient_balance | Your balance doesn't cover the task price. |
404 | unknown_type | That task type doesn't exist. |
429 | rate_limited | Too many requests. Use the webhook instead of polling. |
Technical notes
Empty names fail with invalid_input, as do common unsafe git-ref characters such as spaces, consecutive dots, and forbidden punctuation.
How the convention pattern works and what gets extracted
If the branch does not match the whole pattern, the task fails with invalid_input and a message that quotes both the branch and the convention so developers can fix the name or the policy in one glance.
Input contract, safety checks, and response shape
Control characters are rejected as well. Optional output keys are omitted rather than set to null. Failed validation is not billed. Pair the response with your own policy layer if you need an allow-list of type values such as feature, fix, chore, or release; this capability checks structure and extracts parts, it does not hard-code a single organisation's vocabulary. POST a JSON body with two required strings: branch, the candidate git branch name, and convention, the naming template. Aliases are accepted for convenience—branch_name, name, and ref for the branch field; pattern, format, and template for the convention field—but the canonical names appear in documentation and SDKs. Both fields must be non-empty after rejecting pure whitespace; an empty branch is always invalid_input because git cannot create a zero-length ref and automation that forgets to pass the name should fail closed. On success the body includes valid true, the echoed branch and convention, a components object mapping each placeholder name to its captured value, component_names in template order, and component_count.
Where a branch naming validator earns its keep
Continuous integration jobs use a git branch naming convention validator as the first step of a pipeline so pull requests opened with ad-hoc names never reach expensive build stages. Release automation extracts the ticket component to open or update tracker issues, and extracts the type component to choose changelog sections without fragile substring hacks. Content sites that rank for git branch naming convention validator benefit from a live form whose free path matches the paid automation path byte-for-byte. Platform teams that operate many repositories publish one convention string in their developer portal and point every template, bot, and checklist at this endpoint so a policy change is a single string edit rather than a hunt through shell scripts.
Technical questions
What does the git branch naming validator cost?
The browser tool is free. API requests use prepaid KIT balance at $0.002 per successful call; invalid input is not billed.