GitLab/Policy

This page describes intended policy for GitLab. It covers topics like the expected layout of projects, access control, administrative privileges, enabled features, and expectations of users.

This is a work in progress, and will naturally evolve as we migrate projects to GitLab. Substantive changes should be made in collaboration with the Wikimedia Release Engineering Team and affected users. Feel free to ask questions in #wikimedia-gitlab ^connect on libera.chat, tagged with the Gitlab project on Phabricator, or on the talk page here.

Project layout

Users

A user is a unique identifier for a person identified by an email. Each user has a unique username. A user's username is also a unique top-level namespace in GitLab.

All users login to GitLab with their LDAP developer accounts. A user's display name is their LDAP cn (as is the case with Gerrit), while usernames (which determine profile URLs) are uid, matching shell names. This avoids using ReCaptcha software for account creation.

Users with Developer privileges (or above) outside of their personal namespaces—those who merge code—must have two-factor authentication enabled on their account.

Namespace Groups

Groups are local to the GitLab instance. Groups can act as containers for subgroups.

All officially-supported projects live in one of the top-level namespaces:

Path	Purpose
repos	General projects, including MediaWiki
toolforge-repos	Toolforge tools
cloudvps-repos	Cloud VPS projects

Job runners for CI may be allocated to these groups according to differing security profiles, as needed. Subgroups of these top-level groups (typically repos) act as namespaces for projects, as well as modeling contributor access to those projects. These should be reserved for large functional areas that encompass projects. Although it may be similar, this is not the same thing as a team or organizational unit, since the team responsible for a code project may change.

For example, repos/mediawiki is a namespace group that can contain the project repos/mediawiki/core. More layers of group nesting may be useful. For example, a repos/mediawiki/extensions namespace group is a subgroup of the repos/mediawiki namespace group and may contain MediaWiki extensions.

Membership / ownership

Individual users should be added as privileged members of namespace groups.

For most small groups of projects, it is appropriate for collaborators to own the group and self-manage access for other collaborators.

For larger and higher-risk groups such as /repos/mediawiki, we will define stricter access schemes with more than one level of access.

MediaWiki namespace

For MediaWiki core, extensions, skins, and services, our intention is to migrate the structure used on Gerrit, with some minor changes. Unlike repositories on Gerrit, GitLab projects cannot contain sub-projects, so extensions and skins will need to be handled differently. For example, the repo at mediawiki/extensions on Gerrit will become repos/mediawiki/extensions-all, while repos/mediawiki/extensions will be a group containing individual extensions.

repos/mediawiki/
├── [core]
├── extensions
│   ├── [extension1]
│   ├── [extension2]
│   └── [extension3]
├── [extensions-all]
├── libs
│   ├── [library1]
│   ├── [library2]
│   └── [library3]
├── services
│   ├── [service1]
│   ├── [service2]
│   └── [service3]
├── skins
│   ├── [skin1]
│   ├── [skin2]
│   └── [skin3]
├── [skins-all]
├── tools
│   ├── [tool1]
│   ├── [tool2]
│   └── [tool3]
└── [vendor]

MediaWiki permission model

GitLab roles are described under Permissions and roles in the GitLab docs.

For repos/mediawiki:

• Trusted users who contribute code get the Developer role in repos/mediawiki by default.
  • Includes the LDAP groups: wmf, ops.
  • Includes contributors added individually to the group.
• Protected branches and tags are configured on a per-project basis. In general, these will include main along with release branches and tags.
• Individual projects may restrict merging to protected branches to Maintainers, and contributors who need this capability can be added directly to the project as a Maintainer or Owner.
• Contributors who only work on a specific extension or service may be added directly to that project.

The following table attempts to summarize who can do what with respect to repos/mediawiki.

Role breakdown

GitLab Role	Summary	Capabilities
All users	Contributors with an active GitLab account.	Fork projects to their own user namespace. Create merge requests for main and other protected branches, from their fork.
Developers	Trusted routine contributors.	Create new work branches (e.g. review/[username]/[topic]). Create merge requests for main and other protected branches. Merge requests into protected branches, where allowed. Create new projects but not subgroups.
Maintainers	Contributors with elevated privileges.	Merge requests into protected branches where a more restricted workflow is necessary. Create new projects and subgroups. Manage most project settings. Manage project membership. Alter permissions on protected branches.
Owners	Users who administer either the overall structure of repos/mediawiki or a project within it.	Manage group settings. Manage group membership. Push directly to protected branches (main, release branches). Delete projects.

Projects

Projects are collaborative digital spaces to write, review, test, merge, and browse code in GitLab. A project corresponds to a Git repository. Projects belong to either an individual user (for example thcipriani/train-stats) or a namespace group under /repos (for example repos/releng/dev-images).

Permissions

Projects have features that contain specific permissions.

To ensure everyone can contribute, projects should allow "Everyone with Access" to create merge requests. This is a setting for each repository under "Settings" > "General" > "Visibility, project features, permissions" > "Repository". This will allow all users to create merge requests for a project.

Membership

In general, project membership should be inherited from a containing namespace group that models a functional area of code, as described in #Membership_/_ownership.

Projects may also have individual members with privileges. Project members are users or, potentially, user groups. For specific forms of collaboration it may appropriate to add individual users as privileged project members.

Namespace inheritance

Projects belong to namespace groups. Namespace groups may contain members. Members of a namespace are also members of a project in that namespace. For example, if you are a member of the repos/mediawiki namespace group you will also be a member of the repos/mediawiki/core project.

User groups may be used in the future

When GitLab project migration began, Release Engineering assumed that groups of users would be the best way to model membership in projects. For a number of reasons, this proved impractical. See GitLab: Rethinking how we handle access control for some reasoning about this. Nevertheless, the /people namespace is reserved for possible future use where appropriate.

Groups in GitLab can contain members. Members of a group are individual users or other groups. User groups can be useful models of real world associations of people.

Examples of useful abstractions that could be user groups are teams (for example people/wmf-team-release-engineering) and volunteer project maintainers (for example people/volunteer-group-cloud-admin).

Any defined user groups should be kept under the top-level namespace group /people. If the purpose of a group is to model a real-world group then a subgroup under the people namespace is appropriate.

people
├── trusted-contributors
├── wmde-team-foo
├── volunteer-group-bar
└── wmf-team-baz

User groups may fulfill a number of purposes:

1. To ease onboarding/offboarding for groups of collaborators
2. To enforce user policy (e.g., 2fa) at the group level
3. To model some amount of organizational structure to be independently of project layout, and allow it to change without re-arranging project groups

Privileges

This section borrows text from Gerrit/Privilege_policy

Groups in GitLab contain members. These members have one of 5 roles:

• Guest
• Reporters
• Developers
• Maintainers
• Owners

You can read more about permissions in the upstream GitLab permission documentation. GitLab allows you to build a permission model by policy. Our policy is outlined on this page.

Any user should be able to create or comment on a merge request. Reporters can run tests for a given project. Developers can create branches on the project to use for merge-requests in the work namespace. Developers can also approve and merge code for a project. Maintainers can reconfigure a project, change privileges, and update merge and squash options. Owners can delete and rename projects.

Developers and Maintainers can approve and merge their own merge requests similar to a self-+2 in Gerrit. Self-merge without approval is discouraged by policy. (Exceptions exist for specific cases such as reverting a broken change and deploying backports of already-reviewed code.) Merging your own code without approval from a reviewer may be grounds for revocation of privileges.

Merging a change to the MediaWiki core or an extension deployed by Wikimedia is a big deal. Your merge could cause Wikipedia or other sites to fail. It could create a security vulnerability that allows attackers to delete or corrupt data, or to gain access to private information. And in the more common case, it could cause technical debt to increase if the code doesn't have tests, is poorly implemented or poorly socialized. You should carefully read this document and all relevant policies before merging a merge request.

Maintainer permissions are a strong expression of trust, and trust is maintained through good judgement and careful action.

In code review, design discussions, and bug comments, those with merge abilities have a special responsibility to see from others' points of view.

Project Features

Private repositories

See Hosting a project on GitLab, GitLab private (restricted) repos for details.

Issue tracking and wikis

Phabricator is used for issue tracking, bug reports, and project management in Wikimedia technical spaces. Use of GitLab for issue tracking was considered out of scope during the GitLab consultation (see GitLab consultation#FAQ). Accordingly, to avoid confusion, fragmentation, and administrative overhead, GitLab issues and wikis are disabled on the Wikimedia instance.

Job runners

Users may configure self-service job runners for individual projects.

Administration

Users may be set to an admin status. Application-level administrative privileges are held by:

• Members of the Wikimedia Foundation Release Engineering team, for servicing most application-level administrative tasks and technical support requests.
• Relevant members of the WMF ServiceOps team, for addressing infrastructure-level concerns.
• A limited pool of other trusted contributors who have signed an NDA and volunteered to share administrative workload.

wikitech:GitLab houses documentation on GitLab infrastructure and SRE-related topics.