From 860ffd02d8ede874cb8c058e42755e8520977e0c Mon Sep 17 00:00:00 2001 From: Tenzin Choedon Date: Fri, 27 Mar 2026 09:16:46 -0600 Subject: [PATCH 1/2] MNT: update github access role based on project document --- docs/source/development/git-access-roles.rst | 244 ++----------------- 1 file changed, 24 insertions(+), 220 deletions(-) diff --git a/docs/source/development/git-access-roles.rst b/docs/source/development/git-access-roles.rst index c786ea4ba..e74f2130d 100644 --- a/docs/source/development/git-access-roles.rst +++ b/docs/source/development/git-access-roles.rst @@ -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. --- @@ -21,229 +20,34 @@ 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 -===================================== +----------------------------------- +GitHub Read Role +~~~~~~~~~~~~~~~~~ -Read ----- +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. -Full Permission List -^^^^^^^^^^^^^^^^^^^^ -+----------------------------+-----------+ -| Action | Allowed | -+============================+===========+ -| View repository content | ✅ | -+----------------------------+-----------+ -| Create issues | ✅ | -+----------------------------+-----------+ -| Comment on issues and PRs | ✅ | -+----------------------------+-----------+ -| View pull requests | ✅ | -+----------------------------+-----------+ -| Push code | ❌ | -+----------------------------+-----------+ -| Create PRs | ❌ | -+----------------------------+-----------+ -| Merge anything | ❌ | -+----------------------------+-----------+ +Additional GitHub Roles +----------------------- -**When to Use**: Add people who only need to report issues and view code. +Beyond the **GitHub Read** role (which is sufficient for most contributors), GitHub +provides additional permission levels: `Triage`, `Write`, `Maintain`, and `Admin`. ---- - -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 - ---- - -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. - ---- - -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 - ---- - -Questions? -========== - -If you have questions about your repository access or need a different permission level, please contact the IMAP SDC team. \ No newline at end of file +**If you need permissions** please contact the IMAP SDC team to request the +appropriate access level for your role. From 3e6b432d1d6a9451f9fca821c37147c7148b6aed Mon Sep 17 00:00:00 2001 From: Tenzin Choedon Date: Mon, 30 Mar 2026 13:07:45 -0600 Subject: [PATCH 2/2] feedback changes --- docs/source/development/git-access-roles.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/source/development/git-access-roles.rst b/docs/source/development/git-access-roles.rst index e74f2130d..d0cf43981 100644 --- a/docs/source/development/git-access-roles.rst +++ b/docs/source/development/git-access-roles.rst @@ -48,6 +48,9 @@ Additional GitHub Roles 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 `_. + **If you need permissions** please contact the IMAP SDC team to request the appropriate access level for your role.