GitHub Setup Checklist for Teams (2026)

0 of 41 completed

0%

Organization Setup

The organization is the top-level container. Get the base settings right so every repo inherits sensible defaults.

Set organization base permissions to Readcritical

Go to Organization Settings → Member Privileges → Base permissions → Read. This means all org members can see all repos but cannot push without explicit repo-level permissions. Never set this to Write or Admin.

Assign at least two Owner-role userscritical

If your only Owner leaves or loses access, you are locked out of your organization. Always maintain a minimum of two Owners. Avoid making everyone an Owner.

Require two-factor authentication for all memberscritical

Organization Settings → Authentication security → Require two-factor authentication. Members who haven't set up 2FA will be removed from the org until they do. Do this before inviting the full team.

Restrict who can create repositoriesimportant

Organization Settings → Member Privileges → Repository creation. Set to Members can create private repositories only (or Admins only). Prevents uncontrolled repository sprawl.

Disable forking of private repositoriesimportant

Organization Settings → Member Privileges → Disable Allow forking of private repositories. Prevents code from being copied outside your org's control. Enable only when specifically needed.

Set GITHUB_TOKEN default permissions to read-onlyimportant

Organization Settings → Actions → General → Workflow permissions → Read repository contents and packages permissions. Grants write access explicitly per workflow where needed. Least-privilege by default.

Teams and Permissions

Manage access through teams, not individual users. When someone leaves, you remove them from one team — not from every repo.

Create teams that mirror your actual team structurecritical

Create named teams like team-backend, team-frontend, team-devops, team-security. Assign teams to repositories instead of individual users. Teams survive personnel changes.

Assign the correct permission level to each team per repocritical

Use Read (non-contributors), Triage (PMs, QA leads who manage issues), Write (developers), Maintain (tech leads — can edit settings but not delete), Admin (repo owners only). Never give Admin to everyone.

Use nested teams for inherited permissionsimportant

Create a parent team (e.g., engineering) with broad safe permissions, then child teams (team-backend, team-frontend) with specific repo access. Child teams inherit from parents.

Sync teams to your identity provider if availablenice-to-have

If you use Okta, Azure AD, or another SAML IdP with GitHub Enterprise, sync team membership automatically. When someone changes roles or leaves, their GitHub access updates without manual intervention.

Audit team membership quarterlyimportant

Remove engineers who have left, update roles when people switch teams. Old access lingers invisibly and becomes a security risk.

Repository Settings

Configure each repository consistently. These settings control how code gets merged and how branches are cleaned up.

Configure merge button settingscritical

Repository Settings → General → Pull Requests. Enable Squash merging (recommended for clean history). Set default commit message to Pull request title and description. Optionally disable regular merge commits to enforce squash-only policy.

Enable automatic deletion of head branchescritical

Repository Settings → General → Automatically delete head branches. After a PR is merged, the feature branch is deleted automatically. Prevents branches accumulating for months.

Set repository visibility correctlycritical

Private for all internal code, Internal (Enterprise) to share within the org without making it public, Public only for actual open source. Don't leave repositories public by accident.

Restrict Actions permissions to necessary repos onlyimportant

Repository Settings → Actions → General → Allow select actions and reusable workflows. Whitelist trusted actions rather than allowing all. Prevents supply-chain attacks via malicious GitHub Actions.

Branch Protection and Rulesets

Protect your main branch from direct pushes, force pushes, and unreviewed merges. This is the single most important thing you can configure.

Create a Ruleset for your main branch (preferred over classic branch protection)critical

Repository Settings → Rules → New ruleset. Rulesets are the modern GitHub approach (2024+), support multiple rules simultaneously, have Evaluate mode for safe rollout, and are visible to all team members. Target branch: main or master.

Require a pull request before merging — minimum 1 reviewercritical

In your ruleset or branch protection: Require a pull request before merging → Require approvals: 1 (or 2 for critical repos). Dismiss stale reviews when new commits are pushed. Nobody merges their own code without review.

Require status checks to pass before mergingcritical

Select the specific CI check names from your GitHub Actions workflows (e.g., 'CI / test', 'CI / lint'). Enable Require branches to be up to date before merging (strict mode) to ensure checks run against the latest main.

Block force pushes and branch deletioncritical

Enable Restrict deletions and Block force pushes. Force pushing rewrites git history and can destroy teammates' work. Block both on main and any long-lived branches.

Require conversation resolution before mergingimportant

No PR can be merged while there are unresolved review comments. Forces all reviewer feedback to be explicitly addressed or dismissed before the code ships.

Require review from Code Owners when CODEOWNERS is presentimportant

Enables automatic routing of reviews to the right team. A PR touching /services/payments/ automatically requires a review from the team that owns that directory.

Enable Do not allow bypassing the above settingsimportant

By default, repository administrators can bypass branch protection. Turning this off means even Admins must follow the rules. Essential for compliance and preventing shortcuts.

CODEOWNERS File

Define who automatically reviews code in each part of the codebase. One file that routes reviews correctly for every PR.

Create a .github/CODEOWNERS filecritical

GitHub checks .github/CODEOWNERS first, then CODEOWNERS in root, then docs/CODEOWNERS. Use team references (@your-org/team-name) not individual usernames — teams survive when people leave.

Set a global fallback owner for uncovered filesimportant

Add * @your-org/team-platform at the top of CODEOWNERS as a catch-all. Any file without a more specific owner falls back to this team.

Define owners for key directoriescritical

Example: /services/ @your-org/team-backend, /src/frontend/ @your-org/team-frontend, /terraform/ @your-org/team-devops, **/migrations/ @your-org/team-dba. Last matching rule in the file wins.

Verify all referenced teams have write accessimportant

Teams listed in CODEOWNERS must have at least Write permission on the repository. If they have Read-only, they cannot approve the PR. GitHub will silently ignore missing permissions.

Enable Require review from Code Owners in branch protectionimportant

CODEOWNERS auto-assigns reviewers but doesn't enforce them unless this branch protection setting is on. Without it, the review request is a suggestion, not a requirement.

GitHub Actions — CI/CD

Automate testing, linting, and deployments. Required checks must pass before any PR can merge.

Create a CI workflow that runs on every pull requestcritical

Use trigger: pull_request with types: [opened, synchronize, reopened] targeting your main branch. Run lint and tests as separate jobs so failures are clearly identified.

Register CI job names as required status checkscritical

Job names in your workflow file become status check names in the format 'Workflow Name / job-name'. Go to branch protection → Require status checks and search for your job names. They must have run at least once to appear.

Add a Dependabot configuration fileimportant

Commit a .github/dependabot.yml file. Set package-ecosystem to npm (or your language), directory to /, and schedule interval to weekly. Keeps dependencies automatically updated with auto-PRs.

Pin third-party Actions to commit SHAsimportant

Instead of uses: actions/checkout@v4, use uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683. Pinning to a SHA prevents a supply-chain attack where a tag is silently updated to malicious code.

Configure deployment environments with protection rulesimportant

Repository Settings → Environments. Create staging and production environments. For production: add Required reviewers (1-2 leads), restrict deployment branches to main only, set a Wait timer of 10-30 minutes.

Use GitHub Apps for integrations instead of Personal Access Tokensnice-to-have

GitHub Apps use short-lived tokens (1 hour), have fine-grained permissions, and survive when team members leave. Classic PATs are tied to a person — if they leave, the integration breaks.

Security Features

Enable GitHub's built-in security scanning. Most features are free for public repos and available on paid plans for private repos.

Enable Dependabot alerts and security updatescritical

Repository Settings → Advanced Security → Enable Dependabot alerts, then Enable Dependabot security updates. You'll receive PRs automatically when a dependency has a known vulnerability.

Enable secret scanning and push protectioncritical

Repository Settings → Advanced Security → Enable secret scanning. Then enable Push protection to block commits that contain secrets before they are pushed. Catches accidental API key commits.

Set up CodeQL code scanningimportant

Repository Settings → Code Security → Set up → Default. GitHub auto-configures CodeQL for your language. Scans run on PRs and report security vulnerabilities as check results. Free for public repos.

Create a SECURITY.md security policy filenice-to-have

Add a SECURITY.md file to the root (or .github/) describing your responsible disclosure process and who to contact for security issues. GitHub shows it in the Security tab.

Git Reporting — Connect Gitmore

Once your repositories are set up, connect Gitmore to start receiving automated daily and weekly reports on your team's activity across all repos.

Connect all GitHub repositories to Gitmorecritical

Go to app.gitmore.io → Add Integration → Authenticate with GitHub. Connect all active repositories — including infrastructure and config repos. Gitmore uses webhooks and never accesses your source code.

Configure your Slack channel for automated daily reportscritical

Create a dedicated #engineering-reports Slack channel. Set up daily summaries delivered each morning so your team starts the day with visibility into yesterday's commits, PRs merged, and open reviews.

Set up weekly rollup reports for stakeholdersimportant

Configure weekly reports delivered to your manager, PM, or stakeholders. Gitmore's AI summarises commits and PRs into plain English — no git knowledge required to understand the update.

Use Gitmind to ask questions about your team's activitynice-to-have

Gitmind is Gitmore's AI chat agent. Ask questions like 'What did the backend team ship this week?' or 'Which PRs are still waiting for review?' directly in Slack or the dashboard.

Pro Tips

Expert advice

1

Roll out branch protection using GitHub's Evaluate mode first. It shows you who would be blocked without actually blocking anyone. Run it for one week, fix legitimate bypasses, then switch to Active enforcement.

2

The single highest-impact change you can make to an existing GitHub org is enabling 'Do not allow bypassing branch protection' for admins. Most teams skip this. It's the one setting that prevents engineers (and yourself) from taking shortcuts under pressure.

3

Use teams instead of individuals everywhere — CODEOWNERS, branch protection bypass lists, environment required reviewers. A team with one member is still better than an individual username because the team survives offboarding.

4

Require status checks from your CI before merge, but also check the 'Require branches to be up to date' box. Without it, two PRs can each pass CI individually but break main when both merge — this is the classic 'green CI but broken main' problem.

5

After setting up Gitmore, send your first weekly report to your team and ask them to review it. The first week's report reveals which repos are missing, which developers are committing under unexpected email addresses, and whether your branch naming is consistent enough to track.

FAQ

Common questions

What is the difference between GitHub branch protection rules and Rulesets?

Classic branch protection rules (the original feature) allow only one rule per branch and are less visible to team members. Rulesets (introduced in 2023, now the recommended approach) allow multiple rules to apply simultaneously, support an Evaluate mode for safe rollout, are visible to all team members, and can be applied at the organization level across many repos at once. For new setups, use Rulesets. For existing setups, migrate gradually.

Should I require 1 or 2 PR approvals before merge?

For most teams, 1 required approval is the right default. It catches mistakes without slowing delivery. Require 2 approvals for critical repositories with security implications, compliance requirements, or code that directly handles payments or user data. More than 2 approvals adds friction without meaningful safety improvement for most teams.

How does CODEOWNERS work with branch protection?

CODEOWNERS automatically requests reviews from the relevant team when a PR touches files they own. However, by itself it does not block merging. To make those reviews mandatory, you must also enable 'Require review from Code Owners' in your branch protection rules or Rulesets. Without that setting, the review request is a suggestion only.

Should I use PATs or GitHub Apps for CI/CD integrations?

Use GitHub Apps for all team-level integrations. GitHub Apps have fine-grained permissions, generate short-lived tokens (valid 1 hour), and remain installed even when the user who created them leaves the team. Classic PATs are tied to a personal account — if that person leaves or deactivates their account, the integration silently breaks. Fine-grained PATs are acceptable for personal scripts but not for team tooling.

How do I track what my team is shipping across all these GitHub repositories?

GitHub's built-in Insights are limited to single-repo views and require navigating each repo individually. For team-level visibility across all your repositories, use Gitmore. It aggregates commits, PRs, and code reviews from all your GitHub repos into automated daily and weekly reports delivered to Slack or email. Free to start with 1 repository.

More Checklists

Also set up other platforms

Using more than one git provider? We have setup checklists for every major platform.

🦊

GitLab Setup Checklist for Engineering Teams

Protected branches, merge request rules, GitLab CI/CD, access levels, and security scanning setup.

View checklist

🪣

Bitbucket Setup Checklist for Engineering Teams

Branch permissions, merge checks, Pipelines CI/CD, default reviewers, and workspace security.