beads/docs/cli-reference/gitlab.md
Chris Sells de0200ff77 docs(emitter): Cobra-accurate usage lines, published global flags, MDX ESM guard
Three generated-content defects from the adversarial review, all
structurally invisible to the drift gate (generated-vs-generated):

- Usage lines now mirror Cobra's help template: a runnable command shows
  its UseLine, a command with subcommands shows '<path> [command]', both
  when both apply. Previously bare UseLine() stamped 'bd mol [flags]' on
  30 parent pages — a line the binary never prints.
- The generated CLI index publishes the Global Flags block; the binary
  prints it on every --help but no page carried it.
- docsmint neutralizes prose lines that Mintlify's prebuild would dedent
  into MDX ESM blocks (a line beginning 'export'/'import' outside a
  fence gets wrapped in a code span). This is why /cli-reference/mail
  returned HTTP 200 while rendering only a parse-error placeholder —
  reproduced, fixed, and covered by a planted-hazard test; fenced
  content stays verbatim.

Also rewords check-cli-docs-drift.sh's early-PASS message, which
asserted 'the supplied binary differs' as the cause when uncommitted
local edits produce the same result.

All 113 pages + docs/CLI_REFERENCE.md regenerated through the pipeline;
TDD'd in cmd/bd/help_all_test.go and tools/docsmint/docsmint_test.go.
Verified live: /cli-reference/mail renders real content, zero parse
errors; generate-cli-docs.sh --check, docsync, freshness, and
mint broken-links all pass on this tree.
2026-07-12 10:37:17 -07:00

3 KiB

title description
bd gitlab GitLab integration commands

{/* AUTO-GENERATED: do not edit manually */}

Generated from bd help --doc gitlab.

Commands for syncing issues between beads and GitLab.

Configuration can be set via 'bd config' or environment variables: gitlab.url / GITLAB_URL - GitLab instance URL gitlab.token / GITLAB_TOKEN - Personal access token gitlab.project_id / GITLAB_PROJECT_ID - Project ID or path gitlab.group_id / GITLAB_GROUP_ID - Group ID for group-level sync gitlab.default_project_id / GITLAB_DEFAULT_PROJECT_ID - Project for creating issues in group mode

bd gitlab [command]

bd gitlab projects

List GitLab projects that the configured token has access to.

bd gitlab projects [flags]

bd gitlab pull

Pull one or more items from GitLab.

Accepts bead IDs or external references as positional arguments. Equivalent to: bd gitlab sync --pull-only --issues <refs>

bd gitlab pull [refs...] [flags]

Flags:

      --dry-run   Preview pull without making changes

bd gitlab push

Push one or more beads issues to GitLab.

Accepts bead IDs as positional arguments. Equivalent to: bd gitlab sync --push-only --issues <ids>

bd gitlab push [bead-ids...] [flags]

Flags:

      --dry-run   Preview push without making changes

bd gitlab status

Display current GitLab configuration and sync status.

bd gitlab status [flags]

bd gitlab sync

Synchronize issues between beads and GitLab.

By default, performs bidirectional sync:

  • Pulls new/updated issues from GitLab to beads
  • Pushes local beads issues to GitLab

Use --pull-only or --push-only to limit direction.

bd gitlab sync [flags]

Flags:

      --assignee string       Filter by assignee username
      --dry-run               Show what would be synced without making changes
      --exclude-type string   Exclude these issue types from sync (comma-separated)
      --issues string         Comma-separated bead IDs to sync selectively (e.g., bd-abc,bd-def). Mutually exclusive with --parent.
      --label string          Filter by labels (comma-separated, AND logic)
      --milestone string      Filter by milestone title
      --no-ephemeral          Exclude ephemeral/wisp issues from push (default: true) (default true)
      --parent string         Limit push to this bead and its descendants (push only). Mutually exclusive with --issues.
      --prefer-gitlab         On conflict, use GitLab version
      --prefer-local          On conflict, keep local beads version
      --prefer-newer          On conflict, use most recent version (default)
      --project string        Filter to issues from this project ID (group mode)
      --pull-only             Only pull issues from GitLab
      --push-only             Only push issues to GitLab
      --type string           Only sync these issue types (comma-separated, e.g. 'epic,feature,task')