Updatecli
Docs

Gitlab Merge Request

Description

The gitlab/mergerequest action opens (or updates) a GitLab merge request once a target linked to the same scm has changed something and the change has been pushed.

It is the second half of the GitLab workflow: the gitlab scm commits to a working branch and pushes it, this action turns that branch into a merge request. Without it, the branch is pushed and nothing else happens.

The scm may be either gitlab or gitlabsearch; with the latter, one merge request is opened per discovered project.

Requirements

An action never runs on its own: it needs an scmid pointing at an scm declared in the same manifest, and that scm must be of the matching kind. Both are checked when the manifest loads:

missing value for parameter(s) ["scmid"]
scm of kind "git" is not compatible with action of kind "github/pullrequest"

The action then reuses that scm rather than being configured twice. From it, it inherits:

FieldInherited value

sourcebranch

The working branch the scm created and pushed - the branch carrying the changes.

targetbranch

The scm’s branch - the branch the pull request is opened against.

owner, repository

The repository the scm points at.

credentials, URL

Whatever the scm was given, when the action does not set its own.

Every one of these can be overridden in the action spec, but there is rarely a good reason to: a mismatch between the branch the scm pushed and the branch the action opens the request from produces a request with no changes in it.

Where the title comes from

The title is resolved from the first of these that is set:

  1. spec.title on the action

  2. title on the action itself, one level above spec

  3. the name of the associated target, when there is exactly one

  4. the pipeline name

The second form is the usual one:

actions:
  default:
    kind: <the action kind>
    scmid: default
    title: 'deps: bump axios version'

Create or update

Updatecli looks for a request already open between the same two branches before creating one, so running the same pipeline repeatedly gives you one long-lived request per pipeline and repository rather than one per run. Whether that existing request is then refreshed with the latest title and description differs by plugin (each page says which).

Creation is also skipped, without failing the pipeline, when either branch is missing from the remote. Updatecli attempts it on every run regardless, so that a request closed by hand or lost to an earlier failure gets reopened on the next one.

Pipeline URL

When Updatecli detects that it runs inside a CI job, it appends a link to that job in the request description. Set disablepipelineurl: true on the action (next to kind and scmid, not inside spec) to leave it out.

Detection is limited to three engines, each recognised by one environment variable: Jenkins (JENKINS_URL), GitLab CI (GITLAB_CI), and GitHub Actions (GITHUB_ACTION), checked in that order. Anywhere else no link is added, whatever this setting says.

Parameters

NameTypeDescriptionRequired
allowcollaborationboolean

“allowcollaboration” defines if members who can merge to the target branch may push commits to the source branch.

default: false

remark:

  • when true, members with write access to the repository can push commits to the source branch of the merge request.
assigneesarray

“assignees” defines the list of assignees to add to the merge request.

default: empty

remark:

  • only GitLab user IDs are accepted. To find a user ID:
    1. open the user’s profile page.
    2. in the upper right corner, select Actions (or ⋮).
    3. select Copy user ID.

example:

  • assignees: [123456]
automergeboolean

“automerge” defines if the auto merge feature is enabled on a new merge request.

default: false

remark:

  • when true, the merge request is merged automatically once all conditions are met, such as a successful pipeline and the required approvals.
bodystring

“body” defines a custom merge request body.

default: a body generated from the pipeline execution.

remark:

  • the generated body is usually the right choice.
  • “body” is useful to add information for reviewers, such as a changelog url.
labelsarray

“labels” defines the labels of the merge request.

default: empty

remark:

  • a label that does not exist yet is created as a project label and assigned to the merge request.
mergecommitmessagestring

“mergecommitmessage” defines the commit message used when the merge request is merged.

default: empty

remark:

  • when empty, GitLab uses the default message format defined in the project settings.
ownerstring

“owner” defines the owner of the GitLab repository.

default: the owner of the associated scm of kind “gitlab”.

remark:

  • set it only when the default inherited from the scm does not fit.
removesourcebranchboolean

“removesourcebranch” defines if the source branch is removed when the merge request is merged.

default: false

repositorystring

“repository” defines the name of the GitLab repository, for a specific owner.

default: the repository of the associated scm of kind “gitlab”.

remark:

  • set it only when the default inherited from the scm does not fit.
reviewersarray

“reviewers” defines the list of reviewers to add to the merge request.

default: empty

remark:

  • only GitLab user IDs are accepted. To find a user ID:
    1. open the user’s profile page.
    2. in the upper right corner, select Actions (or ⋮).
    3. select Copy user ID.

example:

  • reviewers: [123456]
sourcebranchstring

“sourcebranch” defines the branch the merge request takes its changes from.

default: the working branch of the associated scm of kind “gitlab”.

remark:

  • set it only when the default inherited from the scm does not fit.
squashboolean

“squash” defines if all commits are squashed into a single commit on merge.

default: false

remark:

  • project settings might override this value.
squashcommitmessagestring

“squashcommitmessage” defines the commit message used when the merge request is squashed and merged.

default: empty

remark:

  • when empty, GitLab uses the default message format defined in the project settings.
targetbranchstring

“targetbranch” defines the branch the merge request is merged into.

default: the branch of the associated scm of kind “gitlab”.

remark:

  • set it only when the default inherited from the scm does not fit.
  • the GitLab scm creates and uses a working branch such as updatecli_xxxx as the source branch.
titlestring

“title” defines the title of the GitLab merge request.

default: the title is taken from the first match of:

  1. “title” set in the action spec.
  2. “title” set in the action.
  3. the title of the first associated target.
  4. the pipeline title.

remark:

  • setting “title” in the action is usually preferred.

example:

actions:
  default:
    kind: gitlab/mergerequest
    scmid: default
    title: This is my title
tokenstring

“token” defines the credential used to authenticate with GitLab.

remark:

  • a token is sensitive information. Do not set it directly in the manifest, use an environment variable or a SOPS file instead.
  • {{ requiredEnv "GITLAB_TOKEN" }} retrieves the token from the environment variable GITLAB_TOKEN.
  • {{ .gitlab.token }} retrieves the token from a SOPS file.
  • for more information about SOPS files, see https://github.com/getsops/sops

example:

  • token: ‘{{ requiredEnv “GITLAB_TOKEN” }}’
urlstring

“url” defines the GitLab url to interact with.

default: gitlab.com

remark:

  • “https://” is added when the url has no “http://” or “https://” scheme.

example:

  • url: gitlab.com
  • url: https://gitlab.example.com
usernamestring“username” defines the username used to authenticate with GitLab.

Assignees and reviewers

assignees and reviewers take numeric GitLab user IDs, not usernames - a list of integers. To find one, open the user’s profile page, then Actions (or ⋮) in the upper-right corner, and Copy user ID.

spec:
  assignees:
    - 1234567
  reviewers:
    - 7654321

Labels

labels are applied to the merge request, and GitLab creates any label that does not exist yet as a new project label. This is the opposite of the GitHub plugin, where a missing label is an error.

Merge behavior

automerge: true turns on GitLab’s auto-merge, so the merge request merges by itself once its conditions are met - pipeline succeeded, required approvals given. It is a single boolean: there is no equivalent of the GitHub plugin’s merge.strategy, and Updatecli never merges client-side here.

The following options shape what merging produces, and the project’s own settings may override them:

squash

Squashes the commits of the source branch into one on merge.

removesourcebranch

Deletes the working branch once merged.

mergecommitmessage, squashcommitmessage

Override the commit messages GitLab generates. Left empty, the project’s message templates apply.

allowcollaboration

Lets members who can merge the target branch push to the merge request’s source branch.

Cleanup

Cleanup is not implemented for this plugin. updatecli apply --clean-git-branches removes working branches that ended up with no changes, but a merge request already opened for one of them is not closed automatically (that stays a manual step).

The same goes for the options this plugin does not expose. If closing stale merge requests, or anything else missing here, is something you would use, say so on the Updatecli issue tracker (these gaps are unimplemented rather than deliberate, and interest is what gets them prioritised).

Example

# updatecli.yaml
# updatecli diff --config updatecli.yaml
#
name: Show Gitlab pipeline example

# Sources are responsible to fetch information from third location such as npm registry.
sources:
  updatecli:
    name: Get latest axios version
    kind: npm
    spec:
      name: axios

# Targets are responsible to update targeted files such as a yaml file.
targets:
  npm:
    name: Update e2e test file
    kind: yaml
    sourceid: updatecli
    scmid: gitlab
    spec:
      file: e2e/updatecli.d/success.d/npm.yaml
      key: conditions.axios.spec.version

### 

# Actions such as gitlab/mergerequest is triggered if a target is updated.
actions:
  default:
    title: Bump axios version
    kind: gitlab/mergerequest
    scmid: gitlab

scms:
  gitlab:
    kind: gitlab
    spec:
      owner: "olblak"
      repository: "updatecli"
      branch: main
      # For the change to be apply, we need to specify gitlab credentials
      #username: gitlab_username
      #token: gitlab_token

Links

Last updated on August 2, 2026
Prev
Bitbucket Cloud Pull Request
Next
Stash Pull Request