Authorization development guidelines

Authorization controls what users are allowed to do in GitLab. When implementing any feature that reads, creates, modifies, or deletes data, you must consider how access is controlled and enforced consistently across all entry points.

Reviews

• Adding a new permission: How to name new permissions and what to include in policy classes.
• Authorization review guidelines: A checklist for preparing a merge request that involve policy changes, permission definitions, and authorization logic for review.
• If you need guidance on whether a new permission is needed or which team to involve, contact the Govern:Authorization team.

Concepts

• DeclarativePolicy framework: Introduction to DeclarativePolicy framework used for authorization.
• Default roles: Overview of default roles, user types, and how abilities are assigned.
• Custom roles: Guidance on how to work on custom role, how to introduce a new ability for custom roles, how to refactor permissions.
• Roles and permissions matrix: The full reference of what each role can do across GitLab features.
• Glossary: Definitions of key authentication and authorization terms used across GitLab.

Where to check permissions

• Where to check permissions: Guidance on where to check permissions.
• GraphQL authorization: How to authorize types, resolvers, and fields in the GraphQL API.

Token permissions

• Job token guidelines: Development guidelines for CI/CD job token permissions.
• Granular Personal Access Tokens: Development guidelines for granular personal access tokens.

Testing

• Testing: Guidance for how to write specs for permission checks.