Orbit planning

The portal reads labels, dates, and health from GitLab. Curate on GitLab, not in YAML. The scheme and its decisions live in the portal repo: label-taxonomy-and-epic-cleanup.md and config/labels.yaml.

Fix one item

Read the item. Pick the area from the substance of the work, not the title. If two areas fit, pick the one where the fix lands. Then apply the checklist for its kind.

Type rules: docs work is type::maintenance plus documentation. Coverage and discussion items are type::ignore. Perf defects are type::bug. Perf refactors are type::maintenance. A capability gap is type::feature even when filed as a bug.

Map old labels: PREP to orbit::infra, devex to orbit::dx, P1/P2 to priority::1/priority::2, and bare bug/feature/maintenance to their type:: form.

Leave other teams' labels alone: section::, devops::, automation:, backend, frontend, bug::availability, and R&D priority variants stay on the item.

GitLab allows one label per scope. Adding an area removes any other orbit:: label. Check what fell off.

Where labels live

Define all Orbit labels at the gitlab-org group. Orbit work also lives in gitlab-org/gitlab, and lower-level labels cannot reach it. Do not create project labels or labels at gitlab-org/orbit. A project copy of a group label is a defect. Move its carriers to the group label. Then delete the copy.

The gitlab-com group holds a sanctioned mirror for runbooks, handbook, and www items. Keep its colors and descriptions in step with gitlab-org.

A new orbit:: area needs four touches: the gitlab-org label, the gitlab-com mirror label, and both the areas: list and the gitlab-com track entry in the portal's config/labels.yaml. The portal renders swimlanes only for configured areas. After a config change run bun run seed in the portal repo. Label-only changes need no seed.

Roadmap membership

An item is on the roadmap when it carries one orbit-roadmap::<confidence> label. Committed means leadership can quote the date. Likely means a target quarter with a known dependency. Exploratory means intent without a date.

The rest derives from GitLab fields:

• Status: closed renders as shipped. Open workflow::in dev|in review|verification|complete renders as building. workflow::planning breakdown|ready for development renders as scoping. Validation or design values render as discovery. No label renders as planned.
• Quarter: from the due date. GitLab FY runs Feb to Jan and is named for the year it ends. FY27 Q1 is Feb-Apr 2026. No due date renders as unscheduled.
• Risk: the native health-status widget (On track, Needs attention, At risk).

One row per deliverable. When an epic is the roll-up, only the epic carries the orbit-roadmap:: label. Children with the label create duplicate rows. Every unshipped roadmap item needs a due date, a workflow:: label, and a health status.

A shipped deliverable stays on the roadmap with orbit-roadmap::committed and workflow::complete. Workstream containers and planning epics stay off the roadmap.

The fixed due date of a closed item is the date the work landed. Bulk-close dates are bookkeeping, not completion dates. Use the last substantive MR or child instead.

Epics

An epic is a dated deliverable with a clear outcome. A long-standing theme is an orbit:: area label, not an epic. An epic that maps to one area is a bucket. An epic that spans areas or wraps a workstream is a container.

• Bucket: label every child with the area, close the epic with a pointer comment, then unparent the children.
• Completed deliverable or container: close with workflow::complete and a fixed due date. Keep the children as the record of the work.

A container gets type:: and workflow:: but no area label.

Bulk sweeps

Work one project at a time. This keeps two people off the same item. Enumerate open issues with glab api "projects/<path>/issues?state=opened&per_page=100&page=N". Classify each one that misses an axis with the checklist. Apply in batches. State the plan and counts before you change more than 20 items.

A person approves every new issue and epic. Prepare the draft and labels. Run the create call only after the user approves in this session. New issues get all three axes at creation. New deliverables also get an epic, a fixed due date, and an orbit-roadmap:: label on the epic.

Labels outside the taxonomy

Do not add or create these labels. The portal ignores them.

• orbit::customer-zero, orbit::GA, orbit::backlog
• knowledge graph and its variants, group::knowledge graph, group::context systems
• orbit::hackathon, orbit_hackathon::*, Big Rock::Orbit
• GKG::*, ai_review::*, design partner, beta-blocker, PREP, devex

Remove GKG::* when you see it. Customer Zero reports get flat customer-zero.

Mechanics

Use label ids, never names. Same-named labels make name-based REST ambiguous. Label search is a substring match. Search a full name, not a bare scope.

glab api "groups/gitlab-org/labels?search=orbit%3A%3Aquery&only_group_labels=true&include_ancestor_groups=false&per_page=50"

The mutation needs a WorkItem gid. The API rejects an Issue gid with the same number.

glab api graphql -f query='query { project(fullPath: "gitlab-org/orbit/knowledge-graph") {
  workItems(iids: ["971"]) { nodes { id } } } }'
# epics: group(fullPath: "gitlab-org") { workItem(iid: "20992") { id } }

glab api graphql -f query='mutation {
  workItemUpdate(input: {
    id: "gid://gitlab/WorkItem/185491112",
    labelsWidget: {addLabelIds: ["gid://gitlab/GroupLabel/52162908"],
                   removeLabelIds: ["gid://gitlab/GroupLabel/40929324"]},
    startAndDueDateWidget: {dueDate: "2026-10-15", isFixed: true}
  }) { errors }
}'

MRs use mergeRequestSetLabels with operationMode: APPEND or REMOVE.

glab api graphql -f query='mutation {
  mergeRequestSetLabels(input: {projectPath: "gitlab-org/orbit/knowledge-graph",
    iid: "2033", labelIds: ["gid://gitlab/GroupLabel/52162078"],
    operationMode: APPEND}) { errors }
}'

Sweep by label. labelName accepts wildcards and includeDescendants: true reaches subgroup projects.

glab api graphql -f query='query { group(fullPath: "gitlab-org") {
  workItems(labelName: ["orbit-roadmap::*"], includeDescendants: true, first: 100) {
    nodes { iid title state webUrl } } } }'

Mint a new area at gitlab-org with the description from config/labels.yaml:

glab api -X POST "groups/gitlab-org/labels" \
  -f name="orbit::query" -f color="#1f75cb" \
  -f description="Query engine, DSL, compiler, pagination, agent query ergonomics"

API facts:

• Label promotion (PUT /projects/:id/labels/:label_id/promote) merges same-named project labels only in direct child projects. Copies in subgroup projects need a manual carrier swap.
• Epic due dates roll up from children. Set isFixed: true to pin one.
• GraphQL count caps at 1000. Paginate with pageInfo for real totals.
• Do not filter out confidential items. The portal badges them.
• Batch up to 10 aliased mutations per request to stay under the complexity limit of 250.

Label ids at gitlab-org:

Conventions

Follow the host repository's AGENTS.md for comment format. Record label and epic decisions in the portal's docs/label-taxonomy-and-epic-cleanup.md. Rename GKG or Knowledge Graph to Orbit in any title you touch. Keep code identifiers such as gkg-webserver and GKG_INDEXER as they are.