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
| Domain | Topics 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:
- Enterprise account -- The top-level container. It owns billing, identity configuration (SAML/SCIM), and enterprise-wide policies. An enterprise has one or more organizations.
- 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.
- 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.
- 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, andacme-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:
-
Permission inheritance: Child teams automatically inherit the repository access permissions of their parent team. If the parent team has
writeaccess to a repository, all child teams also havewriteaccess. A child team can be granted additional permissions beyond what the parent provides, but cannot have permissions removed that the parent grants. -
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. -
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.
-
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 theGH-Engineering-FrontendEntra 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:
| Visibility | Who Can See It | Use Case |
|---|---|---|
| Public | Anyone on the internet | Open-source projects, public documentation, community-facing tools |
| Internal | All members of the enterprise (across all organizations) | Shared libraries, internal documentation, reusable templates that any employee should access |
| Private | Only 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:
- Repository rulesets with name patterns (covered later in this section)
- GitHub Apps or Actions that validate repository names on creation and flag non-compliant names
- Template repositories that pre-populate the correct naming structure
- Documentation and onboarding training that establishes naming standards
A common enterprise naming convention:
<org>/<team>-<project>-<component>
Examples:
acme-platform/devex-github-actions-libraryacme-claims/claims-api-serviceacme-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, andREADME.mdfiles - 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, andtemplate-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:
| Feature | Branch Protection Rules | Repository Rulesets |
|---|---|---|
| Scope | Single repository, single branch pattern | Multiple repositories via targeting |
| Management level | Repository admin | Organization or enterprise owner |
| Stacking | One rule set per branch pattern | Multiple rulesets can apply; all must pass |
| Bypass actors | Specific users | Roles, teams, apps, or deploy keys |
| Status | Active only | Active, evaluate (dry-run), or disabled |
Ruleset components:
- Targets: Which repositories and branches/tags the ruleset applies to. Targets can use patterns (e.g., all repositories matching
*-api-*, all branches matchingrelease/*). - 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)
- 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.
- 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 toolsacme-payments-- payments product divisionacme-commerce-- e-commerce product divisionacme-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
securitysecret team in each organization for AppSec engineers
- Repository visibility:
acme-platformrepositories default tointernal(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
mainbranch across all repos - Organization-level ruleset in
acme-payments: Require 2 approvals and signed commits (PCI DSS compliance)
- Enterprise-level ruleset: Require PR with 1 approval for
- 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
bashorpowershellavailable
Assignment:
- Create two teams in your organization: a parent team called
engineeringand a child team calledengineering-frontend. Set the parent team's visibility to "visible" and the child team's visibility to "visible". - Create a template repository called
template-microservicethat includes aREADME.md, a.github/pull_request_template.md, a basic.github/workflows/ci.ymlGitHub Actions workflow, and a.github/copilot-instructions.mdfile with at least three coding guidelines. - Create a new repository from the template called
frontend-web-app. Set its visibility to "private". Add theengineering-frontendteam withwriteaccess. - Create an organization-level repository ruleset called
protect-mainthat requires pull requests with at least 1 approving review before merging to themainbranch. Apply it to all repositories in the organization. Set the initial enforcement to "evaluate" mode. - Verify that the ruleset is active in evaluate mode and that the
engineering-frontendteam has inheritedreadaccess from theengineeringparent team (after you grant the parent teamreadaccess to thefrontend-web-apprepository).
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 bothengineeringandengineering-frontend - The
template-microservicerepository is marked as a template in its settings - The
frontend-web-apprepository was created from the template (visible in the repository header on GitHub) - Running
gh api orgs/<org>/rulesets --jq '.[].name'showsprotect-main - The
engineering-frontendteam showswriteaccess tofrontend-web-appand inheritsreadfromengineering
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-backendGitHub 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
| Q | Answer | Explanation |
|---|---|---|
| 1 | B | Internal 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. |
| 2 | C | Child 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. |
| 3 | B | Enterprise-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. |
| 4 | C | Secret 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. |
| 5 | B | Repository 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. |
| 6 | B | Creating 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. |
| 7 | B | When 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. |
| 8 | C | Repository 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. |
| 9 | B | A 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. |
| 10 | B | The "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. |