Collaborator has a rich Git integration and you can use Collaborator to review files stored in Git in a variety of different ways. Our philosophy has always been that we adapt to your workflow, not the other way around. Some people like Gerrit’s more restricted workflow. It’s possible to configure Collaborator to integrate with Git in exactly the same way as Gerrit with a few scripts.
(Note: Collaborator Server and Client must be 8.2 or newer.)
Specifically with this setup:
- Commits must be reviewed before they can be pushed to the master branch (and/or other branches of your choice)
- Developers don’t need to install the Collaborator client - instead they push to a specially-named ref to create/update Reviews
- Once the review is complete the commit is automatically merged into the target branch (typically “master”)
Set Up the Server
0.5) Windows only: Create a Windows user account that will run the Collaborator server (by default it runs as “Local System,” but that won’t work for this setup). The user account must have a non-blank password set. Then open the Windows services console. Select the “ccollab-server” service, right-click and select “Properties.” Select the “Log On” tab specify “Log on as: This account:.” Supply the account name - typically if the account is named “ccollab-server” then you would enter “.\ccollab-server”. Supply the password (and again to confirm). Click “OK” to close the “ccollab-server Properties” dialog. Right-click on the “ccollab-server” service and select “Restart”.
1) Create a Collaborator service account to run the automation. Note this service account will not consume a Collaborator license, because it never logs in to the Web UI. Log in as an administrator in the web UI and go to “Admin” -> “Users”. In the “Create New User” section enter:
Log-in Username: git-trigger
Full Name: Git Trigger
Then click “Save”. The user “git-trigger” should appear in the “User List” section at the bottom of the screen.
Click the “[Edit]” link next to “git-trigger” to open up the user’s preferences.
Enter a password, and enter it again to confirm.
Change “Is Administrator” to “Yes”.
Click “Save”
2) Log in to the machine running the Collaborator server *as the same user account that is running the Collaborator server* and install the Collaborator client tool. You can download the client here.
When prompted by the installer, enter:
Server URL: http://localhost
Username: git-trigger
Password: <password you specified above>
3) Log in to the machine running the Collaborator server *as the same user account that is running the Collaborator server*. (Windows only: run “C:\Progra~1\Git\bin\sh.exe --login” to start up the Git bash shell). Run “git config --global user.email <git trigger email>” where <git trigger email> is a valid email account. This is the email that will appear on merge commits when Reviews are completed.
4) Install two server hooks in to your Git repository. The server hooks enforce that commits are reviewed before they get merged into the master branch (you can add more branches to enforce this if you wish - see the “update” hook), and also enable developers to upload commits to a Review using a Gerrit-style workflow. Simply copy the “update” and “post-update” files found in the "Collaborator Gerrit Style Scripts" zip file to /path/to/git/repo/hooks and run “chmod 755 /path/to/git/repo/hooks/update /path/to/git/repo/hooks/post-update” to make them executable.
5) Install a trigger in your Collaborator server. The trigger merges and then pushes changes to the target branch after Reviews complete. Copy the “reviewComplete.sh” file found in the same "Collaborator Gerrit Style Scripts" zip file somewhere convenient on disk.
Log in to the Collaborator web UI as an administrator and go to “Admin”->”Triggers”. In the “Review Phase Changed” section enter (replacing sample paths with real ones and being very careful with quotes and forward/backward slashes!):
| -- Windows Version --
Executable: “C:\Progra~1\Git\bin\sh.exe”
Parameters: “/path/to/reviewComplete.sh /path/to/git/repo ${review.id} ${review.phase}”
|
| -- Linux Version --
Executable: /bin/bash
Parameters: “/path/to/reviewComplete.sh” “/path/to/git/repo” ${review.id} “${review.phase}”
|
6) Rejoice! Setup is now complete.
How it Works From the Developer’s Perspective:
1) Create a commit with some changes.
2) Submit the commit to be reviewed by pushing to a specially-named ref “refs/for/<target branch>” on the remote repository, e.g:
git push origin HEAD:refs/for/master
If the commit doesn’t have a “Change-Id” associated with it you will be prompted to install Gerrit’s “commit-msg” hook that automatically adds a “Change-Id” to every commit. You can amend the existing commit to add the “Change-Id”.
A new Review will be created and the URL will be printed out in the “git push” output.
3) Open the URL in a web browser and assign participants, etc.. as necessary and then begin the Review. Perform the Review using Collaborator’s web UI.
4) (Optional) If you need to rework the changes in the Review, rebase/amend the commit as necessary and then push it to “refs/for/<target branch>” again as per step (2).
5) When the Review completes, the commit will be automatically merged into the target branch in the remote repository (it may take a minute or two).
6) (Optional) If there are any merge conflicts or other problems, the Review will be reopened with a comment in the Review Summary page Chat section explaining how to resolve the problem.
Again, we don’t advocate this workflow, but if you’re used to a Gerrit-style workflow and want to use it along with the metrics, reporting, and other features of Collaborator, you can achieve it.
Have you used a Gerrit-style workflow? How has it gone? Tell us in the comments!
See also: