Documentation/config-groups.txt

= Gerrit Code Review - Groups

== Overview

In Gerrit, we assign permissions to groups of accounts. These groups
can be provided by an external system such as LDAP, but Gerrit also
has a group system built-in ("internal groups")

Starting from 2.16, these internal groups are fully stored in
link:note-db.html[NoteDb].

A group is characterized by the following information:

* list of members (accounts)
* list of subgroups
* properties
  - visibleToAll
  - group owner

Groups are keyed by the following unique identifiers:

* GroupID, the former database key (a sequential number)

* UUID, an opaque identifier. Internal groups use a 40 byte hex string
as UUID

* Name: Gerrit enforces that group names are unique

== Storage format

Group data is stored in the
link:config-accounts.html#all-users[`All-Users` repository]. For each
group, there is a ref, stored as a sharded UUID, e.g.

----
  refs/groups/ef/deafbeefdeafbeefdeafbeefdeafbeefdeafbeef
----

The ref points to commits holding files. The files are

* `members`, holding numeric account IDs of members, one per line
* `subgroups`, holding group UUIDs of subgroups, one per line
* `group.config`, holding further configuration.

The `group.config` file follows the following format

----
[group]
  name = <name of the group>
  id = 42
  visibleToAll = false
  description = <description of the group>
  groupOwnerUuid = <UUID of the owner group>
----

Gerrit updates the ref for a group based on REST API calls, and the
commit log effectively forms an audit log which shows how group
membership evolved over time.

To ensure uniqueness of the name, a separate ref
`refs/meta/group-names` contains a notemap, ie. a map represented as a
branch with a flat list of files.

The format of this map is as follows:

* keys are the normal SHA-1 of the group name
* values are blobs that look like
+
----
[group]
  name = <name of the group>
  uuid = <hex UUID identifier of the group>
----

To ensure uniqueness of the sequential ID, the ID for each new group
is taken from the sequence counter under `refs/sequences/groups`,
which works analogously to the ones for accounts and changes.

== Visibility

Group ownership together with `visibleToAll` determines visibility of
the groups in the REST API.

Fetching a group ref is permitted to the group's owners that also have
READ permissions on the ref. For users that are not owners, the
permissions on the ref are ignored. In addition, anyone with the
link:access-control.html#capability_accessDatabase[Access Database]
capability can read all group refs. The `refs/meta/group-names` ref is
visible only to users with the
link:access-control.html#capability_accessDatabase[Access Database]
capability.

== Pushing to group refs

Validation on push for changes to the group ref is not implemented, so
pushes are rejected. Pushes that bypass Gerrit should be avoided since
the names, IDs and UUIDs must be internally consistent between all the
branches involved. In addition, group references should not be created
or deleted manually either. If you attempt any of these actions
anyway, don't forget to link:rest-api-groups.html#index-group[Index
Group] reindex the affected groups manually.

== Replication

In a replicated setting (eg. backups and or primary/replica configurations), all
refs in the `All-Users` project on primary nodes must be copied onto all
replicas, including `refs/groups/*`, `refs/meta/group-names` and
`refs/sequences/groups`.