Skip to content
Simply SF logoSimply SF logoSimply CLI

Merge requests

simply gitlab mr create

Section titled “simply gitlab mr create”

Open a merge request.

Flags

  • -p, --project <value> — Project id, or its full path such as group/subgroup/project. (required; env: GITLAB_PROJECT)
  • --dry-run — Print the request that would be sent and exit without sending it.
  • --source-branch <value> — Branch holding the changes.
  • --target-branch <value> — Branch the changes are proposed for.
  • --title <value> — Merge request title.
  • --description <value> — Merge request description, as Markdown.
  • --draft — Open it as a draft.
  • --squash — Squash the commits when it merges.
  • --remove-source-branch — Delete the source branch on merge.
  • --assignee-id <value> — User id to assign. Repeatable.
  • --reviewer-id <value> — User id to request review from. Repeatable.
  • --labels <value> — Comma-separated labels to apply.
  • --milestone-id <value> — Milestone id to attach.
  • --body <value> — Raw JSON request body.
  • --body-file <value> — Path to a file holding the raw JSON request body.

Connection

  • -e, --env-file <value> — Path to a .env file holding connection settings.
  • --gitlab-url <value> — Base URL of the GitLab instance. Defaults to https://gitlab.com. (env: GITLAB_URL)
  • --gitlab-token <value> — Personal, project, or group access token. (env: GITLAB_TOKEN)

Global

  • --json — the raw API payload, for scripts and agents.

Both branches must already exist on the project. —draft prefixes the title with “Draft: ”, which is how GitLab itself marks a draft; there is no separate field for it.

Assignees and reviewers are numeric user ids, not usernames — GitLab accepts only ids here. —body or —body-file supplies raw JSON for anything the flags do not cover, such as approval rules. Use —dry-run to see exactly what would be sent.

Examples

Terminal window
simply gitlab mr create --project group/project --source-branch feature --target-branch main --title "feat: the thing"
Terminal window
simply gitlab mr create --project group/project --source-branch feature --target-branch main --title wip --draft --squash

simply gitlab mr list

Section titled “simply gitlab mr list”

List merge requests for a project.

Flags

  • -p, --project <value> — Project id, or its full path such as group/subgroup/project. (required; env: GITLAB_PROJECT)
  • --limit <value> — Maximum number of merge requests to return across all pages. (default: 20)
  • --state <value> — Merge request state to return. (default: opened; one of: opened, closed, locked, merged, all)
  • --source-branch <value> — Only merge requests from this source branch.
  • --target-branch <value> — Only merge requests into this target branch.
  • --author-username <value> — Only merge requests opened by this username.
  • --reviewer-username <value> — Only merge requests this username is reviewing.
  • --labels <value> — Comma-separated labels every result must carry.
  • --search <value> — Match against the title and description.

Connection

  • -e, --env-file <value> — Path to a .env file holding connection settings.
  • --gitlab-url <value> — Base URL of the GitLab instance. Defaults to https://gitlab.com. (env: GITLAB_URL)
  • --gitlab-token <value> — Personal, project, or group access token. (env: GITLAB_TOKEN)

Global

  • --json — the raw API payload, for scripts and agents.

Defaults to open merge requests, which is what a list is nearly always for; pass —state all to include closed and merged ones. The IID column is the number to pass to the other mr commands — it is per-project, and is not the “id” field in the JSON payload.

Examples

Terminal window
simply gitlab mr list --project group/project
Terminal window
simply gitlab mr list --project group/project --state merged --target-branch main --limit 10
Terminal window
simply gitlab mr list --project group/project --author-username someone --json

simply gitlab mr update

Section titled “simply gitlab mr update”

Change an existing merge request.

Flags

  • -p, --project <value> — Project id, or its full path such as group/subgroup/project. (required; env: GITLAB_PROJECT)
  • --dry-run — Print the request that would be sent and exit without sending it.
  • --mr <value> — Merge request iid. (required)
  • --title <value> — New title.
  • --description <value> — New description, as Markdown.
  • --target-branch <value> — New target branch.
  • --state <value> — Close or reopen the merge request. (one of: close, reopen)
  • --squash — Squash the commits when it merges.
  • --remove-source-branch — Delete the source branch on merge.
  • --assignee-id <value> — User id to assign, replacing the set. Repeatable.
  • --reviewer-id <value> — User id to review, replacing the set. Repeatable.
  • --labels <value> — Comma-separated labels, replacing the existing set.
  • --milestone-id <value> — Milestone id to attach.
  • --body <value> — Raw JSON request body.
  • --body-file <value> — Path to a file holding the raw JSON request body.

Connection

  • -e, --env-file <value> — Path to a .env file holding connection settings.
  • --gitlab-url <value> — Base URL of the GitLab instance. Defaults to https://gitlab.com. (env: GITLAB_URL)
  • --gitlab-token <value> — Personal, project, or group access token. (env: GITLAB_TOKEN)

Global

  • --json — the raw API payload, for scripts and agents.

Only the attributes you name are changed, with one exception worth knowing: —labels replaces the whole label set rather than adding to it.

Naming nothing to change is refused rather than sent, because GitLab answers an empty update with a cheerful 200 and an unchanged merge request. —state close and —state reopen do what the buttons of those names do; neither merges anything.

Examples

Terminal window
simply gitlab mr update --project group/project --mr 42 --title "feat: renamed"
Terminal window
simply gitlab mr update --project group/project --mr 42 --state close
Terminal window
simply gitlab mr update --project group/project --mr 42 --labels backend,urgent --dry-run

simply gitlab mr view

Section titled “simply gitlab mr view”

Show one merge request.

Flags

  • -p, --project <value> — Project id, or its full path such as group/subgroup/project. (required; env: GITLAB_PROJECT)
  • --mr <value> — Merge request iid. (required)

Connection

  • -e, --env-file <value> — Path to a .env file holding connection settings.
  • --gitlab-url <value> — Base URL of the GitLab instance. Defaults to https://gitlab.com. (env: GITLAB_URL)
  • --gitlab-token <value> — Personal, project, or group access token. (env: GITLAB_TOKEN)

Global

  • --json — the raw API payload, for scripts and agents.

Takes the project-scoped iid — the number in the merge request URL — not the instance-wide id. Use —json for the full payload, which carries the pipeline status, approvals, and diff refs the summary below leaves out.

Examples

Terminal window
simply gitlab mr view --project group/project --mr 42
Terminal window
simply gitlab mr view --project group/project --mr 42 --json