Last Verified: September 2026
Scope: GitHub.com organization administration, with GitHub Enterprise Cloud and GitHub Enterprise Server differences called out where they materially affect administration.
Audience: GitHub organization owners, platform engineers, DevOps engineers, security administrators, developers with delegated administration duties, technical trainers, and architects.

GitHub Organizations are shared accounts that hold repositories, teams, projects, packages, policies, integrations, security controls, and administrative settings for a group of people. An organization is not a login identity by itself: people normally sign in with personal accounts, then receive organization, team, repository, or delegated administrative roles. Enterprise Managed Users are the important exception because identities are provisioned and controlled by an enterprise identity provider.

This guide teaches GitHub Organization administration as an operating system for engineering governance rather than as a collection of settings pages. The practical pattern throughout is:

Concept -> reason -> configuration -> verification -> operational use -> governance -> troubleshooting

1. What a GitHub Organization Is

A GitHub Organization is a collaboration and governance boundary for shared software assets. It provides a single namespace such as github.com/acme, then lets administrators define who can access resources, what they can do, how repositories are created, how CI/CD runs, which applications can connect, how security features are applied, and how activity is audited.

Personal account vs organization

Area	Personal account	Organization
Login identity	Yes	No, except managed-user enterprise models influence identity
Own repositories	Yes	Yes
Teams	No	Yes
Organization roles	No	Yes
Central repository policy	Limited	Yes
Rulesets across repositories	No organization scope	Yes
Organization Actions policy	No	Yes
SAML/SCIM governance	No	Enterprise Cloud organization/enterprise feature
Central security rollout	No	Yes
Audit log for shared administration	Personal security log	Organization audit log
Billing delegation	Personal billing	Owners and billing managers

Core organization resources

An organization can contain or control:

• Repositories and repository policies
• Teams and nested teams
• Members, owners, outside collaborators, and billing managers
• Projects, issue types, and organization issue fields
• GitHub Packages
• GitHub Actions policies, runners, runner groups, secrets, variables, and usage
• Codespaces policies and organization-paid usage
• GitHub Copilot access and policy controls
• Webhooks, GitHub Apps, OAuth Apps, and personal access token policies
• Security configurations, secret scanning, code scanning, dependency security, and Code Quality
• Verified domains, authentication controls, SAML SSO, SCIM, and IP allow lists where supported
• Audit logs, usage reports, billing controls, compliance reports, and lifecycle controls

Organization mental model

flowchart TD
    U[Users and identities] --> R[Organization roles]
    U --> T[Teams]
    R --> O[Organization settings]
    T --> A[Repository access]
    O --> P[Policies and governance]
    P --> REPO[Repositories]
    P --> CI[Actions and runners]
    P --> SEC[Security and quality]
    P --> APP[Apps and integrations]
    P --> PLAN[Projects and planning]
    REPO --> AUDIT[Audit and reporting]
    CI --> AUDIT
    SEC --> AUDIT
    APP --> AUDIT

The important idea is that organization administration works in layers. Identity determines who the actor is, roles and teams determine permissions, policies constrain behavior, and audit/monitoring verifies what actually happened.

2. GitHub Organization Plans and Editions

GitHub exposes organization functionality through multiple plans and products. Exact commercial packaging changes over time, so administrators should verify plan-specific availability before a rollout.

Edition / plan	Typical administration scope
GitHub Free	Core organizations, repositories, teams, basic permissions, public/private collaboration, Actions, Packages, Projects, basic security controls
GitHub Team	Adds stronger collaboration/governance capabilities and organization features useful to professional teams; many repository ruleset and Codespaces organization controls are available here
GitHub Enterprise Cloud	Enterprise identity and governance, SAML SSO, SCIM patterns, custom roles, enterprise policy inheritance, advanced auditing/network controls, enterprise management, optional security products, data residency options
GitHub Enterprise Server	Self-hosted GitHub platform; features and UI differ by GHES release, and cloud-only functionality may not exist or may arrive later

Standalone vs enterprise-owned organizations

A standalone organization is administered directly at organization level. An enterprise-owned organization can inherit restrictions or settings from the enterprise account. When an enterprise policy is stricter, organization owners may see a setting but be unable to relax it.

A useful precedence model is:

Enterprise policy
      ↓
Organization policy
      ↓
Repository policy
      ↓
Workflow / user action

Lower levels can often become more restrictive, but cannot bypass a higher-level enforced restriction.

Enterprise Managed Users

Enterprise Managed Users (EMU) changes the identity model. Instead of employees using independently managed personal accounts, the enterprise provisions and controls managed user accounts through the identity system. This affects onboarding, offboarding, external collaboration, SSO behavior, SCIM, and some organization-level identity controls. Treat EMU as an enterprise architecture decision, not as a simple organization toggle.

3. Creating an Organization and Establishing a Baseline

Create an organization

The standard UI path is:

1. Open your GitHub account settings.
2. Select Organizations.
3. Choose New organization.
4. Select the appropriate plan.
5. Choose the organization account name.
6. Configure billing details if required.
7. Add initial owners or invite members.
8. Open the new organization’s Settings page and establish a baseline before broad onboarding.

Naming and URL design

The organization account name becomes part of URLs, clone paths, API paths, package namespaces, mentions, and automation. Choose a name that is stable and does not depend on a temporary department, legal entity, or project code unless that is intentional.

Good examples:

acme
acme-platform
acme-open-source

Avoid:

acme-temp-2026
johns-team
migration-test-final2

Initial baseline checklist

Before inviting a large user population:

1. Add at least two trusted owners.
2. Set organization profile and contact details.
3. Set base repository permissions deliberately.
4. Decide who may create repositories and which visibilities they may use.
5. Require 2FA where appropriate and understand the effect on collaborators.
6. Define the team hierarchy.
7. Restrict third-party application access.
8. Configure GitHub Actions policy and default GITHUB_TOKEN permissions.
9. Define repository rulesets for important branches.
10. Create repository custom properties such as owner, service_tier, data_classification, and environment.
11. Decide how organization secrets and variables will be scoped.
12. Configure audit review and billing alerts.
13. Establish onboarding and offboarding procedures.
14. Pilot security configurations before broad enforcement.

Expected result

A newly created organization should have clear owners, a defined default access model, safe repository creation rules, controlled CI/CD execution, and enough metadata to automate future governance.

4. Navigating Organization Administration

A GitHub organization typically exposes top-level areas such as:

• Overview
• Repositories
• Projects
• Packages
• Teams
• People
• Insights or Security and quality views
• Settings

The Settings navigation groups administrative controls into areas that can include:

Settings family	Examples
General	Profile, organization identity, messages, lifecycle
Access	Billing, organization roles, repository roles, member privileges, people, teams
Code, planning, and automation	Repository policies, custom properties, Projects, issue types/fields, Actions, Codespaces, Sandboxes, webhooks, packages, Pages
Security and quality	Authentication, security products, Code Quality, deploy keys, domains, secrets and variables
Third-party access	GitHub Apps, OAuth App policy, personal access tokens
Integrations	Scheduled reminders and external integrations
Archive and logs	Audit logs, deleted repositories, organization archive
Developer settings	Organization-owned GitHub Apps and OAuth Apps

The UI evolves frequently. Use the concept name rather than memorizing only the exact sidebar position.

5. General Settings and Organization Identity

General settings describe the organization publicly and operationally.

Common profile fields include:

• Display name
• Public email
• Description
• Website URL
• Social accounts
• Location
• Billing email
• Organization avatar
• Communication preferences
• Sponsors update email, where used
• Sponsorship/Patreon linkage, when the organization participates in GitHub Sponsors

GitHub also supports organization-level sponsorship settings. Organizations that sponsor maintainers can configure update email behavior, and eligible organizations can connect Patreon or participate in GitHub Sponsors. These settings matter mainly to open-source organizations; they are not core repository-governance controls.

Organization name vs display name

The account name is the URL-safe identifier used in paths such as github.com/acme. The display name is descriptive text shown on the profile. Renaming the account name has much wider technical impact than editing the display name.

Branding and public profile

Treat the public organization profile as part of your engineering identity. For public organizations, confirm that the website domain, email domain, profile description, and verified-domain status are consistent.

6. Ownership and Administrative Continuity

Organization owners have broad administrative authority. GitHub explicitly recommends limiting owner access while maintaining more than one owner for continuity.

Owner responsibilities

Owners can typically:

• Change organization settings
• Manage membership and roles
• Access every repository in the organization
• Configure policies and security controls
• Manage application access
• Access audit information
• Manage organization lifecycle operations

Ownership continuity pattern

Use at least two owners, ideally from separate operational roles or reporting lines.

flowchart LR
    O1[Primary owner] --> ORG[Organization]
    O2[Backup owner] --> ORG
    SEC[Security admin] --> R1[Delegated security role]
    CICD[Platform admin] --> R2[Delegated CI/CD role]
    BILL[Finance admin] --> R3[Billing manager]

Do not make every administrator an owner. Use delegated roles such as security manager, billing manager, moderator, CI/CD admin, App Manager, repository roles, and custom roles where available.

Ownership transfer

GitHub does not provide a single magical “transfer owner” switch. The operational process is:

1. Add or promote the new person to owner.
2. Confirm that the new owner can access Settings.
3. Update payment and billing responsibility if required.
4. Update recovery and operational contacts.
5. Remove or demote the previous owner only after the handover is verified.

7. People and Membership

The People area is the operating center for human access.

Membership categories

Category	Meaning	Typical use
Owner	Full organization administration	Very small trusted admin set
Member	Normal organization participant	Employees and long-term contributors
Outside collaborator	Repository access without organization membership	Vendors, contractors, temporary partners
Billing manager	Billing administration without general organization ownership	Finance or procurement staff
Pending invitation	Invited but not accepted	Onboarding
Former member	Previously belonged to the organization	Reinstatement or audit context

Inviting members

You can invite by username or email, assign the initial role, and optionally add a person to teams. Invitations expire if they are not accepted within GitHub’s invitation validity period, so operational onboarding should verify acceptance rather than assuming the invitation is sufficient.

Recommended onboarding workflow

flowchart LR
    HR[Joiner event] --> ID[Identity ready]
    ID --> INV[Organization invitation]
    INV --> TEAM[Team membership]
    TEAM --> ROLE[Delegated role if needed]
    ROLE --> REPO[Repository access]
    REPO --> SEC[2FA or SSO compliance]
    SEC --> VERIFY[Verify effective access]

Restoring former members

When a former member returns, GitHub can restore some previous access context in supported flows, but administrators should still review whether old access is appropriate. Do not use restoration as an excuse to skip a current access review.

8. Outside Collaborators

Outside collaborators are useful when someone needs access to selected repositories but should not become a full organization member.

Typical examples:

• Short-term consultants
• External auditors
• Agency developers
• Integration partners

Security considerations

Outside collaborators should receive only the repository permissions they need. Review them more frequently than employees because their employment lifecycle may not be visible to your identity platform.

Recommended controls:

• Require secure authentication where supported by your organization policy.
• Give access through the smallest possible repository set.
• Avoid Admin unless it is genuinely required.
• Set an internal expiry/review date.
• Review deploy keys, PATs, and app installations that may outlive the collaborator.

Member vs outside collaborator

Question	Member	Outside collaborator
Needs multiple team memberships?	Good fit	Usually not
Needs organization-level roles?	Yes	Not the normal model
Should appear as part of workforce?	Yes	Usually no
Needs one or two repositories temporarily?	Possible	Often best fit
Central lifecycle through IdP?	Common in enterprise	Often manual

9. Membership Visibility

A member can have public or private organization membership depending on configuration and account choices. Public membership can appear on a user’s profile; private membership does not.

Do not confuse membership visibility with repository access. A private membership can still have extensive internal repository permissions.

10. Teams and Team Administration

Teams are the preferred unit for scalable repository access.

Why teams matter

Without teams, administrators often grant direct access repository by repository. That quickly becomes difficult to audit and remove. Teams let you model real ownership boundaries such as:

engineering
├── platform
│   ├── sre
│   └── developer-experience
├── backend
└── mobile

Team capabilities

Teams can provide:

• Membership grouping
• Repository permissions
• Team mentions such as @acme/platform
• Team review requests
• Team discussions where supported
• Parent/child hierarchy
• Team maintainers
• Identity-provider synchronization in eligible enterprise configurations

Team maintainer

A team maintainer can manage many team-level tasks without becoming an organization owner. This is a useful delegation boundary for engineering managers and technical leads.

Team repository permissions

A team may be granted Read, Triage, Write, Maintain, Admin, or a custom repository role where supported.

Recommended pattern:

platform-readers  -> Read
platform-dev      -> Write
platform-maint    -> Maintain
platform-admin    -> Admin only for a very small set

Avoid building a single giant all-engineers-admin team.

11. Repository Roles

GitHub’s standard organization repository roles are:

Role	Typical purpose
Read	View and discuss code
Triage	Manage issues and pull requests without code write access
Write	Push code and perform normal contributor work
Maintain	Manage repository operations without the most sensitive destructive administration
Admin	Full repository administration

The recommended design principle is “the lowest role that supports the job.”

Base repository permission

Base permission is the default repository access granted to organization members. Repository-specific team or individual grants can add more access.

A conservative enterprise pattern is:

Base permission: None or Read
Normal write access: via team
Admin access: exceptional and reviewed

Effective access model

flowchart TD
    BASE[Organization base permission] --> EFF[Effective repository access]
    TEAM[Team permission] --> EFF
    USER[Direct user permission] --> EFF
    ROLE[All-repository or custom role] --> EFF
    EFF --> RULES[Repository rules and policies still apply]

Permissions determine what an actor is allowed to attempt. Rulesets, branch protections, Actions policy, and other governance can still constrain that actor.

12. Organization Roles and Delegated Administration

Organization roles are sets of permissions that let you delegate specific administrative work without granting ownership.

Predefined roles can include:

• Member
• Owner
• Moderator
• Billing manager
• Security manager
• CI/CD administrative roles
• App Manager
• All-repository roles such as Read, Triage, Write, Maintain, or Admin where available

Exact predefined role availability can depend on plan and GitHub’s evolving role model.

Security manager

Use a security manager team when the security function needs broad visibility and management of security alerts without general ownership.

CI/CD administration

A CI/CD administrative role is appropriate for platform teams that manage Actions policies, runners, or runner groups but should not administer billing or organization membership.

App Manager

App Managers can be delegated responsibility for organization-owned GitHub App registrations without being made owners. App registration management is distinct from installing an app into an organization.

Custom organization roles

GitHub Enterprise Cloud supports custom organization roles that combine selected organization and repository permissions. A custom role is appropriate when predefined roles are too broad or do not match your operating model.

Example role design:

Custom role	Needed capabilities	Avoid granting
Audit reviewer	View organization audit log	Membership changes, billing
Repository governor	Manage repository rules/settings	Organization ownership
Integration operator	View/manage selected app settings	Billing and people admin
Release governance admin	Manage release/repository policy	Unrelated security controls

Role assignment practice

1. Define the job function.
2. Map required actions to permissions.
3. Start with predefined roles.
4. Create a custom role only when a repeatable gap exists.
5. Assign roles to teams when possible.
6. Review assignments periodically.
7. Audit role changes.

13. Custom Repository Roles

Custom repository roles, available on supported enterprise plans, inherit a standard role and add selected permissions.

Example:

Base role: Write
Custom additions: manage selected repository metadata
Result: Service Maintainer

Use a custom repository role when the same permission shape is needed across many repositories. If only one repository has a one-off exception, reconsider whether the exception should exist at all.

When a custom repository role is deleted, affected assignments fall back according to GitHub’s documented behavior, so deletion should be treated as a controlled access change.

14. Member Privileges

Member privileges govern what ordinary members can create or administer by default.

Important decisions include:

• Can members create repositories?
• Which repository visibilities can they create?
• Can members delete or transfer repositories?
• Can members change repository visibility?
• Can members create teams?
• Can members create Projects?
• Can repository administrators install GitHub Apps?
• Can members request app access?

Recommended baseline

For a tightly governed organization:

Capability	Recommended starting point
Create private repositories	Allow only if self-service creation is part of your platform model
Create public repositories	Restrict unless open source publication is intentional
Change visibility	Owners or governed process
Delete repositories	Restricted and auditable
Transfer outside organization	Restricted
Install GitHub Apps	Owners or approved request workflow
Create teams	Centralized or delegated intentionally

The goal is not “lock everything.” The goal is to make high-risk actions deliberate while keeping normal engineering work fast.

15. Billing, Licensing, Budgets, and Cost Control

Organization administration includes both fixed-license and metered products. Owners and billing managers should separate three questions:

1. Who is licensed?
2. What metered usage is occurring?
3. Who is accountable for the cost?

Common billing dimensions

Depending on the products enabled, an organization may incur charges for:

• GitHub Team or GitHub Enterprise Cloud seats
• GitHub Actions compute and storage
• GitHub Packages storage and transfer
• GitHub Codespaces compute and storage
• GitHub Copilot licenses and AI usage
• GitHub Advanced Security products such as Code Security or Secret Protection
• GitHub Code Quality
• Cloud sandbox usage for GitHub Copilot
• Other metered services exposed in GitHub billing

Seats and licenses

Review:

• Total purchased or available seats
• Used seats
• Pending invitations
• Members or outside collaborators consuming billable seats where applicable
• Product-specific license assignments

Do not assume that removing repository access automatically removes every paid product assignment. Offboarding should explicitly review product seats.

Budgets and alerts

Budgets are useful for GitHub’s metered products. A budget can provide thresholds and alerts; for some products it can also be configured to prevent further usage after the limit, while license-based products may continue and simply alert.

Recommended cost model:

Organization budget
├── Actions
├── Codespaces
├── Packages
├── AI / Copilot usage
└── Security or quality products

For enterprise accounts, cost centers can add another allocation layer.

Monthly cost-review procedure

1. Open billing usage.
2. Compare actual usage to budget.
3. Identify the top repositories or users driving metered cost.
4. Investigate unexpected growth.
5. Adjust runner sizes, retention, Codespaces machine policies, or product assignment where appropriate.
6. Export a detailed usage report when finance or engineering needs deeper allocation data.
7. Document exceptions rather than relying on tribal knowledge.

Practical cost questions

Symptom	Likely area to inspect
Actions cost jumps	Job duration, runner size, concurrency, retry loops, artifact/cache use
Codespaces cost grows	Machine size, idle timeout, retention, number of codespaces
Packages storage grows	Old package versions, container image lifecycle
Copilot cost changes	Seat count, premium/AI usage, policy scope
Security product cost grows	Enabled repositories and active committer/licensing model

16. Repository Administration

Repositories are the primary work units of a GitHub organization. Organization administrators need both lifecycle controls and default governance.

Repository lifecycle

flowchart LR
    CREATE[Create or import] --> ACTIVE[Active]
    ACTIVE --> ARCHIVE[Archive]
    ARCHIVE --> ACTIVE
    ACTIVE --> TRANSFER[Transfer]
    ACTIVE --> DELETE[Delete]
    DELETE --> RESTORE[Restore if eligible]

Common lifecycle operations include:

• Create
• Import
• Transfer into or out of the organization
• Archive and unarchive
• Delete and restore when eligible
• Change visibility
• Convert to or create from a template

Repository creation policy

You can restrict whether members create repositories and which visibilities they may choose.

Typical enterprise baseline:

Private: self-service allowed
Internal: allowed where enterprise collaboration requires it
Public: approval required

The exact model should match your threat model. A small open-source foundation may intentionally allow public creation; a regulated company usually does not.

Public, private, and internal

Visibility	Main audience
Public	Anyone on the internet
Private	Explicitly authorized users/teams/apps
Internal	Enterprise members across eligible enterprise organizations

Internal visibility is an enterprise collaboration feature and should not be treated as equivalent to public or ordinary private visibility.

Visibility-change governance

A repository visibility change can expose code, issues, Actions history, release information, and related metadata. Restricting visibility changes is therefore a data-loss prevention control, not merely a repository preference.

Repository deletion and transfer

High-risk actions should be limited to a small group. A transfer can move code and history to a different owner. Deletion can disrupt clones, Actions, Pages, packages, and integrations.

Before deletion:

1. Confirm the repository is genuinely obsolete.
2. Check dependencies and package consumers.
3. Check Pages and Actions usage.
4. Archive first when uncertainty exists.
5. Record approval for destructive deletion.

Forking policy

Organization owners can control forking behavior for private/internal repositories according to plan and enterprise policy. Fork networks can retain code relationships and affect where sensitive code exists, so define whether developers should use forks or branches for internal contribution.

Pull request governance

Organization-level and repository-level controls can shape review behavior. Common protections include:

• Required pull requests
• Required approvals
• Code owner review
• Dismissal of stale approvals
• Required status checks
• Merge queue
• Signed commits
• Linear history
• Force-push restrictions
• Deletion restrictions

Prefer rulesets for scalable, centrally governed policy rather than hand-configuring every repository independently.

Organization repository defaults

Useful defaults can include:

• Default branch naming
• Repository templates
• Default security configuration
• Standard labels through automation
• Standard README, CODEOWNERS, SECURITY.md, and CONTRIBUTING.md through repository templates or provisioning automation

17. Organization Rulesets

Rulesets are one of GitHub’s most important organization-level governance tools. They let you apply branch, tag, push, and related repository rules across many repositories.

Why rulesets instead of manual branch protection everywhere?

A repository-by-repository model creates drift. Organization rulesets let you define a policy once and target repositories dynamically.

flowchart TD
    CLASS[Repository classification] --> TARGET[Ruleset targeting]
    TARGET --> BRANCH[Branch rules]
    TARGET --> TAG[Tag rules]
    TARGET --> PUSH[Push rules]
    BRANCH --> ENFORCE[Central enforcement]
    TAG --> ENFORCE
    PUSH --> ENFORCE
    ENFORCE --> INSIGHT[Ruleset insights and bypass review]

Ruleset targets

Rulesets can target:

• All repositories
• Selected repositories
• Repository names matching patterns
• Repositories matching custom-property filters
• Supported deployment context filters

This makes custom properties especially valuable: metadata becomes policy input.

Branch and tag rules

Typical rules include:

• Restrict creation or deletion
• Restrict updates
• Prevent force pushes
• Require pull requests
• Require approvals
• Require code owner review
• Require status checks
• Require signed commits
• Require linear history
• Require merge queue where applicable
• Restrict tag updates/deletions

Push rulesets

Push rulesets can block pushes based on characteristics such as:

• File extensions
• File sizes
• File and directory paths
• Path length rules

They can protect a repository and, in relevant configurations, its fork network.

Enforcement status

Use:

• Disabled while designing or temporarily suspending a rule
• Active for enforced policy
• Evaluate only where the product/plan and rule type support evaluation mode

Bypass design

Bypass capability should be rare, auditable, and attached to a role or integration rather than a large group. A bypass is not an alternative daily workflow.

Recommended model:

Normal development -> rules enforced
Emergency -> approved bypass actor -> audit event -> post-event review

Rule aggregation

Repository-level rules can coexist with organization-level rules. In general, additional rules make the effective policy more restrictive rather than allowing a repository administrator to weaken an organization rule.

Ruleset rollout strategy

1. Identify the repositories that must be protected first.
2. Create a small pilot ruleset.
3. Validate status-check names and merge behavior.
4. Review bypass requirements.
5. Expand targeting through custom properties or naming rules.
6. Monitor rule insights and bypasses.
7. Export ruleset configuration for backup or reuse.

18. Repository Custom Properties

Custom properties are structured metadata attached to repositories. They solve a common enterprise problem: repository names and team knowledge are not enough to answer governance questions.

Useful property schema

Property	Type	Example values
service_owner	Text or select	platform, payments, mobile
service_tier	Single select	tier-0, tier-1, tier-2
data_classification	Single select	public, internal, confidential
production	Boolean	true, false
lifecycle	Single select	active, maintenance, deprecated
compliance_scope	Multi-select	pci, sox, none

Current repository custom-property types include text, single-select, multi-select, and boolean.

Required properties and defaults

Organization owners can make a property required and provide a default. Where supported, they can also require explicit values for repository creation or transfer rather than allowing a default to remain forever.

Property visibility

Custom property visibility follows repository visibility. A property on a public repository may be visible publicly, so do not store secrets or sensitive internal notes in custom properties.

Repository actors

Organizations can decide whether repository actors are allowed to set selected property values. Use this carefully: some metadata should be owned centrally, while team-owned metadata such as service ownership may be appropriate for repository administrators.

Search and ruleset targeting

Custom properties can drive search and governance. For example, a ruleset could target:

visibility:private props.service_tier:tier-0

That enables policies such as:

If service_tier = tier-0
then require stronger review and status checks

Practical governance pattern

1. Define a small vocabulary.
2. Make the highest-value properties required.
3. Avoid hundreds of free-text variants.
4. Use properties for policy targeting.
5. Review repositories with missing or default values.
6. Automate reporting through the REST API.

19. Planning Administration: Projects, Issue Types, and Issue Fields

GitHub organization planning administration now goes beyond simply enabling Projects. Organizations can standardize issue semantics and metadata.

Project policy

Organization owners can govern:

• Whether organization Projects are available
• Who can create projects
• Base access expectations
• Whether project visibility can be changed by project administrators

Use Projects for planning and cross-repository coordination; do not use project permissions as a substitute for repository security.

Issue types

Organizations can define issue types so teams can classify issues consistently. Default types include:

• Task
• Bug
• Feature

Organizations can create additional types, up to the documented limit, and can edit, disable, or delete types according to current product rules.

Good custom types:

Incident
Security finding
Technical debt
Change request
Research

Avoid creating a type for every team-specific workflow state. Status belongs in planning fields or project workflow, not in the semantic “type” of work.

Organization issue fields

Issue fields provide typed metadata on issues across repositories. Current field types include:

• Single-select
• Text
• Number
• Date

Current GitHub documentation describes organization-level limits and default fields such as Priority, Effort, Start date, and Target date when issue fields are enabled.

Useful organization fields:

Field	Type	Example
Priority	Single-select	Urgent / High / Medium / Low
Effort	Single-select or number	S / M / L or points
Customer impact	Single-select	None / Low / High
Target date	Date	2026-10-31
External ticket	Text	URL or identifier

Pinning fields to issue types

A field can be pinned to selected issue types so only relevant metadata appears. For example:

Bug -> Priority, Severity, Customer impact
Feature -> Priority, Effort, Target date
Task -> Priority, Effort

This keeps issue forms understandable while maintaining organization-wide consistency.

Field visibility

For organizations with public repositories, issue fields can be public or organization-only. Treat field visibility as a data-classification decision.

Issue fields vs project fields

Question	Issue field	Project custom field
Scope	Organization issue	Single project
Source of truth follows issue	Yes	No
Same value across projects	Yes	Not necessarily
Good for canonical priority/effort	Yes	Often, but duplicates can confuse
Good for project-specific planning	Sometimes	Yes

Search examples

is:open field.priority:high
field."target date":>=2026-10-01
field.story-points:>5

Current limitation to remember

Issue fields apply to issues, not pull requests. Do not design a process that assumes the same custom issue metadata automatically exists on PRs.

20. Import, Export, and Migration Administration

There are several different migration concepts in GitHub, and they should not be mixed together.

Repository import

Use repository import or Git-based migration when moving source history from another Git host and you do not need full-fidelity migration of every GitHub-specific object.

Repository transfer

Use transfer when the repository already exists on GitHub and ownership must move to another account or organization.

GitHub Enterprise Importer

GitHub Enterprise Importer (GEI) is the strategic migration tool for supported GitHub-to-GitHub and GitHub Enterprise Server-to-Enterprise Cloud scenarios.

It supports high-fidelity repository migration and, for supported GitHub.com scenarios, organization migration.

Migration governance checklist

1. Inventory repositories and owners.
2. Identify source and target identities.
3. Map teams and permissions.
4. Review rulesets and target policies.
5. Review Actions secrets and environment dependencies.
6. Review Packages, Pages, webhooks, apps, and deploy keys.
7. Run a trial migration.
8. Validate migration logs.
9. Perform a production freeze if required.
10. Validate repository counts, refs, issues, pull requests, teams, and critical integrations.
11. Re-enable or reconfigure items that are intentionally not activated automatically.

Important GEI behavior

Do not assume every organization setting or membership detail is migrated. For example, current GitHub documentation notes that organization migrations can move teams, repositories, team access, member privileges, organization webhooks, and default branch settings in supported scenarios, while team membership requires post-migration work. Always validate the current migration matrix before a production event.

No-delta warning

In common GEI repository migration flows, changes made after the migration snapshot may not be captured by a later “delta” pass. Plan a controlled cutover or a documented way to reconcile changes.

21. Moderation and Interaction Controls

Moderation is especially relevant for public repositories and open-source organizations.

Moderator role

Organization moderators can be delegated capabilities such as:

• Block and unblock users
• Manage organization interaction limits
• Manage repository interaction limits
• Hide disruptive comments where supported

This is a good example of delegated administration: community operations should not require owner access.

Interaction limits

Temporary interaction limits can restrict participation for selected categories of users, such as:

• New accounts
• Users without prior contributions
• Users who are not repository collaborators

Use interaction limits during spam bursts, coordinated abuse, or unusually high moderation load. They are temporary controls, not a replacement for normal community governance.

Blocking users

Blocking may prevent a user from interacting with organization repositories according to GitHub’s moderation behavior. Use it for abuse, harassment, or security reasons and document the internal rationale when your organization has formal moderation procedures.

22. GitHub Actions Organization Administration

GitHub Actions is not just a CI/CD feature; at organization scale it is an execution platform with supply-chain, credential, network, cost, and policy implications.

Organization administrators should control four layers:

flowchart TD
    P[Actions policy] --> W[Workflow permissions]
    W --> A[Allowed actions and reusable workflows]
    A --> R[Runner and runner group access]
    R --> S[Secrets variables and OIDC]
    S --> M[Metrics cost and audit]

Enable, disable, or restrict Actions

At organization level you can:

• Enable Actions for all repositories
• Enable Actions only for selected repositories
• Disable Actions
• Limit which actions and reusable workflows may run

A secure organization should decide whether it trusts:

• Local actions in the same repository
• Actions from the same organization
• GitHub-authored actions
• Marketplace actions by verified creators
• Arbitrary third-party actions
• Reusable workflows from approved repositories

Action allowlist strategy

A useful maturity progression is:

Maturity	Policy
Basic	Allow GitHub and verified actions
Controlled	Allow GitHub plus explicitly approved third-party actions
High assurance	Explicit allowlist plus full-SHA pinning
Regulated	Approved reusable workflows, curated runner groups, provenance/security review

GitHub supports requiring actions to be pinned to a full-length commit SHA. This reduces the risk that a mutable tag points to different code later.

Default GITHUB_TOKEN permissions

The organization can choose a default permission model for GITHUB_TOKEN.

Recommended baseline:

Default: restricted / read-oriented
Workflow: explicitly request only permissions needed

Example workflow:

name: build

on:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@<FULL_COMMIT_SHA>
      - run: npm ci
      - run: npm test

The placeholder must be replaced with the reviewed full commit SHA of the action version you intend to use.

Pull request creation and approval

Organizations can control whether GitHub Actions may create or approve pull requests. This should be enabled only when workflows genuinely need that capability.

Fork pull request policies

Fork-based workflows can execute code from contributors. Never expose organization secrets or trusted self-hosted runners to untrusted pull-request code without a deliberate security design.

23. Runners and Runner Groups

Actions jobs execute on runners. The runner is therefore part of your trust boundary.

Runner types

• Standard GitHub-hosted runners
• Larger GitHub-hosted runners
• Self-hosted runners
• Autoscaled or ephemeral self-hosted runners, often through runner orchestration solutions such as Actions Runner Controller

Runner group purpose

Runner groups provide access boundaries and routing.

A runner group can restrict:

• Which repositories may use the runners
• Which workflows may use the runners in supported configurations
• Which organizations may use an enterprise runner group
• Concurrency, depending on runner-group type and product

Secure runner-group model

runner-public-ci       -> low-trust build jobs
runner-internal        -> internal repositories
runner-deploy-staging  -> selected deployment workflows
runner-deploy-prod     -> only approved production workflows

Do not let every repository access a production deployment runner.

Workflow access restriction

Where workflow-level access is supported, identify approved reusable or deployment workflows by complete path and ref. Prefer full, unambiguous refs.

Self-hosted runner warning

Self-hosted runners execute workflow code on infrastructure you control. A malicious workflow can potentially read local files, credentials, network-accessible resources, or residual data from previous jobs.

Prefer:

• Ephemeral runners
• Clean images
• Minimal network access
• No long-lived cloud credentials
• OIDC federation
• Separate runner groups by trust level
• No public-repository workloads on sensitive self-hosted runners

Disabling standard hosted runners

Organizations can disable standard GitHub-hosted runners and force workloads through governed runner groups. This is useful when all compute must use approved network or compliance boundaries.

24. Hosted Compute Networking

GitHub provides organization-level networking controls for supported hosted compute products.

For GitHub-hosted larger runners, supported private-networking designs can connect runners to private resources while GitHub manages the runner infrastructure.

Administrative considerations:

• Network configuration ownership
• DNS behavior
• Firewall rules
• Static or predictable IP needs
• Connectivity to internal services
• Runner-group binding
• Repository access policy

Do not use private networking as a reason to make workflow permissions broad. Network access and workflow authorization are separate controls.

25. Actions Retention, Caches, Usage, and Metrics

GitHub lets organizations configure retention for Actions-related data within documented limits.

Current GitHub documentation notes an important change effective October 1, 2026: organization retention settings will also apply to checks, workflow runs, and commit statuses, not only artifacts and logs. Review your retention configuration before that date.

Retention considerations

• Public repositories have a lower maximum retention than private repositories.
• Organization or enterprise limits can cap repository-level choices.
• New retention settings are generally not retroactive to older objects.

What to monitor

• Job duration
• Queue duration
• Runner utilization
• Concurrency
• Artifact storage
• Cache storage
• Actions minutes or compute usage
• Failed/retried workflows
• Cost by repository where available

Troubleshooting queue delays

1. Check whether the workflow targets a runner label or group that exists.
2. Confirm repository access to the runner group.
3. Check runner online/offline status.
4. Review concurrency limits.
5. Check whether enterprise policy blocks the workflow.
6. Check whether required actions are blocked by the allowlist.

26. Organization Secrets and Variables

Organization-level secrets and variables reduce duplication but can also create large blast radiuses.

Secrets

Use organization secrets for values that multiple repositories need but do not expose them to every repository automatically unless that is genuinely appropriate.

Typical visibility choices include:

• All repositories
• Private repositories
• Selected repositories

Example with GitHub CLI:

gh secret set DEPLOY_TOKEN \
  --org acme \
  --visibility selected \
  --repos api,worker

GitHub CLI will prompt for or read the secret value according to the command usage.

Variables

Variables are for non-secret configuration.

gh variable set DEFAULT_REGION \
  --org acme \
  --body "ap-northeast-1" \
  --visibility selected \
  --repos api,worker

Secret design rules

• Prefer OIDC federation over static cloud keys.
• Scope organization secrets to selected repositories when possible.
• Rotate secrets on a defined schedule and after incidents.
• Do not store plaintext secrets in repository configuration.
• Audit which workflows can reach a secret.
• Treat Terraform state containing secret material as sensitive.

27. OIDC for Cloud Authentication

GitHub Actions can exchange an OpenID Connect identity for short-lived cloud credentials. This is usually safer than storing permanent cloud access keys as organization secrets.

Conceptual flow:

sequenceDiagram
    participant W as Workflow
    participant G as GitHub OIDC
    participant C as Cloud IAM
    participant R as Cloud resource
    W->>G: Request OIDC token
    G-->>W: Signed identity token
    W->>C: Exchange token under trust policy
    C-->>W: Short lived credentials
    W->>R: Access allowed resource

Cloud trust policy should validate relevant claims such as repository, organization, branch, environment, or workflow identity according to the cloud provider’s model.

28. GitHub Codespaces Organization Administration

Organizations on supported plans can pay for Codespaces usage and apply policies to organization-billed codespaces.

Administrative areas

• Enable or disable Codespaces for selected users/repositories
• Decide who owns and pays for codespaces
• List organization codespaces
• Set spending limits
• Manage Codespaces secrets
• Restrict machine types
• Restrict number of organization-billed codespaces per user
• Restrict base images
• Restrict port visibility
• Set idle timeout
• Set retention period
• Review audit events

Cost-control flow

flowchart TD
    ACCESS[Who may use Codespaces] --> MACHINE[Allowed machine sizes]
    MACHINE --> COUNT[Codespaces per user]
    COUNT --> IDLE[Idle timeout]
    IDLE --> RETAIN[Retention]
    RETAIN --> BUDGET[Budget and usage review]

Machine-type policy

Large machine types cost more. If normal development does not require high CPU/memory, restrict them.

A good policy is:

Default repositories -> 2 or 4 core
Build-heavy repositories -> approved larger types
Exceptional workloads -> repository-specific policy

Organization-wide policies are broad constraints; repository-specific policies can make them more restrictive, not use them to escape an organization maximum.

Idle timeout and retention

Idle timeout controls how long an inactive codespace keeps running. Retention controls how long stopped codespaces remain before deletion.

For cost-conscious teams:

• Use modest idle timeouts.
• Avoid very long retention unless developer workflow needs it.
• Educate users that stopped codespaces can still consume storage.

Codespaces secrets

Codespaces organization secrets should follow the same least-privilege model as Actions secrets. Scope them only to repositories that need them.

29. GitHub Sandboxes for Copilot

GitHub’s cloud and local sandboxes for Copilot are public preview as of September 2026 and should be treated as preview functionality that can change.

Organization owners can control cloud sandbox access from organization settings. Current documentation describes cloud sandbox access as disabled by default unless enabled by organization or enterprise policy.

What a sandbox does

A sandbox constrains commands or tool execution invoked by Copilot, reducing direct exposure of the host environment or providing isolated cloud compute.

Governance considerations

• Is cloud sandbox use allowed for the organization?
• What data may be processed in the sandbox?
• What network destinations are reachable?
• What filesystem access exists?
• What billing applies?
• What enterprise policy overrides organization choices?

Because this capability is preview, do not build irreversible compliance assumptions around the current UI or behavior without re-verification.

30. GitHub Copilot Organization Administration

Organization owners can manage Copilot plans, access, policy, models, agent features, runners, and usage depending on subscription and enterprise policy.

Administrative model

flowchart TD
    PLAN[Copilot plan] --> SEAT[Seat assignment]
    SEAT --> POLICY[Feature policies]
    POLICY --> MODEL[Model availability]
    POLICY --> AGENT[Cloud and custom agents]
    POLICY --> MCP[MCP policy]
    AGENT --> RUNNER[Runner policy]
    MODEL --> USAGE[Usage and AI cost]
    MCP --> USAGE

Seat management

Use team-based assignment where practical. Review inactive seats and remove licenses when employees leave or no longer need the product.

Feature policy

Current organization-level controls can cover features such as:

• Copilot Chat
• Copilot coding agent / cloud agent capabilities
• Copilot CLI
• Model availability
• Third-party agent features where offered
• MCP server capabilities
• Preview features

Availability depends on plan and GitHub product evolution.

Model governance

Organizations can control which supported models are available. Some organizations may also integrate custom models with their own LLM API keys where the feature is supported.

Governance questions:

• Which models are approved?
• Are externally hosted models allowed?
• Who owns API keys?
• What data-handling requirements apply?
• How is AI usage monitored?

Copilot agents

For cloud-agent or coding-agent workflows, review:

• Repository access
• Runner configuration
• Actions policy interaction
• Secret availability
• Network access
• Pull request permissions
• Auditability

MCP administration

Model Context Protocol integrations can extend agent access to tools or systems. Treat MCP servers like privileged integrations:

1. Approve the server/operator.
2. Review authentication.
3. Limit data and action scope.
4. Avoid broad production access by default.
5. Monitor usage and revoke unused connections.

Copilot metrics

Use organization reports to understand:

• Seat utilization
• Adoption
• Activity
• Code-generation or productivity indicators exposed by GitHub
• AI credit consumption where applicable

Metrics should support operational decisions, not be used as simplistic employee performance scores.

31. GitHub Packages Administration

GitHub Packages can host software packages and container images in organization namespaces.

Current permission models

GitHub Packages has two important permission models.

Granular user/organization-scoped permissions are supported by registries including:

• Container registry
• npm
• NuGet
• RubyGems

Repository-scoped permissions apply to registries including:

• Apache Maven
• Gradle

Repository-scoped packages inherit repository access. Granular packages can have visibility and permissions managed separately from a linked repository.

Package roles

Typical package access levels are:

Role	Capability
Read	Download and read metadata
Write	Publish plus read
Admin	Manage access, delete/restore where supported, publish/read

GitHub Actions package access

For granular packages, explicitly grant Actions access to the repositories whose workflows need the package.

Prefer GITHUB_TOKEN in Actions when the package/repository relationship supports it rather than storing a PAT unnecessarily.

Authentication caveat

Current GitHub Packages documentation still documents personal access token (classic) as the general package-registry authentication mechanism for many CLI/client workflows outside Actions. Do not assume fine-grained PAT support is interchangeable across every registry/client path.

Package governance

• Decide whether new packages inherit linked-repository permissions.
• Review public package publication carefully.
• Remove obsolete package versions based on an explicit retention process.
• Track package consumers before deleting artifacts.
• Treat container package deletion as a potentially breaking production change.

32. GitHub Pages Organization Administration

Organizations can control GitHub Pages availability and publication behavior according to plan and enterprise policy.

Governance questions include:

• Are Pages sites allowed?
• Are public sites permitted?
• Are private Pages sites available and appropriate for the plan?
• Which branches or Actions workflows publish?
• Who controls custom domains?
• How are DNS ownership and HTTPS managed?

For public organizations, Pages can be an external publishing surface. Apply the same content and domain-ownership standards used for other public web properties.

33. Organization Discussions

Organization Discussions can provide cross-repository communication where enabled.

Administration includes:

• Categories
• Permissions
• Announcements
• Moderation
• Access expectations

Use organization Discussions for topics that span multiple repositories. Use repository Discussions when the conversation belongs to a specific project.

34. Organization Webhooks

Organization webhooks send event payloads to external systems when selected organization events occur.

Secure webhook design

1. Use HTTPS.
2. Configure a strong webhook secret.
3. Validate GitHub signatures.
4. Subscribe only to events you need.
5. Make consumers idempotent because deliveries can be retried.
6. Log delivery IDs and processing status.
7. Use redelivery for troubleshooting rather than manually recreating events.

Conceptual flow

sequenceDiagram
    participant G as GitHub
    participant W as Webhook endpoint
    participant Q as Queue
    participant S as Service
    G->>W: Event delivery plus signature
    W->>W: Verify signature
    W->>Q: Enqueue accepted event
    Q->>S: Process event
    S-->>Q: Complete

Common organization webhook uses

• Membership-change automation
• Repository provisioning workflows
• Security monitoring
• CMDB synchronization
• Audit augmentation
• Internal developer portal updates

35. Scheduled Reminders and Integrations

GitHub scheduled reminders can send Slack reminders for pull request review requests. They are useful for teams with high review volume.

Current documented constraints include per-reminder repository and result limits, so treat them as a lightweight review aid rather than a full workflow engine.

Use external integrations carefully:

• Review requested permissions.
• Prefer GitHub Apps over broadly scoped OAuth or personal tokens for new integrations when possible.
• Document an owner.
• Review app access periodically.
• Remove integrations no longer used.

36. Authentication Security

Authentication security determines how users prove who they are before permissions are evaluated.

Two-factor authentication

Organization owners can require 2FA for members, outside collaborators, and billing managers on supported plans. GitHub also supports requiring secure 2FA methods such as passkeys, security keys, authenticator apps, and GitHub Mobile rather than allowing weaker methods such as SMS.

Before enforcing a stricter requirement:

1. Review current 2FA compliance.
2. Notify affected users.
3. Prepare service and bot accounts.
4. Confirm all owners have compliant authentication.
5. Understand that noncompliant outside collaborators can be removed from the organization.
6. Review the audit log after enforcement.

Service accounts and bots

Human-oriented 2FA controls can be awkward for unattended accounts. Prefer GitHub Apps, deploy keys with narrow scope, OIDC, or automation-specific credentials over shared bot usernames whenever possible.

37. SAML Single Sign-On

SAML SSO is available to organizations using GitHub Enterprise Cloud in the supported identity model.

SAML adds an enterprise identity-provider authentication step for organization resources while users may still sign in to their GitHub personal account first.

SAML flow

sequenceDiagram
    participant U as User
    participant G as GitHub
    participant I as Identity provider
    U->>G: Access organization resource
    G->>I: Redirect for SAML authentication
    I-->>G: SAML assertion
    G-->>U: Authorized organization session

SAML rollout procedure

1. Inventory members and owners.
2. Connect the identity provider.
3. Test SAML before enforcement.
4. Ensure members link their identities.
5. Download recovery codes.
6. Prepare an IdP-outage process.
7. Enforce SAML only after the pilot is verified.
8. Review unauthorized or unlinked users.

Outside collaborators can have different SSO behavior from members, so verify the current model before assuming every external collaborator is covered by the same SAML policy.

38. SCIM Provisioning

SCIM automates identity lifecycle between an identity provider and GitHub.

For organization-level SCIM with personal GitHub accounts, the common model is:

IdP assignment -> provision organization membership
IdP profile change -> update mapped identity data
IdP deactivation -> deprovision organization membership

Why SCIM matters

Manual invitation is acceptable for a ten-person team. It becomes a security risk at hundreds or thousands of users because offboarding can be missed.

SCIM and Enterprise Managed Users

Do not confuse organization SCIM for personal-account enterprises with SCIM used for Enterprise Managed Users. They are different provisioning architectures with different endpoints and identity ownership.

Team synchronization

Supported IdPs can synchronize identity-provider groups to GitHub teams in eligible enterprise configurations. This can make team membership an identity-system responsibility instead of a manual GitHub task.

39. IP Allow Lists

GitHub Enterprise Cloud supports IP allow lists for restricting access to private organization resources from approved IP addresses or CIDR ranges.

What an allow list affects

Depending on authentication path and product, allow lists can affect:

• Web access
• Git access
• API access
• GitHub App access
• Automation that reaches protected resources

Safe rollout

1. Add your current administrative network first.
2. Add corporate egress, VPN, CI/CD, and integration IP ranges.
3. Test whether each required IP would be allowed.
4. Review GitHub App IP handling.
5. Enable enforcement.
6. Test web, Git, API, and automation paths.
7. Maintain a documented emergency-access process.

Never begin by enabling the list and then trying to discover which addresses were forgotten.

GitHub App IP inheritance

Organizations can optionally allow installed GitHub Apps’ configured IP ranges to participate in the organization allow list. Review this carefully because an app vendor changing its published addresses may affect effective access.

40. Notification and Domain Security

Verified domains help prove organization identity and can support stronger notification controls.

Domain verification

A typical verification procedure is:

1. Add the domain in organization settings.
2. GitHub provides a DNS TXT record.
3. Publish the TXT record in authoritative DNS.
4. Wait for propagation.
5. Complete verification.
6. Confirm profile website and email information align with verified domains if you expect the Verified badge.

Approved domains

GitHub also supports domain approval scenarios where an organization needs to recognize a domain it does not own. This has preview/status caveats in current documentation and should be re-verified before relying on it for policy.

Notification restrictions

For organizations that need stronger data-loss prevention, restrict notification destinations to approved or verified email domains where supported. Pull request and issue notifications can contain sensitive metadata even when source code itself is not attached.

41. GitHub Advanced Security, Code Security, and Secret Protection

GitHub’s security portfolio has evolved from a single “GitHub Advanced Security” label toward separately packaged capabilities such as GitHub Code Security and GitHub Secret Protection, while Advanced Security terminology and SKUs still appear in parts of the product and billing model.

Administrators should focus on capabilities rather than assuming every feature belongs to one fixed SKU forever.

Security configuration model

Security configurations are collections of repository-level security enablement settings that can be applied at scale.

flowchart TD
    BASE[Security baseline] --> CFG[Security configuration]
    CFG --> TARGET[Repository targeting]
    TARGET --> DEP[Dependency security]
    TARGET --> CODE[Code scanning]
    TARGET --> SECRET[Secret scanning]
    TARGET --> OTHER[Related security settings]
    DEP --> COVER[Coverage and alerts]
    CODE --> COVER
    SECRET --> COVER

Rollout approach

1. Inventory repository languages and risk tiers.
2. Pilot on representative repositories.
3. Tune scanning and developer workflow.
4. Apply a default security configuration.
5. Use custom properties for risk-based targeting where helpful.
6. Enforce only after false-positive and build-impact review.
7. Monitor coverage continuously.

42. Dependency Security

Dependency security includes capabilities such as:

• Dependency graph
• Dependabot alerts
• Dependabot security updates
• Dependabot version updates
• Dependency review
• Private registry access configuration

Good operating model

Dependency discovered
      ↓
Vulnerability advisory matches
      ↓
Alert created
      ↓
Owner triages
      ↓
Upgrade / mitigation
      ↓
PR or patch verified
      ↓
Alert resolved

Do not enable alerts without establishing alert ownership. An inbox of thousands of untriaged findings is not a security program.

43. Code Scanning

Code scanning analyzes source code for vulnerability patterns. GitHub CodeQL can be configured with default or advanced setup depending on language and customization needs.

Default setup vs advanced setup

Model	Best fit
Default setup	Fast standardized enablement across supported repositories
Advanced setup	Custom build steps, query suites, languages, schedules, or workflow control

Organization considerations

• Decide which repositories require scanning.
• Standardize default setup where possible.
• Use advanced workflows only when needed.
• Track repositories where scanning is inactive.
• Route alerts to responsible teams.
• Review Copilot Autofix or other AI-assisted remediation according to your secure-development process.

Verification note — “AI Scan”: The supplied syllabus included a topic named AI Scan. During the September 2026 verification pass, no generally available organization-administration control with that exact official product name was established in the GitHub documentation reviewed for this guide. Rather than inventing a feature, this tutorial covers the verified code-scanning, CodeQL, Copilot Autofix, and Code Quality capabilities and treats “AI Scan” as an unverified/possibly preview-or-renamed syllabus term. Re-check GitHub’s current Code Security documentation if that label appears in your UI.

44. Secret Scanning and Push Protection

Secret scanning detects credentials or secret-like values in Git history and other supported content.

Push protection can block a secret before it reaches the repository.

Governance controls

• Provider patterns
• Non-provider patterns where available
• Custom secret patterns
• Push protection
• Bypass permissions
• Bypass review
• Resource links or internal remediation guidance

Incident flow

flowchart LR
    DETECT[Secret detected] --> VALIDATE[Validate exposure]
    VALIDATE --> REVOKE[Revoke credential]
    REVOKE --> ROTATE[Rotate replacement]
    ROTATE --> CLEAN[Remove from code if needed]
    CLEAN --> REVIEW[Root-cause review]

Deleting the secret from the latest commit is not enough. If a credential was exposed, revoke it first. Git history rewriting is secondary to invalidating the credential.

45. Security Managers

A security manager team provides broad security administration without giving all members organization ownership.

Use it for a dedicated security or AppSec team that needs to:

• Review organization security status
• Manage security alerts
• Coordinate scanning rollout
• Investigate vulnerabilities

Avoid assigning security-manager capability to large generic engineering groups.

46. GitHub Code Quality

GitHub Code Quality is an organization-governed product for code-quality findings and trends.

Current organization controls include repository access selection, dynamic filtering, and enforcement so repository administrators cannot opt out where policy requires coverage.

Rollout pattern

1. Select a small pilot repository set.
2. Review finding quality and developer workflow.
3. Tune thresholds or policies where the product allows.
4. Expand by repository filter or ownership property.
5. Review health and trend dashboards.
6. Monitor cost before organization-wide enablement.

Metrics caution

Reliability, maintainability, standard findings, and AI-assisted findings can help identify hotspots. Do not collapse nuanced code-quality signals into a single “developer score.” Use them to guide engineering remediation.

47. Deploy Keys

Deploy keys are SSH keys attached to individual repositories. They can be read-only or write-enabled.

Security risk

A deploy key’s private half grants repository access independent of a user’s future organization membership. Removing a person from the organization does not automatically make a copied deploy-key private key disappear.

Recommended practice

• Prefer read-only keys unless write is mandatory.
• Give each automation system a separate key.
• Store private keys in a managed secret system.
• Rotate keys.
• Inventory and remove stale keys.
• Prefer GitHub Apps for scalable multi-repository automation.

48. Compliance Administration

GitHub provides compliance and security reports that eligible organization administrators can access, including reports such as SOC materials and Cloud Security Alliance documentation.

Compliance administration is broader than downloading a report. A practical evidence set may include:

• Organization owner list
• SSO/SCIM configuration
• 2FA policy
• Rulesets
• Security configuration coverage
• Audit log exports
• Access reviews
• App/PAT/deploy-key reviews
• Billing/licensing evidence
• Repository classification data

Keep evidence collection reproducible. Manual screenshots alone are difficult to scale and easy to miss.

49. Third-Party Access: GitHub Apps

GitHub Apps are generally the preferred integration model for new automation because they can use granular permissions, short-lived installation tokens, repository selection, webhooks, and app identities.

Review checklist for an installed app

• Who owns the vendor or internal app?
• Which organization permissions are requested?
• Which repository permissions are requested?
• All repositories or selected repositories?
• Which webhook events are subscribed?
• Does the app have destructive permissions?
• Does it need access to private data?
• Is there a business owner?
• When was access last reviewed?

Suspend vs uninstall

Suspension is useful for investigation or temporary disablement. Uninstall removes the installation and should be used when the integration is no longer required.

50. OAuth App Policy

OAuth App access restrictions let an organization control whether OAuth Apps authorized by users can access organization resources.

Current GitHub behavior includes organization approval workflows. New organizations enable OAuth App restrictions by default according to current documentation.

Why this matters

Without restrictions, a member can authorize an OAuth App for their personal account and potentially expose organization data the app can reach through that user’s access.

Governance pattern

1. Keep restrictions enabled.
2. Require owner review for new apps.
3. Review scopes and vendor trust.
4. Grant only when business need is clear.
5. Revoke stale apps.

51. Personal Access Token Policies

Organizations can govern personal access tokens (PATs), including classic PATs and fine-grained PATs.

Controls can include:

• Allow or restrict token access to organization resources
• Maximum token lifetime
• Approval requirements for fine-grained PATs
• Token review and revocation

Current GitHub documentation describes a default maximum lifetime policy for fine-grained PATs and separate behavior for classic PATs. Do not assume the two token types have identical lifecycle controls.

Recommended token hierarchy

Prefer, in order:

1. GitHub App installation token for service automation
2. GITHUB_TOKEN inside Actions where sufficient
3. OIDC for external cloud credentials
4. Fine-grained PAT for human or narrowly scoped automation use
5. Classic PAT only when a product or registry still requires it

Token anti-patterns

Avoid:

• Shared PATs
• No-expiry classic PATs
• Tokens in source code
• Tokens with repo and admin:org when only read access is needed
• A single personal token powering critical organization infrastructure

52. Organization Audit Log

The organization audit log records administrative and member activity and is one of the most important tools for incident response and governance.

Current GitHub documentation states that the organization audit log includes organization-affecting events within a defined retention window and provides search/export/API access depending on plan.

Audit event anatomy

Typical fields include:

• Actor
• Action
• Resource or repository
• Organization
• Affected user
• Timestamp
• Country and, where enabled/eligible, source IP context

Event names often use a category plus operation, such as:

repo.create
team.add_member
org.update_member

Useful audit queries

Examples with GitHub CLI:

export ORG="acme"

gh api --paginate \
  "/orgs/$ORG/audit-log?phrase=action:repo.create" \
  --jq '.[] | [.created_at, .actor, .action, .repo] | @tsv'

Review organization-role changes:

gh api --paginate \
  "/orgs/$ORG/audit-log?phrase=action:org.update_member" \
  --jq '.[]'

The exact action name you need depends on the event category; consult GitHub’s audit-event reference for production investigations.

Source IP disclosure

Eligible organizations can enable source-IP disclosure for supported audit events. This can materially improve investigations, but it also has privacy and governance implications. Align it with your organization’s privacy policy.

53. Audit Log Export, API, and Streaming

Organization audit logs can be searched and exported. Enterprise accounts can also support audit log streaming to external systems.

SIEM architecture

flowchart LR
    GH[GitHub audit events] --> COL[Collector or stream]
    COL --> SIEM[SIEM]
    SIEM --> DETECT[Detection rules]
    DETECT --> IR[Incident response]
    SIEM --> COMP[Compliance evidence]

Use streaming when you need near-real-time detection, long-term retention, correlation with identity/cloud/network logs, or regulatory evidence.

For lighter-weight event automation, webhooks can be more efficient than repeatedly polling the audit API.

54. Deleted Repositories and Recovery

Deleted repositories may be restorable under GitHub’s eligibility and retention rules. The restoration window and what is restored can vary, so deletion should never be treated as a backup strategy.

Recovery procedure

1. Confirm repository name and deletion time.
2. Check organization deleted-repository settings.
3. Restore if eligible.
4. Revalidate team permissions, webhooks, Pages, Actions, environments, packages, and external integrations.
5. Review audit events to determine why deletion occurred.

For critical repositories, maintain independent backups or mirrors according to business-continuity requirements.

55. Organization Insights and Monitoring

Organization-level insights can include:

• Repository activity
• Dependency insights
• Security overview
• Actions metrics
• Code Quality insights
• Copilot usage
• Billing and product usage

The useful question is not “what dashboards exist?” but “what operating decisions should a dashboard trigger?”

Example:

Signal	Operational decision
Increasing Actions queue time	Add capacity or adjust runner routing
Unowned critical secret-scanning alerts	Fix ownership model
Many stale outside collaborators	Run access review
High package storage growth	Introduce package retention
Low Copilot seat utilization	Reclaim or reassign seats
Security coverage gaps	Expand security configuration

56. Organization Lifecycle

Organization lifecycle controls are high impact and should be limited to owners.

Renaming an organization

Renaming changes the organization account name and therefore affects URLs and integrations.

GitHub automatically redirects many repository URLs, but not every reference is updated automatically.

After a rename, review:

• Git remotes
• API scripts
• Webhooks
• CI/CD integrations
• package references
• Pages/custom domains
• team mentions
• documentation links
• allowlists and external vendor configuration

Archiving an organization

GitHub supports archiving an organization. An archived organization becomes read-only and repositories display archived/read-only state. Individual repositories cannot simply be reactivated independently while the organization remains archived.

An owner can later unarchive the organization. Unarchiving the organization re-enables normal organization operations and allows individual repositories to be unarchived, but it does not automatically unarchive every repository.

Use archive when you need long-term preservation without active changes.

Deleting an organization

Deletion is irreversible and removes organization content including repositories and related resources. GitHub documentation also notes namespace reuse timing and package/container consequences.

A safe process is:

1. Export or back up critical data.
2. Transfer repositories that must survive.
3. Remove or transfer domains and integrations.
4. Record formal approval.
5. Rename first if immediate namespace reuse is required.
6. Delete only when the business owner confirms destruction.

Converting an organization into a user

GitHub does not directly convert an organization into a personal account. The documented workaround is to create a personal account, transfer repositories, rename the organization to free the name, rename the user if appropriate, then delete the organization.

This distinction matters because “conversion” is not a reversible account-type toggle.

57. Organization-Owned GitHub Apps and Developer Settings

GitHub Apps are the preferred integration model when an automation or service needs narrowly scoped, auditable access to GitHub resources. An application can be owned by a personal account, an organization, or—where supported—an enterprise.

For an organization-owned app, the registration is managed from:

Organization Settings → Developer settings → GitHub Apps

A GitHub App registration normally contains:

Area	Purpose
App name and homepage	Human identity and documentation
Callback URL	OAuth-style user authorization flow when required
Setup URL	Optional post-installation workflow
Webhook URL	Endpoint that receives subscribed GitHub events
Webhook secret	Verifies that webhook requests came from GitHub
Repository permissions	Access to repository resources such as contents, issues, or pull requests
Organization permissions	Access to organization-level resources
Account permissions	Access related to the authorizing user when requested
Event subscriptions	Events that cause webhook deliveries
Installation scope	All or selected repositories, depending on app and installation configuration

App credentials and authentication flow

A GitHub App can use several credential types for different purposes:

flowchart LR
    A[GitHub App private key] --> B[Sign JWT]
    B --> C[Authenticate as App]
    C --> D[Request installation access token]
    D --> E[Call API for installed resources]

    U[User authorization] --> V[User access token]
    V --> W[Call API on behalf of user]

Key points:

• The Client ID identifies the app in applicable authorization flows.
• A client secret is sensitive and must be stored securely.
• An app private key signs JSON Web Tokens (JWTs).
• The JWT authenticates the app itself and is commonly used to request an installation access token.
• Installation access tokens should be preferred over long-lived personal credentials for service automation.
• Private keys do not automatically expire; explicitly rotate and revoke them.

GitHub App managers

Organization owners can delegate management of some or all organization-owned GitHub App registrations to users or teams using the App Manager capability.

This is useful when a platform or integrations team owns application registration while organization owners retain broader account authority.

An App Manager can manage app registration settings within their delegated scope, but this does not automatically grant every unrelated administration capability such as installing or uninstalling apps across the organization.

Recommended GitHub App lifecycle

1. Define the business purpose and owner.
2. Request only the repository and organization permissions actually needed.
3. Subscribe only to required webhook events.
4. Install on selected repositories unless all-repository access is genuinely required.
5. Store private keys in a secrets manager.
6. Use installation access tokens at runtime.
7. Rotate private keys without downtime by overlapping old and new keys.
8. Review installations and permissions periodically.
9. Suspend or remove unused apps.
10. Record ownership and recovery procedures.

Common mistakes

Mistake	Risk	Better approach
Using an owner’s PAT for a service	Excessive privilege and poor ownership	Use a GitHub App
Giving an app all repositories by default	Unnecessary blast radius	Use selected repositories
Requesting broad permissions “just in case”	Violates least privilege	Start narrow and expand deliberately
No webhook secret	Request spoofing risk	Configure and validate a secret
One private key forever	Weak credential hygiene	Rotate keys periodically
No named owner	Orphaned integration	Maintain an integration inventory

58. Organization Administration with REST API, GraphQL, and GitHub CLI

Large organizations should treat the UI as one administration interface—not the only one. GitHub exposes extensive organization administration through REST, GraphQL, and the GitHub CLI.

REST API versioning

GitHub’s REST API is versioned. As of September 2026, 2026-03-10 is a supported API version. For scripts that call the REST API directly, explicitly send the version header rather than relying on the default.

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  https://api.github.com/orgs/acme

The API version is especially important for long-lived automation because GitHub introduces breaking changes through dated API versions.

GitHub CLI as an administration client

The gh api command is useful because it exposes REST and GraphQL without requiring a separate SDK.

export ORG="acme"

gh api "/orgs/$ORG"
gh api "/orgs/$ORG/members"
gh api "/orgs/$ORG/teams"
gh api "/orgs/$ORG/organization-roles"
gh api "/orgs/$ORG/properties/schema"
gh api "/orgs/$ORG/actions/permissions"
gh api "/orgs/$ORG/issue-fields"

For repeatable scripts, make the organization name a variable and fail on errors rather than embedding assumptions throughout the script.

Example: inspect organization custom properties

gh api "/orgs/$ORG/properties/schema" \
  --header "X-GitHub-Api-Version: 2026-03-10"

Example: update repository property values in bulk

The exact request body should be generated from your property schema and repositories. A typical REST call shape is:

gh api \
  --method PATCH \
  "/orgs/$ORG/properties/values" \
  --header "X-GitHub-Api-Version: 2026-03-10" \
  --input property-values.json

Example payload:

{
  "repository_names": ["payments-api", "payments-worker"],
  "properties": [
    {
      "property_name": "service_tier",
      "value": "tier-1"
    },
    {
      "property_name": "business_unit",
      "value": "payments"
    }
  ]
}

Before bulk-changing properties, retrieve the organization schema and validate that property names and allowed values exist.

Example: inspect Actions policy

gh api "/orgs/$ORG/actions/permissions" \
  --header "X-GitHub-Api-Version: 2026-03-10"

Use this as part of a compliance check to detect policy drift.

GraphQL administration

GraphQL is useful when you need nested relationships or must query connected objects efficiently. Typical organization automation uses include:

• organization and repository inventory
• repository and team relationships
• ProjectV2 data
• custom querying for governance reports
• batched retrieval of metadata that would require many REST calls

A basic organization query:

gh api graphql -f query='query($login:String!) {
  organization(login:$login) {
    login
    name
    repositories(first:20) {
      nodes {
        name
        visibility
        isArchived
      }
    }
  }
}' -F login="$ORG"

REST vs GraphQL vs CLI

Interface	Best use
GitHub UI	Interactive administration and one-off changes
REST API	Stable resource-oriented automation
GraphQL	Connected/nested data and efficient custom queries
gh CLI	Operator scripts, shell automation, diagnostics
GitHub App	Long-running service-to-service automation

Safe automation pattern

flowchart LR
    A[Source of truth] --> B[Validation]
    B --> C[GitHub API or Terraform plan]
    C --> D[Approval]
    D --> E[Apply change]
    E --> F[Audit log]
    F --> G[Drift / compliance check]

Do not write destructive organization automation without a dry-run, explicit scope, logging, and recovery plan.

59. Terraform and Infrastructure as Code for GitHub Organizations

GitHub organization administration can be managed through the integrations/github Terraform provider. The latest provider listed in the Terraform Registry at the time of verification is 6.13.0, published in July 2026.

Infrastructure as Code is valuable for stable, repeatable governance such as:

• organization settings
• repositories
• teams
• team-to-repository permissions
• Actions policies
• organization rulesets
• Actions variables and secrets
• repository environments and rules
• selected GitHub integrations supported by the provider

Provider configuration

terraform {
  required_version = ">= 1.6.0"

  required_providers {
    github = {
      source  = "integrations/github"
      version = "~> 6.13"
    }
  }
}

provider "github" {
  owner = var.github_organization
}

Prefer environment-based or workload-identity-based credential injection supported by your execution platform rather than embedding a token in Terraform code.

Example: organization baseline

variable "github_organization" {
  type = string
}

resource "github_organization_settings" "baseline" {
  name                          = "Acme Engineering"
  description                   = "Acme engineering organization"
  default_repository_permission = "read"

  members_can_create_repositories         = true
  members_can_create_public_repositories  = false
  members_can_create_private_repositories = true
}

Choose settings deliberately. For example, some enterprises disable member-created repositories and require a repository-provisioning workflow instead.

Example: team and repository access

resource "github_team" "payments" {
  name        = "payments"
  description = "Payments engineering team"
  privacy     = "closed"
}

resource "github_repository" "payments_api" {
  name       = "payments-api"
  visibility = "private"

  has_issues      = true
  has_discussions = true
}

resource "github_team_repository" "payments_api" {
  team_id    = github_team.payments.id
  repository = github_repository.payments_api.name
  permission = "push"
}

The provider uses API permission names such as pull and push for some resources; conceptually these map to the GitHub repository roles Read and Write.

Example: organization Actions allowlist

resource "github_actions_organization_permissions" "baseline" {
  enabled_repositories = "all"
  allowed_actions      = "selected"

  allowed_actions_config {
    github_owned_allowed = true
    verified_allowed     = true

    patterns_allowed = [
      "actions/checkout@*",
      "actions/setup-node@*"
    ]
  }
}

For stronger supply-chain controls, combine an allowlist with full-length commit SHA pinning in organization policy and dependency/update processes.

Example: default workflow token permissions

resource "github_actions_organization_workflow_permissions" "baseline" {
  organization_slug = var.github_organization

  default_workflow_permissions     = "read"
  can_approve_pull_request_reviews = false
}

Individual workflows can then request specific permissions when they require them.

Example: organization ruleset

resource "github_organization_ruleset" "main_branch" {
  name        = "main-branch-governance"
  target      = "branch"
  enforcement = "active"

  conditions {
    ref_name {
      include = ["~DEFAULT_BRANCH"]
      exclude = []
    }

    repository_name {
      include = ["~ALL"]
      exclude = []
      protected = false
    }
  }

  rules {
    deletion                = true
    non_fast_forward        = true
    required_linear_history = true

    pull_request {
      required_approving_review_count = 1
      dismiss_stale_reviews_on_push   = true
      require_code_owner_review       = true
    }
  }
}

Provider schemas evolve. Validate every resource against the provider version pinned in your project before applying the example.

Secret-handling warning

Avoid putting secret plaintext directly in normal .tf files or variables that will be stored unencrypted in state. Terraform state can contain sensitive values even when output is marked sensitive.

Safer options include:

• create secret metadata/access policy through Terraform while injecting values through a dedicated secrets workflow
• protect remote state with strong access control and encryption
• rotate credentials after accidental state exposure
• separate organization governance state from application runtime secrets when practical

Import existing configuration before managing it

For an existing organization, do not blindly create duplicate resources. Inventory first and import supported resources into state.

terraform import github_team.payments 1234567
terraform import github_team_repository.payments_api 1234567:payments-api

Then run terraform plan and reconcile differences before applying.

60. Automated Repository Provisioning and Standardization

At scale, repository creation should become a governed service instead of an ad hoc owner-only activity.

A useful provisioning workflow is:

flowchart TD
    A[Developer requests repository] --> B[Validate name and owner]
    B --> C[Create repository]
    C --> D[Assign custom properties]
    D --> E[Attach team permissions]
    E --> F[Rulesets automatically target repository]
    F --> G[Apply security configuration]
    G --> H[Configure Actions / environments / webhooks]
    H --> I[Return repository to team]

Recommended repository metadata

Common custom properties include:

Property	Example values	Why it helps
owner_team	payments, identity	Access review and accountability
service_tier	tier-1, tier-2, tier-3	Reliability/security targeting
data_classification	public, internal, confidential	Compliance targeting
environment	shared, prod, nonprod	Policy selection
lifecycle	active, maintenance, deprecated	Archive strategy
cost_center	CC-1234	Cost allocation

Repository template contents

A production repository template can include:

• README.md
• CODEOWNERS
• CONTRIBUTING.md
• SECURITY.md
• issue forms/templates
• pull request template
• standard CI workflow or reusable-workflow caller
• dependency configuration
• language/runtime baseline
• repository-specific documentation skeleton

Do not hard-code secrets, environment IDs, production endpoints, or team-specific assumptions into a template that will be widely cloned.

Standardization hierarchy

Prefer the following order:

1. Organization policy for mandatory controls.
2. Rulesets/security configurations for enforceable repository governance.
3. Custom properties for dynamic classification.
4. Repository templates for starter content.
5. Reusable workflows for shared CI/CD logic.
6. Automation to provision and validate the complete baseline.

Templates alone are not governance because repositories can drift after creation.

61. Identity and Access Governance

The strongest GitHub organization design minimizes direct individual grants and makes identity lifecycle predictable.

Least-privilege model

flowchart LR
    U[User] --> T[Team]
    T --> R[Repository role]
    U --> O[Delegated org role only when needed]
    A[Automation] --> G[GitHub App]
    G --> R2[Selected repositories / permissions]

Use:

• teams for normal engineering access
• repository roles for job-function access
• custom roles only when standard roles are insufficient
• Security Manager for security administration
• Billing Manager for billing tasks
• CI/CD administration role for Actions administration where available
• App Manager for owned GitHub Apps
• Moderator for moderation
• owners for the small number of people who require full organization authority

Access-review checklist

Review at a defined cadence:

• organization owners
• members
• outside collaborators
• team maintainers
• team membership
• direct repository collaborators
• custom organization roles
• custom repository roles
• GitHub App installations
• OAuth app access
• PAT approvals
• deploy keys
• organization secrets
• runner access

Joiner-Mover-Leaver lifecycle

Joiner

1. Provision the GitHub identity according to the organization’s identity model.
2. Require 2FA or SSO as applicable.
3. Add the user to the minimum required teams.
4. Grant product licenses only when needed.
5. Verify access with a test repository or onboarding checklist.

Mover

1. Remove old team assignments.
2. Add new role/team assignments.
3. Re-evaluate direct repository grants.
4. Re-evaluate Copilot and paid-product seats.
5. Review ownership of open work and integrations.

Leaver

1. Remove or deprovision account access promptly.
2. Revoke PATs, SSH credentials, and app/user authorizations as applicable.
3. Remove team and repository access.
4. Transfer ownership of GitHub Apps or automation responsibilities.
5. Review authored secrets/deploy keys/service credentials.
6. Reassign outstanding reviews/issues when necessary.
7. Verify the event in the audit log.

When using enterprise identity integrations, automate lifecycle through the identity provider and SCIM where supported rather than maintaining parallel manual lists.

62. Security Governance at Scale

Security controls should be rolled out as a program, not enabled randomly repository by repository.

Security rollout strategy

1. Define a security baseline.
2. Classify repositories using custom properties.
3. Select representative pilot repositories.
4. Apply a security configuration.
5. Measure alert volume and developer impact.
6. Fix false assumptions and unsupported workflows.
7. Expand by service tier or business unit.
8. Enforce the configuration when confidence is high.
9. Track repositories that are not covered.
10. Review exemptions periodically.

Security baseline example

Control	Typical production baseline
2FA/SSO	Required according to identity model
Dependency graph	Enabled
Dependabot alerts	Enabled
Dependency review	Required on important repositories where applicable
Code scanning	Enabled for supported codebases
Secret scanning	Enabled
Push protection	Enabled
Ruleset	PR review + required checks + restricted force push
Actions permissions	Minimal token + controlled third-party actions
Audit	Central review / export / SIEM as required
Ownership	Required owner_team or equivalent

Supply-chain governance

Protect the software supply chain through multiple layers:

• review third-party Actions before allowlisting
• pin immutable versions where practical, especially high-risk actions
• minimize GITHUB_TOKEN permissions
• prefer OIDC to long-lived cloud credentials
• review dependency changes
• enable artifact attestations where they fit your release model
• secure package publication and deletion rights
• isolate self-hosted runners used for untrusted code

One control does not replace the others.

63. GitHub Actions Governance at Scale

A mature Actions operating model separates policy, workflow design, and runner operations.

Recommended model

Layer	Responsible team	Examples
Organization policy	Platform/security	Allowed actions, SHA pinning, default token permissions
Reusable workflows	Platform/DevEx	Build, test, release, security templates
Repository workflows	Application teams	Service-specific jobs
Runner fleet	Platform/CI team	Images, autoscaling, networking, patching
Cloud access	Platform/security	OIDC trust and role boundaries
Cost/metrics	Platform/FinOps	Queue time, usage, storage, larger-runner cost

Runner fleet principles

• Prefer ephemeral runners for high-assurance self-hosted execution where practical.
• Patch runner images and operating systems regularly.
• Use runner groups as trust and access boundaries.
• Do not expose sensitive self-hosted runners to untrusted public-repository pull requests.
• Separate production deployment runners from general CI when the trust boundary warrants it.
• Monitor queue duration, job duration, failure rate, and utilization.
• Test runner-image changes before fleet-wide rollout.

Workflow security checklist

• [ ] Default GITHUB_TOKEN is read-only or minimally scoped.
• [ ] Jobs request only required permissions.
• [ ] Third-party Actions follow organization policy.
• [ ] Pull requests from forks cannot exfiltrate privileged secrets.
• [ ] Production environments require appropriate protection.
• [ ] Cloud authentication uses OIDC when practical.
• [ ] Reusable workflows are versioned and reviewed.
• [ ] Self-hosted runner labels/groups do not accidentally expose sensitive capacity.

64. Network Governance

GitHub organization networking depends on the product being used. There is no single “organization VPC” that automatically encloses GitHub SaaS resources.

Controls can include:

• organization or enterprise IP allow lists where supported
• private networking for supported hosted compute scenarios
• self-hosted runners in controlled networks
• larger/hosted runner static IP or private networking features where available
• firewall and DNS policy
• proxy configuration for self-hosted infrastructure
• private access from CI to internal services

Connectivity model

flowchart LR
    DEV[Developer] --> GH[GitHub.com]
    GH --> HOSTED[GitHub-hosted compute]
    GH --> SELF[Self-hosted runner group]
    HOSTED --> CLOUD[Cloud/private resource when networking supports it]
    SELF --> PRIVATE[Internal services]
    GH --> PKG[Package registries]

Design questions

Before implementing a network restriction, answer:

1. Does it apply to web access, API access, Git operations, compute, or all of them?
2. Are GitHub Apps and integrations expected to access the organization?
3. How will hosted runners reach private services?
4. Do developers work from dynamic IPs or VPN egress ranges?
5. How will emergency access work if an allowlist is misconfigured?
6. What DNS and proxy dependencies exist for self-hosted runners?

Always add and test a known-good administrative path before enabling a restrictive IP allow list.

65. Copilot and AI Governance at Scale

Copilot administration is no longer only a seat-assignment problem. Organization administrators may need to govern models, agents, features, custom models, MCP access, activity, budgets, and compute used by coding agents.

AI governance model

Area	Governance question
Access	Who receives Copilot seats?
Features	Which Copilot capabilities are allowed?
Models	Which models may users select?
Coding agent	Which repositories and runners can agents use?
Custom agents	Who defines and maintains them?
MCP	Which MCP servers are trusted?
Custom models / API keys	Who owns provider credentials and usage?
Data	What repositories/data classifications are appropriate?
Cost	How are seat and usage budgets monitored?
Audit	Which activity and adoption reports are reviewed?

Practical governance principles

• Start with selected teams or repositories when introducing a new AI capability.
• Separate experimentation from production-sensitive repositories.
• Treat MCP servers as integrations with their own permission and data-access risks.
• Treat coding-agent runners as compute infrastructure, not merely a UI setting.
• Do not grant a model or agent broader repository access than the task requires.
• Review adoption and value before automatically renewing every seat.

66. Audit and Compliance at Scale

Audit logs are most useful when they feed an operating process.

Audit architecture

flowchart LR
    GH[GitHub audit events] --> API[Audit API / export]
    GH --> STREAM[Audit log streaming where supported]
    API --> STORE[Central archive]
    STREAM --> SIEM[SIEM]
    SIEM --> ALERT[Detection rules]
    ALERT --> IR[Incident response]

Events worth monitoring

• owner and role changes
• member and outside-collaborator changes
• SSO/identity policy changes
• PAT and app policy changes
• GitHub App installation changes
• repository visibility/deletion/transfer
• ruleset and branch-protection changes
• Actions policy and runner changes
• secret/configuration changes
• IP allow-list changes
• security-feature changes

Compliance evidence package

A useful evidence package can contain:

• owner and privileged-role inventory
• membership/access review export
• SSO/2FA policy evidence
• ruleset configuration
• security-configuration coverage
• approved GitHub App inventory
• Actions policy
• audit events for the review window
• exception register
• remediation status

Do not use a screenshot as the only evidence when machine-readable exports or APIs can produce a more complete record.

67. Organization Migration Governance and Continuity

Migration is not simply copying Git repositories. A GitHub organization includes identity, teams, permissions, settings, Actions, security configuration, apps, projects, packages, webhooks, and other relationships.

Migration workstreams

Workstream	Validate
Identity	Member mapping, outside collaborators, SSO/SCIM
Teams	Team hierarchy, maintainers, membership
Repositories	Code, refs, visibility, archives, LFS
Permissions	Team/repository/custom roles
CI/CD	Actions, secrets, environments, runners, OIDC
Security	Rulesets, security configurations, alerts
Integrations	GitHub Apps, OAuth apps, webhooks, deploy keys
Packages	Registry names, permissions, consumers
Projects/issues	Issues, Projects, fields, automation
Domains/Pages	DNS, custom domains, Pages publishing
Audit	Before/after inventory and sign-off

GitHub Enterprise Importer caution

GitHub Enterprise Importer supports defined source/destination scenarios and migrates different objects depending on the migration type. Do not assume everything moves automatically.

For example, organization migration from GitHub.com can migrate organization/team/repository structures and selected settings, but team membership and some integrations require separate handling. Webhooks may require re-enablement or validation. Repository migration workflows also have feature-specific limitations.

Always run a representative trial migration and maintain a gap matrix.

No-delta assumption

For migration paths that do not provide a delta migration, changes made on the source after the final migration starts can create drift. Establish a change freeze or documented reconciliation procedure.

Continuity controls

Maintain:

• at least two capable owners
• break-glass procedures
• exported IaC/configuration where possible
• independent source-code backups where business policy requires them
• inventory of package/release dependencies
• current billing contacts
• named owners for critical apps and runners
• tested recovery procedures for deleted repositories

68. Organization Operating Model

There are two common administration models.

Centralized administration

A central platform/security team owns most organization settings.

Advantages

• consistent governance
• strong policy control
• simple accountability

Risks

• platform team becomes a bottleneck
• application teams wait for routine changes

Federated administration

Central teams own guardrails while domain teams receive delegated roles within defined scope.

Advantages

• faster local decisions
• less central operational load
• clearer domain ownership

Risks

• inconsistent practice if guardrails are weak
• requires better audit and role design

Recommended hybrid

Use central ownership for high-impact policy and delegate bounded administration:

Responsibility	Typical owner
Organization owners	Small platform/admin group
Identity/SSO/SCIM	IAM team
Security configurations	Security team / Security Managers
Actions organization policy	Platform/CI administrators
Runner fleet	Platform/CI team
Billing/budgets	FinOps / Billing Managers
App registrations	Integration team / App Managers
Team membership	Team maintainers or IAM automation
Repository ownership	Service team
Ruleset baseline	Platform/security

Repository ownership model

Every active production repository should have an accountable team. Express ownership in multiple complementary ways:

• CODEOWNERS for review routing
• team repository permission
• custom property such as owner_team
• service catalog or inventory
• incident/on-call ownership where applicable

CODEOWNERS alone is not a complete ownership database.

69. Administrative Monitoring and Reporting

A healthy organization is continuously measured rather than reviewed only after incidents.

Suggested operational scorecard

Domain	Metric/example
Access	Owners, stale members, outside collaborators
Repositories	Active vs archived, repositories without owner metadata
Governance	Ruleset/security-configuration coverage
Security	Open critical alerts, push-protection bypasses
CI/CD	Queue time, job failure, runner utilization
Packages	Storage growth, stale package versions
Billing	Spend vs budget, large usage changes
Copilot	Assigned vs active seats, usage trends
Integrations	Apps with broad access, stale apps
Audit	High-risk admin events, unresolved exceptions

Reporting cadence example

• Daily: critical security and service-impacting alerts
• Weekly: runner health, Actions failures, urgent access exceptions
• Monthly: billing, seat utilization, stale repositories, apps, PATs
• Quarterly: privileged access review, outside collaborators, ruleset/security coverage, disaster-recovery procedures

The cadence should reflect your risk and organizational size rather than being copied blindly.

70. Organization Administration Best Practices

Recommended

• Keep at least two organization owners, but keep the owner population small.
• Use teams for repository access instead of repeated direct user grants.
• Use least privilege for users, tokens, Apps, workflows, and runners.
• Require strong authentication through 2FA and/or enterprise identity controls appropriate to the plan.
• Prefer GitHub Apps to shared PATs for service automation.
• Use custom properties to classify repositories.
• Use organization rulesets for enforceable repository governance.
• Use security configurations for consistent security-feature rollout.
• Make the default GITHUB_TOKEN conservative and request elevated permissions only per workflow/job.
• Prefer OIDC over static cloud credentials for supported CI/CD integrations.
• Separate runner groups by trust boundary and workload sensitivity.
• Review GitHub Apps, OAuth apps, PATs, deploy keys, and outside collaborators regularly.
• Use budgets and usage reporting to manage metered services.
• Manage stable organization configuration as code where practical.
• Keep lifecycle documentation for renaming, migration, archive, and deletion.
• Stream or export audit data when centralized monitoring/compliance requires it.
• Test major policy changes on representative repositories before enforcing globally.

Avoid

• Making every senior engineer an organization owner.
• Giving Admin repository access when Write or Maintain is enough.
• Using owner PATs in CI/CD.
• Granting every GitHub App access to all repositories.
• Allowing arbitrary third-party Actions without review.
• Using long-lived cloud secrets when OIDC is available.
• Running untrusted pull-request code on sensitive persistent self-hosted runners.
• Depending solely on repository templates for governance.
• Enforcing a new SSO, IP allow list, or ruleset globally without testing recovery paths.
• Treating an archived or inactive repository as automatically risk-free.
• Assuming migration tools move every organization feature.
• Storing plaintext secrets in Terraform code or casually exposing them through state.

71. Organization Administration Anti-Patterns

Anti-patterns are useful because many GitHub governance problems come from reasonable-looking shortcuts that do not scale.

Access anti-patterns

Anti-pattern	Why it happens	Impact	Better approach
Too many owners	“Owners can fix anything”	Very large blast radius	Delegate specific roles
Shared human accounts	Convenience	No individual accountability	Individual identities + teams
Direct repository access everywhere	Fast one-off grants	Access becomes hard to review	Team-based access
Permanent outside collaborators	No review process	Stale third-party access	Expiring/reviewed access process
Admin for routine development	Role misunderstanding	Unnecessary destructive capability	Write/Maintain where sufficient
One PAT shared by automation	Easy bootstrapping	Poor auditability and rotation	GitHub App or workload identity
No owner backup	Small team	Lockout/continuity risk	Minimum two capable owners

Repository anti-patterns

Anti-pattern	Impact	Better approach
Uncontrolled public-repo creation	Accidental data exposure	Restrict visibility creation/change
Every repository config is unique	High maintenance and drift	Organization rulesets + templates
No ownership metadata	Alerts and incidents have no accountable team	Required custom property/service catalog
No archive policy	Large stale attack surface and clutter	Lifecycle status + archive criteria
Branch protection only per repository	Inconsistent enforcement	Organization rulesets
Template treated as enforcement	Repositories drift after creation	Enforce with policy/rulesets

Security anti-patterns

Anti-pattern	Risk	Better approach
No 2FA/SSO enforcement	Account compromise	Strong authentication policy
Unrestricted Actions	Supply-chain exposure	Allowlist + SHA pinning policy where appropriate
Broad GITHUB_TOKEN	Workflow compromise has more power	Read-only default + explicit permissions
Persistent sensitive runners for untrusted code	Credential/network compromise	Ephemeral/isolation boundaries
Long-lived cloud keys in secrets	Credential leakage	OIDC federation
Push protection disabled everywhere	Secrets reach Git history	Enable and govern bypasses
No audit review	Suspicious changes go unnoticed	SIEM/review process

72. Troubleshooting Guide

The table below focuses on common organization-administration failures rather than generic Git usage.

Problem	Likely cause	How to diagnose	Resolution
Member cannot access repository	Missing team/direct permission or base permission is too low	Check People, Teams, repository Collaborators/Teams	Add correct team/repository role
User was invited but is not active	Invitation not accepted, expired, identity requirement unmet	Check pending/failed invitations	Resend invitation and validate identity requirements
Outside collaborator cannot access expected repo	Only selected repository access exists	Review collaborator repository list	Grant only required repository
Team permission seems ignored	Higher/lower permission comes from another source	Inspect all teams, direct grants, base permission	Remove conflicting grants and standardize
User cannot manage settings expected by job	Wrong organization role	Review assigned organization roles	Assign delegated role rather than owner
Ruleset is not affecting repository	Target conditions do not match	Inspect repository name/custom properties/visibility	Fix ruleset targeting
Ruleset unexpectedly blocks a push	Multiple rulesets aggregate	Review all organization and repository rules	Identify matching rule and intended bypass
Required status check never appears	Workflow/check name mismatch or workflow does not run	Inspect PR checks and workflow triggers	Correct check name/trigger
GitHub Actions workflow cannot run	Actions disabled or action not allowlisted	Check org/repo Actions policy	Enable repository/action within policy
Workflow gets permission denied from GitHub API	GITHUB_TOKEN permission too low	Inspect workflow permissions: and org defaults	Add smallest required permission
Workflow cannot create/approve PR	Organization policy blocks it	Check workflow permissions settings	Enable only if governance permits
Reusable workflow inaccessible	Repository/workflow access scope does not permit caller	Check reusable workflow access settings	Allow appropriate org/enterprise scope
Self-hosted runner remains offline	Runner service, token, network, version issue	Check runner service logs and outbound connectivity	Repair/upgrade/re-register runner
Job stays queued	No matching online runner/label/group or capacity exhausted	Inspect requested labels/group and runner status	Fix routing or add capacity
Runner can access too many repos	Runner group is too broad	Inspect runner group repository/workflow access	Split runner groups by trust boundary
OIDC cloud login fails	Trust policy claims do not match workflow	Inspect token subject/audience and cloud trust	Correct claim conditions
Organization secret unavailable	Visibility scope excludes repository	Check secret access policy	Add selected repository or adjust visibility
Package install returns 403	Missing package permission or token type/scope	Check package access and workflow repository access	Grant package Read and proper auth
GitHub App receives 403	App installation or permission does not cover resource	Review app permissions and installation repos	Change requested permission/install scope
GitHub App webhook signature fails	Wrong webhook secret or verification implementation	Compare secret and delivery headers	Fix secret/verification code
Fine-grained PAT request pending	Approval policy requires admin review	Check PAT requests	Approve/deny according to policy
OAuth app cannot access org data	OAuth restrictions enabled	Review Third-party access/OAuth app policy	Approve app if justified
User removed after 2FA enforcement	User did not satisfy requirement	Review audit log and 2FA state	Reinvite after compliant setup
SAML user cannot access organization	Identity not linked/authorized or IdP issue	Test SSO and linked identity	Reauthorize/fix IdP assignment
SCIM user not provisioned	IdP provisioning/app configuration issue	Check IdP SCIM logs and GitHub identity state	Repair provisioning mapping/token
IP allow list locks out admin	Current egress IP/CIDR was omitted	Use known-good recovery path/enterprise admin	Add correct CIDR and test before re-enabling
Custom property cannot be set	Wrong type/value or actor editing disabled	Inspect property schema	Use valid value and allowed actor
Issue field missing from PR	Organization issue fields apply to issues, not PRs	Confirm item type	Use Project field or another mechanism
Audit event not found in default view	Date filter/time window or retention	Expand filter and use API/export if available	Query correct time range
Terraform wants to recreate existing object	Object not imported or identifier mismatch	Compare state with GitHub	Import and reconcile before apply
Terraform constantly shows drift	Setting also managed manually/elsewhere	Review audit log and state ownership	Establish one source of truth
Organization rename breaks integration	Integration stored literal old URL/name	Inspect failed webhook/API/CI config	Update integration and remotes
Migration missing team members	Migration path does not migrate that relationship	Compare source/destination inventory	Recreate/sync team membership separately
Deleted repository cannot be restored	Outside restoration window or unsupported dependency	Check Deleted repositories and support docs	Restore if eligible; otherwise use backup/migration copy

Diagnostic command starter set

# Confirm login and scopes/authentication context
gh auth status

# Organization metadata
gh api "/orgs/$ORG"

# Members
gh api --paginate "/orgs/$ORG/members"

# Teams
gh api --paginate "/orgs/$ORG/teams"

# Organization roles
gh api "/orgs/$ORG/organization-roles"

# Actions policy
gh api "/orgs/$ORG/actions/permissions"

# Custom-property schema
gh api "/orgs/$ORG/properties/schema"

# Audit log — permissions and plan requirements apply
gh api --paginate "/orgs/$ORG/audit-log"

Use the audit log whenever a setting “changed by itself.” In mature organizations, unexplained configuration change is usually an ownership/source-of-truth problem rather than a GitHub UI problem.

73. Beginner → Intermediate → Advanced Learning Map

Level	Learn first	Practical outcome
Beginner	Organization model, owners/members, teams, repository roles, base permissions, repository creation	Safely administer a small organization
Essentials	Rulesets, custom properties, Actions policy, secrets/variables, billing, 2FA, Apps/PATs	Establish a controlled team organization
Intermediate	SAML/SCIM, audit logs, Codespaces, Packages, Pages, security configurations, Code Quality	Operate organization-wide services
Advanced	Delegated/custom roles, IaC, migration, runner governance, SIEM, AI governance, policy automation	Run an enterprise-scale operating model

Suggested sequence for a new administrator:

1. People and teams
2. Repository permissions
3. Repository policies/rulesets
4. Actions and secrets
5. Authentication and third-party access
6. Security controls
7. Audit/billing
8. APIs and IaC
9. Enterprise identity and migration
10. Operating model and continuous governance

74. Quick Reference / Cheat Sheet

Important organization areas

Need	Common location
Members/owners	Organization → People
Teams	Organization → Teams
Repository inventory	Organization → Repositories
Organization settings	Organization → Settings
Billing	Settings → Billing and licensing
Rulesets	Settings → Repository / Rules / Rulesets area
Custom properties	Settings → Repository → Custom properties
Actions policy	Settings → Actions
Runners	Settings → Actions → Runners / Runner groups
Secrets/variables	Settings → Secrets and variables
GitHub Apps/OAuth/PAT	Settings → Third-party access / Developer settings
2FA/SSO	Settings → Authentication security
Audit log	Organization → Settings → Audit log / Logs
Copilot	Settings → Copilot
Codespaces	Settings → Codespaces
Packages	Organization → Packages / package settings

Exact navigation labels can change as GitHub evolves; search within organization Settings if an item has moved.

Repository access hierarchy reminder

• Organization base permission establishes a baseline for members.
• Team grants add repository permissions.
• Direct collaborator grants add repository permissions.
• Custom repository roles extend a base role with additional permissions on supported plans.
• Organization owners have administrative capability across organization repositories.

Repository roles

UI role	Typical API/provider term in older endpoints/resources	Purpose
Read	pull	View/clone/read
Triage	triage	Manage issues/PRs without code write
Write	push	Push code/manage development
Maintain	maintain	Manage repo without full destructive admin
Admin	admin	Full repository administration

Useful gh commands

# Authenticate
gh auth login

gh auth status

# Repository inventory
gh repo list "$ORG" --limit 1000

# REST API
gh api "/orgs/$ORG"

# Paginate
gh api --paginate "/orgs/$ORG/members"

# GraphQL
gh api graphql -f query='query { viewer { login } }'

API header

X-GitHub-Api-Version: 2026-03-10

High-risk changes that deserve change control

• owner changes
• SSO/SCIM/2FA enforcement
• IP allow-list enforcement
• repository visibility policy
• organization-wide rulesets
• Actions allowlist/SHA-pinning changes
• runner trust-boundary changes
• PAT/OAuth/GitHub App policy changes
• security-configuration enforcement
• organization rename/archive/delete
• migration cutover

75. Hands-On Exercises

Exercise 1 — Beginner: Build a Team-Based Access Model

Objective: Replace direct repository access with team-based access.

Scenario:

The payments-api repository has five developers added individually with Write access. You want a maintainable model.

Tasks:

1. Create a payments team.
2. Add the five developers as members.
3. Add one lead as team maintainer.
4. Grant the team Write access to payments-api.
5. Remove redundant direct user grants.
6. Verify each user still has expected access.
7. Document the team as the repository owner.

Expected outcome:

Repository access is primarily controlled by team membership rather than five separate user assignments.

Validation:

• A team member can clone/push as expected.
• A removed team member loses the team-derived permission.
• The audit log records the access changes.

Exercise 2 — Essentials: Govern the Default Branch

Objective: Create an organization ruleset for production repositories.

Tasks:

1. Create a custom property service_tier with values tier-1, tier-2, tier-3.
2. Mark two test repositories as tier-1.
3. Create a branch ruleset targeting service_tier=tier-1.
4. Target the default branch.
5. Require pull requests.
6. Require at least one approval.
7. Require a CI status check.
8. Restrict force pushes/deletion.
9. Test with a non-production repository first.
10. Review bypass roles.

Expected outcome:

Any repository classified as tier-1 receives the baseline automatically without creating repository-specific branch protection repeatedly.

Exercise 3 — Intermediate: Harden GitHub Actions

Objective: Reduce CI/CD credential and supply-chain risk.

Tasks:

1. Set default workflow permissions to read-only.
2. Identify workflows that need write permissions and declare them explicitly.
3. Review third-party Actions in the organization.
4. Create an allowlist appropriate to your policy.
5. Enable immutable SHA pinning if required by your security model.
6. Replace one static cloud credential with OIDC.
7. Put deployment jobs behind a protected environment.
8. Review runner groups and repository access.

Expected outcome:

A compromised workflow receives substantially less ambient authority.

Exercise 4 — Intermediate: Audit Programmatic Access

Objective: Build an inventory of non-human access.

Inventory:

• GitHub Apps
• OAuth Apps
• fine-grained PAT requests
• classic PAT policy
• deploy keys
• organization secrets
• self-hosted runners

For each item, record:

• business purpose
• owner
• repositories/resources
• permissions
• credential/rotation model
• last review date

Expected outcome:

Every non-human access path has an owner and a justified scope.

Exercise 5 — Advanced: Build a Governance Drift Check

Objective: Detect deviations from the organization baseline.

Write a script or workflow that checks at minimum:

• organization owner count
• Actions policy
• custom-property schema
• ruleset inventory
• repositories missing owner_team
• archived repositories still receiving broad integrations

Output a report and fail only on controls you are ready to enforce.

Expected outcome:

GitHub governance becomes continuously testable instead of relying only on screenshots and manual reviews.

76. Complete Practical Project — Production-Ready Organization Baseline

Requirement

Design a GitHub organization called acme-engineering for 60 engineers across four product teams:

• payments
• identity
• mobile
• platform

The organization needs:

• least-privilege repository access
• standardized repository creation
• production branch governance
• controlled GitHub Actions
• cloud deployments without static credentials
• security scanning
• auditability
• delegated administration
• cost visibility

Target architecture

flowchart TB
    IDP[Identity provider / user lifecycle] --> ORG[acme-engineering]

    ORG --> TEAMS[Teams]
    ORG --> META[Custom properties]
    ORG --> RULES[Organization rulesets]
    ORG --> SEC[Security configurations]
    ORG --> ACT[Actions policy]
    ORG --> APPS[GitHub Apps]
    ORG --> AUDIT[Audit logs]

    TEAMS --> REPOS[Repositories]
    META --> REPOS
    RULES --> REPOS
    SEC --> REPOS

    REPOS --> WF[Workflows]
    ACT --> WF
    WF --> OIDC[OIDC]
    OIDC --> CLOUD[Cloud deployment roles]

    WF --> RUNNERS[Runner groups]
    AUDIT --> SIEM[SIEM / compliance archive]

Step 1 — Define administrative roles

Create a role matrix before configuring repositories.

Function	Role
Core GitHub account administration	2–4 organization owners
Security operations	Security Manager team
CI/CD/runners	CI/CD admin / delegated capability
Billing	Billing Managers
App registration	App Managers
Product repository access	Product teams

Do not make all team leads owners.

Step 2 — Create teams

Create:

• payments
• identity
• mobile
• platform
• security-managers

Use nested teams only if the hierarchy represents a durable access relationship. Avoid deep nesting that becomes difficult to reason about.

Step 3 — Define repository metadata

Create these custom properties:

Property	Type	Example
owner_team	Single select	payments
service_tier	Single select	tier-1
data_classification	Single select	confidential
lifecycle	Single select	active

Require the critical metadata needed for governance.

Step 4 — Define repository creation workflow

Create repositories only through an approved path:

1. Request repository name and owner.
2. Validate naming convention.
3. Create private repository.
4. Assign owner team.
5. Set properties.
6. Attach team permission.
7. Initialize from standard template.
8. Confirm ruleset/security configuration coverage.

Step 5 — Create tier-1 ruleset

Target repositories where service_tier=tier-1.

Require:

• pull request before merge
• at least one or two approvals according to risk
• code-owner review where appropriate
• required CI checks
• no force push to protected branch
• no default-branch deletion

Minimize bypass identities and audit any use.

Step 6 — Configure Actions policy

Recommended baseline:

• Actions enabled
• organization/GitHub-approved actions allowed
• third-party actions reviewed
• default GITHUB_TOKEN read-only
• explicit workflow permissions
• fork PR behavior restricted according to trust model
• reusable workflows for standard CI/deployment

Step 7 — Build runner groups

Example groups:

Group	Workload	Access
general-ci	Unit tests/build	Broad private repo set
prod-deploy	Production deployment	Selected deployment repos/workflows
security	Security jobs	Selected security workflows

Use ephemeral workers for sensitive self-hosted capacity when practical.

Step 8 — Configure cloud OIDC

For each cloud role:

1. Trust GitHub’s OIDC issuer.
2. Restrict subject/claims to expected organization/repository/environment/workflow.
3. Request an ID token only in the job that needs it.
4. Give the cloud role least privilege.
5. Test from non-production first.

Step 9 — Apply security configuration

Start with pilot repositories, then expand by custom property.

Include appropriate combinations of:

• dependency graph
• Dependabot alerts/updates
• code scanning
• secret scanning
• push protection
• dependency review

Step 10 — Configure programmatic access policy

• Prefer GitHub Apps for integrations.
• Restrict classic PAT usage if business requirements permit.
• Require approval for fine-grained PATs where appropriate.
• Review OAuth app access.
• Restrict App installations/requests based on operating model.

Step 11 — Configure audit and reporting

Create at least these reports:

• owners and privileged roles
• outside collaborators
• repositories without owner metadata
• repositories not covered by tier-appropriate security/rulesets
• Actions runner health and usage
• GitHub App inventory
• paid-seat utilization

Stream audit events to a SIEM if required by the plan/compliance model.

Step 12 — Manage configuration as code

Move stable controls into Terraform or scripted API configuration:

• teams
• team/repository mapping
• organization settings
• Actions policy
• rulesets
• repository baseline

Use pull requests for administration changes.

Validation checklist

• [ ] At least two owners exist.
• [ ] Normal developers are not owners.
• [ ] Every active repository has owner_team.
• [ ] Tier-1 repositories match the tier-1 ruleset.
• [ ] Security configuration coverage matches the intended repository set.
• [ ] Default workflow token permission is conservative.
• [ ] Production cloud deployments use OIDC rather than static access keys where supported.
• [ ] Production runner access is restricted.
• [ ] GitHub Apps have named owners and scoped installation access.
• [ ] Outside collaborators have business justification.
• [ ] Audit data can identify administrative changes.
• [ ] Billing budgets/alerts are configured for meaningful usage products.
• [ ] A repository deletion/restore test has been performed on a disposable repository.
• [ ] Organization rename/delete procedures are documented even if never expected.

Improvement ideas

After the baseline is stable:

• automate joiner/mover/leaver processes with IdP + SCIM where supported
• add repository self-service provisioning
• add drift detection
• add policy checks for custom-property completeness
• automate quarterly access-review evidence
• adopt artifact attestations for release provenance
• add Copilot/MCP governance if AI features are enabled

77. Knowledge-Check and Interview Questions

Conceptual

1. Why should normal users sign in with personal accounts instead of sharing an organization login?
2. What is the difference between an organization owner and a repository admin?
3. Why are teams preferable to direct repository grants?
4. What is the difference between Read, Triage, Write, Maintain, and Admin?
5. What problem do custom repository roles solve?
6. What problem do custom organization roles solve?
7. What is an outside collaborator?
8. How does base repository permission affect members?
9. Why are organization rulesets more scalable than per-repository branch protection?
10. How can custom properties drive dynamic governance?
11. Why should GITHUB_TOKEN permissions be minimized?
12. When should you use a GitHub App instead of a PAT?
13. What is the purpose of a runner group?
14. Why is OIDC safer than storing a long-lived cloud access key in many repositories?
15. What is the difference between SAML SSO and SCIM?
16. What does push protection add beyond secret scanning after commit?
17. Why should security features be rolled out through security configurations/pilots?
18. What is the operational value of the audit log?
19. Why is an organization template not the same as organization policy?
20. Why should organization deletion and renaming be treated as formal change events?

Scenario-based

21. A contractor needs access to one private repository for 30 days. How would you model access?
22. A platform team wants every tier-1 repository to require two approvals. How can custom properties and rulesets work together?
23. A workflow needs to publish a release but the default token is read-only. What is the safe fix?
24. A public repository receives untrusted pull requests. Should those jobs run on a privileged persistent self-hosted runner? Why?
25. An integration currently uses an owner’s classic PAT. How would you migrate it?
26. A company turns on an IP allow list and administrators are locked out. What design mistake occurred?
27. A Terraform plan wants to create a team that already exists. What should you do before applying?
28. A migrated organization contains teams but missing memberships. What should the migration runbook include?
29. An organization has 25 owners “for convenience.” How would you reduce privilege without blocking operations?
30. Copilot coding agents need access to a production repository. What governance questions should be answered first?

78. Frequently Asked Questions

Is a GitHub Organization a separate login account?

No. People normally authenticate with their own GitHub accounts and receive organization membership/roles. The organization owns shared resources and policy.

How many organization owners should we have?

GitHub recommends limiting owners while maintaining continuity. A practical baseline is at least two capable owners, then use delegated roles for routine administration.

Should developers receive Admin access to repositories?

Only when they actually need repository-administration capabilities. Many engineering tasks fit Write or Maintain.

Should we use teams or direct collaborators?

Prefer teams for normal organizational access. Direct grants are useful for exceptional cases but become difficult to review at scale.

Are organization rulesets the same as branch protection rules?

They solve overlapping governance needs, but rulesets provide richer centralized targeting and policy composition. Organizations commonly use rulesets as the scalable policy layer.

Can custom properties be used only for labels/documentation?

No. They can support repository search/filtering and can be used in policy targeting such as organization rulesets, making them a governance primitive.

Are issue fields and Project fields the same?

No. Organization issue fields belong to issues and can be surfaced in Projects. Project fields are project-specific metadata. Organization issue fields do not simply become pull-request fields.

Should we allow all Marketplace Actions?

That depends on your risk model. Mature organizations often allow GitHub-owned/verified or reviewed Actions and control third-party use rather than allowing everything without review.

Does setting the default GITHUB_TOKEN to read-only break every deployment workflow?

Not necessarily. Workflows can explicitly request the specific write permissions they need. This makes privilege visible in workflow code.

Can GitHub-hosted runners reach private resources?

There are supported private-networking options for some hosted compute configurations, and self-hosted runners can also be placed inside private networks. Choose based on plan, network architecture, trust, and operational burden.

Is a self-hosted runner automatically more secure?

No. It gives you more control but also more responsibility. Persistent runners can retain state and network access, so isolation, patching, ephemeral design, and repository trust boundaries matter.

Do organization secrets automatically reach every repository?

No. Organization secret access is governed by visibility/repository scope. Restrict sensitive secrets to the repositories that need them.

Can I make an organization private?

An organization has public-facing account/profile concepts, while repositories/projects/packages and membership visibility have their own controls. Do not treat “organization privacy” as a single switch that hides every resource.

Is SAML SSO the same as Enterprise Managed Users?

No. SAML SSO can be applied to organizations using normal personal GitHub accounts. Enterprise Managed Users is a different identity model where user accounts are provisioned and controlled by the enterprise identity system.

Does SCIM replace SAML?

No. SAML handles authentication/SSO; SCIM handles lifecycle provisioning/deprovisioning and synchronization.

Does secret scanning prevent all secrets from being committed?

Secret scanning identifies supported secret patterns. Push protection can block supported secrets before they are pushed, subject to policy/bypass behavior. Neither removes the need for secret hygiene and incident response.

Can Terraform manage everything in GitHub Organization settings?

No single IaC provider covers every current/preview GitHub capability immediately. Use Terraform for supported stable resources and REST/GraphQL/gh for gaps. Keep ownership clear to avoid drift.

Can an organization be directly converted into a personal account?

No. GitHub documents a transfer/rename workaround rather than a direct account-type conversion.

Does GitHub Enterprise Importer migrate everything?

No. Coverage depends on source, destination, and migration type. Validate teams, membership, permissions, Actions, secrets, apps, packages, projects, webhooks, and other features separately.

How should we introduce Copilot/MCP/agents?

Treat them as governed capabilities: define access, model/agent policy, repository scope, external server trust, data sensitivity, compute boundaries, and cost monitoring before organization-wide rollout.

What should be the first three controls in a new organization?

A solid start is: establish owner continuity and team-based access, restrict dangerous repository/Actions defaults, and enable strong authentication/security basics. Then add metadata, rulesets, and automation.

79. Freshness and Current-Behavior Notes — September 2026

This guide intentionally distinguishes several newer/current behaviors that are easy to miss when reading older GitHub tutorials.

Area	Current note
REST API	2026-03-10 is a supported dated REST API version; explicitly version production integrations
Organization roles	Delegated predefined roles include security, billing, moderation, CI/CD, and App-management capabilities in applicable products/plans
Custom organization roles	Enterprise Cloud capability; use only where the plan supports it
Custom repository roles	Enterprise Cloud capability
Custom properties	Organization repository metadata supports multiple property types and policy/search use cases
Issue fields	Organization-level issue fields are distinct from Project-only fields and apply to issues, not PRs
Sandboxes	GitHub cloud/local sandbox functionality is still a newer/preview-oriented area; confirm current entitlement and billing before standardizing
Code Quality	Current organization-level governance/insights product; confirm language/plan coverage before rollout
Advanced Security packaging	Current GitHub security offerings may be presented as GitHub Code Security and GitHub Secret Protection capabilities rather than only older “GHAS” terminology
Actions retention	GitHub announced broader retention-policy behavior for checks/workflow runs/commit statuses starting October 1, 2026; this date is after this guide’s September 26 verification date
Organization conversion	Direct organization → personal-account conversion is not supported; use the documented transfer/rename procedure
Migration	GitHub Enterprise Importer has scenario-specific coverage; do not assume team membership/integrations automatically migrate
Approved domains	Some domain-related capabilities may be preview/plan dependent; verify before making them a compliance control

Preview features, product names, navigation labels, limits, and plan entitlements can change faster than foundational GitHub concepts. Re-check official documentation immediately before an enterprise rollout or purchase decision.

80. Summary and Recommended Next Steps

You now have a complete organization-administration model covering:

• organization foundations, plans, creation, profile, and ownership
• people, invitations, outside collaborators, teams, and roles
• repository roles, policies, rulesets, custom properties, and lifecycle
• planning administration, issue types, and organization issue fields
• billing, licensing, budgets, and usage
• Actions policy, runners, networking, retention, secrets, variables, and OIDC
• Codespaces, Sandboxes, Copilot, Packages, Pages, and Discussions
• 2FA, SAML, SCIM, IP allow lists, security configurations, code/secret/dependency security, and Code Quality
• GitHub Apps, OAuth Apps, PAT governance, webhooks, and deploy keys
• audit logs, compliance, migrations, deleted-repository recovery, and organization lifecycle
• REST, GraphQL, GitHub CLI, Terraform, automation, and policy-as-code patterns
• enterprise operating models, monitoring, access reviews, and continuity

Recommended next steps

1. Build a disposable training organization.
2. Practice team/repository access before experimenting with custom roles.
3. Add custom properties and a non-enforced/test ruleset.
4. Harden one Actions workflow and implement OIDC.
5. Enable security controls on test repositories.
6. Query the organization with gh api and GraphQL.
7. Import a small subset into Terraform.
8. Build a governance report from APIs/audit data.
9. Run a repository deletion/restore drill.
10. Document the final production operating model and exception process.

The goal is not to enable every setting. The goal is to create an organization whose access, policy, automation, security, and ownership are intentional, repeatable, auditable, and understandable.

81. Official References

The following references were prioritized while verifying this tutorial. GitHub documentation remains the authoritative source for plan eligibility, previews, current limits, and navigation.

Organizations, roles, and repositories

• About organizations
• Roles in an organization
• Repository roles for an organization
• Custom organization roles
• Custom repository roles
• Managing organization settings

Governance and planning

• Rules available for rulesets
• Creating rulesets for repositories in your organization
• Managing custom properties for repositories
• Managing issue types in an organization
• Managing issue fields in an organization

Actions and Codespaces

• Disabling or limiting GitHub Actions for your organization
• Managing GitHub Actions settings for a repository
• Managing access to self-hosted runners using groups
• Managing GitHub-hosted runners in a runner group
• Managing GitHub Actions settings for a repository
• Managing Codespaces for your organization

Authentication, security, and audit

• Requiring two-factor authentication in your organization
• About SAML single sign-on
• About SCIM for organizations
• Managing allowed IP addresses for your organization
• About security configurations
• Reviewing the audit log for your organization

Apps, tokens, and APIs

• About programmatic access in your organization
• Registering a GitHub App
• Managing private keys for GitHub Apps
• Adding and removing GitHub App managers
• REST API versions
• REST API endpoints for organizations

Terraform

• GitHub Terraform provider
• github_actions_organization_permissions
• github_organization_ruleset
• github_team

82. Coverage Map to the Supplied 164-Topic Organization Administration Syllabus

The original syllabus is intentionally broader than GitHub’s left-navigation menu. The table below shows where each topic family is handled in this guide.

Supplied topic groups	Topic family	Covered in this guide
1–7	Foundations, plans, creation, navigation, general settings, identity, ownership	§§1–6
8–12	People, invitations, member management, outside collaborators, visibility	§§7–9
13–15	Teams, administration, team access	§10
16–20	Organization roles, predefined/all-repo roles, custom roles	§§12–13
21–22	Repository roles and custom repository roles	§§11, 13
23–24	Member privileges and base permissions	§§11, 14
25–30	Billing, licensing, payments, usage, budgets, billing managers	§15
31–37	Repository management, creation, visibility, transfer/deletion, forks, PR governance, defaults	§16
38–40	Organization rulesets and branch governance	§17
41–43	Custom-property schema, administration, and use	§18
44–47	Planning, issue types, issue fields, Project policy	§19
48	Import/export administration	§§20, 67
49–51	Moderation, interaction limits, blocking	§21
52–58	Actions policies, workflow permissions, runners, runner groups, networking, retention, metrics	§§22–25, 63–64
59–62	Codespaces access, billing, policy, administration	§28
63	Sandboxes	§29
64–70	Copilot plans/access/policies/models/agents/MCP/metrics	§§30, 65
71	Packages administration	§31
72	Pages administration	§32
73	Discussions	§33
74	Webhooks	§34
75–79	2FA, SAML, SCIM, IP allow lists, notification/domain security	§§36–40
80–85	Advanced Security, Security Managers, dependency/code/secret scanning, security configurations	§§41–45, 62
86–87	Code Quality and insights	§46
88	Deploy keys	§47
89	Compliance	§§48, 66
90	Verified/approved domains	§40
91–92	Organization secrets and variables	§26
93–95	GitHub Apps, OAuth policy, PAT policy	§§49–51, 57
96–97	Scheduled reminders and external integrations	§35
98–100	Audit log, security events, export/API/streaming	§§52–53, 66
101	Deleted repositories	§54
102	Organization insights	§§55, 69
103–107	Rename, ownership transfer, archive, deletion, conversion	§§6, 56
108–110	Organization-owned GitHub Apps, credentials, App Managers	§57
111	Developer settings	§57
112–115	REST, GraphQL, CLI, organization-role APIs	§58
116–118	Property-driven rules, automated provisioning, standardization	§60
119–121	Least privilege, access reviews, joiner/mover/leaver	§61
122–124	Enterprise SAML/SCIM/EMU identity model	§§2, 37–38, 61
125–128	Security rollout, security overview, secret/supply-chain governance	§62
129–131	CI/CD administration, runner fleet, Actions security	§63
132–133	Network controls and service connectivity	§64
134	AI/Copilot governance at scale	§65
135–136	Audit architecture and compliance controls	§66
137–138	Organization migration and migration governance	§§20, 67
139–140	Administrative/repository recovery and continuity	§§54, 67
141–143	Operating model, delegated administration, repository ownership	§68
144–146	Administrative/user/governance automation	§§58–60
147–148	Monitoring, alerting, reporting	§69
149–152	Organization/security/repository/CI best practices	§70
153–155	Access/repository/security anti-patterns	§71
156–164	Complete Settings-area reference	§§4 and 74, with detailed chapters throughout

This mapping is a navigation aid—not a substitute for the detailed chapters. Features are deliberately discussed where they fit operationally rather than repeated under every original syllabus heading.