Getting Started: Enterprises, Organizations, Repositories, and Teams

The following provides an overview and some basic best practices for getting started with GitHub Enterprise, Organizations, Repos, and Teams.

Enterprise

The enterprise account provides a single point of visibility, management, and enforcement of policies and settings for your company's GitHub account.

What's in an Enterprise Account?

Organizations
Policies and Settings for all organizations
Security insights for customers using Advanced Security
GitHub Connect (connects Server instances to Cloud instances for customers using GitHub Enterprise Server in addition to GitHub Enterprise Cloud)
Audit Log
GitHub Compliance documentation

Best Practices

Set up Audit Log streaming to a SIEM.
- The GitHub Audit Log allows you to view user activity, including Git activity.
- With Audit Log Streaming, you can:
  - track user activity over time.
  - retain your audit log beyond the 3-6 months it is available from GitHub.
  - set alerts for certain activities.
- To view the Enterprise Audit Log and set up streaming, go to:
  - Enterprise → Settings (left sidebar) → Audit Log → Events/Log Streaming (tabs under the Audit Log heading)
- GitHub Docs:
  - Streaming Audit Log
  - Setting Up Audit Log Streaming & Supported SIEMs
Configure settings and policies that cannot or should not be configured by org owners.
- Some policies must be configured at the enterprise level.
  - Examples:
    - Actions Workflow Permissions (Note: these default to Read on the enterprise).
    - Copilot Access Permissions (Note: Copilot licenses are assigned at the org level, but org level access must be granted at the enterprise level).
- To configure Settings and Policies, go to:
  - Enterprise → Policies or Settings (left sidebar)
- GitHub Docs:
  - Setting Policies for Your Enterprise

Organizations

Enterprises can have one or more organizations.
Each organization can have a distinct set of members.
Each organization has it's own repositories.
What's in an Organization?
- Repositories
- Copilot access
- Projects
- Packages
- Discussions
- Teams
- Security & org level insights
- Audit Log
Note: Distinct organizations are NOT needed to limit repository access. Repository access can be limited via base user permissions and Teams.

Best Practices

Start with only ONE organization.
- Why start with only one organization?
  - Individual organizations are intended for users who work together, i.e., whole engineering teams and their cross functional counterparts.
  - Access to and permissions on repositories are managed with base member permissions and GitHub Teams, so in many cases a company will only need one organization.
  - SCIM is only available at the organization level.
    
    Using SCIM across multiple organizations requires unique SSO & SCIM configurations on each organization, so having only one organization simplifies setup.
- When does it make sense to create more than one organization?
  - Two main use cases:
    
    Companies with distinct business entitities who's engineering teams operate indepently.
    
    Example:
    
    Company A acquires Company B.
    
    Each company has a unique product line and different engineerint teams.
    
    The engineering teams rarely interact or work together on the same project.
    
    Deploys are separate.
    
    Companies with divisions/departments that operate independently.
    
    Example:
    
    Company A has an engineering team that works on their primary product.
    
    They also have an R&D team that works on highly sensitive code.
    
    The two teams rarely interact or work together on the same project.
    
    None of the R&D conversations in PRs, Issues, or Discussions need to be visible to the engineering team working on the primary product.
  - Note: For Enterprises with multiple organizations, if the organizations need to collaborate on projects (for example share internal tooling), this can be done using Internal Repositories.
- To create an organization, go to:
  - Enterprise → Organizations (left sidebar) → New organization (button upper right)
- GitHub Docs:
  - Creating a New Organization
Set base user permissions to Read.
- Why set permissions to Read?
  - Providing Read access to your repositories facilitates learning and development and cross team collaboration.
    
    Developers tend to be curious and learn from each other. Fostering this curiousity and learning leads to a stronger dev team, with multiple devs capable of taking on and troubleshooting different types of projects.
- When should base user permissions be set to No Permissions.
  - If your organization includes some repositories with particularly sensitive code that should not be viewed by all devs, you can set the base permissions to No Permissions. This will ensure that no one has read access to some repositories unless explicitly granted that access.
    
    Example: repos that contains proprietary encryption algorithms.
  - To set base user permissions, go to:
    - Enterprise → Settings → Repositories (landing page) → Base Permissions (top of the page) OR
    - Organization → Settings → Member Permissions (left sidebar) → Base Permissions (top of the page)
  - GitHub Docs:
    - Setting Base User Permissions on an Organization

Repositories

Organizations can have a few to a few thousand repositories.
Repositories are where your developers (and, in many cases, cross functional peers) collaborate.
Three Types of Repositories
- Private - only accessible to members of the org.
- Internal - accessible to members of all orgs (used for innersource).
- Public - can be read or forked by anyone on the internet.
Repositories can be categorized for easy filtering.
Repository access is managed via GitHub Teams.
Rulesets control how users interact with repository branches and tags.
What's in a Repository (Code! but there's more 🙂)?
- Code
- Markdown
- Pull Requests
- Issues & Projects (project management)
- Wikis
- Actions (CI/CD)
- GitHub Advanced Security tooling
- Repo insights

Best Practices

Create Rulesets for your production branches and/or release tags.
- Rulesets protect your branches and tags from unexpected changes.
- Example rules:
  - Require pull requests before code is merged to a production branch.
  - Require Codeowner review.
  - Prevent deletions.
- Create rulesets for other branches (e.g., staging or QA branches).
- To create Rulesets, go to:
  - Organization → Settings (tab at the top) → Repositories (left sidebar) → Rulesets OR
  - Repository → Settings (tab at the top) → Rules (left sidebar) → Rulesets
- GitHub Docs:
Use Custom Properties to organize your repositories.
- Many companies have hundred or thousands of repositories that contain things like monorepos, microservices, internal tooling, documentation, client libraries, backfill scripts, and forks of open source tools.
- Finding specific repositories can become unwieldy, and it's not always feasible to implement strict naming conventions for repositories.
- Categorizing repositories makes it much easier to find and manage reposotiries over time.
- Custom properties are the best way to categorize repositories in GitHub.
- Examples: Use custom properities on repositories to identify
  - repos that contain internal tooling and the type of tooling.
  - microservices for particular projects or product lines.
  - people or dev teams repsonsible for monitoring deploys.
  - people or dev teams responsible for monintoring security alerts.
- To create Custom Properties, go to:
  - Organization → Settings (tab at the top) → Repositories (left sidebar) → Custom Properties → New property (button top right)
- To assign Custom Properties, go to:
  - Repository → Settings (tab at the top) → Custom Properties (left sidebar)
- GitHub Docs:
Pin important repositories on the org landing page for easy access.
- Many companies have repos that are very active. Pin these repos to the organization landing page so that everyone, especially new developers, can find them easily.
- To pin repositories, go to:
  - Organization (landing page) → View as (right sidebar) → Member → Pin Repositories (blue link)
- GitHub Docs:
  - Customizing Your Organization's Profile
  - Pinning Repositories to Your Profile

Teams

Teams are groups of organization members.
Teams are used grant/control repository and organization access permissions.
Teams are used for communication within GitHub (e.g., notifying a team that a particular PR needs attention).
What's in a Team?
- Members
- Repository access controls
- Project access controls
- Organization role controls

Best Practices

Organize members into teams that reflect your company's internal structure.
- Teams are used for managing repository access, but they are also used for communication and can be used to filter repositories and security alerts (for customers using Advanced Security).
- Given this, it is important to set up teams that reflect your company or engineering team's structure.
- Note: In addition to teams that reflect your comapny structure, you can also create teams that grant permissions only.
  - Example:
    - Your company's engineering organization has a dev team called, "DevTeam1," that includes a team lead, four develoeprs, a QA engineer, and a scrum leader.
    - The team lead should have admin permissions on three repository, but everyone else should only have read or write permissions on those repositories.
    - Create a GitHub team for DevTeam1 that can be used for communication. Assign repos and give the team Read access.
    - Create another GitHub team for the developers on DevTeam1. Assign repos and give the devs Write access.
    - Finally, create one more GitHub team for the team lead. Assign repos and give the team lead Admin access. (Alternatively, give the team lead admin access individually, via the People tab).
- Note: Teams can be synced to IdP groups.
- To create teams, go to:
  - Organization → Teams → New team (button to the right)
- GitHub Docs:

For more best practices, please talk to your GitHub Rep or Solutions Engineer.