Creating Gerrit Projects/Repositories
Creating new repositories in Gerrit is an operation which requires a number of manual steps, both to match existing project configuration, and because there is no tooling around some of the configuration.
Prerequisites
- Admin access to the Gerrit web UI
- SSH access to gerrit.ovirt.org:22, yielding a shell, and sudo access on that host
- Be an owner of the oVirt Project on github to create repos to sync to
Creating a Group in Gerrit
Group creation can be found in the Gerrit web UI under People
.
The convention used by oVirt is for every project in Gerrit to have a matching
project owner group which includes the project + -maintainers
name,
comprised of the users who will have permissions to that project.
For example, a foobar
project should have a foobar-maintainers
group.
It's easy to add or remove members to a group either
from a specific project => Access
=>
clicking on <project>-maintainers
group => members
or
from People
=> <project>-mintainers
group => members
Creating a Project in Gerrit
Once the group is created, proceed to creating the project. This is found
in the Gerrit web UI under Projects
=> Create New Project
.
Create the project with your desired name and inherit project rights from All-Projects.
- Project Name: 'your desired project name'
- Rights Inherit From:
All-Projects
If this is initial development, with no git history which will be pulled in from Github or elsewhere, check the "Create initial empty commit" checkbox.
Drill into the project settings (under Projects/General
, or searching),
and make sure the settings match the following:
- Submit Type: Rebase if Necessary
- Require
Signed-off-by
in commit message: True
Other settings can be changed if necessary, but default to (ignoring INHERIT):
- State: Active
- Automatically resolve conflicts: FALSE
- Require
Change-Id
in commit message: TRUE
Setting permissions to a project in Gerrit
Basically all the default permissions are inherited from All-Projects
group.
It's set during the project creation.
The default permissions include the following rights:
Right(s) | Group(s) |
---|---|
View (Read) projects and patches | Anonymous and Registered Users |
Add new patch | Registered Users |
Forge Author Identity | Registered Users |
Forge Committer Identity | Project Owners |
Add Code Review +2 label | Project Owners |
Add Code Review +1 label | Registered Users |
Add Continuous Integration +1 label | Project Owners |
Add Verified +1 label | Registered Users |
Remove a Reviewer | Project Owners |
Submit a patch | Project Owners |
Edit a Topic | Registered Users |
Create Annotated/Signed Tag | Project Onwers |
In order to give to our group a full permission on the project,
we must to set our group as the project Owners
group.
Click on the Access
under Projects
=> Edit
Click on the Add Reference
=> change the Reference from refs/heads/*
to refs/*
.
Click on the Add Permission...
drop-down box, it will show
a list of possible rights for our project, select the Owner
and it will add it to the list.
Click on the Add Group
and select the group you created earlier,
and make sure that the ALLOW
right is granted.
Add a Commit Message => Click on the Save Changes
button.
Note: You can add a specific permission which will override the default one but it's not recommended.
For example: you can change the default permission to add Verify +1 label to a specific group (default: Registered Users)
Enabling Anonymous Cloning
In order to allow cloning over the git protocol (which also allows for github
mirroring), it's necessary to ssh directly into gerrit.ovirt.org
.
If you have an alias for it in ssh_config
, you may need to pass -p 22
to ssh to avoid trying to ssh into gerrit.
ssh -p 22 youruser@gerrit.ovirt.org
Then change to the gerrit2 user
sudo -i -u gerrit2
Gerrit lives under ~gerrit2/review_site
. chdir to your new project
cd ~/review_site/git/foobar.git
From here, two steps must be taken. First, gerrit requires the existence of a
file named git-daemon-export-ok
in the project root in order to serve it
over git://
touch git-daemon-export-ok
Enabling Custom Gerrit Hooks
oVirt projects support various verification gerrit hooks which handle integration between Gerrit and Bugzilla and can perform updates as well as verifications.
Instead of maintaining specific hooks for specific projects, we have a custom
hooks that are located under ~/review_site/hooks/default-hooks
directory.
Inside the default-hooks
directory the hooks are splitted into the
following directories:
- update
- check
- all (includes both update and check hooks)
In each directory we have links to the real hooks that are located inside
the custom_hooks
directory.
For example:
Inside the check
directory we have a link to the check_bug_url hook
patchset-created.bz.1.check_bug_url -> ../../custom_hooks/check_bug_url
List of all the custom hooks under each directory:
directory | hooks | purpose |
---|---|---|
update | update_tracker | add/update the external tracker of a bug |
set_modified | change bug status from POST => MODOFIED | |
set_post | change bug status from NEW/ASSIGNED => POST | |
check | check_bug_url | check for bug url existance |
check_product | check patch project == bug product | |
check_target_milestone | check patch branch major version == bug milestone major version | |
check_backport | check patch merged to all newer branches |
If you want to use the custom hooks you need to remove the hooks
directory
under your project and create a symbolic link to one of the default hooks directories
(i.e update, check, all)
This is most easily done by running the following commands:
cd ~/review_site/git/foobar.git/
rm -r hooks
ln -s ~/review_site/hooks/default-hooks/all hooks
Creating the Github repository
Finally, log into Github, and create a new repository. When creating the repo,
there is a dropdown box preceding the input box for the repository name which
is populated with yourusername
. Change it to oVirt
.
The repository name should exactly match the name of the project in gerrit. If
it was foobar
, Github should also be foobar
.
The description should be:
This is a mirror for http://gerrit.ovirt.org, for issues use
http://bugzilla.redhat.com
It's not necessary to select the "Initialize this repository" checkbox.
TODO: add verify steps to make sure the repo is synced to GitHub.
Enable Gerrit to Gihub mirroring
The mirroring is run using the gerrit replication plugin. In order to enable gerrit to github mirroring, First we need to make sure our new repository (foobar) is exist on github.
Second we need to ssh directly into gerrit.ovirt.org
as explained in the
Enabling Anonymous Cloning
section.
Third we need to update the replication.config file with our new project that should be replicated.
vi ~/review_site/etc/replication.config
Add your new project (foobar) under the [remote github]
section.
Each project should be on a separate line.
In the next example only foobar project will be replicated.
projects = foobar
Regex can be used by adding ^ at the begging of the line In the next example foobar-prod and foobar-test projects will be replicated.
projects = ^foobar-(prod|test)
You can check the replication_log file to see the status of your replication
tailf ~/review_site/logs/replication_log
Force replication to Github
If replication is set up for an existing repo gerrit will not automatically replicate until the next patch is merged. To force a replication, run this:
ssh -p 29418 gerrit.ovirt.org replication start <repo-name>
Populating the repository
Treat this like any other git repository with a couple of nits. If it's a brand-new project with no existing code, the initial commit you should have selected in Gerrit will suffice.
If you're pushing from somewhere else, you can clone that repository, add the
gerrit project as a remote, and push. However, in order to push, you'll need
to add the Push
right to the Gerrit project configuration, with a group
that you're a member of. Force Push
is available under Push
for extreme
cases.
If you're not the author of all the commits, Forge Author
and Forge
Committer
may need to be set, otherwise the Gerrit hooks will reject your
push, even if forced.