diff options
Diffstat (limited to 'doc/user/project/push_options.md')
-rw-r--r-- | doc/user/project/push_options.md | 77 |
1 files changed, 77 insertions, 0 deletions
diff --git a/doc/user/project/push_options.md b/doc/user/project/push_options.md new file mode 100644 index 00000000000..51c46dbd1d4 --- /dev/null +++ b/doc/user/project/push_options.md @@ -0,0 +1,77 @@ +--- +type: reference +--- + +# Push Options + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/15643) in GitLab 11.7. + +GitLab supports using [Git push options](https://git-scm.com/docs/git-push#Documentation/git-push.txt--oltoptiongt) +to perform various actions at the same time as pushing changes. + +Currently, there are push options available for: + +- [Skipping CI jobs](#push-options-for-gitlab-cicd) +- [Merge requests](#push-options-for-merge-requests) + +NOTE: **Note:** +Git push options are only available with Git 2.10 or newer. + +For Git versions 2.10 to 2.17 use `--push-option`: + +```shell +git push --push-option=<push_option> +``` + +For version 2.18 and later, you can use the above format, or the shorter `-o`: + +```shell +git push -o <push_option> +``` + +## Push options for GitLab CI/CD + +If the `ci.skip` push option is used, the commit will be pushed, but no [CI pipeline](../../ci/pipelines.md) +will be created. + +| Push option | Description | +| ----------- | ----------- | +| `ci.skip` | Do not create a CI pipeline for the latest push. | + +For example: + +```shell +git push -o ci.skip +``` + +## 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](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/26752) | +| `merge_request.target=<branch_name>` | Set the target of the merge request to a particular branch. | [11.10](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/26752) | +| `merge_request.merge_when_pipeline_succeeds` | Set the merge request to [merge when its pipeline succeeds](merge_requests/merge_when_pipeline_succeeds.md). | [11.10](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/26752) | +| `merge_request.remove_source_branch` | Set the merge request to remove the source branch when it's merged. | [12.2](https://gitlab.com/gitlab-org/gitlab-foss/issues/64320) | +| `merge_request.title="<title>"` | Set the title of the merge request. Ex: `git push -o merge_request.title="The title I want"`. | [12.2](https://gitlab.com/gitlab-org/gitlab-foss/issues/64320) | +| `merge_request.description="<description>"` | Set the description of the merge request. Ex: `git push -o merge_request.description="The description I want"`. | [12.2](https://gitlab.com/gitlab-org/gitlab-foss/issues/64320) | +| `merge_request.label="<label>"` | Add labels to the merge request. If the label does not exist, it will be created. For example, for two labels: `git push -o merge_request.label="label1" -o merge_request.label="label2"`. | [12.3](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/31831) | +| `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](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/31831) | + +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: + +```shell +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`: + +```shell +git push -o merge_request.create -o merge_request.target=my-target-branch +``` |