Skip to content
SHC Docs

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.


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.

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.

AxisMechanismValues
SubsystemComponent (one per issue)ce-daemon, console, traefik-plugin, catalog-apps, ci-release, estate-ops, security, marketplace-portal
Kind of workLabel (may be several)bug, feature, chore, security, ops-runbook, decision
ReleaseMilestonev0.0.62, v0.0.63
UrgencyPriorityUrgent, 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 SHC project runs a six-state workflow. Five of them are the normal path; Canceled is the exit.

StateMeansMoved by
BacklogFiled, not yet committed to. Default for a new issue.Whoever files it
ReadyUnderstood well enough to start. No open questions.Whoever triages
In ProgressSomebody is working on it right now.The person doing the work, when they start
In ReviewA merge request is open against it.The person doing the work, when they open the MR
DoneMerged and verified.The person doing the work, or the reviewer on merge
CanceledWill not be done. Say why in the issue before you move it.Whoever decides

Two rules that matter more than the rest:

  1. Move the issue when the fact changes, not hours later. A board that is accurate only in retrospect is a report, not a tool.
  2. In Review means an MR exists. If there is no open MR, the issue is not in review, whatever the conversation looks like.

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.

Put the issue id at the start of the branch, after the lane prefix if you use one:

Terminal window
git checkout -b lane/SHC-42-docuseal-external-signing

The whole ref is scanned, so all of these work:

SHC-42-short-slug
lane/SHC-42-short-slug
feature/SHC-42
jd/SHC-42/retry

The 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.

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-42

closes, 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.

Pasting the issue link works too:

https://projects.corp.bitspur.com/workbench/<workspace>/tracker/SHC-42

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.

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 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-42

on every merge request it links. It renders as a chip on the MR page and in the list, and it is queryable:

Terminal window
# every MR attached to SHC-42, on the corp instance
curl -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 applying huly::SHC-9 automatically drops huly::SHC-42) are a Premium feature. Corp runs gitlab-ce, so huly::SHC-42 is an ordinary label whose title contains two colons. The bridge does the exclusion itself: it removes any other huly:: 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.

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.

  1. The repository has to be wired to the bridge. The bridge reads one list (vars.gitlab.projects on the gitlab-huly deployment) 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 in vars.gitlab.webhookSecrets, which doubles as the allowlist.
  2. 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:

BeforeNow
Scoperead_apiapi
Role on the projectReporterDeveloper
Identityper-project botper-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.

Terminal window
# 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.