diff options
Diffstat (limited to 'doc/user/project/merge_requests/allow_collaboration.md')
| -rw-r--r-- | doc/user/project/merge_requests/allow_collaboration.md | 113 |
1 files changed, 62 insertions, 51 deletions
diff --git a/doc/user/project/merge_requests/allow_collaboration.md b/doc/user/project/merge_requests/allow_collaboration.md index 5d1a04e1fe0..b10d6597c1e 100644 --- a/doc/user/project/merge_requests/allow_collaboration.md +++ b/doc/user/project/merge_requests/allow_collaboration.md @@ -2,77 +2,99 @@ stage: Create group: Code Review info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -type: reference, howto --- -# Allow collaboration on merge requests across forks **(FREE)** +# Collaborate on merge requests across forks **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17395) in GitLab 10.6. +When you open a merge request from your fork, you can allow upstream +members to collaborate with you on your branch. +When you enable this option, members who have permission to merge to the target branch get +permission to write to the merge request's source branch. -When a user opens a merge request from a fork, they are given the option to allow -upstream members to collaborate with them on the source branch. This allows -the members of the upstream project to make small fixes or rebase branches -before merging, reducing the back and forth of accepting external contributions. +The members of the upstream project can then make small fixes or rebase branches +before merging. This feature is available for merge requests across forked projects that are publicly accessible. -When enabled for a merge request, members with merge access to the target -branch of the project is granted write permissions to the source branch -of the merge request. +## Allow commits from upstream members -## Enabling commit edits from upstream members +> Enabled by default in [GitLab 13.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/23308). -In [GitLab 13.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/23308), -this setting is enabled by default. It can be changed by users with the -Developer [role](../../permissions.md) for the source project. After it's enabled, -upstream members can retry the pipelines and jobs of the merge request: +As the author of a merge request, you can allow commit edits from +upstream members of the project you're contributing to: 1. While creating or editing a merge request, scroll to **Contribution** and - then select the **Allow commits from members who can merge to the target branch**. + select the **Allow commits from members who can merge to the target branch** checkbox. 1. Finish creating your merge request. -After you create the merge request, the merge request widget displays a message: -**Members who can merge are allowed to add commits.** +After you create the merge request, the merge request widget displays the message +**Members who can merge are allowed to add commits**. Upstream members can then +commit directly to your branch, as well as retry the pipelines and jobs of the +merge request. -## Pushing to the fork as the upstream member +## Prevent commits from upstream members -If the creator of the merge request has enabled contributions from upstream -members, you can push directly to the branch of the forked repository. +As the author of a merge request, you can prevent commit edits from +upstream members of the project you're contributing to: -Assuming that: +1. While creating or editing a merge request, scroll to **Contribution** and + clear the **Allow commits from members who can merge to the target branch** + checkbox. +1. Finish creating your merge request. + +## Push to the fork as the upstream member -- The forked project URL is `git@gitlab.com:thedude/awesome-project.git`. -- The branch of the merge request is `update-docs`. +You can push directly to the branch of the forked repository if: -To find and work with the changes from the fork: +- The author of the merge request has enabled contributions from upstream + members. +- You have at least the [Developer role](../../permissions.md) in the + upstream project. + +In the following example: + +- The forked repository URL is `git@gitlab.com:contributor/forked-project.git`. +- The branch of the merge request is `fork-branch`. + +To change or add a commit to the contributor's merge request: 1. Open the merge request page, and select the **Overview** tab. -1. Scroll to the merge request widget, and select **Check out branch**: -  -1. In the modal window, select **{copy-to-clipboard}** (**Copy**) for step 1 - to copy the `git fetch` and `git checkout` instructions to your clipboard. - Paste the commands (which look like this example) into your terminal: +1. Scroll to the merge request widget, and select **Check out branch**. +1. In the modal window, select **Copy** (**{copy-to-clipboard}**). +1. In your terminal, navigate to your cloned version of the repository, and + paste the commands. For example: ```shell - git fetch git@gitlab.com:thedude/awesome-project.git update-docs - git checkout -b thedude-awesome-project-update-docs FETCH_HEAD + git fetch "git@gitlab.com:contributor/forked-project.git" 'fork-branch' + git checkout -b contributor/fork-branch' FETCH_HEAD ``` - These commands fetch the branch from the forked project, and create a local branch - based off the fetched branch. + Those commands fetch the branch from the forked project, and create a local branch + for you to work on. + +1. Make your changes to your local copy of the branch, and then commit them. +1. Push your local changes to the forked project. The following command pushes + the local branch `contributor/fork-branch` to the `fork-branch` branch of + the `git@gitlab.com:contributor/forked-project.git` repository: -1. Make your changes to the local copy of the branch, and then commit them. -1. In your terminal, push your local changes back up to the forked project. This - command pushes the local branch `thedude-awesome-project-update-docs` to the - `update-docs` branch of the `git@gitlab.com:thedude/awesome-project.git` repository: + ```shell + git push git@gitlab.com:contributor/forked-project.git contributor/fork-branch:fork-branch + ``` + + If you have amended or squashed any commits, you must force push. Proceed + with caution as this command rewrites the commit history: ```shell - git push git@gitlab.com:thedude/awesome-project.git thedude-awesome-project-update-docs:update-docs + git push --force git@gitlab.com:contributor/forked-project.git contributor/fork-branch:fork-branch ``` - Note the colon (`:`) between the two branches. + Note the colon (`:`) between the two branches. The general scheme is: + + ```shell + git push <forked_repository_git_url> <local_branch>:<fork_branch> + ``` ## Troubleshooting @@ -89,14 +111,3 @@ going back to the original project: 1. Create a group containing all the upstream members. 1. Go to the **Project information > Members** page in the forked project and invite the newly-created group to the forked project. - -<!-- ## Troubleshooting -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. - -Each scenario can be a third-level heading, e.g. `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> |