Title here
Summary here
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:
| Field | Inherited value |
|---|---|
| The working branch the scm created and pushed - the branch carrying the changes. |
| The scm’s |
| 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:
spec.titleon the actiontitleon the action itself, one level abovespecthe name of the associated target, when there is exactly one
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
| Name | Type | Description | Required |
|---|---|---|---|
| allowcollaboration | boolean | allowcollaboration indicates whether to allow commits from members who can merge to the target branch default: false remark: when set to true, members with write access to the repository can push commits to the source branch of the merge request | |
| assignees | array | “assignees” contains the list of assignee to add to the merge request default: empty remark: assignees only accept GitLab User IDs. To find the user ID:
| |
| automerge | boolean | automerge allows to enable/disable the automerge feature on new merge request default: false remark: when set to true, the merge request will be automatically merged when all conditions are met (pipeline succeeds, approvals are given, etc.) | |
| body | string | “body” defines a custom mergerequest body default: By default a mergerequest body is generated out of a pipeline execution. remark: Unless you know what you are doing, you shouldn’t set this value and rely on the sane default. “body” is useful to provide additional information when reviewing mergerequest, such as changelog url. | |
| labels | array | “labels” defines labels for the merge request. default: empty remark: if a label does not already exist, this creates a new project label and assigns it to the merge request | |
| mergecommitmessage | string | mergecommitmessage defines the commit message used when the merge request is merged default: empty remark: if empty, GitLab will use the default message format defined in the project settings | |
| owner | string | “owner” defines the GitLab repository owner. remark: unless you know what you are doing, you shouldn’t set this value and rely on the scmid to provide the sane default. | |
| removesourcebranch | boolean | “removesourcebranch” is a flag indicating if a merge request should remove the source branch when merging default: false | |
| repository | string | “repository” defines the GitLab repository for a specific owner remark: unless you know what you are doing, you shouldn’t set this value and rely on the scmid to provide the sane default. | |
| reviewers | array | “reviewers” contains the list of reviewers to add to the merge request default: empty remark: assignees only accept GitLab User IDs. To find the user ID:
| |
| sourcebranch | string | “sourcebranch” defines the branch name used as a source to create the GitLab mergerequest. default: “sourcebranch” inherits the value from the scm branch if a scm of kind “gitlab” is specified by the action. remark: unless you know what you are doing, you shouldn’t set this value and rely on the scmid to provide the sane default. | |
| squash | boolean | “squash” defines if all commits should be squashed into a single commit on merge default: false remark: project settings might override this value | |
| squashcommitmessage | string | squashcommitmessage defines the commit message used when the merge request is squashed and merged default: empty remark: if empty, GitLab will use the default message format defined in the project settings | |
| targetbranch | string | “targetbranch” defines the branch name used as a target to create the GitLab mergerequest. default: “targetbranch” inherits the value from the scm working branch if a scm of kind “gitlab” is specified by the action. remark: unless you know what you are doing, you shouldn’t set this value and rely on the scmid to provide the sane default. the GitLab scm will create and use a working branch such as updatecli_xxxx | |
| title | string | “title” defines the GitLab mergerequest title default: A GitLab mergerequest title is defined by one of the following location (first match) 1. title is defined by the spec such as: actions: default: kind: gitlab/mergerequest scmid: default spec: title: This is my awesome title
actions: default: kind: gitlab/mergerequest scmid default title: This is my awesome title
remark: usually we prefer to go with option 2 | |
| token | string | “token” defines the credential used to authenticate with GitLab remark: A token is a sensitive information, it’s recommended to not set this value directly in the configuration file but to use an environment variable or a SOPS file. The value can be set to For more information, about a SOPS file, please refer to the following documentation: https://github.com/getsops/sops | |
| url | string | “url” defines the GitLab url to interact with default: “gitlab.com” | |
| username | string | “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:
- 7654321Labels
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:
squashSquashes the commits of the source branch into one on merge.
removesourcebranchDeletes the working branch once merged.
mergecommitmessage,squashcommitmessageOverride the commit messages GitLab generates. Left empty, the project’s message templates apply.
allowcollaborationLets 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