GitLab Workflow

Operate on GitLab repositories using the glab CLI — merge requests, CI/CD pipelines, issues, and releases.

FIRST: Verify Environment

Run both checks before any glab command. If either fails, STOP.

git remote -v | grep -i gitlab glab auth status

If glab is not installed, ask the user to install it (brew install glab on macOS, sudo apt install glab on Debian/Ubuntu). If not authenticated, run glab auth login . For self-managed instances, use glab auth login --hostname gitlab.example.com .

Critical Rules

• Avoid interactive commands. glab ci view launches a TUI the agent cannot operate. Use glab ci status for pipeline state and glab ci view --web to open in browser. Always pass --fill --yes to glab mr create to skip interactive prompts.

• Check CI before requesting review. Run glab ci status after pushing. A broken pipeline wastes reviewer time and signals the MR isn't ready.

• Pull logs first on CI failure. Run glab ci trace <job-name> before anything else — 90% of failures are self-explanatory from the logs.

Behavioral Guidelines

• Use draft MRs for work in progress: create with --draft , mark ready with glab mr update <id> --ready

• Reference issues explicitly: Closes #123 for auto-close, Relates to #123 for tracking only

• Retry flaky failures, fix real ones: glab ci retry <job-name> once. If it fails again, it's a real issue — read the logs and fix the code.

Quick Reference: MR Commands

Task Command

Create MR (non-interactive) glab mr create --fill --yes -b main

Create draft MR glab mr create --fill --yes --draft -b main

List open MRs glab mr list

View MR details glab mr view 123

View MR comments glab mr view 123 --comments

View MR diff glab mr diff 123

Check out MR locally glab mr checkout 123

Mark draft as ready glab mr update 123 --ready

Add reviewers glab mr update 123 --reviewer user1,user2

Approve MR glab mr approve 123

Squash and merge glab mr merge 123 --squash

Merge without waiting for CI glab mr merge 123 --auto-merge=false

Add MR comment glab mr note 123 -m "message"

Quick Reference: CI Commands

Task Command

Check pipeline status glab ci status

Watch pipeline live glab ci status --live

Open pipeline in browser glab ci view --web

List recent pipelines glab ci list

Pull job logs glab ci trace <job-name>

Retry failed job glab ci retry <job-name>

Run new pipeline glab ci run

Run with variables glab ci run --variables "KEY:value"

Download artifacts glab job artifact <ref> <job-name>

Workflow: Branch to Merged MR

After branching, committing, and pushing:

glab mr create --fill --yes -b main # create MR glab ci status --live # watch pipeline

if CI fails:

glab ci trace <failed-job-name> # pull logs, fix, push glab ci status --live # verify fix

when CI passes and MR is approved:

glab mr merge --squash --remove-source-branch

CI Failure Remediation

• glab ci status — identify which pipeline failed

• glab ci trace <job-name> — pull the failed job's logs

• Read the logs from the bottom up — the final error is usually the root cause

• Reproduce locally if possible (run the same commands from .gitlab-ci.yml )

• Fix, commit, push

• glab ci status --live — watch the new pipeline

• If still failing, repeat from step 2

Common CI Log Signatures

Pattern Log Signature

Test failure FAIL , AssertionError , expected ... got

Build failure compilation failed , cannot find module

Timeout Job timed out , exceeded limit

Missing env/secret undefined , authentication failed

Dependency issue 404 Not Found , version not found

For operations not covered by glab subcommands, use glab api directly. For detailed command options, issue management, releases, search, and advanced CI debugging, see references/commands.md.

Use --fill --yes for MR creation and glab ci status instead of glab ci view — interactive TUI commands will hang.