Push options (FREE ALL)

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. This does not skip pipelines for CI integrations, such as Jenkins.	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. Only passes variables to branch pipelines and not merge request pipelines.	12.6
`integrations.skip_ci`	Skip push events for CI integrations, such as Atlassian Bamboo, Buildkite, Drone, Jenkins, and JetBrains TeamCity.	16.2

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"

An example of using integrations.skip_ci:

git push -o integrations.skip_ci

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. For example: `git push -o merge_request.title="The title I want"`.	12.2
`merge_request.description="<description>"`	Set the description of the merge request. For example: `git push -o merge_request.description="The description I want"`.	12.2
`merge_request.draft`	Mark the merge request as a draft. For example: `git push -o merge_request.draft`.	15.0
`merge_request.milestone="<milestone>"`	Set the milestone of the merge request. For example: `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, support for usernames added in 15.5
`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, support for usernames added in 15.5

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>