| :linkattrs: | |
| = Project Owner Guide | |
| This is a Gerrit guide that is dedicated to project owners. It | |
| explains the many possibilities that Gerrit provides to customize the | |
| workflows for a project. | |
| [[project-owner]] | |
| == What is a project owner? | |
| Being project owner means that you own a project in Gerrit. | |
| Technically this is expressed by having the | |
| link:access-control.html#category_owner[Owner] access right on | |
| `+refs/*+` on that project. As project owner you have the permission to | |
| edit the access control list and the project settings of the project. | |
| It also means that you should get familiar with these settings so that | |
| you can adapt them to the needs of your project. | |
| Being project owner means being responsible for the administration of | |
| a project. This requires having a deeper knowledge of Gerrit than the | |
| average user. Normally per team there should be 2 to 3 persons, who | |
| have a certain level of Git/Gerrit knowledge, assigned as project | |
| owners. It normally doesn't make sense that everyone in a team is | |
| project owner. For normal team members it is sufficient to be committer | |
| or contributor. | |
| [[access-rights]] | |
| == Access Rights | |
| As a project owner you can edit the access control list of your | |
| project. This allows you to grant permissions on the project to | |
| different groups. | |
| Gerrit comes with a rich set of permissions which allow a very | |
| fine-grained control over who can do what on a project. Access | |
| control is one of the most powerful Gerrit features but it is also a | |
| rather complex topic. This guide will only highlight the most | |
| important aspects of access control, but the link:access-control.html[ | |
| Access Control] chapter explains all the details. | |
| [[edit-access-rights]] | |
| === Editing Access Rights | |
| To see the access rights of your project | |
| - go to the Gerrit Web UI | |
| - click on the `Projects` > `List` menu entry | |
| - find your project in the project list and click on it | |
| - click on the `Access` menu entry | |
| By clicking on the `Edit` button the access rights become editable and | |
| you may save any changes by clicking on the `Save Changes` button. | |
| Optionally you can provide a `Commit Message` to explain the reasons | |
| for changing the access rights. | |
| The access rights are stored in the project's Git repository in a | |
| special branch called `refs/meta/config`. On this branch there is a | |
| `project.config` file which contains the access rights. More | |
| information about this storage format can be found in the | |
| link:config-project-config.html[Project Configuration File Format] | |
| chapter. What is important to know is that by looking at the history | |
| of the `project.config` file on the `refs/meta/config` branch you can | |
| always see how the access rights were changed and by whom. If a good | |
| commit message is provided you can also see from the history why the | |
| access rights were modified. | |
| If a Git browser such as gitweb is configured for the Gerrit server you | |
| can find a link to the history of the `project.config` file in the | |
| Web UI. Otherwise you may inspect the history locally. If you have | |
| cloned the repository you can do this by executing the following | |
| commands: | |
| ---- | |
| $ git fetch ssh://localhost:29418/project refs/meta/config | |
| $ git checkout FETCH_HEAD | |
| $ git log project.config | |
| ---- | |
| Non project owners may still edit the access rights and propose the | |
| modifications to the project owners by clicking on the `Save for | |
| Review` button. This creates a new change with the access rights | |
| modifications that can be approved by a project owner. The project | |
| owners are automatically added as reviewer on this change so that they | |
| get informed about it by email. | |
| [[inheritance]] | |
| === Inheritance | |
| Normally when a new project is created in Gerrit it already has some | |
| access rights which are inherited from the parent projects. | |
| Projects in Gerrit are organized hierarchically as a tree with the | |
| `All-Projects` project as root from which all projects inherit. Each | |
| project can have only a single parent project, multi-inheritance is | |
| not supported. | |
| Looking at the access rights of your project in the Gerrit Web UI, you | |
| only see the access rights which are defined on that project. To see | |
| the inherited access rights you must follow the link to the parent | |
| project under `Rights Inherit From`. | |
| Inherited access rights can be overwritten unless they are defined as | |
| link:access-control.html#block[BLOCK rule]. BLOCK rules are used to | |
| limit the possibilities of the project owners on the inheriting | |
| projects. With this, global policies can be enforced on all projects. | |
| Please note that Gerrit doesn't prevent you from assigning access | |
| rights that contradict an inherited BLOCK rule, but these access rights | |
| will simply have no effect. | |
| If you are responsible for several projects which require the same | |
| permissions, it makes sense to have a common parent for them and to | |
| maintain the access rights on that common parent. Changing the parent | |
| of a project is only allowed for Gerrit administrators. This means you | |
| need to contact the administrator of your Gerrit server if you want to | |
| reparent your project. One way to do this is to change the parent | |
| project in the Web UI, save the modifications for review and get the | |
| change approved and merged by a Gerrit administrator. | |
| [[refs]] | |
| === References | |
| Access rights in Gerrit are assigned on references (aka refs). Refs in | |
| Git exist in different namespaces, e.g. all branches normally exist | |
| under `refs/heads/` and all tags under `refs/tags/`. In addition there | |
| are a number of link:access-control.html#references_special[special refs] | |
| and link:access-control.html#references_magic[magic refs]. | |
| Gerrit only supports tags that are reachable by any ref not owned by | |
| Gerrit. This includes branches (refs/heads/*) or custom ref namespaces | |
| (refs/my-company/*). Tagging a change ref is not supported. | |
| When filtering tags by visibility, Gerrit performs a reachability check | |
| and will present the user ony with tags that are reachable by any ref | |
| they can see. | |
| Access rights can be assigned on a concrete ref, e.g. | |
| `refs/heads/master` but also on ref patterns and regular expressions | |
| for ref names. | |
| A ref pattern ends with `+/*+` and describes a complete ref name | |
| namespace, e.g. access rights assigned on `+refs/heads/*+` apply to all | |
| branches. | |
| Regular expressions must start with `^`, e.g. access rights assigned | |
| on `+^refs/heads/rel-.*+` would apply to all `+rel-*+` branches. | |
| [[groups]] | |
| === Groups | |
| Access rights are granted to groups. It is useful to know that Gerrit | |
| maintains its own groups internally but also supports different external | |
| group backends. | |
| The Gerrit internal groups can be seen in the Gerrit Web UI by clicking | |
| on the `Groups` > `List` menu entry. By clicking on a group you can | |
| edit the group members (`Members` tab) and the group options | |
| (`General` tab). | |
| Gerrit internal groups contain users as members, but can also include | |
| other groups, even external groups. | |
| Every group is owned by an owner group. Only members of the owner | |
| group can administrate the owned group (assign members, edit the group | |
| options). A group can own itself; in this case members of the group | |
| can, for example, add further members to the group. When you create new | |
| groups for your project to assign access rights to committer or other | |
| roles, make sure that they are owned by the project owner group. | |
| An important setting on a group is the option | |
| `Make group visible to all registered users.`, which defines whether | |
| non-members can see who is member of the group. | |
| New internal Gerrit groups can be created under `Groups` > | |
| `Create New Group`. This menu is only available if you have the global | |
| capability link:access-control.html#capability_createGroup[Create Group] | |
| assigned. | |
| Gerrit also has a set of special | |
| link:access-control.html#system_groups[system groups] that you might | |
| find useful. | |
| External groups need to be prefixed when assigning access rights to | |
| them, e.g. link:access-control.html#ldap_groups[LDAP group names] need | |
| to be prefixed with `ldap/`. | |
| If the link:https://gerrit-review.googlesource.com/admin/repos/plugins/singleusergroup[ | |
| singleusergroup,role=external,window=_blank] plugin is installed you can also directly assign | |
| access rights to users, by prefixing the username with `user/` or the | |
| user's account ID by `userid/`. | |
| [[common-access-rights]] | |
| === Common Access Rights | |
| Different roles in a project, such as developer (committer) or | |
| contributor, need different access rights. Examples for which access | |
| rights are typically assigned for which role are described in the | |
| link:access-control.html#example_roles[Access Control] chapter. | |
| [[code-review]] | |
| === Code Review | |
| Gerrit's main functionality is code review, however using code review | |
| is optional and you may decide to only use Gerrit as a Git server with | |
| access control. Whether you allow only pushes for review or also | |
| direct pushes depends on the project's access rights. | |
| To push a commit for review it must be pushed to | |
| link:access-control.html#refs_for[refs/for/<branch-name>]. This means | |
| the link:access-control.html#category_push_review[Push] access right | |
| must be assigned on `refs/for/<branch-name>`. | |
| To allow direct pushes and bypass code review, the | |
| link:access-control.html#category_push_direct[Push] access right is | |
| required on `refs/heads/<branch-name>`. | |
| By pushing for review you are not only enabling the review workflow, | |
| but you can also get link:#continuous-integration[automatic | |
| verifications from a build server] before changes are merged. In | |
| addition you can benefit from Gerrit's merge strategies that can | |
| automatically merge/rebase commits on server side if necessary. You can | |
| control the merge strategy by configuring the | |
| link:config-project-config.html#submit-type[submit type] on the project. If you | |
| bypass code review you always need to merge/rebase manually if the tip | |
| of the destination branch has moved. Please keep this in mind if you | |
| choose to not work with code review because you think it's easier to | |
| avoid the additional complexity of the review workflow; it might | |
| actually not be easier. | |
| You may also enable link:user-upload.html#auto_merge[auto-merge on | |
| push] to benefit from the automatic merge/rebase on server side while | |
| pushing directly into the repository. | |
| [[project-options]] | |
| == Project Options | |
| As project owner you can control several options on your project. | |
| The different options are described in the | |
| link:project-configuration.html#project_options[Project Options] section. | |
| To see the options of your project: | |
| . Go to the Gerrit Web UI. | |
| . Click on the `Projects` > `List` menu entry. | |
| . Find your project in the project list and click it. | |
| . Click the `General` menu entry. | |
| [[submit-type]] | |
| === Submit Type | |
| An important decision for a project is the choice of the submit type | |
| and the content merge setting (see the `Allow content merges` option). | |
| The link:config-project-config.html#submit-type[submit type] is the method | |
| Gerrit uses to submit a change to the project. The submit type defines | |
| what Gerrit should do on submit of a change if the destination branch | |
| has moved while the change was in review. The | |
| link:project-configuration.html#content_merge[content merge] setting applies | |
| if the same files have been modified concurrently and tells Gerrit | |
| whether it should attempt a content merge for these files. | |
| When choosing the submit type and the content merge setting one must | |
| weigh development comfort against the safety of not breaking the | |
| destination branch. | |
| The most restrictive submit type is | |
| link:project-configuration.html#fast_forward_only[Fast Forward Only]. Using | |
| this submit type means that after submitting one change all other open | |
| changes for the same destination branch must be rebased manually. This | |
| is quite burdensome and in practice only feasible for branches with | |
| very few changes. On the other hand, if changes are verified before | |
| submit, e.g. automatically by a CI integration, with this submit type, | |
| you can be sure that the destination branch never gets broken. | |
| Choosing link:project-configuration.html#merge_if_necessary[Merge If Necessary] | |
| as submit type makes the life for developers more comfortable, | |
| especially if content merge is enabled. If this submit strategy is used | |
| developers only need to rebase manually if the same files have been | |
| modified concurrently or if the content merge on such a file fails. The | |
| drawback with this submit type is that there is a risk of breaking | |
| the destination branch, e.g. if one change moves a class into another | |
| package and another change imports this class from the old location. | |
| Experience shows that in practice `Merge If Necessary` with content | |
| merge enabled works pretty well and breaking the destination branch | |
| happens rarely. This is why this setting is recommended at least for | |
| development branches. You likely want to start with | |
| `Merge If Necessary` with content merge enabled and only switch to a | |
| more restrictive policy if you are facing issues with the build and | |
| test stability of the destination branches. | |
| It is also possible to define the submit type dynamically via | |
| link:#prolog-submit-type[Prolog]. This way you can use different submit | |
| types for different branches. | |
| Please note that there are other submit types available; they are | |
| described in the link:config-project-config.html#submit-type[Submit Type] | |
| section. | |
| [[labels]] | |
| == Labels | |
| The code review process includes that reviewers formally express their | |
| opinion about a change by voting on different link:config-labels.html[ | |
| labels]. By default Gerrit comes with the | |
| link:config-labels.html#label_Code-Review[Code-Review] label and many | |
| Gerrit servers have the link:config-labels.html#label_Verified[Verified] | |
| label configured globally. However projects can also define their own | |
| link:config-labels.html#label_custom[custom labels] to formalize | |
| project-specific workflows. For example if a project requires an IP | |
| approval from a special IP-team, it can define an `IP-Review` label | |
| and grant permissions to the IP-team to vote on this label. | |
| The behavior of a label can be controlled by its | |
| link:config-labels.html#label_function[function], e.g. it can be | |
| configured whether a max positive voting on the label is required for | |
| submit or if the voting on the label is optional. | |
| By using a custom link:#submit-rules[submit rule] it can be controlled | |
| per change whether a label is required for submit or not. | |
| A useful feature on labels is the possibility to automatically copy | |
| scores forward to new patch sets if it was a | |
| link:config-labels.html#label_copyAllScoresOnTrivialRebase[trivial | |
| rebase] or if link:config-labels.html#label_copyAllScoresIfNoCodeChange[ | |
| there was no code change] (e.g. only the commit message was edited). | |
| [[submit-rules]] | |
| == Submit Rules | |
| A link:prolog-cookbook.html#SubmitRule[submit rule] in Gerrit is logic | |
| that defines when a change is submittable. By default, a change is | |
| submittable when it gets at least one highest vote on each label and | |
| has no lowest vote (aka veto vote) on any label. | |
| The submit rules in Gerrit are implemented in link:prolog-cookbook.html[ | |
| Prolog] and projects that need more flexibility can define their own | |
| submit rules to decide when a change should be submittable. A good | |
| link:prolog-cookbook.html#NonAuthorCodeReview[example] from the Prolog | |
| cookbook shows how to allow submit only if a change has a | |
| `Code-Review+2` vote from a person that is not the change author. This | |
| way a four-eyes principle for the reviews can be enforced. | |
| A Prolog submit rule has access to link:prolog-change-facts.html[ | |
| information] about the change for which it is testing the | |
| submittability. Among others the list of the modified files can be | |
| accessed, which allows special logic if certain files are touched. For | |
| example, a common practice is to require a vote on an additional label, | |
| like `Library-Compliance`, if the dependencies of the project are | |
| changed. | |
| [[prolog-submit-type]] | |
| It is also possible to control the link:prolog-cookbook.html#SubmitType[ | |
| submit type] from Prolog. For example this can be used to define a more | |
| restrictive submit type such as `Fast Forward Only` for stable branches | |
| while using a more liberal submit type, e.g. `Merge If Necessary` with | |
| content merge, for development branches. How this can be done can be | |
| seen from an link:prolog-cookbook.html#SubmitTypePerBranch[example] in | |
| the Prolog cookbook. | |
| Submit rules are maintained in the link:prolog-cookbook.html#RulesFile[ | |
| rules.pl] file in the `refs/meta/config` branch of the project. How to | |
| write submit rules is explained in the | |
| link:prolog-cookbook.html#HowToWriteSubmitRules[Prolog cookbook]. There | |
| is also good support for link:prolog-cookbook.html#TestingSubmitRules[ | |
| testing submit rules] while developing them. | |
| [[continuous-integration]] | |
| == Continuous Integration | |
| With Gerrit you can have continuous integration builds not only for | |
| updates of central branches but also whenever a new change/patch set is | |
| uploaded for review. This way you get automatic verification of all | |
| changes *before* they are merged and any build and test issues are | |
| detected early. To indicate the build and test status the continuous | |
| integration system normally votes with the | |
| link:config-labels.html#label_Verified[Verified] label on the change. | |
| There are several solutions for integrating continuous integration | |
| systems. The most commonly used are: | |
| - link:https://wiki.jenkins-ci.org/display/JENKINS/Gerrit+Trigger[ | |
| Gerrit Trigger,role=external,window=_blank] plugin for link:http://jenkins-ci.org/[Jenkins,role=external,window=_blank] | |
| - link:http://www.mediawiki.org/wiki/Continuous_integration/Zuul[ | |
| Zuul,role=external,window=_blank] for link:http://jenkins-ci.org/[Jenkins,role=external,window=_blank] | |
| For the integration with the continuous integration system you must | |
| have a service user that is able to access Gerrit. To create a service | |
| user in Gerrit you can use the link:cmd-create-account.html[create-account] | |
| SSH command if the link:access-control.html#capability_createAccount[ | |
| Create Account] global capability is granted. If not, you need to ask | |
| a Gerrit administrator to create the service user. | |
| If the link:https://gerrit-review.googlesource.com/admin/repos/plugins/serviceuser[ | |
| serviceuser,role=external,window=_blank] plugin is installed you can also create new service users | |
| in the Gerrit Web UI under `People` > `Create Service User`. For this | |
| the `Create Service User` global capability must be assigned. | |
| The service user must have link:access-control.html#category_read[read] | |
| access to your project. In addition, if automatic change verification | |
| is enabled, the service user must be allowed to vote on the | |
| link:config-labels.html#label_Verified[Verified] label. | |
| Continuous integration systems usually integrate with Gerrit by | |
| listening to the Gerrit link:cmd-stream-events.html#events[stream | |
| events]. For this the service user must have the | |
| link:access-control.html#capability_streamEvents[Stream Events] global | |
| capability assigned. | |
| [[commit-validation]] | |
| == Commit Validation | |
| Gerrit provides an | |
| link:https://gerrit-review.googlesource.com/Documentation/config-validation.html#new-commit-validation[ | |
| extension point to do validation of new commits,role=external,window=_blank]. A Gerrit plugin | |
| implementing this extension point can perform validation checks when | |
| new commits are pushed to Gerrit. The plugin can either provide a | |
| message to the client or reject the commit and cause the push to fail. | |
| There are some plugins available that provide commit validation: | |
| - link:https://gerrit-review.googlesource.com/admin/repos/plugins/uploadvalidator[ | |
| uploadvalidator,role=external,window=_blank]: | |
| + | |
| The `uploadvalidator` plugin allows project owners to configure blocked | |
| file extensions, required footers and a maximum allowed path length. | |
| - link:https://gerrit-review.googlesource.com/admin/repos/plugins/commit-message-length-validator[ | |
| commit-message-length-validator,role=external,window=_blank] | |
| + | |
| The `commit-message-length-validator` core plugin validates that commit | |
| messages conform to line length limits. | |
| [[branch-administration]] | |
| == Branch Administration | |
| As project owner you can administrate the branches of your project in | |
| the Gerrit Web UI under `Projects` > `List` > <your project> > | |
| `Branches`. In the Web UI link:project-configuration.html#branch-creation[ | |
| branch creation] is allowed if you have | |
| link:access-control.html#category_create[Create Reference] access right and | |
| link:project-configuration.html#branch-deletion[branch deletion] is allowed if | |
| you have the link:access-control.html#category_delete[Delete Reference] or the | |
| link:access-control.html#category_push[Push] access right with the `force` | |
| option. | |
| By setting `HEAD` on the project you can define its | |
| link:project-configuration.html#default-branch[default branch]. For convenience | |
| reasons, when the repository is cloned Git creates a local branch for | |
| this default branch and checks it out. | |
| [[notifications]] | |
| == Email Notifications | |
| With Gerrit individual users control their own email subscriptions. By | |
| editing the link:user-notify.html#user[watched projects] in the Web UI | |
| under `Settings` > `Watched Projects` users can decide which events to | |
| be informed about by email. The change notifications can be filtered by | |
| link:user-search.html[change search expressions]. | |
| This means as a project owner you normally don't need to do anything | |
| about email notifications, except maybe telling your project team where | |
| to configure the watches. | |
| Gerrit also supports link:user-notify.html#project[notifications on | |
| project level] that allow project owners to set up email notifications | |
| for team mailing lists or groups of users. This configuration is done | |
| in the `project.config` file in the `refs/meta/config` branch as | |
| explained in the section about link:user-notify.html#project[project | |
| level notifications]. | |
| [[dashboards]] | |
| == Dashboards | |
| Gerrit comes with a pre-defined user dashboard that provides a view | |
| of the changes that are relevant for a user. Users can also define | |
| their own link:user-dashboards.html[custom dashboards] where the | |
| dashboard sections can be freely configured. As a project owner you can | |
| configure such custom dashboards on | |
| link:user-dashboards.html#project-dashboards[project level]. This way | |
| you can define a view of the changes that are relevant for your | |
| project and share this dashboard with all users. The project dashboards | |
| can be seen in the Web UI under `Projects` > `List` > <your project> > | |
| `Dashboards`. | |
| [[issue-tracker-integration]] | |
| == Issue Tracker Integration | |
| There are several possibilities to integrate issue trackers with | |
| Gerrit. | |
| - Comment Links | |
| + | |
| As described in the link:#comment-links[Comment Links] section, comment | |
| links can be used to link IDs from commit message footers to issues in | |
| an issue tracker system. | |
| - Tracking IDs | |
| + | |
| Gerrit can be configured to index IDs from commit message footers so | |
| that the link:user-search.html#tr[tr/bug] search operators can be used | |
| to query for changes with a certain ID. The | |
| link:config-gerrit.html#trackingid[configuration of tracking IDs] can | |
| only be done globally by a Gerrit administrator. | |
| - Issue Tracker System Plugins | |
| + | |
| There are Gerrit plugins for a tight integration with | |
| link:https://gerrit-review.googlesource.com//admin/repos/plugins/its-jira[Jira,role=external,window=_blank], | |
| link:https://gerrit-review.googlesource.com/admin/repos/plugins/its-bugzilla[Bugzilla,role=external,window=_blank] and | |
| link:https://gerrit-review.googlesource.com/admin/repos/plugins/its-rtc[IBM Rational Team Concert,role=external,window=_blank]. | |
| If installed, these plugins can e.g. be used to automatically add links | |
| to Gerrit changes to the issues in the issue tracker system or to | |
| automatically close an issue if the corresponding change is merged. | |
| If installed, project owners may enable/disable the issue tracker | |
| integration from the Gerrit Web UI under `Projects` > `Lists` > | |
| <your project> > `General`. | |
| [[comment-links]] | |
| == Comment Links | |
| Gerrit can linkify strings in commit messages, summary comments and | |
| inline comments. A string that matches a defined regular expression is | |
| then displayed as hyperlink to a configured backend system. | |
| So called comment links can be configured globally by a Gerrit | |
| administrator, but also per project by the project owner. Comment links | |
| on project level are defined in the `project.config` file in the | |
| `refs/meta/config` branch of the project as described in the | |
| documentation of the link:config-gerrit.html#commentlink[commentlink] | |
| configuration parameter. | |
| Often comment links are used to link an ID in a commit message footer | |
| to an issue in an issue tracker system. For example, to link the ID | |
| from the `Bug` footer to Jira the following configuration can be used: | |
| ---- | |
| [commentlink "myjira"] | |
| match = ([Bb][Uu][Gg]:\\s+)(\\S+) | |
| link = https://myjira/browse/$2 | |
| ---- | |
| [[reviewers]] | |
| == Reviewers | |
| Normally it is not needed to explicitly assign reviewers to every | |
| change since the project members either link:user-notify.html#user[ | |
| watch the project] and get notified by email or regularly check the | |
| list of open changes in the Gerrit Web UI. The project members then | |
| pick the changes themselves that are interesting to them for review. | |
| If authors of changes want to have a review by a particular person | |
| (e.g. someone who is known to be expert in the touched code area, or a | |
| stakeholder for the implemented feature), they can request the review | |
| by adding this person in the Gerrit Web UI as a reviewer on the change. | |
| Gerrit will then notify this person by email about the review request. | |
| With the link:https://gerrit-review.googlesource.com/admin/repos/plugins/reviewers[ | |
| reviewers,role=external,window=_blank] plugin it is possible to configure default reviewers who | |
| will be automatically added to each change. The default reviewers can | |
| be configured in the Gerrit Web UI under `Projects` > `List` > | |
| <your project> > `General` in the `reviewers Plugin` section. | |
| The link:https://gerrit-review.googlesource.com/admin/repos/plugins/reviewers-by-blame[ | |
| reviewers-by-blame,role=external,window=_blank] plugin can automatically add reviewers to changes | |
| based on the link:https://www.kernel.org/pub/software/scm/git/docs/git-blame.html[ | |
| git blame,role=external,window=_blank] computation on the changed files. This means that the plugin | |
| will add those users as reviewer that authored most of the lines | |
| touched by the change, since these users should be familiar with the | |
| code and can most likely review the change. How many reviewers the | |
| plugin will add to a change at most can be configured in the Gerrit | |
| Web UI under `Projects` > `List` > <your project> > `General` in the | |
| `reviewers-by-blame Plugin` section. | |
| [[download-commands]] | |
| == Download Commands | |
| On the change screen in the `Downloads` drop-down panel Gerrit offers | |
| commands for downloading the currently viewed patch set. | |
| The download commands are implemented by Gerrit plugins. This means | |
| that the available download commands depend on the installed Gerrit | |
| plugins: | |
| - link:https://gerrit-review.googlesource.com/admin/repos/plugins/download-commands[ | |
| download-commands,role=external,window=_blank] plugin: | |
| + | |
| The `download-commands` plugin provides the default download commands | |
| (`Checkout`, `Cherry Pick`, `Format Patch` and `Pull`). | |
| + | |
| Gerrit administrators may configure which of the commands are shown on | |
| the change screen. | |
| - link:https://gerrit-review.googlesource.com/admin/repos/plugins/project-download-commands[ | |
| project-download-commands,role=external,window=_blank] plugin: | |
| + | |
| The `project-download-commands` plugin enables project owners to | |
| configure project-specific download commands. For example, a | |
| project-specific download command may update submodules, trigger a | |
| build, execute the tests or even do a deployment. | |
| + | |
| The project-specific download commands must be configured in the | |
| `project.config` file in the `refs/meta/config` branch of the project: | |
| + | |
| ---- | |
| [plugin "project-download-commands"] | |
| Build = git fetch ${url} ${ref} && git checkout FETCH_HEAD && bazel build ${project} | |
| Update = git fetch ${url} ${ref} && git checkout FETCH_HEAD && git submodule update | |
| ---- | |
| + | |
| Project-specific download commands that are defined on a parent project | |
| are inherited by the child projects. A child project can overwrite an | |
| inherited download command, or remove it by assigning no value to it. | |
| [[tool-integration]] | |
| == Integration with other tools | |
| Gerrit provides many possibilities for the integration with other | |
| tools: | |
| - Stream Events: | |
| + | |
| The link:cmd-stream-events.html[stream-events] SSH command allows to | |
| listen to Gerrit link:cmd-stream-events.html#events[events]. Other | |
| tools can use this to react on actions done in Gerrit. | |
| + | |
| The link:access-control.html#capability_streamEvents[Stream Events] | |
| global capability is required for using the `stream-events` command. | |
| - REST API: | |
| + | |
| Gerrit provides a rich link:rest-api.html[REST API] that other tools | |
| can use to query information from Gerrit and and to trigger actions in | |
| Gerrit. | |
| - Gerrit Plugins: | |
| + | |
| The Gerrit functionality can be extended by plugins and there are many | |
| extension points, e.g. plugins can | |
| + | |
| ** link:pg-plugin-admin-api.html[add new menu entries] | |
| ** link:pg-plugin-endpoints.html[hook into DOM elements] and | |
| link:pg-plugin-dev.html#plugin-screen[add new pages] | |
| ** link:config-validation.html[do validation], e.g. of new commits | |
| ** add new REST endpoints and link:dev-plugins.html#ssh[SSH commands] | |
| + | |
| How to develop a Gerrit plugin is described in the link:dev-plugins.html[ | |
| Plugin Development] section. | |
| [[project-lifecycle]] | |
| == Project Lifecycle | |
| [[project-creation]] | |
| === Project Creation | |
| New projects can be created in the Gerrit Web UI under `Projects` > | |
| `Create Project`. The `Create Project` menu entry is only available if | |
| you have the link:access-control.html#capability_createProject[ | |
| Create Project] global capability assigned. | |
| Projects can also be created via REST or SSH as described in the | |
| link:project-configuration.html#project-creation[Project Setup] section. | |
| Creating the project with an initial empty commit is generally | |
| recommended because some tools have issues with cloning repositories | |
| that are completely empty. However, if you plan to link:#import-history[ | |
| import an existing history] into the new project, it is better to | |
| create the project without an initial empty commit. | |
| [[import-history]] | |
| === Import Existing History | |
| If you have an existing history you can import it into a Gerrit | |
| project. To do this you need to have a local Git repository that | |
| contains this history. If your existing codebase is in another VCS you | |
| must migrate it to Git first. For Subversion you can use the | |
| link:http://git-scm.com/book/en/Git-and-Other-Systems-Git-and-Subversion[ | |
| git svn,role=external,window=_blank] command as described in the | |
| link:http://git-scm.com/book/en/Git-and-Other-Systems-Migrating-to-Git#Subversion[ | |
| Subversion migration guide,role=external,window=_blank]. An importer for Perforce is available in | |
| the `contrib` section of the Git source code; how to use | |
| link:http://git-scm.com/docs/git-p4[git p4,role=external,window=_blank] to do the import from | |
| Perforce is described in the | |
| link:http://git-scm.com/book/en/Git-and-Other-Systems-Migrating-to-Git#Perforce[ | |
| Perforce migration guide,role=external,window=_blank]. | |
| To import an existing history into a Gerrit project you bypass code | |
| review and push it directly to `refs/heads/<branch>`. For this you must | |
| have the corresponding link:access-control.html#category_push_direct[ | |
| Push] access right assigned. If the destination branch in the Gerrit | |
| repository already contains a history (e.g. an initial empty commit), | |
| you can overwrite it by doing a force push. In this case force push | |
| must be allowed in the access controls of the project. | |
| Some Gerrit servers may disallow forging committers by blocking the | |
| link:access-control.html#category_forge_committer[Forge Committer] | |
| access right globally. In this case you must use the | |
| link:https://www.kernel.org/pub/software/scm/git/docs/git-filter-branch.html[ | |
| git filter-branch,role=external,window=_blank] command to rewrite the committer information for all | |
| commits (the author information that records who was writing the code | |
| stays intact; signed tags will lose their signature): | |
| ---- | |
| $ git filter-branch --tag-name-filter cat --env-filter 'GIT_COMMITTER_NAME="John Doe"; GIT_COMMITTER_EMAIL="john.doe@example.com";' -- --all | |
| ---- | |
| If a link:config-gerrit.html#receive.maxObjectSizeLimit[max object size | |
| limit] is configured on the server you may need to remove large objects | |
| from the history before you are able to push. To find large objects in | |
| the history of your project you can use the `reposize.sh` script which | |
| you can download from Gerrit: | |
| ---- | |
| $ curl -Lo reposize.sh http://review.example.com:8080/tools/scripts/reposize.sh | |
| or | |
| $ scp -p -P 29418 john.doe@review.example.com:scripts/reposize.sh . | |
| ---- | |
| You can then use the | |
| link:https://www.kernel.org/pub/software/scm/git/docs/git-filter-branch.html[ | |
| git filter-branch] command to remove the large objects from the history | |
| of all branches: | |
| ---- | |
| $ git filter-branch -f --index-filter 'git rm --cached --ignore-unmatch path/to/large-file.jar' -- --all | |
| ---- | |
| Since this command rewrites all commits in the repository it's a good | |
| idea to create a fresh clone from this rewritten repository before | |
| pushing to Gerrit, this will ensure that the original objects which | |
| have been rewritten are removed. | |
| [[project-deletion]] | |
| === Project Deletion | |
| Gerrit core does not support the deletion of projects. | |
| If the link:https://gerrit-review.googlesource.com/admin/repos/plugins/delete-project[ | |
| delete-project,role=external,window=_blank] plugin is installed, projects can be deleted from the | |
| Gerrit Web UI under `Projects` > `List` > <project> > `General` by | |
| clicking on the `Delete` command under `Project Commands`. The `Delete` | |
| command is only available if you have the `Delete Projects` global | |
| capability assigned, or if you own the project and you have the | |
| `Delete Own Projects` global capability assigned. If neither of these | |
| capabilities is granted, you need to contact a Gerrit administrator to | |
| request the deletion of your project. | |
| Instead of deleting a project you may set the | |
| link:project-configuration.html#project-state[project state] to `ReadOnly` or | |
| `Hidden`. | |
| [[project-rename]] | |
| === Project Rename | |
| Gerrit core does not support the renaming of projects. | |
| If the link:https://gerrit-review.googlesource.com/admin/repos/plugins/rename-project[rename-project] | |
| plugin is installed, projects can be renamed using the | |
| link:https://gerrit.googlesource.com/plugins/rename-project/+/refs/heads/master/src/main/resources/Documentation/cmd-rename.md[rename-project] | |
| ssh command. | |
| Find details about prerequisites in the | |
| link:https://gerrit.googlesource.com/plugins/rename-project/+/refs/heads/master/src/main/resources/Documentation/about.md[plugin documentation]. | |
| If you don't want to use the rename-project plugin you can perform the following steps as | |
| a workaround: | |
| . link:#project-creation[Create a new project] with the new name. | |
| . link:#import-history[Import the history of the old project]. | |
| . link:#project-deletion[Delete the old project]. | |
| Please note that a drawback of this workaround is that the whole review | |
| history (changes, review comments) is lost. | |
| GERRIT | |
| ------ | |
| Part of link:index.html[Gerrit Code Review] | |
| SEARCHBOX | |
| --------- |