GitLab Workflow Standards

On this page

This page is the authoritative source for GitLab issue/MR/epic standards. CONTRIBUTING.adoc is a thin pointer that defers here — it must NOT restate these protocols (a second copy only drifts).

Issue Standards

Every issue must be self-contained — a new contributor should understand the problem, context, and expected outcome without reading any other resource.

Required sections:

  1. Title: action-oriented, prefixed with type (feat: Add user registration flow, fix: Contact form resets on hydration, chore: Update Playwright image).

  2. Description: what needs to happen and why — not just "add X", explain the motivation.

  3. Acceptance Criteria: a bulleted checklist of concrete, independently-verifiable outcomes.

  4. Context & References: links to the plan file, related issues (Relates to #123, Blocks #456), and the key files/services that will change.

  5. Labels: at least one type (feat/fix/chore/refactor/docs/test) and, where applicable, a priority (P0-critical…P3-low).

Issue Decomposition

  • One issue per independently shippable unit of work. If a plan has 5 MRs, create 5 issues.

  • Avoid mega-issues. If an issue has more than ~10 acceptance criteria, split it.

Epics & Work Items

  • Use epics to group related issues spanning multiple services or MRs.

  • Use milestones for time-boxed iterations or release targets.

  • When a plan produces multiple issues, always create an epic first, then child issues linked to it.

  • Use GitLab’s /relate quick action to link related (non-parent/child) issues.

  • Issue weights: assign weights (1=trivial, 2=small, 3=medium, 5=large, 8=very large) for capacity planning. Weight reflects implementation complexity, not calendar time.

Epic description format

  1. Summary: 1–2 sentence description of the scope.

  2. Plan link: full clickable markdown URL. Never a plain-text path.

  3. Task list: each child issue as - [ ] #N title (weight: W) — full title + weight, never bare numbers.

Issue-epic linking

Every child issue must be linked to its epic via the epic_id API field — not just referenced in the description:

glab api -X PUT "projects/$(glab project view --output json | jq -r '.id')/issues/N" -f epic_id=EPIC_NUMERIC_ID

Bulk Issue Creation

The quality bar does not change for batch operations. Every issue must meet the full Issue Standards at creation time. Do not create stub issues with placeholder descriptions.

Merge Request Standards

  1. Title: match the issue title; include the issue reference: feat: Add user registration flow (#12).

  2. Description: use the template:

    ## Summary
<1-3 bullet points describing what changed and why>

## Changes
<Bulleted list of key changes, grouped by file or component>

## Test Plan
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] E2E tests pass (if applicable)
- [ ] <Any manual verification steps>

Closes #<issue-number>

  3. Link to issue: every MR references its issue via Closes #N or Relates to #N.

  4. One MR per issue unless there is a strong reason to bundle (document why).

  5. Draft MRs (Draft: prefix) are encouraged for WIP to signal intent and get early feedback.

Closes #N auto-closes the issue but does NOT satisfy the closing protocol. After the MR merges you MUST also add a closing comment (below).

Closing Issues

This step is mandatory after every MR merge. Always leave a closing comment that future contributors and agents can follow:

  1. Reference the commit or merge: include the implementation commit SHA and merge commit SHA. Use bare SHAs (no backticks) so GitLab auto-links them. Cite the commit with the substantive work, not fixup commits.

  2. List changed files: key files added/modified, grouped by purpose.

  3. Check off acceptance criteria: copy from the issue and mark each done with [x].

  4. Note anything deferred or discovered: edge cases, follow-up work, related issues created.

Code Review Checklist

When reviewing (or self-reviewing before MR creation), verify:

  • Security: no SQL injection, XSS, hardcoded secrets, or exposed credentials. Parameterized queries. Input sanitized at the API boundary.

  • Performance: no N+1 queries, unbounded allocations, or unnecessary cloning. Pagination on list endpoints.

  • Correctness: error cases handled, edge cases covered, no silent failures.

  • Conventions: matches coding conventions; SPDX header on new files; tests included.

Labels

Universal requirement: every issue and MR must carry a type signal and (where applicable) a priority signal, and titles must use the commit-type vocabulary from git workflow.

Default starter labels (replaceable). The flat set below is a sensible default. A project MAY adopt a different taxonomy — GitLab scoped labels (type::feat, priority::high), additional dimensions, or another scheme — as long as the universal type+priority requirement holds. Record the project’s chosen taxonomy in .claude/CLAUDE.md so it supersedes this default unambiguously.

Label Color Purpose

feat

green

New feature or capability

fix

red

Bug fix

chore

grey

Maintenance, dependencies, CI

refactor

blue

Code restructuring without behavior change

docs

purple

Documentation only

test

orange

Test additions or improvements

P0-critical

red

Blocks all work

P1-high

orange

Important, do soon

P2-medium

yellow

Normal priority

P3-low

blue

Nice to have
Edit this page · latest