Push Options (FREE)

GitLab supports using client-side Git push options to perform various actions at the same time as pushing changes. Additionally, Push Rules offer server-side control and enforcement options.

Currently, there are push options available for:

Skipping CI jobs
Merge requests

NOTE: Git push options are only available with Git 2.10 or newer.

For Git versions 2.10 to 2.17 use --push-option:

git push --push-option=<push_option>

For version 2.18 and later, you can use the above format, or the shorter -o:

git push -o <push_option>

Push options for GitLab CI/CD

You can use push options to skip a CI/CD pipeline, or pass CI/CD variables.

Push option	Description	Introduced in version
`ci.skip`	Do not create a CI pipeline for the latest push. Only skips branch pipelines and not merge request pipelines.	11.7
`ci.variable="<name>=<value>"`	Provide CI/CD variables to be used in a CI pipeline, if one is created due to the push.	12.6

An example of using ci.skip:

git push -o ci.skip

An example of passing some CI/CD variables for a pipeline:

git push -o ci.variable="MAX_RETRIES=10" -o ci.variable="MAX_TIME=600"

Push options for merge requests

You can use Git push options to perform certain actions for merge requests at the same time as pushing changes:

Push option	Description	Introduced in version
`merge_request.create`	Create a new merge request for the pushed branch.	11.10
`merge_request.target=<branch_name>`	Set the target of the merge request to a particular branch or upstream project, such as: `git push -o merge_request.target=project_path/branch`	11.10
`merge_request.merge_when_pipeline_succeeds`	Set the merge request to merge when its pipeline succeeds.	11.10
`merge_request.remove_source_branch`	Set the merge request to remove the source branch when it's merged.	12.2
`merge_request.title="<title>"`	Set the title of the merge request. Ex: `git push -o merge_request.title="The title I want"`.	12.2
`merge_request.description="<description>"`	Set the description of the merge request. Ex: `git push -o merge_request.description="The description I want"`.	12.2
`merge_request.milestone="<milestone>"`	Set the milestone of the merge request. Ex: `git push -o merge_request.milestone="3.0"`.	14.1
`merge_request.label="<label>"`	Add labels to the merge request. If the label does not exist, it is created. For example, for two labels: `git push -o merge_request.label="label1" -o merge_request.label="label2"`.	12.3
`merge_request.unlabel="<label>"`	Remove labels from the merge request. For example, for two labels: `git push -o merge_request.unlabel="label1" -o merge_request.unlabel="label2"`.	12.3
`merge_request.assign="<user>"`	Assign users to the merge request. Accepts username or user ID. For example, for two users: `git push -o merge_request.assign="user1" -o merge_request.assign="user2"`.	13.10
`merge_request.unassign="<user>"`	Remove assigned users from the merge request. Accepts username or user ID.For example, for two users: `git push -o merge_request.unassign="user1" -o merge_request.unassign="user2"`.	13.10

If you use a push option that requires text with spaces in it, you need to enclose it in quotes ("). You can omit the quotes if there are no spaces. Some examples:

git push -o merge_request.label="Label with spaces"
git push -o merge_request.label=Label-with-no-spaces

You can combine push options to accomplish multiple tasks at once, by using multiple -o (or --push-option) flags. For example, if you want to create a new merge request, and target a branch named my-target-branch:

git push -o merge_request.create -o merge_request.target=my-target-branch

Additionally if you want the merge request to merge as soon as the pipeline succeeds you can do:

git push -o merge_request.create -o merge_request.target=my-target-branch -o merge_request.merge_when_pipeline_succeeds

Useful Git aliases

As shown above, Git push options can cause Git commands to grow very long. If you use the same push options frequently, it's useful to create Git aliases. Git aliases are command line shortcuts for Git which can significantly simplify the use of long Git commands.

Merge when pipeline succeeds alias

To set up a Git alias for the merge when pipeline succeeds Git push option:

git config --global alias.mwps "push -o merge_request.create -o merge_request.target=master -o merge_request.merge_when_pipeline_succeeds"

Then to quickly push a local branch that targets the default branch and merges when the pipeline succeeds:

git mwps origin <local-branch-name>

Troubleshooting

Push options for merge request assignment ignored

When you push a branch to GitLab, you can use push options to assign to (merge_request.assign="<USERNAME>") or unassign from (merge_request.unassign="<USERNAME>") a user. If GitLab creates the merge request successfully, but fails to assign or unassign the merge request correctly, you can use the user ID instead. For more information, read the issue Push option merge_request.(un)assign seems to be ignored.