gitlab-guide

GitLab workflow delivery and enforcement: quick reference

How to realize tickets, kanban, merge-request delivery, durable context projections, and provider-native external enforcement on GitLab. The operations map finished artifacts and workflow intent onto GitLab-native resources.

The one thing to internalize: a project issue/work item, an issue-board list, a top-level Note, an inline discussion, and approval are separate objects. Most board cards are views over issue attributes, and review has no atomic object, so preserve every native identity and effect separately.

Before any write:

1. Run glab auth status and confirm the intended identity on the intended host: a stale env token silently acts as the wrong user.
2. Read /metadata and the actual resource/schema when version or tier changes the operation.
3. Re-fetch the three diff SHAs after every push and verify each inline comment came back as a DiffNote, never trust a 201 alone.

Requirements

• glab on PATH, authenticated to the target host. First-time machine setup (install, glab auth login, protocol, clone, verify) is in references/first-time-setup.md; token types and exact per-operation scopes are in references/auth.md.
• A token with read_api for read-only work or api (plus write_repository for git ops) for any write, carried by an identity with >= Developer role on the project (or the MR author).
• jq for reading API responses (verifying note type, merge status, discussion ids).

Essentials

• Manage workflow tickets: create/reconcile project issues; update metadata without losing unrelated values; preserve project + IID + global ID + URL; and manage native links or work-item-only widgets explicitly. See references/issues.md.
• Manage issue-board kanban: resolve board/list type and IDs, translate card moves into minimal issue-attribute changes, use native Status only on supporting hosts, and keep vertical ranking separate. See references/boards.md.
• Publish durable issue/MR context: use append-only top-level Notes with canonical ID/version/digest markers, exact retry reconciliation, successor links, and native note references. See references/context-notes.md.
• MR object & branch flags: glab mr create --source-branch <b> --target-branch main (-s defaults to current branch, -b to project default); glab addresses MRs by per-project iid. See references/create.md.
• glab does not push: git push -u origin HEAD first (see git-guide's push reference), then create; or pass --push. Always pass --yes in scripts or create hangs on the confirmation prompt. See references/create.md.
• Summary note: the review's prose is a plain non-anchored note: glab mr note <iid> -m "## Summary..." (POST .../notes). See references/review-post.md.
• Inline comment: a position-anchored discussion: glab mr note create <iid> --file path --line N -m "...", or raw POST .../discussions with a position object carrying three SHAs and conditional line keys. Realizes code-review-guide's findings on GitLab. See references/review-post.md.
• Blocking: there is no REST REQUEST_CHANGES; gate by withholding /approve against approval rules or by leaving resolvable threads unresolved with only_allow_merge_if_all_discussions_are_resolved. See references/review-post.md.
• Resolve a thread: PUT .../discussions/:discussion_id?resolved=true (REST is enough on GitLab; no GraphQL needed); match by discussion id, never by line. See references/review-resolve.md.
• Deep-link: MR notes carry no web_url; build <mr_url>#note_<note_id> from the returned note id. See references/review-post.md.
• Auth & host: api scope for writes (read_api reads), GITLAB_HOST targets self-managed, GITLAB_TOKEN is the general auth token. See references/auth.md.
• Enforce with native automation: use pinned, typed, tested CI/CD components, pipeline execution policies, compliance frameworks, protected environments, least-privilege credentials, and provider-native evidence. See references/automation-and-enforcement.md.
• Transact every governance change: discover, preview exact group/project mutations and authority, authorize, apply idempotently against observed revisions, verify with allow and deny probes, roll back, and own the drift. See references/onboarding.md.
• Preserve provider conformance: map tickets, boards, changes, reviews, context, and evidence to separate native identities while exposing tier/version and concurrency limits. See references/provider-conformance.md.