Skip to main content

Chapter 7: Organization Design & Team Architecture

Part III: Organization Structure & Access Prerequisites: Chapter 1: Enterprise Subscription & Environment Setup GH-100 Exam Mapping: Domain 4 (Manage access and permissions based on membership -- 18%) Verified: 2026-02-01 against official documentation

1. Introduction​

Learning Objectives​

After completing this chapter, you will be able to:

  • Design an organization and repository structure that scales for 50+ developer enterprises
  • Create team hierarchies using parent teams and child teams with inherited permissions
  • Configure repository visibility policies across public, internal, and private settings
  • Implement repository creation policies and enforce naming conventions at the enterprise level
  • Build template repositories and apply repository rulesets for governance at scale

Exam Domain Coverage​

DomainTopics in This Chapter
D4: Manage access and permissions based on membership (18%)Organization structure, team hierarchies, nested permissions, repository visibility, repository policies, template repositories, rulesets

Chapter Overview​

Once an enterprise account is provisioned and identity is federated (see Chapter 1: Enterprise Subscription & Environment Setup), the next critical step is designing the organizational structure that will house your teams, repositories, and policies. This chapter addresses the "topology" of your GitHub Enterprise -- how you arrange organizations, teams, and repositories so that permissions, visibility, and governance flow naturally through the hierarchy.

Organization design is not a one-time activity. As enterprises grow, acquire new business units, and adopt new development practices, the organizational structure must evolve. Poor early decisions -- such as creating a single monolithic organization for thousands of developers, or scattering repositories across dozens of ungoverned organizations -- create friction that compounds over time. Access reviews become painful, policy enforcement becomes inconsistent, and onboarding new developers takes days instead of minutes.

This chapter provides a principled framework for designing your GitHub Enterprise topology. You will learn how GitHub's enterprise-organization-team-repository hierarchy maps to real-world organizational structures, how nested teams enable permission inheritance that mirrors reporting lines, and how repository policies and rulesets let you enforce governance without bottlenecking delivery. By the end, you will have a working multi-team structure with template repositories and rulesets applied -- the foundation for the access control model covered in Chapter 8: Access Control & Permissions Model.


2. Theory & Deep Dive​

The Enterprise Account Hierarchy​

GitHub Enterprise Cloud (GHEC) uses a four-level hierarchy:

  1. Enterprise account -- The top-level container. It owns billing, identity configuration (SAML/SCIM), and enterprise-wide policies. An enterprise has one or more organizations.
  2. Organization -- A shared workspace that groups repositories and people. Organizations have their own membership, teams, and settings. Enterprise policies can override or constrain organization-level settings.
  3. Team -- A group of organization members. Teams are the primary mechanism for granting repository access. Teams can be nested (parent/child) to model departmental hierarchies.
  4. Repository -- The unit of code, issues, and collaboration. Every repository belongs to exactly one organization.

Understanding this hierarchy is essential because permissions, policies, and visibility settings cascade downward. Enterprise-level policies override organization settings, organization-level team permissions flow to child teams, and repository-level settings operate within the constraints set above.

Designing Your Organization Structure​

There are three common patterns for mapping enterprise business units to GitHub organizations:

Pattern 1: Single Organization

All teams and repositories reside in one organization. This pattern is simplest for enterprises with fewer than 200 developers and a relatively flat structure. It provides a single namespace for repositories, one set of organization-level policies, and straightforward team management.

Advantages:

  • Simplest to administer
  • Internal repositories are visible to all members by default
  • Single set of webhooks, OAuth apps, and installed GitHub Apps
  • Easiest cross-team collaboration

Disadvantages:

  • All members see all internal repositories (which may be undesirable for regulated divisions)
  • Organization-level settings apply uniformly, with no ability to vary policies by business unit
  • Team and repository counts can become unwieldy beyond 500+ repositories

Pattern 2: Multiple Organizations by Business Unit

Each major business unit or division gets its own organization. An enterprise account governs all organizations. This is the most common pattern for enterprises with 200+ developers or those with distinct regulatory boundaries between divisions.

Advantages:

  • Isolation between business units (repositories in Org A are invisible to members of Org B unless cross-org access is granted)
  • Organization-level policies can vary by division (for example, stricter policies for a financial services division)
  • Cleaner audit trails per division

Disadvantages:

  • Cross-organization collaboration requires explicit forking or cross-org team invitations
  • Internal visibility is scoped to the organization, not the enterprise (unless using GHEC with enterprise-managed users)
  • More administrative overhead: each organization needs its own owners, webhook configurations, and app installations

Pattern 3: Hybrid (Shared Services + Division Organizations)

A "platform" or "shared services" organization contains shared libraries, CI/CD (Continuous Integration/Continuous Delivery) templates, and internal tools. Division-specific organizations contain product repositories. This pattern balances isolation with reuse.

Enterprise Scenario: A 600-developer insurance company has three divisions: Claims, Underwriting, and Digital. They create four organizations: acme-platform (shared libraries, GitHub Actions reusable workflows, Copilot custom instructions), acme-claims, acme-underwriting, and acme-digital. The platform organization's repositories are set to "internal" visibility so developers in any division can consume shared libraries. Each division organization has its own security policies tailored to its regulatory environment. Enterprise-level policies enforce SAML Single Sign-On (SSO) and two-factor authentication (2FA) across all four organizations.

Team Hierarchies: Parent Teams and Child Teams​

Teams are the backbone of permission management in GitHub. Every organization can contain teams, and teams can be nested to form hierarchies.

Parent teams represent broad organizational groups (e.g., "Engineering", "Platform", "Data Science"). Child teams represent specific squads or functional groups within those broader groups (e.g., "Engineering > Frontend", "Engineering > Backend", "Engineering > QA").

Key behaviors of nested teams:

  1. Permission inheritance: Child teams automatically inherit the repository access permissions of their parent team. If the parent team has write access to a repository, all child teams also have write access. A child team can be granted additional permissions beyond what the parent provides, but cannot have permissions removed that the parent grants.

  2. Mention cascading: Mentioning a parent team (e.g., @acme/engineering) notifies all members of the parent team and all members of every child team. Mentioning a child team (e.g., @acme/engineering-frontend) notifies only members of that child team.

  3. Visibility: Teams can be "visible" (any organization member can see the team and mention it) or "secret" (only team members and organization owners can see it). Secret teams are useful for security teams, incident response groups, or executive committees.

  4. Membership independence: A member of a child team is not automatically a member of the parent team. However, they inherit the parent team's repository permissions. To be notified when the parent team is mentioned, a user must be a direct member of the parent team.

Recommended hierarchy depth: GitHub supports arbitrary nesting depth, but practical experience shows that two to three levels is optimal for most enterprises. Deeper nesting creates confusion about where permissions originate and makes access reviews more difficult.

Example hierarchy for a 200-developer product company:

Engineering (parent)
Frontend (child)
Frontend - Web (child of Frontend)
Frontend - Mobile (child of Frontend)
Backend (child)
Backend - API (child of Backend)
Backend - Data (child of Backend)
DevOps (child)
QA (child)
Platform (parent)
SRE (child)
Developer Experience (child)
Security (parent - secret visibility)
AppSec (child - secret visibility)
Incident Response (child - secret visibility)

Synchronizing Teams with Identity Providers​

For enterprises using SCIM (System for Cross-domain Identity Management) provisioning (see Chapter 3: SCIM Provisioning & Lifecycle Management), teams can be synchronized with Identity Provider (IdP) groups. When a user is added to an Azure AD (now Microsoft Entra ID) group that is mapped to a GitHub team, they are automatically added to that team. When removed from the IdP group, they are removed from the team.

Team synchronization is configured at the organization level and requires SAML SSO to be enabled. Each GitHub team can be linked to one or more IdP groups. This linkage ensures that team membership -- and therefore repository access -- stays in sync with your corporate directory without manual intervention.

Enterprise Scenario: A 300-developer logistics company provisions all developers via SCIM from Microsoft Entra ID. They create Entra ID groups that mirror their GitHub team hierarchy: GH-Engineering, GH-Engineering-Frontend, GH-Engineering-Backend, and so on. When a new developer joins the frontend squad, their manager adds them to the GH-Engineering-Frontend Entra ID group. Within minutes, SCIM syncs the membership change, and the developer gains access to all repositories the Frontend child team can reach -- including inherited access from the Engineering parent team. No GitHub administrator action is required.

Repository Visibility: Public, Internal, and Private​

Every repository has a visibility setting that determines who can see it:

VisibilityWho Can See ItUse Case
PublicAnyone on the internetOpen-source projects, public documentation, community-facing tools
InternalAll members of the enterprise (across all organizations)Shared libraries, internal documentation, reusable templates that any employee should access
PrivateOnly users explicitly granted access (via team or direct collaboration)Proprietary product code, sensitive configurations, security tooling

Internal visibility is only available with GitHub Enterprise Cloud. It is one of the most powerful features for inner-source development, where organizations want to share code across teams and divisions without making it public. Internal repositories are visible to every member of the enterprise account, regardless of which organization the repository belongs to.

Enterprise policies for repository visibility: Enterprise owners can restrict which visibility settings organizations are allowed to use. For example, an enterprise policy can:

  • Prevent organizations from creating public repositories (common in regulated industries)
  • Require all new repositories to default to "internal" or "private"
  • Allow only specific organizations to create public repositories (e.g., the open-source program office)
# Example: Enterprise-level repository visibility policy
# Configured via: Enterprise Settings > Policies > Repositories
repository_creation:
public: disabled # No org can create public repos
internal: enabled # All orgs can create internal repos
private: enabled # All orgs can create private repos
default_visibility: internal

Repository Creation Policies and Naming Conventions​

Uncontrolled repository creation leads to sprawl. Enterprises with hundreds of developers can accumulate thousands of repositories with inconsistent names, unclear ownership, and abandoned code. GitHub provides several mechanisms to govern repository creation:

Who can create repositories: Enterprise owners can restrict repository creation to organization owners only, or allow all members to create repositories. A balanced approach is to allow members to create private repositories (for experimentation) but restrict internal and public repository creation to owners or a designated team.

Naming conventions: GitHub does not enforce naming conventions natively, but enterprises can implement them through:

  1. Repository rulesets with name patterns (covered later in this section)
  2. GitHub Apps or Actions that validate repository names on creation and flag non-compliant names
  3. Template repositories that pre-populate the correct naming structure
  4. Documentation and onboarding training that establishes naming standards

A common enterprise naming convention:

<org>/<team>-<project>-<component>

Examples:

  • acme-platform/devex-github-actions-library
  • acme-claims/claims-api-service
  • acme-claims/claims-frontend-web

Benefits of consistent naming:

  • Developers can find repositories by browsing or searching predictable names
  • Automation scripts can target repositories by pattern (e.g., all repositories matching *-api-service)
  • Audit reports are easier to read when repository names are self-documenting
  • CODEOWNERS files can reference team slugs that align with repository prefixes

Template Repositories​

Template repositories allow organizations to define starter repository structures that developers use when creating new repositories. Unlike forking, creating a repository from a template produces a clean repository with no commit history link to the template.

A template repository typically includes:

  • Standard directory structure (src/, tests/, docs/, .github/)
  • Pre-configured CI/CD workflows (.github/workflows/)
  • Default branch protection rules via CODEOWNERS
  • Issue and Pull Request (PR) templates (.github/ISSUE_TEMPLATE/, .github/pull_request_template.md)
  • Copilot custom instructions (.github/copilot-instructions.md)
  • Standard .gitignore, LICENSE, and README.md files
  • Pre-configured Dependabot settings (.github/dependabot.yml)

To designate a repository as a template, navigate to the repository's Settings page and check "Template repository" under the General section.

Enterprise Scenario: A platform engineering team at a 150-developer SaaS (Software as a Service) company maintains three template repositories: template-microservice-java, template-microservice-node, and template-frontend-react. Each template includes GitHub Actions workflows for building, testing, and deploying to their Kubernetes cluster, plus pre-configured Copilot instructions tuned for their coding standards. When a new squad starts building a service, they create a repository from the appropriate template and have a deployable skeleton within minutes -- complete with CI/CD, linting, and security scanning.

Repository Rulesets​

Repository rulesets are a governance mechanism that allows organization owners and enterprise owners to enforce rules across multiple repositories. Rulesets replaced the older "branch protection rules" model with a more flexible, scalable approach.

Key advantages of rulesets over legacy branch protection:

FeatureBranch Protection RulesRepository Rulesets
ScopeSingle repository, single branch patternMultiple repositories via targeting
Management levelRepository adminOrganization or enterprise owner
StackingOne rule set per branch patternMultiple rulesets can apply; all must pass
Bypass actorsSpecific usersRoles, teams, apps, or deploy keys
StatusActive onlyActive, evaluate (dry-run), or disabled

Ruleset components:

  1. Targets: Which repositories and branches/tags the ruleset applies to. Targets can use patterns (e.g., all repositories matching *-api-*, all branches matching release/*).
  2. Rules: The specific protections enforced. Common rules include:
    • Require a pull request before merging
    • Require N approving reviews (e.g., 2 for production branches)
    • Require status checks to pass (e.g., CI build, security scan)
    • Require signed commits
    • Block force pushes
    • Restrict branch deletions
    • Require linear history (no merge commits)
  3. Bypass actors: Who can bypass the ruleset. Typically limited to repository administrators or specific automation apps (e.g., release bots). Bypass should be granted sparingly and audited.
  4. Enforcement status: Active (enforced), evaluate (logs violations but does not block), or disabled. The "evaluate" mode is invaluable for rolling out new rulesets without disrupting existing workflows.

Enterprise-level rulesets: Enterprise owners can create rulesets that apply across all organizations in the enterprise. This ensures baseline governance (e.g., "all repositories across the enterprise must require pull requests for the main branch") while allowing organizations to add stricter rules on top.

# List existing rulesets for an organization using the GitHub CLI
gh api orgs/acme-platform/rulesets --jq '.[].name'
# Create a ruleset via the GitHub CLI (simplified example)
gh api orgs/acme-platform/rulesets \
--method POST \
--field name="require-pr-for-main" \
--field target="branch" \
--field enforcement="active" \
--field conditions='{"ref_name":{"include":["refs/heads/main"],"exclude":[]}}' \
--field rules='[{"type":"pull_request","parameters":{"required_approving_review_count":2,"dismiss_stale_reviews_on_push":true,"require_code_owner_review":true}}]'

Bringing It All Together: A Reference Architecture​

For a 200-developer enterprise with three product divisions and a shared platform team, a recommended architecture looks like this:

  • Enterprise account: Acme Corp -- owns billing, enforces SAML SSO, sets enterprise-wide policies (no public repos, require 2FA)
  • Organizations:
    • acme-platform -- shared libraries, CI/CD templates, developer tools
    • acme-payments -- payments product division
    • acme-commerce -- e-commerce product division
    • acme-mobile -- mobile applications division
  • Team hierarchy (per organization, synced via SCIM from Entra ID):
    • Each organization has a top-level team matching the division name
    • Child teams for each squad (e.g., payments-checkout, payments-fraud-detection)
    • A cross-cutting security secret team in each organization for AppSec engineers
  • Repository visibility:
    • acme-platform repositories default to internal (visible to entire enterprise)
    • Product division repositories default to private (visible only to division members)
  • Rulesets:
    • Enterprise-level ruleset: Require PR with 1 approval for main branch across all repos
    • Organization-level ruleset in acme-payments: Require 2 approvals and signed commits (PCI DSS compliance)
  • Template repositories in acme-platform: One per tech stack, pre-configured with org-standard CI/CD and Copilot instructions

3. Diagrams​

Enterprise Hierarchy and Permission Flow​

graph TD
EA["Enterprise Account<br/>Acme Corp"]
EA --> ORG1["Organization<br/>acme-platform"]
EA --> ORG2["Organization<br/>acme-payments"]
EA --> ORG3["Organization<br/>acme-commerce"]

ORG1 --> T1["Team: Platform"]
T1 --> T1A["Team: SRE"]
T1 --> T1B["Team: DevEx"]

ORG2 --> T2["Team: Payments"]
T2 --> T2A["Team: Checkout"]
T2 --> T2B["Team: Fraud Detection"]

ORG3 --> T3["Team: Commerce"]
T3 --> T3A["Team: Catalog"]
T3 --> T3B["Team: Cart"]

T1 --> R1["Repo: shared-actions<br/>(internal)"]
T1 --> R2["Repo: template-service<br/>(internal)"]
T2A --> R3["Repo: checkout-api<br/>(private)"]
T2B --> R4["Repo: fraud-engine<br/>(private)"]
T3A --> R5["Repo: catalog-service<br/>(private)"]

style EA fill:#2d333b,stroke:#58a6ff,color:#ffffff
style ORG1 fill:#1f6feb,stroke:#58a6ff,color:#ffffff
style ORG2 fill:#1f6feb,stroke:#58a6ff,color:#ffffff
style ORG3 fill:#1f6feb,stroke:#58a6ff,color:#ffffff
style T1 fill:#238636,stroke:#3fb950,color:#ffffff
style T2 fill:#238636,stroke:#3fb950,color:#ffffff
style T3 fill:#238636,stroke:#3fb950,color:#ffffff
style T1A fill:#2ea043,stroke:#3fb950,color:#ffffff
style T1B fill:#2ea043,stroke:#3fb950,color:#ffffff
style T2A fill:#2ea043,stroke:#3fb950,color:#ffffff
style T2B fill:#2ea043,stroke:#3fb950,color:#ffffff
style T3A fill:#2ea043,stroke:#3fb950,color:#ffffff
style T3B fill:#2ea043,stroke:#3fb950,color:#ffffff
style R1 fill:#6e40c9,stroke:#8b5cf6,color:#ffffff
style R2 fill:#6e40c9,stroke:#8b5cf6,color:#ffffff
style R3 fill:#6e40c9,stroke:#8b5cf6,color:#ffffff
style R4 fill:#6e40c9,stroke:#8b5cf6,color:#ffffff
style R5 fill:#6e40c9,stroke:#8b5cf6,color:#ffffff

Figure 7.1: Enterprise hierarchy showing the relationship between the enterprise account, organizations, teams (parent and child), and repositories with their visibility settings. Permissions flow downward: enterprise policies constrain organizations, parent team permissions are inherited by child teams, and child teams grant access to repositories.

Ruleset Enforcement Flow​

flowchart LR
DEV["Developer<br/>pushes to main"] --> RS1{"Enterprise<br/>Ruleset"}
RS1 -->|Pass| RS2{"Org<br/>Ruleset"}
RS1 -->|Fail| BLOCK1["Push Blocked"]
RS2 -->|Pass| RS3{"Repo<br/>Ruleset"}
RS2 -->|Fail| BLOCK2["Push Blocked"]
RS3 -->|Pass| MERGE["Merge<br/>Allowed"]
RS3 -->|Fail| BLOCK3["Push Blocked"]

style DEV fill:#2d333b,stroke:#58a6ff,color:#ffffff
style RS1 fill:#da3633,stroke:#f85149,color:#ffffff
style RS2 fill:#da3633,stroke:#f85149,color:#ffffff
style RS3 fill:#da3633,stroke:#f85149,color:#ffffff
style MERGE fill:#238636,stroke:#3fb950,color:#ffffff
style BLOCK1 fill:#6e40c9,stroke:#8b5cf6,color:#ffffff
style BLOCK2 fill:#6e40c9,stroke:#8b5cf6,color:#ffffff
style BLOCK3 fill:#6e40c9,stroke:#8b5cf6,color:#ffffff

Figure 7.2: Ruleset enforcement is layered. A push or merge must pass all applicable rulesets at the enterprise, organization, and repository levels. If any ruleset blocks the action, the push is rejected. This stacking model allows enterprise-wide baseline governance with organization- and repository-specific additions.


4. Summary​

Key Takeaways:

  • The GitHub Enterprise hierarchy flows from enterprise account to organizations to teams to repositories. Policies cascade downward, and each level constrains the levels below it.
  • Choose your organization structure based on your enterprise's size and regulatory needs: single organization for smaller enterprises, multiple organizations by business unit for larger or regulated enterprises, or a hybrid model with a shared platform organization.
  • Nested teams (parent/child) enable permission inheritance that mirrors your organizational structure. Keep hierarchies to two or three levels deep for manageability.
  • Repository visibility (public, internal, private) controls who can see code. Internal visibility is a key enabler of inner-source practices across enterprise organizations.
  • Repository creation policies at the enterprise level prevent sprawl. Combine with naming conventions and template repositories for consistent governance.
  • Template repositories provide pre-configured starter kits (CI/CD, linting, Copilot instructions, security scanning) so new repositories are production-ready from day one.
  • Repository rulesets replace legacy branch protection with scalable, stackable governance. Use enterprise-level rulesets for baseline policies and organization-level rulesets for division-specific requirements. Always test new rulesets in "evaluate" mode before activating.
  • Team synchronization with your IdP (Identity Provider) via SCIM ensures that GitHub team membership stays current with your corporate directory, eliminating manual access management.

What's Next: See Chapter 8: Access Control & Permissions Model for a deep dive into GitHub's five permission levels (read, triage, write, maintain, admin), custom repository roles, and how to design a least-privilege access model that builds on the organization and team structure established in this chapter.


5. Hands-On Assignment​

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

  • A working GitHub Enterprise Cloud environment (Chapter 1: Enterprise Subscription & Environment Setup)
  • At least one organization created under your enterprise account

Lab: Design and Build a Multi-Team Organization with Templates and Rulesets​

Objective: Create a GitHub organization with a nested team hierarchy, configure repository visibility policies, set up a template repository, and apply a repository ruleset -- simulating the organizational structure of a 100-developer enterprise.

Prerequisites:

  • A GitHub Enterprise Cloud trial or paid enterprise account (see Chapter 1: Enterprise Subscription & Environment Setup)
  • Organization owner permissions on at least one organization
  • GitHub CLI (gh) installed and authenticated (version 2.40 or later)
  • A terminal with bash or powershell available

Assignment:

  1. Create two teams in your organization: a parent team called engineering and a child team called engineering-frontend. Set the parent team's visibility to "visible" and the child team's visibility to "visible".
  2. Create a template repository called template-microservice that includes a README.md, a .github/pull_request_template.md, a basic .github/workflows/ci.yml GitHub Actions workflow, and a .github/copilot-instructions.md file with at least three coding guidelines.
  3. Create a new repository from the template called frontend-web-app. Set its visibility to "private". Add the engineering-frontend team with write access.
  4. Create an organization-level repository ruleset called protect-main that requires pull requests with at least 1 approving review before merging to the main branch. Apply it to all repositories in the organization. Set the initial enforcement to "evaluate" mode.
  5. Verify that the ruleset is active in evaluate mode and that the engineering-frontend team has inherited read access from the engineering parent team (after you grant the parent team read access to the frontend-web-app repository).

Expected Outcome: You should have an organization with a two-level team hierarchy, a template repository, a repository created from that template with proper team access, and an organization-level ruleset in evaluate mode.

Validation:

  • Running gh api orgs/<org>/teams --jq '.[].slug' shows both engineering and engineering-frontend
  • The template-microservice repository is marked as a template in its settings
  • The frontend-web-app repository was created from the template (visible in the repository header on GitHub)
  • Running gh api orgs/<org>/rulesets --jq '.[].name' shows protect-main
  • The engineering-frontend team shows write access to frontend-web-app and inherits read from engineering

6. Step-by-Step Walkthrough​

This section provides a guided solution for the hands-on assignment above. If you completed the assignment independently, you can skip this section or use it to verify your approach.

Step 1: Authenticate and Set Your Organization Name​

First, confirm that your GitHub CLI is authenticated and set a variable for your organization name to use throughout the lab.

# Verify authentication
gh auth status

# Set your organization name (replace with your actual org)
ORG="your-org-name"

Expected output (for gh auth status):

github.com
Logged in to github.com account your-username (keyring)
Active account: true
Git operations protocol: https
Token: gho_****
Token scopes: admin:org, repo, ...

Step 2: Create the Parent Team​

Create the engineering parent team with visible visibility.

# Create the parent team
gh api orgs/$ORG/teams \
--method POST \
--field name="engineering" \
--field description="Engineering department - all engineering squads" \
--field privacy="closed"

Note: In the GitHub API, "closed" means visible to all organization members, and "secret" means visible only to team members and org owners.

Expected output:

{
"name": "engineering",
"id": 12345678,
"slug": "engineering",
"privacy": "closed",
...
}

Step 3: Create the Child Team​

Create the engineering-frontend child team nested under engineering.

# Get the parent team ID
PARENT_ID=$(gh api orgs/$ORG/teams/engineering --jq '.id')

# Create the child team
gh api orgs/$ORG/teams \
--method POST \
--field name="engineering-frontend" \
--field description="Frontend engineering squad" \
--field privacy="closed" \
--field parent_team_id=$PARENT_ID

Expected output:

{
"name": "engineering-frontend",
"slug": "engineering-frontend",
"parent": {
"name": "engineering",
"slug": "engineering"
},
...
}

If using PowerShell:

# PowerShell equivalent
$PARENT_ID = gh api orgs/$env:ORG/teams/engineering --jq '.id'

gh api orgs/$env:ORG/teams `
--method POST `
--field name="engineering-frontend" `
--field description="Frontend engineering squad" `
--field privacy="closed" `
--field parent_team_id=$PARENT_ID

Step 4: Create the Template Repository​

Create a repository and configure it as a template.

# Create the repository
gh repo create $ORG/template-microservice \
--private \
--description "Microservice template with CI/CD and Copilot instructions" \
--clone

# Navigate into the repo
cd template-microservice

Now create the required files:

# Create directory structure
mkdir -p .github/workflows
mkdir -p src
mkdir -p tests

Create the README.md:

cat > README.md << 'EOF'
# Microservice Template

This repository is a template for creating new microservices. It includes:

- CI/CD pipeline via GitHub Actions
- Pull request template
- Copilot coding instructions
- Standard directory structure

## Getting Started

1. Create a new repository from this template
2. Update this README with your service details
3. Begin developing in the `src/` directory

## Structure

src/ - Application source code tests/ - Test files .github/ - GitHub configuration (workflows, templates, Copilot instructions)

EOF

Create the pull request template:

cat > .github/pull_request_template.md << 'EOF'
## Description
<!-- Describe your changes -->

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing
- [ ] Unit tests pass
- [ ] Integration tests pass (if applicable)

## Checklist
- [ ] Code follows project coding standards
- [ ] Self-review completed
- [ ] Documentation updated (if applicable)
EOF

Create the CI workflow:

cat > .github/workflows/ci.yml << 'EOF'
name: CI

on:
push:
branches: [main]
pull_request:
branches: [main]

jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run tests
run: echo "Add your test commands here"
- name: Lint
run: echo "Add your lint commands here"
EOF

Create the Copilot instructions:

cat > .github/copilot-instructions.md << 'EOF'
# Copilot Instructions for This Repository

1. Follow the project's established coding style. Use consistent naming
conventions: camelCase for variables and functions, PascalCase for
classes and interfaces.
2. Always include error handling. Never swallow exceptions silently.
Log errors with contextual information (function name, input parameters)
before re-throwing or returning error responses.
3. Write unit tests for all new functions. Each test should follow the
Arrange-Act-Assert pattern. Aim for at least 80% code coverage on
new code.
4. Use environment variables for all configuration values. Never hardcode
secrets, API endpoints, or environment-specific values.
5. Keep functions small and focused. A function should do one thing. If
a function exceeds 30 lines, consider extracting helper functions.
EOF

Commit and push the template files:

git add -A
git commit -m "Initial template structure with CI, PR template, and Copilot instructions"
git push origin main

Now mark the repository as a template:

# Enable the template flag via the API
gh api repos/$ORG/template-microservice \
--method PATCH \
--field is_template=true

Expected output (partial):

{
"name": "template-microservice",
"is_template": true,
...
}

Step 5: Create a Repository from the Template​

# Create a new repo from the template
gh api repos/$ORG/template-microservice/generate \
--method POST \
--field owner="$ORG" \
--field name="frontend-web-app" \
--field description="Frontend web application" \
--field private=true

Expected output (partial):

{
"name": "frontend-web-app",
"private": true,
"template_repository": {
"name": "template-microservice"
},
...
}

Step 6: Grant Team Access to the Repository​

Grant the engineering parent team read access and the engineering-frontend child team write access.

# Grant parent team read access
gh api orgs/$ORG/teams/engineering/repos/$ORG/frontend-web-app \
--method PUT \
--field permission="pull"

# Grant child team write access
gh api orgs/$ORG/teams/engineering-frontend/repos/$ORG/frontend-web-app \
--method PUT \
--field permission="push"

Note: In the API, pull = read, push = write, admin = admin, maintain = maintain, triage = triage.

Step 7: Create an Organization-Level Ruleset​

Create a ruleset that requires pull requests with at least 1 approval for the main branch, applied to all repositories, in evaluate mode.

# Create the ruleset
gh api orgs/$ORG/rulesets \
--method POST \
--input - << 'EOF'
{
"name": "protect-main",
"target": "branch",
"enforcement": "evaluate",
"conditions": {
"ref_name": {
"include": ["refs/heads/main"],
"exclude": []
},
"repository_name": {
"include": ["~ALL"],
"exclude": []
}
},
"rules": [
{
"type": "pull_request",
"parameters": {
"required_approving_review_count": 1,
"dismiss_stale_reviews_on_push": true,
"require_code_owner_review": false,
"require_last_push_approval": false,
"required_review_thread_resolution": true
}
}
]
}
EOF

Expected output (partial):

{
"id": 98765,
"name": "protect-main",
"enforcement": "evaluate",
"target": "branch",
...
}

Verification​

Run the following commands to verify your setup:

# Verify teams exist
echo "=== Teams ==="
gh api orgs/$ORG/teams --jq '.[].slug'

# Verify team hierarchy
echo "=== Frontend team parent ==="
gh api orgs/$ORG/teams/engineering-frontend --jq '.parent.slug'

# Verify template repository
echo "=== Template flag ==="
gh api repos/$ORG/template-microservice --jq '.is_template'

# Verify frontend-web-app was created from template
echo "=== Template source ==="
gh api repos/$ORG/frontend-web-app --jq '.template_repository.name'

# Verify rulesets
echo "=== Rulesets ==="
gh api orgs/$ORG/rulesets --jq '.[] | "\(.name) - enforcement: \(.enforcement)"'

# Verify team access on the repository
echo "=== Team access ==="
gh api repos/$ORG/frontend-web-app/teams --jq '.[] | "\(.slug): \(.permission)"'

Expected output:

=== Teams ===
engineering
engineering-frontend
=== Frontend team parent ===
engineering
=== Template flag ===
true
=== Template source ===
template-microservice
=== Rulesets ===
protect-main - enforcement: evaluate
=== Team access ===
engineering: pull
engineering-frontend: push

7. Q&A -- Chapter Review​

Instructions: Select the best answer for each question. Answers and explanations follow after all questions.

Question 1​

A GitHub Enterprise Cloud customer has four organizations. They want all developers to be able to browse shared libraries without being added to the organization that hosts them. Which repository visibility setting should they use for the shared library repositories?

  • A) Public
  • B) Internal
  • C) Private with outside collaborators
  • D) Private with cross-organization teams

Question 2​

An organization has a parent team called platform with write access to a repository called infra-modules. A child team called platform-sre is created under platform. What repository access does platform-sre have to infra-modules without any additional configuration?

  • A) No access -- child teams do not inherit permissions
  • B) Read access only
  • C) Write access -- inherited from the parent team
  • D) Admin access -- child teams receive elevated permissions

Question 3​

An enterprise owner wants to prevent all organizations from creating public repositories. Where should this policy be configured?

  • A) In each organization's settings under "Member privileges"
  • B) In the enterprise account settings under "Policies > Repositories"
  • C) In a repository ruleset applied to all organizations
  • D) In the SAML SSO configuration for each organization

Question 4​

A team is set to "secret" visibility. Which of the following statements is true?

  • A) Only organization owners can add members to the team
  • B) The team's repositories are automatically set to private
  • C) Only team members and organization owners can see the team
  • D) The team cannot be assigned repository permissions

Question 5​

Which of the following is an advantage of repository rulesets over legacy branch protection rules?

  • A) Rulesets can only be managed by repository administrators
  • B) Rulesets can target multiple repositories from the organization level
  • C) Rulesets do not support required status checks
  • D) Rulesets replace the need for CODEOWNERS files entirely

Question 6​

A developer creates a new repository from a template repository. Which of the following is true about the new repository?

  • A) It maintains a fork relationship with the template and receives upstream updates
  • B) It contains the template's files but has no commit history link to the template
  • C) It automatically inherits the template's team permissions
  • D) It must be in the same organization as the template repository

Question 7​

An enterprise uses SCIM provisioning with Microsoft Entra ID. A developer is removed from the Entra ID group GH-Engineering-Backend. What happens to their GitHub team membership?

  • A) Nothing -- SCIM does not manage team membership
  • B) They are removed from the engineering-backend GitHub team automatically
  • C) Their GitHub account is suspended enterprise-wide
  • D) They retain team membership but lose SSO access

Question 8​

An organization has the following rulesets applied to the main branch: an enterprise-level ruleset requiring 1 approval, and an organization-level ruleset requiring 2 approvals and signed commits. How many approvals are required to merge a pull request to main?

  • A) 1 approval (enterprise ruleset takes precedence)
  • B) 2 approvals (organization ruleset takes precedence)
  • C) 2 approvals (all rulesets must pass; the strictest requirement applies)
  • D) 3 approvals (requirements are additive: 1 + 2)

Question 9​

Which repository naming convention best supports automated tooling and developer discoverability in a 200-developer enterprise?

  • A) Sequential numbering: repo-001, repo-002, repo-003
  • B) Structured convention: <team>-<project>-<component>
  • C) Free-form names chosen by the creating developer
  • D) UUIDs generated automatically: a1b2c3d4-service

Question 10​

An organization owner wants to test a new ruleset that requires signed commits before enforcing it. Which enforcement mode should they use?

  • A) Active -- the ruleset is enforced immediately
  • B) Evaluate -- the ruleset logs violations but does not block actions
  • C) Disabled -- the ruleset is stored but has no effect
  • D) Warn -- the ruleset shows warnings in pull requests but allows merges

Answer Key​

QAnswerExplanation
1BInternal visibility makes repositories visible to all members of the enterprise account, across all organizations, without requiring individual access grants. This is the intended use case for inner-source shared libraries. Public would expose code to the internet, and private would require explicit access management.
2CChild teams inherit all repository permissions from their parent team. Since the parent team has write access, the child team automatically inherits write access without additional configuration.
3BEnterprise-wide repository visibility restrictions are configured in the enterprise account settings under Policies > Repositories. This setting overrides organization-level configurations, ensuring no organization can create public repositories.
4CSecret teams are visible only to team members and organization owners. They can still be assigned repository permissions and function normally for access control -- they are simply hidden from other organization members.
5BRepository rulesets can be managed at the organization level and target multiple repositories using name patterns. This is a major advantage over legacy branch protection rules, which are configured per-repository by repository administrators.
6BCreating a repository from a template copies the template's files into a new repository with a fresh commit history. There is no ongoing fork relationship or automatic upstream synchronization. Team permissions and organization placement are independent of the template.
7BWhen SCIM team synchronization is configured, removing a user from the IdP group that is mapped to a GitHub team automatically removes them from that GitHub team. This keeps team membership in sync with the corporate directory.
8CRepository rulesets are stackable -- all applicable rulesets must pass. The enterprise ruleset requires 1 approval and the organization ruleset requires 2 approvals. Since the merge must satisfy both, the effective requirement is 2 approvals (the stricter rule) plus signed commits. Requirements are not additive (1+2=3); rather, each ruleset independently evaluates and the action must pass all of them.
9BA structured naming convention like <team>-<project>-<component> enables developers to find repositories by browsing predictable names and allows automation scripts to target repositories by pattern. Sequential numbers and UUIDs are not human-readable, and free-form names lead to inconsistency at scale.
10BThe "evaluate" enforcement mode logs ruleset violations in the audit log and shows them in the UI but does not block any actions. This allows organization owners to assess the impact of a new ruleset before switching it to "active" enforcement. There is no "warn" mode in GitHub rulesets.