Integration With Repository Hosting Services

After you configured integration settings, Collaborator tracks changes in one or several branches of your repository (you specify the branches to track and to ignore when configuring integration settings in Collaborator).

Collaborator automatically creates reviews in the following cases:

• When it detects a pull request to the tracked branch (in some systems, pull requests are called merge requests).

• When it detects push events (commits, not pull requests) to the tracked branch.

Collaborator uploads the copies of changed files to the review and assigns the review to the respective user. On the repository side, it registers the review as a CI test for the pull request (in GitHub terms, these are called status checks, in GitLab — pipelines, in Bitbucket and Bitbucket Server — builds). So, you can see the status of the created review in the pull request details:

See examples

See examplesSee examples

• GitHub
• GitLab
• Bitbucket
• Bitbucket Server
• Azure DevOps

Click the image to enlarge it.

Click the image to enlarge it.

Click the image to enlarge it.

Click the image to enlarge it.

Click the image to enlarge it.

For protected branches, you have to complete Collaborator reviews before closing the pull request.

Collaborator also automatically creates reviews for changes in submodules (or subrepositories). See below.

The new review includes changes made to the remote repository. Namely —

• When creating a new review, Collaborator automatically uploads copies of the pull request’s or commit’s files to the review. That is, the review contains the modified files, not the file links or commit IDs. You can see these files in the Review Materials section of the review.

• The Remote System Links section contains the links to pull requests or commits, as well as their current statuses.

• The Pull Request Merge Info section allows to check and change what action will be performed with pull request when current review will be accomplished.

• The Chat section would display a link to the remote repository, names of pull request branches, pull request description (if provided) and comments that users made to pull request/commit on the remote repository side.

Click the image to enlarge it.

The initial phase of the newly created review will be Planning, so authors could check the review, add notes or upload additional materials before notifying other participants. Alternatively, Collaborator administrators can enable the Move pull request reviews to Inspection setting to start reviews automatically. In this case Collaborator will verify if the review meets the workflow requirements (for example, has minimal number of participants) and will move it to the Inspection phase on success.

When Collaborator gets a notification about changes in a repository, it also retrieves information about the source-control user, who made these changes. So, it attempts to find a corresponding user in Collaborator to assign the new review to that user. In order for the search to be successful, you and your teammates need to link their Collaborator and source-control accounts in Collaborator settings. See Link User Accounts for details.

• For direct commits, Collaborator retrieves the commit author from the source-control and assigns the matching Collaborator user as a review author and creator.

• For pull/merge requests Collaborator tries to obtain information about its author from the source-control and assigns the matching Collaborator user as a review author and creator. Some repository hosting services do not provide e-mail addresses of pull request authors, even when source-control users made them public. Thus Collaborator could fail to find a user matching to pull request author. In this case Collaborator retrieves the author of pull request’s last commit and assigns the matching Collaborator user as a review author and creator.

If Collaborator does not find any matching user, it assigns the Collaborator administrator as a review author and creator.

Additionally, Collaborator can assign reviewers in the following cases:

• GitHub, GitLab: If repository contains a CODEOWNERS file that defines users responsible for certain files in a repository and integration can match those GitHub/GitLab users with Collaborator users,
• GitHub: If some team was added as reviewer when creating pull request on the GitHub side, or some team was specified in CODEOWNERS file and integration can match members of that team with Collaborator users, and the Auto assign reviewers option is on.
• Bitbucket, Bitbucket Server: If some specific users were added as reviewers when creating pull request on the Bitbucket side and integration can match those Bitbucket users with Collaborator users.
• Github, Gitlab, Bitbucket, Bitbucket Server, Azure DevOps: If some specific users were added as reviewers when creating pull request on the remote system side and integration can match those remote system users with Collaborator users, and the Auto assign reviewers option is on.

• If a review was created for a pull request

  If your teammates make more changes to the branch after a review was created, and if the pull request is not closed, Collaborator uploads new file versions to the created review. This works until the pull request is closed. If the review remains open after the pull request is closed, then Collaborator will not upload files from subsequent commits to the review.

• If a review was created for a commit (push event)

  Collaborator will not upload new file versions to the review automatically.

By default the integration does not allow to complete a review when the respective pull request has some conflicts. This behavior is controlled by the Allow to complete review with conflicts in pull request setting.

If a file conflict can be resolved automatically, Collaborator will not add any new file copies to the review. If a file conflict needs to be resolved manually (that is, if some files are to be changed to complete the merge request), then Collaborator will update the review with newer file versions.

... file changes made by merge commits will only be displayed in Separate view of the Review Materials section of the review. They will not be displayed in Overlay view. Besides, file changes made by merge commits are not taken into account when calculating overall LOC metrics and they do not affect the overall rework count of a file.

... Collaborator will process the outdated commits and will reorder the list of file revisions to keep it up-to-date.

• If some file revisions have been removed, the comments or defects addressing that file revision will be promoted to resulting revision and will display a special icon indicating that the comment/defect could be outdated.
  
  
• If some files have been removed, they will also be removed from the review materials. For audit purposes, comments and defects for removed files will be copied to the review's general chat.
  
  

... Collaborator can automatically merge, squash or rebase changes. This behavior is controlled by the When review completed option and by the current merge strategy selected in the Pull Request Merge Info section:

Click the image to enlarge it.

If integration fails to automatically merge pull request, it notifies the authors of the respective review, so they can resolve the issue manually.

... the review can be reopened. The Reopen a review when option allows selecting what events should reopen the review.

... Collaborator can automatically close the corresponding pull request. Additionally, it can automatically delete the corresponding branch. This behavior is controlled by the When Review Cancelled/Deleted/Rejected option that you set when integrating Collaborator with your repository.

... Collaborator posts a comment and closes the corresponding review. Reviews in planning phase will be deleted, while in progress reviews will be cancelled.

For review with multiple linked pull requests all of them should be closed or deleted.

It is quite possible, that the pull request, for which a review was created, is reopened after that review was completed. In this case, Collaborator will reopen the review.

If review was canceled, deleted or rejected and if the pull request is reopened, Collaborator creates a new review.