> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pipefort.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GitLab CLI usage

> Scan GitLab projects and open Merge Requests from pipefort.

The `-g` / `--git` flag is URL-aware: GitLab URLs are detected automatically
and routed to the GitLab scanner. No new subcommand or mode is needed —
existing scripts that pass `https://gitlab.com/<group>/<project>` just work.

## Scan a GitLab project

```bash theme={null}
# gitlab.com — short URL form
pipefort -g https://gitlab.com/gitlab-org/cli

# Self-hosted instance — host is parsed from the URL
pipefort -g https://gitlab.acme.com/security/demo \
  --gitlab-token glpat-xxxxxxxxxxxxxxxxxxxxx
```

Both forms clone `--depth 1` into a temp directory, scan the entire CI tree
(`.gitlab-ci.yml` and `.gitlab-ci/**/*.yml`), and emit findings tagged with
the GitLab rule IDs (`cicd-sec-1-gl-mr-target`, `cicd-sec-7-gl-debug-trace`,
etc.). The portable structural rules (`best-prac-1-pipe-to-shell`,
`cicd-sec-9-download-without-checksum`) also fire — they share their ID
across both platforms.

## Token resolution

`--gitlab-token` mirrors `--github-token`:

1. The explicit `--gitlab-token` flag value.
2. The `$GITLAB_TOKEN` env var.
3. The output of `glab auth token` if `glab` is on `PATH` and authenticated.

The token needs the `api` scope to open Merge Requests; `read_api` is enough
for a read-only scan.

## --fix is local and platform-agnostic

`--fix` rewrites the YAML in place using the same conservative fixers the web
app applies — for GitLab that's currently three rules: debug-trace,
allow-failure, missing-timeout. Run it against a local clone:

```bash theme={null}
pipefort -p /path/to/project --fix
```

`--fix` doesn't need GitLab credentials because nothing leaves the local
filesystem. This is the recommended workflow for editor / pre-commit
integrations.

## --fix-mr opens Merge Requests

For workflow rules with a registered fixer, `--fix-mr` opens (or reuses) one
Merge Request per finding via the GitLab API:

```bash theme={null}
pipefort -g https://gitlab.com/<your-fork>/demo \
  --gitlab-token glpat-xxxxxxxxxxxxxxxxxxxxx \
  --fix-mr
```

Combine with `--dry-run` to print what would be opened without writing:

```bash theme={null}
pipefort -g https://gitlab.com/<your-fork>/demo \
  --gitlab-token glpat-xxxxxxxxxxxxxxxxxxxxx \
  --fix-mr --dry-run
```

Branch names are deterministic (`pipefort/fix/<rule-id>/<file-slug>`) so
re-running the command after a partial merge converges on the same MR rather
than spawning duplicates.

### Why a separate flag?

`--fix-mr` requires the `api` scope on your token, which is broader than the
read-only scope `--fix` (local) and the audit-only scope `--github-token`
need. We keep it behind its own flag so adding remote-write capability is
always explicit. The same convention applies to `--fix-settings` (GitHub
repo-settings remediation) and `--fix-settings-gl` (reserved for GitLab
project-settings remediation — currently a no-op pending the GitLab project
settings audit).

## What's GitHub-only in v1

| Capability                          | GitHub                         | GitLab                           |
| ----------------------------------- | ------------------------------ | -------------------------------- |
| Workflow YAML scan                  | ✓                              | ✓                                |
| Workflow YAML auto-fix (`--fix`)    | ✓                              | ✓ (3 rules)                      |
| Open PR / MR from CLI               | ✗ (`--fix-pr` not implemented) | ✓ (`--fix-mr`)                   |
| Repository / project settings audit | ✓                              | ✗ (roadmap)                      |
| Settings auto-fix                   | ✓ (`--fix-settings`)           | ✗ (`--fix-settings-gl` reserved) |