Skip to content

MNT: update github access role based on project document #2877

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tech3371 merged 2 commits into from
Mar 30, 2026
Merged

MNT: update github access role based on project document #2877

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
860ffd0
MNT: update github access role based on project document
tech3371 Mar 27, 2026
3e6b432
feedback changes
tech3371 Mar 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
245 changes: 26 additions & 219 deletions docs/source/development/git-access-roles.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,15 +3,14 @@
GitHub Access & Permissions Guide
======================================

This document outlines the different permission levels available in IMAP
repositories and what each role can do.
This document outlines the permission levels available in IMAP SDC
repositories.

Overview
========

GitHub provides five repository roles. Below is a detailed breakdown of
permissions for each role, including what GitHub users can access and
and what access requests must be submitted to IMAP SDC.
GitHub provides five repository roles with varying permission levels.
Below we outline the permissions needed to contribute to IMAP SDC repositories.

---

Expand All @@ -21,229 +20,37 @@ What GitHub Users Can Access
Any GitHub user (without invitation) can:

- ✅ View **public repositories**
- ✅ Create issues in public repos (if enabled)
- ✅ Comment on public issues/PRs
- ✅ Fork public repositories
- ❌ **Cannot** push, merge, or modify anything
- ✅ Create issues in public repos
- ✅ Comment on public issues
- ✅ Edit titles and descriptions of your own issues
- ✅ Create pull requests
- ❌ **Cannot** add label or assignees, etc to the issues
- ❌ **Cannot** trigger unit test workflows on PRs (requires SDC approval)
- ❌ **Cannot** request reviewers on PRs (SDC must assign reviewers)
- ❌ **Cannot** push code, merge PRs, or modify issues
- ❌ **Cannot** access private repositories

---

Role Permissions & Responsibilities
=====================================

Read
----

Full Permission List
^^^^^^^^^^^^^^^^^^^^

+----------------------------+-----------+
| Action | Allowed |
+============================+===========+
| View repository content | ✅ |
+----------------------------+-----------+
| Create issues | ✅ |
+----------------------------+-----------+
| Comment on issues and PRs | ✅ |
+----------------------------+-----------+
| View pull requests | ✅ |
+----------------------------+-----------+
| Push code | ❌ |
+----------------------------+-----------+
| Create PRs | ❌ |
+----------------------------+-----------+
| Merge anything | ❌ |
+----------------------------+-----------+

**When to Use**: Add people who only need to report issues and view code.
-----------------------------------
GitHub Read Role
~~~~~~~~~~~~~~~~~

---

Triage
------

Full Permission List
^^^^^^^^^^^^^^^^^^^^

+----------------------------+-----------+
| Action | Allowed |
+============================+===========+
| Everything in Read | ✅ |
+----------------------------+-----------+
| Manage labels | ✅ |
+----------------------------+-----------+
| Manage assignees | ✅ |
+----------------------------+-----------+
| Manage milestones | ✅ |
+----------------------------+-----------+
| Mark as duplicate | ✅ |
+----------------------------+-----------+
| Close/reopen issues | ✅ |
+----------------------------+-----------+
| Push code | ❌ |
+----------------------------+-----------+
| Create PRs | ❌ |
+----------------------------+-----------+
| Merge anything | ❌ |
+----------------------------+-----------+

**When to Use**: Add people who manage the issue/ticket workflow but don't
write code.

---

Write
-----

Full Permission List
^^^^^^^^^^^^^^^^^^^^

+----------------------------------+-------------------------------------------+
| Action | Allowed |
+==================================+===========================================+
| Everything in Triage | ✅ |
+----------------------------------+-------------------------------------------+
| Push code to branches | ✅ |
+----------------------------------+-------------------------------------------+
| Create pull requests | ✅ |
+----------------------------------+-------------------------------------------+
| Review PRs | ✅ |
+----------------------------------+-------------------------------------------+
| Approve PRs | ✅ |
+----------------------------------+-------------------------------------------+
| Merge PRs | ❌ (controlled by branch protection) |
+----------------------------------+-------------------------------------------+
| Delete branches | ❌ |
+----------------------------------+-------------------------------------------+
| Manage settings | ❌ |
+----------------------------------+-------------------------------------------+

**When to Use**: Add developers who create PRs but need approval before
merging.

**Branch Protection Required**:

.. code-block::

✅ Require pull request reviews before merging (1+ approval)
✅ Require status checks to pass before merging
✅ Require branches to be up to date
Read role should give same permissions as a user without invitation for IMAP SDC public repositories.
These permissions align with IMAP project requirements and are sufficient for most L0 to L3 code
contributors based on project guidelines.

---

Maintain
--------

Full Permission List
^^^^^^^^^^^^^^^^^^^^

+----------------------------------+-------------------------------------------+
| Action | Allowed |
+==================================+===========================================+
| Everything in Write | ✅ |
+----------------------------------+-------------------------------------------+
| Merge pull requests | ✅ |
+----------------------------------+-------------------------------------------+
| Manage branches and protections | ✅ |
+----------------------------------+-------------------------------------------+
| Create releases | ✅ |
+----------------------------------+-------------------------------------------+
| Dismiss pull request reviews | ❌ (controlled by branch protection) |
+----------------------------------+-------------------------------------------+
| Override branch protections | ❌ (controlled by branch protection) |
+----------------------------------+-------------------------------------------+
| Delete repository | ❌ |
+----------------------------------+-------------------------------------------+
| Manage access/members | ❌ |
+----------------------------------+-------------------------------------------+

**When to Use**: Add team leads who can approve, merge, and manage the PR
workflow.

**Branch Protection Required** (for "merge only when tests pass, no override"):

.. code-block::

✅ Require pull request reviews before merging
✅ Require status checks to pass before merging
✅ Require branches to be up to date
✅ Include administrators (enforces restrictions on all)
❌ Allow force pushes

---

Admin
-----

Full Permission List
^^^^^^^^^^^^^^^^^^^^

+----------------------------------+-------------------------------------------+
| Action | Allowed |
+==================================+===========================================+
| Everything in Maintain | ✅ |
+----------------------------------+-------------------------------------------+
| Full repository control | ✅ |
+----------------------------------+-------------------------------------------+
| Override all branch protections | ✅ |
+----------------------------------+-------------------------------------------+
| Delete repository | ✅ |
+----------------------------------+-------------------------------------------+
| Manage all repository settings | ✅ |
+----------------------------------+-------------------------------------------+
| Manage repository access | ✅ |
+----------------------------------+-------------------------------------------+

**When to Use**: Only for repository owners.
Additional GitHub Roles
-----------------------

---

How to Add Users to This Repository
====================================

1. Go to **Settings → Collaborators and teams** (or **Access** in newer
GitHub UI)
2. Click **Add people**
3. Search for the GitHub username
4. Select the appropriate role from the dropdown
5. Click **Add [username] to the repository**

---

Permission Assignment Examples
===============================

Example 1: New Team Member (Contributor)
----------------------------------------
- **Role**: `Write`
- **Access**: Can create PRs and review code
- **Restrictions**: Cannot merge until approved and tests pass
- **Branch Protection**: Required approvals enforce this

Example 2: IMAP SDC Manager(s)
------------------------------
- **Role**: `Triage`
- **Access**: Can manage issue labels, assignees, milestones
- **Restrictions**: Cannot write code or modify PRs
- **Use Case**: Triaging bugs and managing workflow

Example 3: Team Lead
--------------------
- **Role**: `Maintain`
- **Access**: Can merge PRs, manage releases
- **Restrictions**: Cannot override failed tests (with branch protection)
- **Use Case**: Merges reviewed and tested code

Example 4: Repository Owner
---------------------------
- **Role**: `Admin`
- **Access**: Full control
- **Use Case**: Repository administration and settings

---
Beyond the **GitHub Read** role (which is sufficient for most contributors), GitHub
provides additional permission levels: `Triage`, `Write`, `Maintain`, and `Admin`.
Please read the GitHub's breakdown of these roles and their permissions in the
`GitHub documentation on repository roles <https://docs.github.com/en/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization#permissions-for-each-role>`_.

Questions?
==========

If you have questions about your repository access or need a different permission level, please contact the IMAP SDC team.
**If you need permissions** please contact the IMAP SDC team to request the
appropriate access level for your role.
Loading