Project management
Where SHC work is tracked, how to file it, and the branch/MR convention that attaches a merge request to the story it implements.
Audience: SHC contributors. For the engineering bar itself, see Engineering standards.
Where work lives
Section titled “Where work lives”Work is tracked in Huly, at https://projects.corp.bitspur.com, in the
project SelfHosted Cloud (identifier SHC). Every issue has a
human-readable id of the form SHC-<n>; that id is the join key for
everything below, so it is worth getting used to reading it.
Code lives in GitLab. The public release face is
gitlab.com/bitspur/selfhosted-cloud/*; the corp instance at
git.corp.bitspur.com carries the group selfhostedcloud.org.
Huly is the source of truth for what is being worked on and why. GitLab is the source of truth for the change itself. Neither replaces the other, and the convention in this document is the only thing that ties them together.
File it before you start
Section titled “File it before you start”If a piece of work is worth doing, it is worth an issue first. The issue is what a second person reads when they pick the work up cold, so it needs three things and not much else:
- What is wrong: the observed behaviour, not the theory.
- Evidence: a file path and line, a commit, a log line, a measurement. “Seems slow” is not evidence; “9.0 GB anon-rss, kernel-killed 2026-08-21T06:54:57Z” is.
- Done when: the condition that ends the work, written so somebody other than the author can check it.
Do not open an issue to record that a decision is needed and then argue it in
chat. File it with the decision label, assign it to the owner, and write the
options down. A ruling that never lands in the issue did not happen.
How the project is organised
Section titled “How the project is organised”| Axis | Mechanism | Values |
|---|---|---|
| Subsystem | Component (one per issue) | ce-daemon, console, traefik-plugin, catalog-apps, ci-release, estate-ops, security, marketplace-portal |
| Kind of work | Label (may be several) | bug, feature, chore, security, ops-runbook, decision |
| Release | Milestone | v0.0.62, v0.0.63 |
| Urgency | Priority | Urgent, High, Medium, Low, No priority |
Component is single-valued on purpose: it answers “whose queue is this in”.
Labels are multi-valued because a single issue really can be both a security
fix and an ops-runbook.
The states, and who moves them
Section titled “The states, and who moves them”The SHC project runs a six-state workflow. Five of them are the normal path;
Canceled is the exit.
| State | Means | Moved by |
|---|---|---|
| Backlog | Filed, not yet committed to. Default for a new issue. | Whoever files it |
| Ready | Understood well enough to start. No open questions. | Whoever triages |
| In Progress | Somebody is working on it right now. | The person doing the work, when they start |
| In Review | A merge request is open against it. | The person doing the work, when they open the MR |
| Done | Merged and verified. | The person doing the work, or the reviewer on merge |
| Canceled | Will not be done. Say why in the issue before you move it. | Whoever decides |
Two rules that matter more than the rest:
- Move the issue when the fact changes, not hours later. A board that is accurate only in retrospect is a report, not a tool.
In Reviewmeans an MR exists. If there is no open MR, the issue is not in review, whatever the conversation looks like.
Linking a merge request to its story
Section titled “Linking a merge request to its story”This is the part the tooling depends on. A bridge (gitlab-huly) watches
merge-request events on the corp GitLab and attaches the MR to the Huly issue
it names, so the issue shows the MR’s title, state, author, branch and URL
without anybody pasting a link.
There are three accepted ways to name the issue. Use the first one.
1. Branch name: preferred
Section titled “1. Branch name: preferred”Put the issue id at the start of the branch, after the lane prefix if you use one:
git checkout -b lane/SHC-42-docuseal-external-signingThe whole ref is scanned, so all of these work:
SHC-42-short-sluglane/SHC-42-short-slugfeature/SHC-42jd/SHC-42/retryThe branch is preferred because it costs nothing after git checkout -b and
every later event carries it. Nobody has to remember to edit anything.
If a branch names two ids, the leftmost wins. One MR attaches to one issue.
2. A keyword line in the MR description
Section titled “2. A keyword line in the MR description”For work that started on a branch nobody named carefully, put a keyword line in the merge-request description. The line must start with the keyword:
Closes SHC-42closes, close, closed, fixes, fixed, resolves, resolve, refs,
ref, references, relates to, related to, part of and a bare huly:
all work, with or without a colon, and a leading - or > is fine.
3. A Huly issue URL in the MR description
Section titled “3. A Huly issue URL in the MR description”Pasting the issue link works too:
https://projects.corp.bitspur.com/workbench/<workspace>/tracker/SHC-42What does not link
Section titled “What does not link”A bare SHC-42 sitting in the middle of the description is deliberately
ignored. MR descriptions quote logs, versions and hashes, and a false link
writes a reference onto somebody else’s issue where nobody will look for it.
For the same reason, an id whose prefix is not a real Huly project is dropped:
SHA-1, UTF-8, release-2 and renovate/npm-express-4.x all look like issue
ids to a regex and none of them are. The bridge checks the prefix against the
actual project list, so no denylist has to be maintained.
What the bridge does, exactly
Section titled “What the bridge does, exactly”Worth knowing so nobody waits on behaviour that was never built.
It does:
- Attach a merge request to the Huly issue named by the branch or description.
- Keep that reference current: title, state (
opened/merged/closed/locked), draft flag, source and target branch, author, URL. - Move the reference if the branch is renamed to name a different issue, and detach it from the old one.
- Re-walk recent merge requests every five minutes, so a webhook GitLab failed to deliver is repaired rather than lost.
- Optionally move the issue’s status when the MR merges into the default
branch. This is off unless the deployment sets
MERGE_TRANSITION. - Optionally label the merge request with the issue it belongs to, the
back-link below. Also off unless the deployment sets
vars.gitlab.backlinkLabel.
It does not:
- Create Huly issues. Nothing in GitLab opens a story; you file it in Huly.
- Sync GitLab issues. Use Huly, not GitLab issues.
- Sync comments in either direction.
- Post comments on merge requests, or edit their descriptions. The one thing it can write into GitLab is the label below, and only when asked to.
The back-link label
Section titled “The back-link label”The link used to be one-way: the issue showed the MR and the MR showed nothing. Reading a merge request, there was no way back to the story.
There is now, and it is a property of the merge request rather than a comment.
With vars.gitlab.backlinkLabel set to huly, the bridge puts
huly::SHC-42on every merge request it links. It renders as a chip on the MR page and in the list, and it is queryable:
# every MR attached to SHC-42, on the corp instancecurl -H "PRIVATE-TOKEN: $TOKEN" \ "https://git.corp.bitspur.com/api/v4/projects/<id>/merge_requests?labels=huly::SHC-42"Filter by the exact label. huly::* wildcard filtering is a licensed
GitLab feature and the corp instance runs Community Edition.
Three things worth knowing:
- It is spelled like a GitLab scoped label and is not one. Scoped labels
(where a
huly::prefix is mutually exclusive, so applyinghuly::SHC-9automatically dropshuly::SHC-42) are a Premium feature. Corp runsgitlab-ce, sohuly::SHC-42is an ordinary label whose title contains two colons. The bridge does the exclusion itself: it removes any otherhuly::label in the same request that adds the right one. The spelling is kept so that licensing the instance later upgrades the behaviour with no relabelling. - It follows the branch. Rename a branch to name a different issue and the label swaps. Rename it to something with no issue id and the label comes off.
- It leaves your labels alone. The bridge only ever touches labels starting
huly::. Anything else you put on the MR survives.
If you would rather it not appear on a given merge request, remove it; it will
come back on the next sweep, because the bridge’s job is to keep it true. Turn
it off for the whole deployment by clearing vars.gitlab.backlinkLabel.
Preconditions
Section titled “Preconditions”Two things have to be true before the loop above works for a given repository,
and neither is met yet. Neither is a code change; both are deployment
configuration, tracked in SHC-51.
- The repository has to be wired to the bridge. The bridge reads one list
(
vars.gitlab.projectson thegitlab-hulydeployment) that is simultaneously the sweep list, the webhook-provisioning list, and the read token’s blast radius. A repository absent from that list gets no webhook and is never swept. Each entry also needs a matching<projectId>=<secret>pair invars.gitlab.webhookSecrets, which doubles as the allowlist. - The merge request has to be opened on the corp instance. The bridge is
wired to
git.corp.bitspur.com. A merge request opened on gitlab.com is invisible to it; a mirror carries branches and commits, not merge requests.
Until both hold, name your branches by the convention anyway. It costs nothing and the links appear retroactively when the sweep first covers the repository.
The back-link label had a third precondition of its own (a credential rather
than a list) and it is now met. The bridge’s GitLab token is minted by the
gitlab socket as a project access token, and until 2026-08-23 that token
was a Reporter with the read_api scope, which is right for everything else
the bridge does and could not make this write: read_api is read-only, and
PUT /merge_requests/:iid needs the update_merge_request ability, which
GitLab grants to Developer and not to Reporter.
Both halves were widened, on the owner’s approval, and the widening is a role change rather than a rung change:
| Before | Now | |
|---|---|---|
| Scope | read_api | api |
| Role on the project | Reporter | Developer |
| Identity | per-project bot | per-project bot, unchanged |
The identity row is the one that bounds it. api on a personal access token
belonging to the instance administrator really is read+write over every project
on the instance; api on a bot whose only membership is the projects in
vars.gitlab.projects reaches those projects and 404s everywhere else. The
gitlab socket refuses the scope unless the plug also declares
projectWrite: true, which is refused in turn without a project list, so the
grant cannot drift onto the instance-wide rung by someone clearing projects.
What it costs, plainly: a Developer can push to unprotected branches on those
projects, and api covers every endpoint on them rather than the one the
bridge calls. GitLab CE offers nothing narrower that can attach a label.
Clearing either vars.gitlab.scopes or vars.gitlab.projectWrite puts the
credential back where it was; the bridge then logs a refusal per merge request
and the Huly side of the link is unaffected, so nothing else breaks while it is
wrong.
Quick reference
Section titled “Quick reference”# 1. Find or file the story in Huly, note its id.# 2. Branch with the id in the name.git checkout -b lane/SHC-42-docuseal-external-signing
# 3. Move the issue to In Progress.# 4. Work. Commit signed off.git commit -s -m "feat(docuseal): ungate the slug-authenticated signing route"
# 5. Push and open the MR on git.corp.bitspur.com.# Move the issue to In Review.# 6. On merge, move the issue to Done.