| Gerrit Code Review - Access Controls |
| ==================================== |
| |
| Access controls in Gerrit are group based. Every user account is a |
| member of one or more groups, and access and privileges are granted |
| to those groups. Access rights cannot be granted to individual |
| users. |
| |
| |
| System Groups |
| ------------- |
| |
| Gerrit comes with 4 system groups, with special access privileges |
| and membership management. The identity of these groups is set |
| in the `system_config` table within the database, so the groups |
| can be renamed after installation if desired. |
| |
| [[administrators]] |
| Administrators |
| ~~~~~~~~~~~~~~ |
| |
| This is the Gerrit "root" identity. |
| |
| Users in the 'Administrators' group can perform any action under |
| the Admin menu, to any group or project, without further validation |
| or any other access controls. In most installations only those |
| users who have direct filesystem and database access would be |
| placed into this group. |
| |
| Membership in the 'Administrators' group does not imply any other |
| access rights. Administrators do not automatically get code review |
| approval or submit rights in projects. This is a feature designed |
| to permit administrative users to otherwise access Gerrit as any |
| other normal user would, without needing two different accounts. |
| |
| [[anonymous_users]] |
| Anonymous Users |
| ~~~~~~~~~~~~~~~ |
| |
| All users are automatically a member of this group. Users who are |
| not signed in are a member of only this group, and no others. |
| |
| Any access rights assigned to this group are inherited by all users. |
| |
| Administrators and project owners can grant access rights to this |
| group in order to permit anonymous users to view project changes, |
| without requiring sign in first. Currently it is only worthwhile |
| to grant `Read` access to this group as Gerrit requires an account |
| identity for all other operations. |
| |
| [[non-interactive_users]] |
| Non-Interactive Users |
| ~~~~~~~~~~~~~~~~~~~~~ |
| |
| This is an internal user group, members of this group are not expected |
| to perform interactive operations on the Gerrit web frontend. |
| |
| However, sometimes such a user may need a separate thread pool in |
| order to prevent it from grabbing threads from the interactive users. |
| |
| These users live in a second thread pool, which separates operations |
| made by the non-interactive users from the ones made by the interactive |
| users. This ensures that the interactive users can keep working when |
| resources are tight. |
| |
| [[project_owners]] |
| Project Owners |
| ~~~~~~~~~~~~~~ |
| |
| Access rights assigned to this group are always evaluated within the |
| context of a project to which the access rights apply. These rights |
| therefore apply to all the users who are owners of this project. |
| |
| By assigning access rights to this group on a parent project Gerrit |
| administrators can define a set of default access rights for |
| <<category_owner,project owners>>. Child projects inherit these |
| access rights where they are resolved to the users that own the child |
| project. Having default access rights for |
| <<category_owner,project owners>> assigned on a parent project may |
| avoid the need to initially configure access rights for |
| newly created child projects. |
| |
| [[registered_users]] |
| Registered Users |
| ~~~~~~~~~~~~~~~~ |
| |
| All signed-in users are automatically a member of this group (and |
| also <<anonymous_users,'Anonymous Users'>>, see above). |
| |
| Any access rights assigned to this group are inherited by all |
| users as soon as they sign-in to Gerrit. If OpenID authentication |
| is being employed, moving from only 'Anonymous Users' into this |
| group is very easy. Caution should be taken when assigning any |
| permissions to this group. |
| |
| It is typical to assign `Code-Review -1..+1` to this group, |
| allowing signed-in users to vote on a change, but not actually |
| cause it to become approved or rejected. |
| |
| Registered users are always permitted to make and publish comments |
| on any change in any project they have `Read` access to. |
| |
| |
| Account Groups |
| -------------- |
| |
| Account groups contain a list of zero or more user account members, |
| added individually by a group owner. Any user account listed as |
| a group member is given any access rights granted to the group. |
| |
| Every group has one other group designated as its owner. Users who |
| are members of the owner group can: |
| |
| * Add users and other groups to this group |
| * Remove users and other groups from this group |
| * Change the name of this group |
| * Change the description of this group |
| * Change the owner of this group, to another group |
| |
| It is permissible for a group to own itself, allowing the group |
| members to directly manage who their peers are. |
| |
| Newly created groups are automatically created as owning themselves, |
| with the creating user as the only member. This permits the group |
| creator to add additional members, and change the owner to another |
| group if desired. |
| |
| It is somewhat common to create two groups at the same time, |
| for example `Foo` and `Foo-admin`, where the latter group |
| `Foo-admin` owns both itself and also group `Foo`. Users who |
| are members of `Foo-admin` can thus control the membership of |
| `Foo`, without actually having the access rights granted to `Foo`. |
| This configuration can help prevent accidental submits when the |
| members of `Foo` have submit rights on a project, and the members of |
| `Foo-admin` typically do not need to have such rights. |
| |
| |
| Project Access Control Lists |
| ---------------------------- |
| |
| A system wide access control list affecting all projects is stored in |
| project "`All-Projects`". This inheritance can be configured |
| through link:cmd-set-project-parent.html[gerrit set-project-parent]. |
| |
| Per-project access control lists are also supported. |
| |
| Users are permitted to use the maximum range granted to any of their |
| groups on a label. For example, a user is a member of `Foo Leads`, and |
| the following ACLs are granted on a project: |
| |
| [options="header"] |
| |=================================================== |
| |Group |Reference Name |Label |Range |
| |Anonymous Users |refs/heads/* |Code-Review|-1..+1 |
| |Registered Users|refs/heads/* |Code-Review|-1..+2 |
| |Foo Leads |refs/heads/* |Code-Review|-2..0 |
| |=================================================== |
| |
| Then the effective range permitted to be used by the user is |
| `-2..+2`, as the user is a member of all three groups (see above |
| about the system groups) and the maximum range is chosen (so the |
| lowest value granted to any group, and the highest value granted |
| to any group). |
| |
| Reference-level access control is also possible. |
| |
| Permissions can be set on a single reference name to match one |
| branch (e.g. `refs/heads/master`), or on a reference namespace |
| (e.g. `refs/heads/*`) to match any branch starting with that |
| prefix. So a permission with `refs/heads/*` will match |
| `refs/heads/master` and `refs/heads/experimental`, etc. |
| |
| Reference names can also be described with a regular expression |
| by prefixing the reference name with `^`. For example |
| `^refs/heads/[a-z]{1,8}` matches all lower case branch names |
| between 1 and 8 characters long. Within a regular expression `.` |
| is a wildcard matching any character, but may be escaped as `\.`. |
| The link:http://www.brics.dk/automaton/[dk.brics.automaton library] |
| is used for evaluation of regular expression access control |
| rules. See the library documentation for details on this |
| particular regular expression flavor. |
| |
| References can have the current user name automatically included, |
| creating dynamic access controls that change to match the currently |
| logged in user. For example to provide a personal sandbox space |
| to all developers, `refs/heads/sandbox/${username}/*` allowing |
| the user 'joe' to use 'refs/heads/sandbox/joe/foo'. |
| |
| When evaluating a reference-level access right, Gerrit will use |
| the full set of access rights to determine if the user |
| is allowed to perform a given action. For example, if a user is a |
| member of `Foo Leads`, they are reviewing a change destined for |
| the `refs/heads/qa` branch, and the following ACLs are granted |
| on the project: |
| |
| [options="header"] |
| |=============================================================== |
| |Group |Reference Name|Label |Range |Exclusive |
| |Registered Users |refs/heads/* |Code-Review| -1..+1 | |
| |Foo Leads |refs/heads/* |Code-Review| -2..+2 | |
| |QA Leads |refs/heads/qa |Code-Review| -2..+2 | |
| |=============================================================== |
| |
| Then the effective range permitted to be used by the user is |
| `-2..+2`, as the user's membership of `Foo Leads` effectively grant |
| them access to the entire reference space, thanks to the wildcard. |
| |
| Gerrit also supports exclusive reference-level access control. |
| |
| It is possible to configure Gerrit to grant an exclusive ref level |
| access control so that only users of a specific group can perform |
| an operation on a project/reference pair. This is done by ticking |
| the exclusive flag when setting the permission for the |
| `refs/heads/qa` branch. |
| |
| For example, if a user who is a member of `Foo Leads` tries to |
| review a change destined for branch `refs/heads/qa` in a project, |
| and the following ACLs are granted: |
| |
| [options="header"] |
| |============================================================== |
| |Group |Reference Name|Label |Range |Exclusive |
| |Registered Users|refs/heads/* |Code-Review| -1..+1 | |
| |Foo Leads |refs/heads/* |Code-Review| -2..+2 | |
| |QA Leads |refs/heads/qa |Code-Review| -2..+2 |X |
| |============================================================== |
| |
| Then this user will not have `Code-Review` rights on that change, |
| since there is an exclusive access right in place for the |
| `refs/heads/qa` branch. This allows locking down access for a |
| particular branch to a limited set of users, bypassing inherited |
| rights and wildcards. |
| |
| In order to grant the ability to `Code-Review` to the members of |
| `Foo Leads`, in `refs/heads/qa` then the following access rights |
| would be needed: |
| |
| [options="header"] |
| |============================================================== |
| |Group |Reference Name|Category |Range |Exclusive |
| |Registered Users|refs/heads/* |Code-Review| -1..+1 | |
| |Foo Leads |refs/heads/* |Code-Review| -2..+2 | |
| |QA Leads |refs/heads/qa |Code-Review| -2..+2 |X |
| |Foo Leads |refs/heads/qa |Code-Review| -2..+2 | |
| |============================================================== |
| |
| OpenID Authentication |
| ~~~~~~~~~~~~~~~~~~~~~ |
| |
| If the Gerrit instance is configured to use OpenID authentication, |
| an account's effective group membership will be restricted to only |
| the `Anonymous Users` and `Registered Users` groups, unless *all* |
| of its OpenID identities match one or more of the patterns listed |
| in the `auth.trustedOpenID` list from `gerrit.config`. |
| |
| All Projects |
| ~~~~~~~~~~~~ |
| |
| Any access right granted to a group within `All-Projects` |
| is automatically inherited by every other project in the same |
| Gerrit instance. These rights can be seen, but not modified, |
| in any other project's `Access` administration tab. |
| |
| Only members of the groups with the `Administrate Server` capability |
| may edit the access control list for `All-Projects`. By default this |
| capability is given to the group `Administrators`, but can be given |
| to more groups. |
| |
| Ownership of this project cannot be delegated to another group. |
| This restriction is by design. Granting ownership to another |
| group gives nearly the same level of access as membership in |
| `Administrators` does, as group members would be able to alter |
| permissions for every managed project including global capabilities. |
| |
| Per-Project |
| ~~~~~~~~~~~ |
| |
| The per-project ACL is evaluated before the global `All-Projects` ACL, |
| permitting some limited override capability to project owners. This |
| behavior is generally only useful on the `Read` category when |
| granting 'DENY' within a specific project to deny a group access. |
| |
| |
| [[access_labels]] |
| Review Labels |
| ------------- |
| |
| For every configured label `My-Name` in the project, there is a |
| corresponding permission `label-My-Name` with a range corresponding to |
| the defined values. |
| |
| Gerrit comes pre-configured with several default labels that can be |
| granted to groups within projects, enabling functionality for that |
| group's members. link:config-labels.html[Custom labels] may also be |
| defined globally or on a per-project basis. |
| |
| With the release of the Gerrit 2.2.x series, the web GUI for ACL |
| configuration was rewritten from scratch. Use this |
| <<conversion_table,table>> to better understand the access rights |
| conversions from the Gerrit 2.1.x to the Gerrit 2.2.x series. |
| |
| [[category_abandon]] |
| Abandon |
| ~~~~~~~ |
| |
| This category controls whether users are allowed to abandon changes |
| to projects in Gerrit. It can give permission to abandon a specific |
| change to a given ref. |
| |
| This also grants the permission to restore a change if the change |
| can be uploaded. |
| |
| [[category_create]] |
| Create reference |
| ~~~~~~~~~~~~~~~~ |
| |
| The create reference category controls whether it is possible to |
| create new references, branches or tags. This implies that the |
| reference must not already exist, it's not a destructive permission |
| in that you can't overwrite or remove any previously existing |
| references (and also discard any commits in the process). |
| |
| It's probably most common to either permit the creation of a single |
| branch in many gits (by granting permission on a parent project), or |
| to grant this permission to a name pattern of branches. |
| |
| This permission is often given in conjunction with regular push |
| branch permissions, allowing the holder of both to create new branches |
| as well as bypass review for new commits on that branch. |
| |
| To push lightweight (non-annotated) tags, grant |
| `Create Reference` for reference name `refs/tags/*`, as lightweight |
| tags are implemented just like branches in Git. |
| |
| For example, to grant the possibility to create new branches under the |
| namespace `foo`, you have to grant this permission on |
| `refs/heads/foo/*` for the group that should have it. |
| Finally, if you plan to grant each user a personal namespace in |
| where they are free to create as many branches as they wish, you |
| should grant the create reference permission so it's possible |
| to create new branches. This is done by using the special |
| `${username}` keyword in the reference pattern, e.g. |
| `refs/heads/sandbox/${username}/*`. If you do, it's also recommended |
| you grant the users the push force permission to be able to clean up |
| stale branches. |
| |
| |
| [[category_forge_author]] |
| Forge Author |
| ~~~~~~~~~~~~ |
| |
| Normally Gerrit requires the author and the committer identity |
| lines in a Git commit object (or tagger line in an annotated tag) to |
| match one of the registered email addresses of the uploading user. |
| This permission allows users to bypass parts of that validation, which |
| may be necessary when mirroring changes from an upstream project. |
| |
| Permits the use of an unverified author line in commit objects. |
| This can be useful when applying patches received by email from |
| 3rd parties, when cherry-picking changes written by others across |
| branches, or when amending someone else's commit to fix up a minor |
| problem before submitting. |
| |
| By default this is granted to `Registered Users` in all projects, |
| but a site administrator may disable it if verified authorship |
| is required. |
| |
| |
| [[category_forge_committer]] |
| Forge Committer |
| ~~~~~~~~~~~~~~~ |
| |
| Normally Gerrit requires the author and the committer identity |
| lines in a Git commit object (or tagger line in an annotated tag) to |
| match one of the registered email addresses of the uploading user. |
| This permission allows users to bypass parts of that validation, which |
| may be necessary when mirroring changes from an upstream project. |
| |
| Allows the use of an unverified committer line in commit objects, or an |
| unverified tagger line in annotated tag objects. Typically this is only |
| required when mirroring commits from an upstream project repository. |
| |
| |
| [[category_forge_server]] |
| Forge Server |
| ~~~~~~~~~~~~ |
| |
| Normally Gerrit requires the author and the committer identity |
| lines in a Git commit object (or tagger line in an annotated tag) to |
| match one of the registered email addresses of the uploading user. |
| This permission allows users to bypass parts of that validation, which |
| may be necessary when mirroring changes from an upstream project. |
| |
| Allows the use of the server's own name and email on the committer |
| line of a new commit object. This should only be necessary when force |
| pushing a commit history which has been rewritten by 'git filter-branch' |
| and that contains merge commits previously created by this Gerrit Code |
| Review server. |
| |
| |
| [[category_owner]] |
| Owner |
| ~~~~~ |
| |
| The `Owner` category controls which groups can modify the project's |
| configuration. Users who are members of an owner group can: |
| |
| * Change the project description |
| * Create/delete a branch through the web UI (not SSH) |
| * Grant/revoke any access rights, including `Owner` |
| |
| Note that project owners implicitly have branch creation or deletion |
| through the web UI, but not through SSH. To get SSH branch access |
| project owners must grant an access right to a group they are a |
| member of, just like for any other user. |
| |
| Ownership over a particular branch subspace may be delegated by |
| entering a branch pattern. To delegate control over all branches |
| that begin with `qa/` to the QA group, add `Owner` category |
| for reference `refs/heads/qa/*`. Members of the QA group can |
| further refine access, but only for references that begin with |
| `refs/heads/qa/`. See <<project_owners,project owners>> to find |
| out more about this role. |
| |
| |
| [[category_push]] |
| Push |
| ~~~~ |
| |
| This category controls how users are allowed to upload new commits |
| to projects in Gerrit. It can either give permission to push |
| directly into a branch, bypassing any code review process |
| that would otherwise be used. Or it may give permission to upload |
| new changes for code review, this depends on which namespace the |
| permission is granted to. |
| |
| |
| [[category_push_direct]] |
| Direct Push |
| ^^^^^^^^^^^ |
| |
| Any existing branch can be fast-forwarded to a new commit. |
| Creation of new branches is controlled by the |
| link:access-control.html#category_create['Create Reference'] |
| category. Deletion of existing branches is rejected. This is the |
| safest mode as commits cannot be discarded. |
| |
| * Force option |
| + |
| Allows an existing branch to be deleted. Since a force push is |
| effectively a delete immediately followed by a create, but performed |
| atomically on the server and logged, this option also permits forced |
| push updates to branches. Enabling this option allows existing commits |
| to be discarded from a project history. |
| |
| The push category is primarily useful for projects that only want to |
| take advantage of Gerrit's access control features and do not need |
| its code review functionality. Projects that need to require code |
| reviews should not grant this category. |
| |
| |
| [[category_push_review]] |
| Upload To Code Review |
| ^^^^^^^^^^^^^^^^^^^^^ |
| |
| The `Push` access right granted on the namespace |
| `refs/for/refs/heads/BRANCH` permits the user to upload a non-merge |
| commit to the project's `refs/for/BRANCH` namespace, creating a new |
| change for code review. |
| |
| A user must be able to clone or fetch the project in order to create |
| a new commit on their local system, so in practice they must also |
| have the `Read` access granted to upload a change. |
| |
| For an open source, public Gerrit installation, it is common to |
| grant `Read` and `Push` for `refs/for/refs/heads/*` |
| to `Registered Users` in the `All-Projects` ACL. For more |
| private installations, its common to simply grant `Read` and |
| `Push` for `refs/for/refs/heads/*` to all users of a project. |
| |
| * Force option |
| + |
| The force option has no function when granted to a branch in the |
| `refs/for/refs/heads/*` namespace. |
| |
| |
| [[category_push_merge]] |
| Push Merge Commits |
| ~~~~~~~~~~~~~~~~~~~~ |
| |
| The `Push Merge Commit` access right permits the user to upload merge |
| commits. It's an addon to the <<category_push,Push>> access right, and |
| so it won't be sufficient with only `Push Merge Commit` granted for a |
| push to happen. Some projects wish to restrict merges to being created |
| by Gerrit. By granting `Push` without `Push Merge Commit`, the only |
| merges that enter the system will be those created by Gerrit. |
| |
| The reference name connected to a `Push Merge Commit` entry must always |
| be prefixed with `refs/for/`, for example `refs/for/refs/heads/BRANCH`. |
| This applies even for an entry that complements a `Push` entry for |
| `refs/heads/BRANCH` that allows direct pushes of non-merge commits, and |
| the intention of the `Push Merge Commit` entry is to allow direct pushes |
| of merge commits. |
| |
| [[category_push_annotated]] |
| Push Annotated Tag |
| ~~~~~~~~~~~~~~~~~~ |
| |
| This category permits users to push an annotated tag object into the |
| project's repository. Typically this would be done with a command line |
| such as: |
| |
| ==== |
| git push ssh://USER@HOST:PORT/PROJECT tag v1.0 |
| ==== |
| |
| Or: |
| |
| ==== |
| git push https://HOST/PROJECT tag v1.0 |
| ==== |
| |
| Tags must be annotated (created with `git tag -a`), should exist in |
| the `refs/tags/` namespace, and should be new. |
| |
| This category is intended to be used to publish tags when a project |
| reaches a stable release point worth remembering in history. |
| |
| It allows for a new annotated (unsigned) tag to be created. The |
| tagger email address must be verified for the current user. |
| |
| To push tags created by users other than the current user (such |
| as tags mirrored from an upstream project), `Forge Committer Identity` |
| must be also granted in addition to `Push Annotated Tag`. |
| |
| To push lightweight (non annotated) tags, grant |
| <<category_create,`Create Reference`>> for reference name |
| `refs/tags/*`, as lightweight tags are implemented just like |
| branches in Git. |
| |
| To delete or overwrite an existing tag, grant `Push` with the force |
| option enabled for reference name `refs/tags/*`, as deleting a tag |
| requires the same permission as deleting a branch. |
| |
| |
| [[category_push_signed]] |
| Push Signed Tag |
| ~~~~~~~~~~~~~~~ |
| |
| This category permits users to push a PGP signed tag object into the |
| project's repository. Typically this would be done with a command |
| line such as: |
| |
| ==== |
| git push ssh://USER@HOST:PORT/PROJECT tag v1.0 |
| ==== |
| |
| Or: |
| |
| ==== |
| git push https://HOST/PROJECT tag v1.0 |
| ==== |
| |
| Tags must be signed (created with `git tag -s`), should exist in the |
| `refs/tags/` namespace, and should be new. |
| |
| |
| [[category_read]] |
| Read |
| ~~~~ |
| |
| The `Read` category controls visibility to the project's |
| changes, comments, code diffs, and Git access over SSH or HTTP. |
| A user must have this access granted in order to see a project, its |
| changes, or any of its data. |
| |
| This category has a special behavior, where the per-project ACL is |
| evaluated before the global all projects ACL. If the per-project |
| ACL has granted `Read` with 'DENY', and does not otherwise grant |
| `Read` with 'ALLOW', then a `Read` in the all projects ACL |
| is ignored. This behavior is useful to hide a handful of projects |
| on an otherwise public server. |
| |
| For an open source, public Gerrit installation it is common to grant |
| `Read` to `Anonymous Users` in the `All-Projects` ACL, enabling |
| casual browsing of any project's changes, as well as fetching any |
| project's repository over SSH or HTTP. New projects can be |
| temporarily hidden from public view by granting `Read` with 'DENY' |
| to `Anonymous Users` and granting `Read` to the project owner's |
| group within the per-project ACL. |
| |
| For a private Gerrit installation using a trusted HTTP authentication |
| source, granting `Read` to `Registered Users` may be more |
| typical, enabling read access only to those users who have been |
| able to authenticate through the HTTP access controls. This may |
| be suitable in a corporate deployment if the HTTP access control |
| is already restricted to the correct set of users. |
| |
| |
| [[category_rebase]] |
| Rebase |
| ~~~~~~ |
| |
| This category permits users to rebase changes via the web UI by pushing |
| the `Rebase Change` button. |
| |
| The change owner and submitters can always rebase changes in the web UI |
| (even without having the `Rebase` access right assigned). |
| |
| Users without this access right who are able to upload new patch sets |
| can still do the rebase locally and upload the rebased commit as a new |
| patch set. |
| |
| [[category_remove_reviewer]] |
| Remove Reviewer |
| ~~~~~~~~~~~~~~~ |
| |
| This category permits users to remove other users from the list of |
| reviewers on a change. |
| |
| The change owner, project owner and site administrator can always |
| remove reviewers (even without having the `Remove Reviewer` access |
| right assigned). |
| |
| Users without this access right can only remove themselves from the |
| reviewer list on a change. |
| |
| |
| [[category_submit]] |
| Submit |
| ~~~~~~ |
| |
| This category permits users to push the `Submit Patch Set n` button |
| on the web UI. |
| |
| Submitting a change causes it to be merged into the destination |
| branch as soon as possible, making it a permanent part of the |
| project's history. |
| |
| In order to submit, all labels (such as `Verified` and `Code-Review`, |
| above) must enable submit, and also must not block it. See above for |
| details on each label. |
| |
| |
| [[category_view_drafts]] |
| View Drafts |
| ~~~~~~~~~~~ |
| |
| This category permits users to view draft changes uploaded by other |
| users. |
| |
| The change owner and any explicitly added reviewers can always see |
| draft changes (even without having the `View Drafts` access right |
| assigned). |
| |
| |
| [[category_publish_drafts]] |
| Publish Drafts |
| ~~~~~~~~~~~~~~ |
| |
| This category permits users to publish draft changes uploaded by other |
| users. |
| |
| The change owner can always publish draft changes (even without having |
| the `Publish Drafts` access right assigned). |
| |
| |
| [[category_delete_drafts]] |
| Delete Drafts |
| ~~~~~~~~~~~~~ |
| |
| This category permits users to delete draft changes uploaded by other |
| users. |
| |
| The change owner can always delete draft changes (even without having |
| the `Delete Drafts` access right assigned). |
| |
| |
| [[category_edit_topic_name]] |
| Edit Topic Name |
| ~~~~~~~~~~~~~~~ |
| |
| This category permits users to edit the topic name of a change that |
| is uploaded for review. |
| |
| The change owner, branch owners, project owners, and site administrators |
| can always edit the topic name (even without having the `Edit Topic Name` |
| access right assigned). |
| |
| |
| Examples of typical roles in a project |
| -------------------------------------- |
| |
| Below follows a set of typical roles on a server and which access |
| rights these roles typically should be granted. You may see them as |
| general guidelines for a typical way to set up your project on a |
| brand new Gerrit instance. |
| |
| [[examples_contributor]] |
| Contributor |
| ~~~~~~~~~~~ |
| |
| This is the typical user on a public server. They are able to read |
| your project and upload new changes to it. They are able to give |
| feedback on other changes as well, but are unable to block or approve |
| any changes. |
| |
| Suggested access rights to grant: |
| |
| * xref:category_read[`Read`] on 'refs/heads/\*' and 'refs/tags/*' |
| * xref:category_push[`Push`] to 'refs/for/refs/heads/*' |
| * link:config-labels.html#label_Code-Review[`Code-Review`] with range '-1' to '+1' for 'refs/heads/*' |
| |
| |
| [[examples_developer]] |
| Developer |
| ~~~~~~~~~ |
| |
| This is the typical core developer on a public server. They are able |
| to read the project, upload changes to a branch. They are allowed to |
| push merge commits to merge branches together. Also, they are allowed |
| to forge author identity, thus handling commits belonging to others |
| than themselves, effectively allowing them to transfer commits |
| between different branches. |
| |
| They are furthermore able to code review and verify commits, and |
| eventually submit them. If you have an automated CI system that |
| builds all uploaded patch sets you might want to skip the |
| verification rights for the developer and let the CI system do that |
| exclusively. |
| |
| Suggested access rights to grant: |
| |
| * xref:category_read[`Read`] on 'refs/heads/\*' and 'refs/tags/*' |
| * xref:category_push[`Push`] to 'refs/for/refs/heads/*' |
| * xref:category_push_merge[`Push merge commit`] to 'refs/for/refs/heads/*' |
| * xref:category_forge_author[`Forge Author Identity`] to 'refs/heads/*' |
| * link:config-labels.html#label_Code-Review[`Label: Code-Review`] with range '-2' to '+2' for 'refs/heads/*' |
| * link:config-labels.html#label_Verified[`Label: Verify`] with range '-1' to '+1' for 'refs/heads/*' |
| * xref:category_submit[`Submit`] |
| |
| If the project is small or the developers are seasoned it might make |
| sense to give them the freedom to push commits directly to a branch. |
| |
| Optional access rights to grant: |
| |
| * <<category_push,`Push`>> to 'refs/heads/*' |
| * <<category_push_merge,`Push merge commit`>> to 'refs/heads/*' |
| |
| |
| [[examples_cisystem]] |
| CI system |
| ~~~~~~~~~ |
| |
| A typical Continous Integration system should be able to download new changes |
| to build and then leave a verdict somehow. |
| |
| As an example, the popular |
| link:https://wiki.jenkins-ci.org/display/JENKINS/Gerrit+Trigger[gerrit-trigger plugin] |
| for Jenkins/Hudson can set labels at: |
| |
| * The start of a build |
| * A successful build |
| * An unstable build (tests fails) |
| * A failed build |
| |
| Usually the range chosen for this verdict is the verify label. Depending on |
| the size of your project and discipline of involved developers you might want |
| to limit access right to the +1 `Verify` label to the CI system only. That |
| way it's guaranteed that submitted commits always get built and pass tests |
| successfully. |
| |
| If the build doesn't complete successfully the CI system can set the |
| `Verify` label to -1. However that means that a failed build will block |
| submit of the change even if someone else sets `Verify` +1. Depending on the |
| project and how much the CI system can be trusted for accurate results, a |
| blocking label might not be feasible. A recommended alternative is to set the |
| label `Code-review` to -1 instead, as it isn't a blocking label but still |
| shows a red label in the Gerrit UI. Optionally, to enable the possibility to |
| deliver different results (build error vs unstable for instance), it's also |
| possible to set `Code-review` +1 as well. |
| |
| If pushing new changes is granted, it's possible to automate cherry-pick of |
| submitted changes for upload to other branches under certain conditions. This |
| is probably not the first step of what a project wants to automate however, |
| and so the push right can be found under the optional section. |
| |
| Suggested access rights to grant, that won't block changes: |
| |
| * xref:category_read[`Read`] on 'refs/heads/\*' and 'refs/tags/*' |
| * link:config-labels.html#label_Code-Review[`Label: Code-Review`] with range '-1' to '0' for 'refs/heads/*' |
| * link:config-labels.html#label_Verified[`Label: Verify`] with range '0' to '+1' for 'refs/heads/*' |
| |
| Optional access rights to grant: |
| |
| * link:config-labels.html#label_Code-Review[`Label: Code-Review`] with range '-1' to '+1' for 'refs/heads/*' |
| * xref:category_push[`Push`] to 'refs/for/refs/heads/*' |
| |
| |
| [[examples_integrator]] |
| Integrator |
| ~~~~~~~~~~ |
| |
| Integrators are like developers but with some additional rights granted due |
| to their administrative role in a project. They can upload or push any commit |
| with any committer email (not just their own) and they can also create new |
| tags and branches. |
| |
| Suggested access rights to grant: |
| |
| * <<examples_developer,Developer rights>> |
| * <<category_push,`Push`>> to 'refs/heads/*' |
| * <<category_push_merge,`Push merge commit`>> to 'refs/heads/*' |
| * <<category_forge_committer,`Forge Committer Identity`>> to 'refs/for/refs/heads/*' |
| * <<category_create,`Create Reference`>> to 'refs/heads/*' |
| * <<category_push_annotated,`Push Annotated Tag`>> to 'refs/tags/*' |
| |
| |
| [[examples_project-owner]] |
| Project owner |
| ~~~~~~~~~~~~~ |
| |
| The project owner is almost like an integrator but with additional destructive |
| power in the form of being able to delete branches. Optionally these users |
| also have the power to configure access rights in gits assigned to them. |
| |
| [WARNING] |
| These users should be really knowledgable about git, for instance knowing why |
| tags never should be removed from a server. This role is granted potentially |
| destructive access rights and cleaning up after such a mishap could be time |
| consuming! |
| |
| Suggested access rights to grant: |
| |
| * <<examples_integrator,Integrator rights>> |
| * <<category_push,`Push`>> with the force option to 'refs/heads/\*' and 'refs/tags/*' |
| |
| Optional access right to grant: |
| |
| * <<category_owner,`Owner`>> in the gits they mostly work with. |
| |
| [[examples_administrator]] |
| Administrator |
| ~~~~~~~~~~~~~ |
| |
| The administrator role is the most powerful role known in the Gerrit universe. |
| This role may grant itself (or others) any access right, and it already has |
| all capabilities granted as well. By default the |
| <<administrators,`Administrators` group>> is the group that has this role. |
| |
| Mandatory access rights: |
| |
| * <<capability_administrateServer,The `Administrate Server` capability>> |
| |
| Suggested access rights to grant: |
| |
| * <<examples_project-owner,Project owner rights>> |
| |
| Enforcing site wide access policies |
| ----------------------------------- |
| |
| By granting the <<category_owner,`Owner`>> access right on the `refs/*` to a |
| group, Gerrit administrators can delegate the responsibility of maintaining |
| access rights for that project to that group. |
| |
| In a corporate deployment it is often necessary to enforce some access |
| policies. An example could be that no-one can update or delete a tag, not even |
| the project owners. The 'ALLOW' and 'DENY' rules are not enough for this |
| purpose as project owners can grant themselves any access right they wish and, |
| thus, effectively override any inherited access rights from the |
| "`All-Projects`" or some other common parent project. |
| |
| What is needed is a mechanism to block a permission in a parent project so |
| that even project owners cannot allow a blocked permission in their child |
| project. Still, project owners should retain the possibility to manage all |
| non-blocked rules as they wish. This gives best of both worlds: |
| |
| * Gerrit administrators can concentrate on enforcing site wide policies |
| and providing a meaningful set of default access permissions |
| * Project owners can manage access rights of their projects without a danger |
| of violating a site wide policy |
| |
| [[block]] |
| 'BLOCK' access rule |
| ~~~~~~~~~~~~~~~~~~~ |
| |
| The 'BLOCK' rule blocks a permission globally. An inherited 'BLOCK' rule cannot |
| be overridden in the inheriting project. Any 'ALLOW' rule, from a different |
| access section or from an inheriting project, which conflicts with an |
| inherited 'BLOCK' rule will not be honored. Searching for 'BLOCK' rules, in |
| the chain of parent projects, ignores the Exclusive flag that is normally |
| applied to access sections. |
| |
| A 'BLOCK' rule that blocks the 'push' permission blocks any type of push, |
| force or not. A blocking force push rule blocks only force pushes, but |
| allows non-forced pushes if an 'ALLOW' rule would have permitted it. |
| |
| It is also possible to block label ranges. To block a group 'X' from voting |
| '-2' and '+2', but keep their existing voting permissions for the '-1..+1' |
| range intact we would define: |
| |
| ==== |
| [access "refs/heads/*"] |
| label-Code-Review = block -2..+2 group X |
| ==== |
| |
| The interpretation of the 'min..max' range in case of a blocking rule is: block |
| every vote from '-INFINITE..min' and 'max..INFINITE'. For the example above it |
| means that the range '-1..+1' is not affected by this block. |
| |
| 'BLOCK' and 'ALLOW' rules in the same access section |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| When an access section of a project contains a 'BLOCK' and an 'ALLOW' rule for |
| the same permission then this 'ALLOW' rule overrides the 'BLOCK' rule: |
| |
| ==== |
| [access "refs/heads/*"] |
| push = block group X |
| push = group Y |
| ==== |
| |
| In this case a user which is a member of the group 'Y' will still be allowed to |
| push to 'refs/heads/*' even if it is a member of the group 'X'. |
| |
| NOTE: An 'ALLOW' rule overrides a 'BLOCK' rule only when both of them are |
| inside the same access section of the same project. An 'ALLOW' rule in a |
| different access section of the same project or in any access section in an |
| inheriting project cannot override a 'BLOCK' rule. |
| |
| Examples |
| ~~~~~~~~ |
| |
| The following examples show some possible use cases for the 'BLOCK' rules. |
| |
| Make sure no one can update or delete a tag |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| This requirement is quite common in a corporate deployment where |
| reproducibility of a build must be guaranteed. To achieve that we block 'push' |
| permission for the <<anonymous_users,'Anonymous Users'>> in "`All-Projects`": |
| |
| ==== |
| [access "refs/tags/*"] |
| push = block group Anonymous Users |
| ==== |
| |
| By blocking the <<anonymous_users,'Anonymous Users'>> we effectively block |
| everyone as everyone is a member of that group. Note that the permission to |
| create a tag is still necessary. Assuming that only <<category_owner,project |
| owners>> are allowed to create tags, we would extend the example above: |
| |
| ==== |
| [access "refs/tags/*"] |
| push = block group Anonymous Users |
| create = group Project Owners |
| pushTag = group Project Owners |
| ==== |
| |
| Let only a dedicated group vote in a special category |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| Assume there is a more restrictive process for submitting changes in stable |
| release branches which is manifested as a new voting category |
| 'Release-Process'. Assume we want to make sure that only a 'Release Engineers' |
| group can vote in this category and that even project owners cannot approve |
| this category. We have to block everyone except the 'Release Engineers' to vote |
| in this category and, of course, allow 'Release Engineers' to vote in that |
| category. In the "`All-Projects`" we define the following rules: |
| |
| ==== |
| [access "refs/heads/stable*"] |
| label-Release-Proces = block -1..+1 group Anonymous Users |
| label-Release-Proces = -1..+1 group Release Engineers |
| ==== |
| |
| [[conversion_table]] |
| Conversion table from 2.1.x series to 2.2.x series |
| -------------------------------------------------- |
| |
| [options="header"] |
| |================================================================================= |
| |Gerrit 2.1.x |Gerrit 2.2.x |
| |Code review |link:config-labels.html#label_Code-Review[Label: Code-Review] |
| |Verify |link:config-labels.html#label_Verified[Label: Verify] |
| |Forge Identity +1 |Forge <<category_forge_author,author>> identity |
| |Forge Identity +2 |Forge <<category_forge_committer,committer>> & <<category_forge_author,author>> identity |
| |Forge Identity +3 |Forge <<category_forge_server,server>> & <<category_forge_committer,committer>> & <<category_forge_author,author>> identity |
| |Owner |<<category_owner,Owner>> |
| |Push branch +1 |<<category_push_direct,Push>> |
| |Push branch +2 |<<category_create,Create reference>> & <<category_push_direct,Push>> |
| |Push branch +3 |<<category_push_direct,Push>> (with force) & <<category_create,Create reference>> |
| |Push tag +1 & Push Branch +2 |No support to limit to push signed tag |
| |Push tag +2 & Push Branch +2 |<<category_push_annotated,Push annotated tag>> |
| |Push Branch +2 (refs/tags/*) |<<category_create,Create reference>> (refs/tags/...) |
| |Push Branch +3 (refs/tags/*) |<<category_push_direct,Push>> (with force on refs/tags/...) |
| |Read +1 |<<category_read,Read>> |
| |Read +2 |<<category_read,Read>> & <<category_push_review,Push>> (refs/for/refs/...) |
| |Read +3 |<<category_read,Read>> & <<category_push_review,Push>> (refs/for/refs/...) & <<category_push_merge,Push Merge Commit>> |
| |Submit |<<category_submit,Submit>> |
| |================================================================================= |
| |
| |
| [NOTE] |
| In Gerrit 2.2.x, the way to set permissions for upload has changed entirely. |
| To upload a change for review is no longer a separate permission type, |
| instead you grant ordinary push permissions to the actual |
| recieving reference. In practice this means that you set push permissions |
| on `refs/for/refs/heads/<branch>` rather than permissions to upload changes |
| on `refs/heads/<branch>`. |
| |
| |
| [[system_capabilities]] |
| System capabilities |
| ------------------- |
| |
| The system capabilities control actions that the administrators of |
| the server can perform which usually affect the entire |
| server in some way. The administrators may delegate these |
| capabilities to trusted groups of users. |
| |
| Delegation of capabilities allows groups to be granted a subset of |
| administrative capabilities without being given complete |
| administrative control of the server. This makes it possible to |
| keep fewer users in the administrators group, even while spreading |
| much of the server administration burden out to more users. |
| |
| Below you find a list of capabilities available: |
| |
| |
| [[capability_administrateServer]] |
| Administrate Server |
| ~~~~~~~~~~~~~~~~~~~ |
| |
| This is in effect the owner and administrator role of the Gerrit |
| instance. Any members of a group granted this capability will be |
| able to grant any access right to any group. They will also have all |
| capabilities granted to them automatically. |
| |
| |
| [[capability_createAccount]] |
| Create Account |
| ~~~~~~~~~~~~~~ |
| |
| Allow link:cmd-create-account.html[account creation over the ssh prompt]. |
| This capability allows the granted group members to create non-interactive |
| service accounts. These service accounts are generally used for automation |
| and made to be members of the |
| link:access-control.html#non-interactive_users['Non-Interactive users'] group. |
| |
| |
| [[capability_createGroup]] |
| Create Group |
| ~~~~~~~~~~~~ |
| |
| Allow group creation. Groups are used to grant users access to different |
| actions in projects. This capability allows the granted group members to |
| either link:cmd-create-group.html[create new groups via ssh] or via the web UI. |
| |
| |
| [[capability_createProject]] |
| Create Project |
| ~~~~~~~~~~~~~~ |
| |
| Allow project creation. This capability allows the granted group to |
| either link:cmd-create-project.html[create new git projects via ssh] |
| or via the web UI. |
| |
| [[capability_emailReviewers]] |
| Email Reviewers |
| ~~~~~~~~~~~~~~~ |
| |
| Allow or deny sending email to change reviewers and watchers. This can be used |
| to deny build bots from emailing reviewers and people who watch the change. |
| Instead, only the authors of the change and those who starred it will be |
| emailed. The allow rules are evaluated before deny rules, however the default |
| is to allow emailing, if no explicit rule is matched. |
| |
| [[capability_flushCaches]] |
| Flush Caches |
| ~~~~~~~~~~~~ |
| |
| Allow the flushing of Gerrit's caches. This capability allows the granted |
| group to link:cmd-flush-caches.html[flush some or all Gerrit caches via ssh]. |
| |
| [NOTE] |
| This capability doesn't imply permissions to the show-caches command. For that |
| you need the <<capability_viewCaches,view caches capability>>. |
| |
| |
| [[capability_kill]] |
| Kill Task |
| ~~~~~~~~~ |
| |
| Allow the operation of the link:cmd-kill.html[kill command over ssh]. The |
| kill command ends tasks that currently occupy the Gerrit server, usually |
| a replication task or a user initiated task such as an upload-pack or |
| recieve-pack. |
| |
| |
| [[capability_priority]] |
| Priority |
| ~~~~~~~~ |
| |
| This capability allows users to use |
| link:config-gerrit.html#sshd.batchThreads[the thread pool reserved] for |
| link:access-control.html#non-interactive_users['Non-Interactive Users']. |
| It's a binary value in that granted users either have access to the thread |
| pool, or they don't. |
| |
| There are three modes for this capability and they're listed by rising |
| priority: |
| |
| No capability configured.:: |
| The user isn't a member of a group with any priority capability granted. By |
| default the user is then in the 'INTERACTIVE' thread pool. |
| |
| 'BATCH':: |
| If there's a thread pool configured for 'Non-Interactive Users' and a user is |
| granted the priority capability with the 'BATCH' mode selected, the user ends |
| up in the separate batch user thread pool. This is true unless the user is |
| also granted the below 'INTERACTIVE' option. |
| |
| 'INTERACTIVE':: |
| If a user is granted the priority capability with the 'INTERACTIVE' option, |
| regardless if they also have the 'BATCH' option or not, they are in the |
| 'INTERACTIVE' thread pool. |
| |
| |
| [[capability_queryLimit]] |
| Query Limit |
| ~~~~~~~~~~~ |
| |
| Allow site administrators to configure the query limit for users to |
| be above the default hard-coded value of 500. Administrators can add |
| a global block to `All-Projects` with group(s) that |
| should have different limits: |
| |
| When applying a query limit to a user the largest value granted by |
| any of their groups is used. |
| |
| This limit applies not only to the link:cmd-query.html[`gerrit query`] |
| command, but also to the web UI results pagination size. |
| |
| |
| [[capability_accessDatabase]] |
| Access Database |
| ~~~~~~~~~~~~~~~ |
| |
| Allow users to access the database using the `gsql` command. |
| |
| |
| [[capability_runGC]] |
| Run Garbage Collection |
| ~~~~~~~~~~~~~~~~~~~~~~ |
| |
| Allow users to run the Git garbage collection for the repositories of |
| all projects. |
| |
| |
| [[capability_startReplication]] |
| Start Replication |
| ~~~~~~~~~~~~~~~~~ |
| |
| Allow access to execute `replication start` command, if the |
| replication plugin is installed on the server. |
| |
| |
| [[capability_viewCaches]] |
| View Caches |
| ~~~~~~~~~~~ |
| |
| Allow querying for status of Gerrit's internal caches. This capability allows |
| the granted group to |
| link:cmd-show-caches.html[look at some or all Gerrit caches via ssh]. |
| |
| |
| [[capability_viewConnections]] |
| View Connections |
| ~~~~~~~~~~~~~~~~ |
| |
| Allow querying for status of Gerrit's current client connections. This |
| capability allows the granted group to |
| link:cmd-show-connections.html[look at Gerrit's current connections via ssh]. |
| |
| |
| [[capability_viewQueue]] |
| View Queue |
| ~~~~~~~~~~ |
| |
| Allow querying for status of Gerrit's internal task queue. This capability |
| allows the granted group to |
| link:cmd-show-queue.html[look at the Gerrit task queue via ssh]. |
| |
| |
| GERRIT |
| ------ |
| Part of link:index.html[Gerrit Code Review] |