Push options
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:
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. Only passes variables to branch pipelines and not merge request pipelines. | 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. 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>