Skip to main content

Chapter 8: Access Control & Permissions Model

Part III: Organization Structure & Access Prerequisites: Chapter 7: Organization Design & Team Architecture GH-100 Exam Mapping: Domain 4 — Manage access and permissions based on membership (18%) Last Verified: 2026-02-01


Learning Objectives​

By the end of this chapter, you will be able to:

  1. Differentiate between enterprise, organization, and repository-level roles and explain when each applies.
  2. Configure enterprise roles (owner, member, billing manager) to enforce least-privilege access across a GitHub Enterprise Cloud deployment.
  3. Assign organization roles (owner, member, moderator, security manager) appropriate to team function and compliance requirements.
  4. Apply the five repository permission levels (read, triage, write, maintain, admin) to real-world team structures in organizations with 50 or more developers.
  5. Create custom repository roles that map to your organization's unique workflow requirements.
  6. Generate fine-grained Personal Access Tokens (PATs) scoped to specific repositories and permissions.
  7. Evaluate the tradeoffs between GitHub Apps and OAuth Apps for enterprise integration scenarios.
  8. Design a comprehensive access control strategy that satisfies audit, compliance, and developer productivity goals.

8.1 Introduction​

Access control is the backbone of any enterprise software delivery platform. In organizations with hundreds or thousands of developers, the difference between a well-designed permissions model and a poorly designed one is measured in security incidents, compliance audit failures, and developer frustration.

GitHub Enterprise Cloud provides a layered access control model that operates at three distinct levels: the enterprise account, the organization, and the repository. Each layer has its own set of roles, and each role grants a specific set of capabilities. Understanding how these layers compose is essential for any administrator responsible for governing GitHub Copilot and the broader GitHub platform at scale.

This chapter builds directly on the organizational structures introduced in Chapter 7: Organization Design & Team Architecture. Where Chapter 7 focused on how to structure teams and organizations, this chapter focuses on what each member of those structures can do — and, critically, what they cannot.

Why Access Control Matters for GitHub Copilot​

GitHub Copilot's availability is governed by the same access control hierarchy as the rest of GitHub. Copilot license assignment, policy configuration, and content exclusion rules all flow through the enterprise and organization permission model. An enterprise owner can set Copilot policies that organization owners cannot override. An organization owner can assign Copilot seats to members. A repository administrator can configure content exclusion patterns. Understanding the permissions model is therefore not merely a platform administration concern — it is a prerequisite for effective Copilot governance.

The Principle of Least Privilege​

Throughout this chapter, we apply the Principle of Least Privilege (PoLP): every user, service account, and automation should have exactly the permissions required to perform their function, and no more. In a 50+ developer organization, PoLP is not optional — it is the foundation upon which audit compliance, intellectual property protection, and incident containment are built.


8.2 Theory & Deep Dive​

8.2.1 The Three-Layer Permissions Hierarchy​

GitHub Enterprise Cloud organizes access control into three nested layers. Each layer can restrict but never expand the permissions granted by the layer above it.

Layer 1: Enterprise Account

The enterprise account is the top-level administrative boundary. It contains one or more organizations and provides centralized policy enforcement. Enterprise-level roles govern who can manage billing, configure Security Assertion Markup Language (SAML) Single Sign-On (SSO), set organization creation policies, and establish default Copilot policies.

There are three enterprise-level roles:

RoleDescriptionTypical Assignment
Enterprise OwnerFull administrative control over the enterprise account. Can manage all organizations, configure enterprise-wide policies, manage billing, configure SAML SSO and System for Cross-domain Identity Management (SCIM) provisioning, and set Copilot policies.CTO, VP of Engineering, Platform Lead (2-4 people maximum)
Enterprise MemberA user who belongs to at least one organization within the enterprise. Has no enterprise-level administrative capabilities. Permissions are determined entirely by their organization and repository roles.All developers, QA engineers, technical writers, and other contributors
Billing ManagerCan view and manage billing settings, payment methods, and usage reports. Cannot access repositories, organization settings, or enterprise policies beyond billing.Finance team leads, procurement specialists

Enterprise Scenario: A financial services company with 200 developers across three organizations (platform, trading, compliance) assigns two enterprise owners — the VP of Engineering and the Head of Platform. The CFO's delegate is assigned as billing manager. All other staff are enterprise members whose access is governed by their organization and repository roles.

Layer 2: Organization

Organizations are the primary unit of collaboration within an enterprise. Each organization has its own set of roles that determine what members can do within that organization's scope.

RoleDescriptionKey Capabilities
Organization OwnerFull administrative control over the organization.Manage members, teams, repositories, billing, security settings, Copilot seat assignment, webhooks, and third-party integrations.
Organization MemberStandard contributor role.Create repositories (if allowed by policy), see other organization members, be assigned to teams. Repository access is determined by team membership and direct repository grants.
ModeratorSpecialized role for community management.Block/unblock users, manage interaction limits, hide comments in public repositories. Cannot manage organization settings or billing.
Security ManagerSpecialized role for security operations.Read access to all repositories in the organization, manage security alerts and settings across all repositories, configure code scanning and secret scanning, manage Dependabot alerts. Cannot modify code or manage organization settings.

Key Distinction: Organization owners can configure whether members are allowed to create repositories, invite outside collaborators, or fork internal repositories. These are policy settings, not role definitions — they restrict what the member role can do within that specific organization.

Layer 3: Repository

Repository permissions are the most granular layer and the one developers interact with most frequently. GitHub provides five built-in permission levels, plus the ability to define custom roles.

Permission LevelCode AccessIssue/PR ManagementRepository SettingsTypical Role
ReadClone and pullView issues and PRs; cannot create or commentNoneStakeholders, auditors, cross-team observers
TriageClone and pullCreate, label, assign, and close issues/PRs; request reviewsNoneProject managers, QA analysts, support engineers
WritePush to non-protected branchesFull issue/PR management; create branches; merge PRs (if allowed by branch protection)NoneSoftware engineers, contributing developers
MaintainPush to non-protected branchesFull issue/PR management; manage topics, wikis, and GitHub PagesManage some repository settings (not destructive ones)Tech leads, senior engineers
AdminFull code accessFull issue/PR managementFull repository settings including branch protection, webhooks, deploy keys, and repository deletionRepository owners, team leads with operational responsibility

8.2.2 Enterprise Roles in Detail​

Enterprise Owner Responsibilities

Enterprise owners hold the keys to the kingdom. Their responsibilities include:

  • Identity and Access Management (IAM): Configuring SAML SSO providers (Azure Active Directory, Okta, PingFederate, OneLogin), setting up SCIM for automated user provisioning and deprovisioning, and managing the enterprise's authentication policies.
  • Organization Lifecycle: Creating and deleting organizations, transferring repositories between organizations, and setting policies for organization creation by non-owners.
  • Policy Enforcement: Setting enterprise-wide policies that organization owners cannot override, including:
    • Base repository permissions (the default permission level for all organization members)
    • Repository creation permissions
    • Repository forking policies
    • GitHub Actions workflow permissions
    • GitHub Copilot policies (enabled/disabled, suggestions matching public code filter, Copilot Chat availability)
  • Audit and Compliance: Accessing the enterprise audit log, configuring audit log streaming to Security Information and Event Management (SIEM) systems, and generating compliance reports.

Security Note: Enterprise owner accounts should be protected with hardware security keys for two-factor authentication (2FA). Consider requiring WebAuthn-capable keys for all enterprise owners and maintaining at least two owner accounts to prevent lockout.

Enterprise Member Default Experience

Enterprise members have no inherent access to any organization or repository. Their effective permissions are the intersection of:

  1. The organizations they belong to
  2. The teams they are assigned to within those organizations
  3. Direct repository permission grants
  4. The enterprise and organization policies that constrain those permissions

This "default deny" model is fundamental to understanding GitHub's access control: membership in an enterprise grants nothing by itself.

Billing Manager Isolation

The billing manager role is deliberately isolated from all technical operations. A billing manager cannot:

  • View repository contents
  • Access organization settings (beyond billing)
  • Manage members or teams
  • Configure policies

This separation supports financial controls and SOC 2 Type II audit requirements by ensuring that individuals with access to payment instruments do not have access to intellectual property.

8.2.3 Organization Roles in Detail​

Organization Owner: The 80/20 of Daily Administration

In most enterprises, organization owners handle the majority of day-to-day administrative work. They operate within the boundaries set by enterprise owners but have wide latitude within their organization.

Key capabilities include:

  • Team Management: Creating teams, setting team membership, configuring team-level repository access. Teams are the primary mechanism for scaling access control beyond a handful of developers (See Chapter 7: Organization Design & Team Architecture).
  • Copilot Seat Assignment: Assigning and revoking GitHub Copilot licenses for organization members. Enterprise policies determine whether Copilot is available at all; organization owners determine who gets seats.
  • Third-Party Integration: Installing and configuring GitHub Apps, managing OAuth App access, and configuring webhooks.
  • Repository Policy: Setting the base (default) repository permission for organization members, configuring branch protection rules templates, and managing repository creation policies (within enterprise constraints).

Best Practice for 50+ Developer Organizations: Limit organization owners to 3-5 individuals. Use the security manager role for security team members who need cross-repository visibility, and use team maintainer roles for individuals who need to manage team membership without full organization control.

Security Manager: Purpose-Built for AppSec Teams

The security manager role was introduced specifically for Application Security (AppSec) teams that need visibility across all repositories without code write access. Security managers can:

  • View all repositories in the organization (including private ones)
  • View and dismiss security alerts (code scanning, secret scanning, Dependabot)
  • Configure security features at the organization level
  • Access the organization security overview dashboard

They cannot:

  • Push code to any repository
  • Manage teams, members, or organization settings
  • Access billing information
  • Install or configure GitHub Apps

Enterprise Scenario: A healthcare company with 150 developers has a 4-person security team. Rather than granting these individuals admin access to every repository (a common anti-pattern), the company assigns them the security manager role. This satisfies Health Insurance Portability and Accountability Act (HIPAA) audit requirements for security monitoring while maintaining the principle of least privilege.

Moderator: Community and InnerSource Governance

The moderator role is most relevant for organizations that maintain public or InnerSource repositories. Moderators can manage community interactions without having access to code or organization settings. In an enterprise context, moderators are typically assigned to developer experience or InnerSource program office staff who manage contribution guidelines and community health.

8.2.4 Repository Permission Levels in Practice​

Choosing the correct repository permission level requires understanding the day-to-day workflows of each role in your organization. Here is a mapping for a typical enterprise software team:

Team FunctionRecommended PermissionRationale
Junior/Mid DeveloperWriteCan push feature branches, create PRs, and participate in code review. Branch protection rules prevent direct pushes to main.
Senior/Staff DeveloperWrite or MaintainWrite is sufficient for most workflows. Maintain adds the ability to manage topics and merge queues, useful for tech leads.
Tech LeadMaintainCan manage repository settings that affect workflow (merge strategies, topic tags) without the destructive capabilities of admin.
Repository Owner/ArchitectAdminFull control including branch protection configuration, webhook management, and repository settings.
Product ManagerTriageCan manage the issue backlog (label, assign, prioritize, close) without code access.
QA EngineerTriage or WriteTriage if QA only manages test issues; Write if QA contributes test automation code.
External AuditorReadView-only access for compliance review. Consider time-boxed access via team membership with expiration.
CI/CD AutomationWrite (via GitHub App)Automation should use a GitHub App installation token, not a personal account. Scoped to the minimum permissions required.

8.2.5 Custom Repository Roles​

For organizations where the five built-in permission levels do not precisely match workflow requirements, GitHub Enterprise Cloud supports custom repository roles. Custom roles allow organization owners to compose a role from individual permissions.

When to Use Custom Roles

Custom roles are appropriate when:

  • A team function falls between two built-in levels (e.g., a role that can manage issues and merge PRs but cannot push code directly)
  • Compliance requirements demand a specific permission set that no built-in role matches
  • You want to codify a named role that maps to your organization's job titles or team structure

Creating a Custom Role

Custom roles are created at the organization level. You select a base role (Read, Triage, Write, Maintain, or Admin) and then add or remove individual permissions.

Available additional permissions that can be toggled include:

  • Close, reopen, or delete issues
  • Apply or dismiss code scanning results
  • Create, edit, or delete GitHub Actions workflow files
  • Manage repository webhooks
  • Edit repository metadata (topics, description, homepage)
  • Mark issues or pull requests as duplicate
  • Manage deploy keys
  • Set repository social media preview
  • Edit repository custom properties
  • Create protected tags
  • Manage repository rulesets

Example: "Release Engineer" Custom Role

A "Release Engineer" role might be based on the Write level with the following additions:

  • Manage repository webhooks (for release notification integrations)
  • Create protected tags (for release tagging)
  • Manage deploy keys (for deployment pipeline access)
  • Edit repository metadata (to update release-related descriptions)

This allows release engineers to perform their function without granting full Admin access.

# List existing custom roles for an organization (bash)
gh api \
-H "Accept: application/vnd.github+json" \
/orgs/{org}/custom-repository-roles
# List existing custom roles for an organization (PowerShell)
gh api `
-H "Accept: application/vnd.github+json" `
/orgs/{org}/custom-repository-roles

Limit: Organizations can create up to 5 custom repository roles on GitHub Enterprise Cloud. Plan carefully and avoid creating one-off roles for individual users.

8.2.6 Fine-Grained Personal Access Tokens (PATs)​

Personal Access Tokens are used to authenticate API requests and Git operations outside of the browser. GitHub supports two types:

Classic PATs (Legacy)

Classic PATs have broad, coarse-grained scopes (e.g., repo, admin:org, user). A classic PAT with the repo scope grants full read/write access to every repository the user can access. This is a significant security concern in enterprise environments.

Fine-Grained PATs (Recommended)

Fine-grained PATs, introduced as the modern alternative, offer:

  • Repository Scoping: A token can be restricted to specific repositories, not all repositories the user can access.
  • Permission Granularity: Each token specifies individual permissions (e.g., "Contents: Read-only", "Issues: Read and write") rather than broad scopes.
  • Expiration Enforcement: Fine-grained PATs require an expiration date (maximum 1 year). Organization owners can set a policy requiring shorter maximum lifetimes.
  • Approval Workflow: Organization owners can require that fine-grained PATs targeting their organization be approved before they become active.
  • Audit Trail: Token creation, use, and revocation are logged in the organization and enterprise audit logs.

Fine-Grained PAT Permissions Categories

CategoryAvailable PermissionsExample Use Case
Repository: ActionsRead / Read-writeCI/CD status checks
Repository: ContentsRead / Read-writeCloning, pushing code
Repository: IssuesRead / Read-writeAutomated issue management
Repository: Pull RequestsRead / Read-writePR automation, review bots
Repository: WebhooksRead / Read-writeWebhook management scripts
Repository: MetadataRead (always granted)Basic repository information
Organization: MembersRead / Read-writeTeam membership automation
Organization: AdministrationRead / Read-writeOrg settings management

Creating a Fine-Grained PAT

# Generate a fine-grained PAT via the CLI (bash)
# Note: Interactive token creation is done via the web UI at
# https://github.com/settings/tokens?type=beta
# The CLI can list and delete tokens:

# List existing fine-grained PATs
gh auth token

# Verify token permissions by making a scoped API call
gh api \
-H "Accept: application/vnd.github+json" \
/repos/{owner}/{repo}/issues \
--jq '.[0:3] | .[].title'
# Verify token permissions by making a scoped API call (PowerShell)
gh api `
-H "Accept: application/vnd.github+json" `
/repos/{owner}/{repo}/issues `
--jq '.[0:3] | .[].title'

Enterprise PAT Policies

Enterprise and organization owners can set policies governing PAT usage:

  1. Restrict classic PATs: Disable classic PATs entirely, forcing all token-based authentication to use fine-grained PATs.
  2. Require approval: Require organization owner approval for fine-grained PATs that target the organization.
  3. Set maximum lifetime: Limit token expiration to a maximum number of days (e.g., 90 days for compliance).
  4. Restrict allowed permissions: Limit which permissions fine-grained PATs can request.

Best Practice: For organizations subject to SOC 2 or similar compliance frameworks, disable classic PATs, require approval for fine-grained PATs, and set a maximum lifetime of 90 days. This creates a reviewable, time-limited, least-privilege token ecosystem.

8.2.7 GitHub Apps vs. OAuth Apps​

Enterprise integrations — CI/CD pipelines, ChatOps bots, security scanners, project management tools, and Copilot extensions — require programmatic access to GitHub. Two authentication models are available: GitHub Apps and OAuth Apps.

GitHub Apps (Recommended)

GitHub Apps are the modern, recommended integration model. Key characteristics:

  • Installation-Based Access: A GitHub App is installed on specific organizations or repositories. It acts as its own identity, not as a user.
  • Granular Permissions: Apps request specific permissions (e.g., "Contents: Read", "Pull Requests: Write") and only receive those permissions.
  • Short-Lived Tokens: GitHub Apps authenticate with installation access tokens that expire after 1 hour. Tokens are generated on demand using a private key.
  • Webhook-Driven: Apps can subscribe to specific webhook events and respond to them.
  • Rate Limit Advantage: GitHub Apps have higher API rate limits (5,000 requests/hour per installation for REST API) compared to user-based authentication.
  • No Seat Consumption: GitHub Apps do not consume a user license.

OAuth Apps (Legacy)

OAuth Apps authenticate on behalf of a user through the OAuth 2.0 authorization code flow. Key characteristics:

  • User-Based Access: An OAuth App acts with the permissions of the authorizing user. If a user has admin access to 50 repositories, the OAuth App inherits that access.
  • Coarse Scopes: OAuth Apps use the same broad scopes as classic PATs (e.g., repo, admin:org).
  • Long-Lived Tokens: OAuth tokens do not expire unless explicitly revoked.
  • Seat Consumption: Some OAuth App patterns effectively consume a user seat.

Comparison Matrix

DimensionGitHub AppOAuth App
IdentityActs as itself (bot)Acts as a user
Permission ModelGranular, per-installationBroad scopes, per-user
Token Lifetime1 hour (auto-renewable)Until revoked
Rate Limits5,000/hour per installation5,000/hour per user
Repository ScopeSelected repositories onlyAll user-accessible repos
Audit TrailDistinct identity in logsAttributed to user
License ImpactNo seat consumedMay consume a seat
SAML SSONot affected by user SSORequires user SSO session
Best ForCI/CD, bots, automationUser-facing web apps

When to Choose Each

Use a GitHub App when:

  • The integration is a service (CI/CD, scanner, bot) that should not be tied to a human identity
  • You need fine-grained, repository-scoped permissions
  • You want a clear audit trail that distinguishes automation from human activity
  • You need to survive employee offboarding without breaking integrations

Use an OAuth App when:

  • The integration is a user-facing web application that needs to act on behalf of the authenticated user (e.g., a dashboard that shows a user's PRs across organizations)
  • You need to perform actions that require user context (e.g., "star this repository as the current user")

Enterprise Scenario: A 300-person engineering organization uses a GitHub App for their CI/CD pipeline (Jenkins/GitHub Actions), a GitHub App for their security scanner (Snyk/SonarQube), and a GitHub App for their ChatOps bot. They use an OAuth App only for their internal developer portal, which displays personalized dashboards. When an engineer leaves the company, SCIM deprovisioning removes the user — but all automations continue uninterrupted because they use GitHub App identities, not user identities.

8.2.8 Access Control and GitHub Copilot​

GitHub Copilot policy enforcement follows the enterprise-organization hierarchy:

  1. Enterprise Level: Enterprise owners can enable or disable Copilot for the entire enterprise, choose between "allowed for all organizations" or "allowed for selected organizations," and set the public code filter policy.
  2. Organization Level: Organization owners (if permitted by enterprise policy) can enable Copilot for all members, selected teams, or selected members. They can also configure content exclusion rules that prevent Copilot from providing suggestions based on specified file paths or repositories.
  3. Individual Level: If the enterprise and organization policies permit, individual users can configure their own Copilot settings (e.g., enable/disable suggestions in specific editors, enable/disable Copilot Chat).

Content exclusion rules (See Chapter 14: Content Exclusion & IP Protection) are configured at the organization or enterprise level and are enforced regardless of the user's individual settings. This ensures that sensitive code (e.g., proprietary algorithms, regulated data handling logic) is never used as context for Copilot suggestions, even if the developer has Copilot enabled.


8.3 Diagrams​

8.3.1 Enterprise Access Control Hierarchy​

The following diagram illustrates the three-layer permissions model and how roles cascade from the enterprise level through organizations to repositories.

graph TB
subgraph Enterprise["Enterprise Account"]
EO["Enterprise Owner<br/>(Full Control)"]
EM["Enterprise Member<br/>(No Enterprise Privileges)"]
BM["Billing Manager<br/>(Billing Only)"]
end

subgraph Org1["Organization: Platform"]
OO1["Org Owner"]
OM1["Org Member"]
SM1["Security Manager"]
MOD1["Moderator"]
end

subgraph Org2["Organization: Product"]
OO2["Org Owner"]
OM2["Org Member"]
SM2["Security Manager"]
end

subgraph Repos1["Platform Repositories"]
R1["infra-core<br/>Admin | Write | Read"]
R2["shared-libs<br/>Maintain | Write | Read"]
R3["docs-internal<br/>Write | Triage | Read"]
end

subgraph Repos2["Product Repositories"]
R4["web-app<br/>Admin | Write | Read"]
R5["mobile-app<br/>Admin | Write | Triage"]
R6["api-gateway<br/>Maintain | Write | Read"]
end

EO -->|"Manages"| Org1
EO -->|"Manages"| Org2
EM -->|"Belongs to"| Org1
EM -->|"Belongs to"| Org2

OO1 -->|"Manages"| Repos1
OM1 -->|"Contributes"| Repos1
SM1 -->|"Monitors Alerts"| Repos1

OO2 -->|"Manages"| Repos2
OM2 -->|"Contributes"| Repos2
SM2 -->|"Monitors Alerts"| Repos2

style Enterprise fill:#1a1a2e,color:#ffffff
style Org1 fill:#16213e,color:#ffffff
style Org2 fill:#16213e,color:#ffffff
style Repos1 fill:#0f3460,color:#ffffff
style Repos2 fill:#0f3460,color:#ffffff

8.3.2 Token and App Authentication Decision Flow​

flowchart TD
A["Need programmatic<br/>GitHub access?"] --> B{"Is it a service<br/>or automation?"}
B -->|Yes| C{"Needs to act<br/>as a user?"}
B -->|No| D{"Is it a<br/>human developer?"}

C -->|No| E["Use GitHub App<br/>(Installation Token)"]
C -->|Yes| F["Use GitHub App<br/>with user-to-server token"]

D -->|Yes| G{"Short-lived<br/>script or long<br/>running?"}
D -->|No| E

G -->|"Short-lived"| H["Use gh CLI<br/>(OAuth session)"]
G -->|"Long-running or<br/>CI pipeline"| I{"Can use<br/>GitHub App?"}

I -->|Yes| E
I -->|No| J["Use Fine-Grained PAT<br/>(scoped, expiring)"]

E --> K["Configure:<br/>- Specific repos<br/>- Minimal permissions<br/>- Webhook events"]
J --> L["Configure:<br/>- Specific repos<br/>- Minimal permissions<br/>- Expiration (max 90d)<br/>- Require approval"]

style E fill:#28a745,color:#ffffff
style J fill:#ffc107,color:#000000
style K fill:#155724,color:#ffffff
style L fill:#856404,color:#000000

8.3.3 Repository Permission Levels — Capability Comparison​

graph LR
subgraph Permissions["Repository Permission Levels"]
READ["Read<br/>- Clone/Pull<br/>- View Issues<br/>- View PRs<br/>- View Wiki"]
TRIAGE["Triage<br/>+ Create Issues<br/>+ Label/Assign<br/>+ Close/Reopen<br/>+ Request Reviews"]
WRITE["Write<br/>+ Push Code<br/>+ Create Branches<br/>+ Merge PRs<br/>+ Edit Wiki"]
MAINTAIN["Maintain<br/>+ Manage Topics<br/>+ Manage Pages<br/>+ Push to Protected*<br/>+ Edit Repo Settings"]
ADMIN["Admin<br/>+ Branch Protection<br/>+ Manage Webhooks<br/>+ Delete Repository<br/>+ Manage Access"]
end

READ --> TRIAGE --> WRITE --> MAINTAIN --> ADMIN

style READ fill:#6c757d,color:#ffffff
style TRIAGE fill:#17a2b8,color:#ffffff
style WRITE fill:#28a745,color:#ffffff
style MAINTAIN fill:#fd7e14,color:#ffffff
style ADMIN fill:#dc3545,color:#ffffff

8.4 Summary​

This chapter covered the complete GitHub Enterprise Cloud access control model across its three hierarchical layers:

Enterprise Level:

  • Enterprise owners have full control over enterprise policy, identity configuration (SAML SSO, SCIM), and Copilot governance. Limit to 2-4 trusted individuals.
  • Enterprise members have no enterprise-level privileges; their access is determined entirely by organization and repository roles.
  • Billing managers are isolated from all technical operations, supporting separation of duties for compliance.

Organization Level:

  • Organization owners manage day-to-day team and repository administration within enterprise policy boundaries.
  • Security managers provide cross-repository security visibility without code write access — a purpose-built role for AppSec teams.
  • Moderators handle community management for public and InnerSource repositories.

Repository Level:

  • Five built-in permission levels (Read, Triage, Write, Maintain, Admin) cover the majority of use cases.
  • Custom repository roles (up to 5 per organization) address gaps between built-in levels.
  • Branch protection rules are the enforcement layer that makes Write and Maintain permissions safe at scale.

Authentication for Automation:

  • Fine-grained PATs replace classic PATs with repository-scoped, permission-specific, time-limited tokens.
  • GitHub Apps are the recommended model for service integrations (CI/CD, scanners, bots) because they act as their own identity, use short-lived tokens, and survive employee offboarding.
  • OAuth Apps remain appropriate only for user-facing web applications that need to act on behalf of the authenticated user.

Copilot Governance:

  • Copilot policies cascade from enterprise to organization to individual.
  • Content exclusion rules are enforced regardless of individual user settings.
  • Copilot seat assignment is an organization-level operation governed by enterprise policy.

Key Takeaways​

  1. Default deny: Enterprise membership grants no access; all access flows through organization membership, team assignment, and repository grants.
  2. Least privilege: Use the lowest permission level that enables each function. Use custom roles to avoid over-granting.
  3. Separate humans from machines: Use GitHub Apps (not user accounts or PATs) for automations.
  4. Enforce token hygiene: Disable classic PATs, require approval for fine-grained PATs, and set maximum lifetimes.
  5. Audit everything: Enterprise and organization audit logs capture role changes, token creation, and policy modifications. Stream them to your SIEM.

8.5 Hands-On Assignment​

Prerequisites Check: Before starting this lab, ensure you have completed:

  • Identity provider configured with SSO (Chapter 2: Identity & Single Sign-On)
  • Organization and team structure in place (Chapter 7: Organization Design & Team Architecture)
  • A working GitHub Enterprise Cloud environment (Chapter 1: Enterprise Subscription & Environment Setup)

Lab Title: Designing and Implementing an Access Control Strategy​

Objective: Design and implement a complete access control configuration for a simulated 75-person engineering organization using GitHub Enterprise Cloud.

Prerequisites:

  • A GitHub Enterprise Cloud trial account (free 30-day trial at https://github.com/enterprise)
  • GitHub CLI (gh) version 2.40 or later installed and authenticated
  • At least one additional GitHub user account for testing (or use a second browser session)

Environment:

  • Organization name: acme-engineering (substitute your trial organization name)
  • Simulated teams: platform-core (10 engineers), web-frontend (15 engineers), mobile (12 engineers), qa-automation (8 engineers), security (4 engineers), management (6 product managers)

Assignment Tasks​

Task 1: Organization Base Permissions Audit

Assess the current base permission level for your organization and determine the appropriate setting.

# Check current base permission (bash)
gh api \
-H "Accept: application/vnd.github+json" \
/orgs/{org} \
--jq '.default_repository_permission'
# Check current base permission (PowerShell)
gh api `
-H "Accept: application/vnd.github+json" `
/orgs/{org} `
--jq '.default_repository_permission'

Requirement: Set the base permission to "read" (or "none" for high-security environments). Document your rationale.

Task 2: Team Structure and Repository Access

Create the following teams and configure repository access:

TeamRepositoryPermission Level
platform-coreinfra-servicesAdmin
platform-coreshared-librariesMaintain
web-frontendweb-applicationWrite
web-frontendshared-librariesRead
mobilemobile-iosWrite
mobilemobile-androidWrite
qa-automationAll repositoriesTriage
security(use security manager role)N/A

Task 3: Custom Repository Role

Create a "Release Coordinator" custom role based on the Write permission level with the following additional permissions:

  • Create and manage protected tags
  • Manage repository webhooks
  • Edit repository metadata

Task 4: Fine-Grained PAT Policy

Configure the organization to:

  • Require approval for all fine-grained PATs
  • Set maximum token lifetime to 90 days
  • Restrict classic PAT access

Task 5: GitHub App vs. PAT Analysis

Your organization uses three integrations:

  1. A CI/CD pipeline that builds and tests code on every PR
  2. A Slack bot that posts PR review notifications
  3. A developer's personal script that generates weekly code metrics

For each integration, determine whether it should use a GitHub App or a fine-grained PAT, and document the minimum permissions required.

Deliverables:

  1. Screenshot or CLI output showing organization base permission configuration
  2. CLI output showing team structure and repository permissions
  3. Documentation of your custom role configuration
  4. PAT policy configuration screenshot or API output
  5. Written analysis of GitHub App vs. PAT decisions for the three integrations

8.6 Step-by-Step Walkthrough​

This walkthrough implements the hands-on assignment tasks using the GitHub CLI and web interface.

Step 1: Verify Organization and Authentication​

# Verify you are authenticated and have the correct organization (bash)
gh auth status

# List your organizations
gh api \
-H "Accept: application/vnd.github+json" \
/user/orgs \
--jq '.[].login'
# Verify you are authenticated and have the correct organization (PowerShell)
gh auth status

# List your organizations
gh api `
-H "Accept: application/vnd.github+json" `
/user/orgs `
--jq '.[].login'

Expected output should include your trial organization name.

Step 2: Set Base Repository Permission to Read​

# Set base permission to "read" (bash)
# Replace {org} with your organization name
gh api \
-X PATCH \
-H "Accept: application/vnd.github+json" \
/orgs/{org} \
-f default_repository_permission=read

# Verify the change
gh api \
-H "Accept: application/vnd.github+json" \
/orgs/{org} \
--jq '{base_permission: .default_repository_permission, members_can_create_repos: .members_can_create_repositories}'
# Set base permission to "read" (PowerShell)
gh api `
-X PATCH `
-H "Accept: application/vnd.github+json" `
/orgs/{org} `
-f default_repository_permission=read

# Verify the change
gh api `
-H "Accept: application/vnd.github+json" `
/orgs/{org} `
--jq '{base_permission: .default_repository_permission, members_can_create_repos: .members_can_create_repositories}'

Expected output:

{
"base_permission": "read",
"members_can_create_repos": true
}

Why "read"? Setting the base permission to "read" means every organization member can view every repository by default but cannot modify anything. This supports InnerSource visibility while enforcing explicit access grants for write operations. For organizations handling regulated data, consider "none" (which GitHub calls "No permission").

Step 3: Create Test Repositories​

# Create repositories for the lab (bash)
gh repo create {org}/infra-services --private --description "Core infrastructure services"
gh repo create {org}/shared-libraries --internal --description "Shared libraries and utilities"
gh repo create {org}/web-application --private --description "Main web application"
gh repo create {org}/mobile-ios --private --description "iOS mobile application"
gh repo create {org}/mobile-android --private --description "Android mobile application"
# Create repositories for the lab (PowerShell)
gh repo create {org}/infra-services --private --description "Core infrastructure services"
gh repo create {org}/shared-libraries --internal --description "Shared libraries and utilities"
gh repo create {org}/web-application --private --description "Main web application"
gh repo create {org}/mobile-ios --private --description "iOS mobile application"
gh repo create {org}/mobile-android --private --description "Android mobile application"

Step 4: Create Teams​

# Create teams (bash)
gh api \
-X POST \
-H "Accept: application/vnd.github+json" \
/orgs/{org}/teams \
-f name="platform-core" \
-f description="Core platform engineering team" \
-f privacy="closed"

gh api \
-X POST \
-H "Accept: application/vnd.github+json" \
/orgs/{org}/teams \
-f name="web-frontend" \
-f description="Web frontend development team" \
-f privacy="closed"

gh api \
-X POST \
-H "Accept: application/vnd.github+json" \
/orgs/{org}/teams \
-f name="mobile" \
-f description="Mobile development team (iOS and Android)" \
-f privacy="closed"

gh api \
-X POST \
-H "Accept: application/vnd.github+json" \
/orgs/{org}/teams \
-f name="qa-automation" \
-f description="QA and test automation team" \
-f privacy="closed"

gh api \
-X POST \
-H "Accept: application/vnd.github+json" \
/orgs/{org}/teams \
-f name="security" \
-f description="Application security team" \
-f privacy="closed"

gh api \
-X POST \
-H "Accept: application/vnd.github+json" \
/orgs/{org}/teams \
-f name="management" \
-f description="Product management and leadership" \
-f privacy="closed"
# Create teams (PowerShell) - example for one team; repeat pattern for others
gh api `
-X POST `
-H "Accept: application/vnd.github+json" `
/orgs/{org}/teams `
-f name="platform-core" `
-f description="Core platform engineering team" `
-f privacy="closed"

Step 5: Assign Repository Permissions to Teams​

# platform-core: admin on infra-services (bash)
gh api \
-X PUT \
-H "Accept: application/vnd.github+json" \
/orgs/{org}/teams/platform-core/repos/{org}/infra-services \
-f permission="admin"

# platform-core: maintain on shared-libraries
gh api \
-X PUT \
-H "Accept: application/vnd.github+json" \
/orgs/{org}/teams/platform-core/repos/{org}/shared-libraries \
-f permission="maintain"

# web-frontend: write on web-application
gh api \
-X PUT \
-H "Accept: application/vnd.github+json" \
/orgs/{org}/teams/web-frontend/repos/{org}/web-application \
-f permission="push"

# web-frontend: read on shared-libraries (already covered by base permission)
# Explicitly setting it reinforces the intent:
gh api \
-X PUT \
-H "Accept: application/vnd.github+json" \
/orgs/{org}/teams/web-frontend/repos/{org}/shared-libraries \
-f permission="pull"

# mobile: write on mobile-ios and mobile-android
gh api \
-X PUT \
-H "Accept: application/vnd.github+json" \
/orgs/{org}/teams/mobile/repos/{org}/mobile-ios \
-f permission="push"

gh api \
-X PUT \
-H "Accept: application/vnd.github+json" \
/orgs/{org}/teams/mobile/repos/{org}/mobile-android \
-f permission="push"

# qa-automation: triage on all repositories
for repo in infra-services shared-libraries web-application mobile-ios mobile-android; do
gh api \
-X PUT \
-H "Accept: application/vnd.github+json" \
/orgs/{org}/teams/qa-automation/repos/{org}/$repo \
-f permission="triage"
done
# Assign repository permissions to teams (PowerShell)
# platform-core: admin on infra-services
gh api `
-X PUT `
-H "Accept: application/vnd.github+json" `
/orgs/{org}/teams/platform-core/repos/{org}/infra-services `
-f permission="admin"

# Repeat the pattern for each team-repository pair.
# For qa-automation across all repos:
$repos = @("infra-services", "shared-libraries", "web-application", "mobile-ios", "mobile-android")
foreach ($repo in $repos) {
gh api `
-X PUT `
-H "Accept: application/vnd.github+json" `
/orgs/{org}/teams/qa-automation/repos/{org}/$repo `
-f permission="triage"
}

Note on API Permission Values: The REST API uses legacy names for some permissions: pull = Read, triage = Triage, push = Write, maintain = Maintain, admin = Admin.

Step 6: Verify Team Repository Permissions​

# List repositories for a specific team (bash)
gh api \
-H "Accept: application/vnd.github+json" \
/orgs/{org}/teams/platform-core/repos \
--jq '.[] | {name: .name, permission: .role_name}'
# List repositories for a specific team (PowerShell)
gh api `
-H "Accept: application/vnd.github+json" `
/orgs/{org}/teams/platform-core/repos `
--jq '.[] | {name: .name, permission: .role_name}'

Expected output:

{
"name": "infra-services",
"permission": "admin"
}
{
"name": "shared-libraries",
"permission": "maintain"
}

Step 7: Assign Security Manager Role​

The security manager role is assigned at the organization level, not per-repository. Navigate to:

Organization Settings > Security > Security managers > Add team

Or use the API:

# Assign the security team as security managers (bash)
gh api \
-X PUT \
-H "Accept: application/vnd.github+json" \
/orgs/{org}/security-managers/teams/security
# Assign the security team as security managers (PowerShell)
gh api `
-X PUT `
-H "Accept: application/vnd.github+json" `
/orgs/{org}/security-managers/teams/security

Verify:

# List security manager teams (bash)
gh api \
-H "Accept: application/vnd.github+json" \
/orgs/{org}/security-managers \
--jq '.[].slug'

Expected output: security

Step 8: Create a Custom Repository Role​

Custom roles must be created through the web interface or the REST API.

# Create the "Release Coordinator" custom role (bash)
gh api \
-X POST \
-H "Accept: application/vnd.github+json" \
/orgs/{org}/custom-repository-roles \
-f name="Release Coordinator" \
-f description="Can manage releases, tags, and webhooks without full admin access" \
-f base_role="write" \
-F 'permissions[]=manage_webhooks' \
-F 'permissions[]=create_tag_protection' \
-F 'permissions[]=edit_repo_metadata'
# Create the "Release Coordinator" custom role (PowerShell)
gh api `
-X POST `
-H "Accept: application/vnd.github+json" `
/orgs/{org}/custom-repository-roles `
-f name="Release Coordinator" `
-f description="Can manage releases, tags, and webhooks without full admin access" `
-f base_role="write" `
-F 'permissions[]=manage_webhooks' `
-F 'permissions[]=create_tag_protection' `
-F 'permissions[]=edit_repo_metadata'

Validation: After creating the role, navigate to Organization Settings > Repository roles to verify the "Release Coordinator" role appears with the correct base permission and additional capabilities.

Step 9: Configure PAT Policies​

PAT policies are configured through the organization settings UI:

  1. Navigate to Organization Settings > Third-party access > Personal access tokens > Settings
  2. Under "Fine-grained personal access tokens":
    • Set "Require approval" to enabled
    • Set "Maximum lifetime" to 90 days
  3. Under "Personal access tokens (classic)":
    • Set "Restrict access" to block classic PATs from accessing this organization

API Alternative: As of the last verification date, PAT policy configuration is primarily a web interface operation. Check the GitHub REST API changelog for updates on programmatic PAT policy management.

Step 10: Audit Your Configuration​

# Comprehensive audit of team permissions (bash)
echo "=== Organization Base Permission ==="
gh api /orgs/{org} --jq '.default_repository_permission'

echo -e "\n=== Teams ==="
gh api /orgs/{org}/teams --jq '.[] | "\(.slug): \(.description)"'

echo -e "\n=== Security Managers ==="
gh api /orgs/{org}/security-managers --jq '.[].slug'

echo -e "\n=== Custom Roles ==="
gh api /orgs/{org}/custom-repository-roles --jq '.custom_roles[] | "\(.name) (base: \(.base_role))"'

echo -e "\n=== Platform-Core Repos ==="
gh api /orgs/{org}/teams/platform-core/repos --jq '.[] | "\(.name): \(.role_name)"'
# Comprehensive audit of team permissions (PowerShell)
Write-Host "=== Organization Base Permission ==="
gh api /orgs/{org} --jq '.default_repository_permission'

Write-Host "`n=== Teams ==="
gh api /orgs/{org}/teams --jq '.[] | "\(.slug): \(.description)"'

Write-Host "`n=== Security Managers ==="
gh api /orgs/{org}/security-managers --jq '.[].slug'

Write-Host "`n=== Custom Roles ==="
gh api /orgs/{org}/custom-repository-roles --jq '.custom_roles[] | "\(.name) (base: \(.base_role))"'

Write-Host "`n=== Platform-Core Repos ==="
gh api /orgs/{org}/teams/platform-core/repos --jq '.[] | "\(.name): \(.role_name)"'

8.7 Q&A — Review Questions​

Test your understanding of GitHub Enterprise Cloud access control with the following 10 questions. Each question has exactly one correct answer.


Question 1: An enterprise has three organizations. The enterprise owner sets the Copilot policy to "Allowed for selected organizations" and enables it only for the "product" organization. An organization owner of the "platform" organization tries to enable Copilot for their members. What happens?

A) The platform organization owner can enable Copilot because organization owners have full control over their organization's settings. B) The platform organization owner cannot enable Copilot because the enterprise policy restricts it to the product organization only. C) The platform organization owner can enable Copilot but must pay for seats from a separate billing allocation. D) The enterprise policy is overridden because Copilot settings are always controlled at the organization level.


Question 2: A company wants their finance team lead to be able to view and manage GitHub Enterprise billing and payment methods, but not access any code repositories or organization settings. Which role should they assign?

A) Enterprise Member with read-only repository access B) Organization Owner with restricted permissions C) Enterprise Billing Manager D) Organization Member with no team assignments


Question 3: Your organization has a 4-person application security team that needs to view code scanning alerts and Dependabot alerts across all 85 repositories. They should NOT be able to modify code. What is the most appropriate configuration?

A) Add each security team member as a collaborator with Read access to all 85 repositories. B) Create a "security" team, assign it the organization Security Manager role. C) Make all four security team members Organization Owners. D) Create a custom repository role with alert management permissions and assign it per repository.


Question 4: A developer creates a classic Personal Access Token (PAT) with the repo scope. How does this token's access compare to a fine-grained PAT?

A) The classic PAT grants access only to public repositories, while the fine-grained PAT can access private repositories. B) The classic PAT grants full read/write access to ALL repositories the user can access, while a fine-grained PAT can be scoped to specific repositories with specific permissions. C) Both token types grant identical access; the difference is only in the token format. D) The classic PAT is more secure because it uses a longer token string with built-in encryption.


Question 5: Your CI/CD pipeline currently authenticates to GitHub using a senior engineer's personal access token. The engineer is leaving the company in two weeks. What is the recommended action?

A) Transfer the PAT to another team member's account before the engineer leaves. B) Create a new classic PAT under a shared service account. C) Replace the PAT with a GitHub App installation that authenticates with short-lived installation tokens. D) Extend the departing engineer's GitHub access for 90 days to allow a gradual transition.


Question 6: An organization sets its base repository permission to "none." A new developer joins the organization and is added to the "frontend" team, which has Write access to the "web-app" repository. What access does this developer have to the "api-backend" repository?

A) Write access, because team membership grants organization-wide Write access. B) Read access, because all organization members can read all repositories. C) No access, because the base permission is "none" and the developer has no team or direct grant for that repository. D) Triage access, because that is the minimum access for any authenticated organization member.


Question 7: Which of the following is a key advantage of GitHub Apps over OAuth Apps for enterprise integrations?

A) GitHub Apps can access more API endpoints than OAuth Apps. B) GitHub Apps use long-lived tokens that never expire, reducing maintenance overhead. C) GitHub Apps act as their own identity with short-lived tokens, scoped to specific repositories and permissions, and do not consume a user license. D) GitHub Apps are free, while OAuth Apps require a per-seat license.


Question 8: An organization owner wants to create a custom repository role called "Documentation Lead" that can edit wiki pages and manage GitHub Pages settings but cannot push code to the main branch. What base role should they select?

A) Read — then add wiki and Pages management permissions B) Triage — then add wiki and Pages management permissions C) Write — then rely on branch protection rules to prevent pushes to main D) Maintain — because it includes wiki and Pages management by default


Question 9: An enterprise streams its audit log to a SIEM system. A security analyst notices that a fine-grained PAT was created with "Contents: Read-write" permission scoped to a sensitive repository. What organization-level policy could have prevented this token from being used without oversight?

A) Disabling all API access to the organization B) Requiring organization owner approval for fine-grained PATs targeting the organization C) Setting the base repository permission to "none" D) Enabling two-factor authentication for all organization members


Question 10: Your organization has 120 developers and uses GitHub Enterprise Cloud. You need to grant the QA team the ability to create and label issues, assign issues to developers, and close resolved issues across all repositories — but they should NOT be able to push code. Which repository permission level is most appropriate?

A) Read B) Triage C) Write D) Maintain


Answer Key​

Question 1: B Enterprise policies set by enterprise owners take precedence over organization-level settings. If the enterprise restricts Copilot to selected organizations, organization owners outside that selection cannot enable it. This is a fundamental aspect of the cascading policy model.

Question 2: C The Enterprise Billing Manager role provides access to billing and payment management without any access to repositories, organization settings, or enterprise policies beyond billing. This supports separation of duties required by compliance frameworks like SOC 2.

Question 3: B The Security Manager role is purpose-built for this scenario. It grants read access to all repositories and the ability to view and manage security alerts across the organization, without code write access. Option A is administratively unscalable at 85 repositories. Option C violates least privilege. Option D would require maintaining 85 individual role assignments.

Question 4: B Classic PATs with the repo scope grant full read/write access to every repository the user can access — there is no way to scope them to specific repositories. Fine-grained PATs allow repository-level and permission-level scoping, making them significantly more secure for enterprise use.

Question 5: C GitHub Apps authenticate as their own identity using short-lived installation tokens generated from a private key. They are not tied to any individual user account, so they survive employee offboarding without interruption. Option A is not technically possible (PATs cannot be transferred). Option B uses a shared account, which violates audit trail requirements. Option D creates a security risk.

Question 6: C With a base permission of "none," organization members have no default access to any repository. Access must be explicitly granted through team membership or direct collaborator assignment. Since the developer is only on the "frontend" team with access to "web-app," they have no access to "api-backend."

Question 7: C GitHub Apps act as their own identity (not a user), use installation tokens that expire after 1 hour, can be scoped to specific repositories with granular permissions, and do not consume a user license. Option B is incorrect because GitHub Apps use short-lived tokens, not long-lived ones.

Question 8: D The Maintain base role includes the ability to manage topics, wikis, and GitHub Pages settings — which is exactly what a Documentation Lead needs. Branch protection rules (not custom role definitions) are the mechanism to prevent pushes to protected branches. While option C could work with additional branch protection configuration, Maintain is the most direct and appropriate choice because it is designed for this level of repository management.

Question 9: B The "Require approval" policy for fine-grained PATs ensures that any token targeting the organization must be reviewed and approved by an organization owner before it becomes active. This provides oversight for token creation targeting sensitive repositories. Option C (base permission) affects repository-level default access, not token creation. Option D (2FA) protects account access but does not govern token scope.

Question 10: B The Triage permission level grants exactly these capabilities: create, label, assign, and close issues and pull requests, as well as request reviews — without the ability to push code. Read (A) does not allow creating or managing issues. Write (C) would grant code push access, which violates the requirement. Maintain (D) would grant even more access than necessary.


Next: Chapter 9: Team-Based Permission Strategies (See Chapter 9: Team-Based Permission Strategies)

Previous: Chapter 7: Organization Design & Team Architecture (See Chapter 7: Organization Design & Team Architecture)