User Tools

Site Tools


wiki:setup_guides:github_org_setup_guide

GitHub Organization Setup Guide

Org, private repo, dev roles, and a staging/live workflow for a small team

  • You create a GitHub organization — a shared container for the project. You start as its Owner.
  • Inside the org, you create one private repository — the actual project (code + history).
  • Each dev is invited to the org as a Member, then given Write access to just that repo.
  • The repo has two branches: staging (default, all work lands here first) and main (live, admin-only).
  • Day to day: dev clones repo, works locally in their own folder (`frontend/` or `backend/`), and pushes directly to staging — no feature branch or PR needed for that step. Admin later promotes staging into main via a PR.
  • CLAUDE.md + .claude/ config files live in the repo, so Claude Code automatically knows the project rules.
  • The gap: GitHub Free can't technically block direct pushes to main on a private repo — that's process-based unless you upgrade.

1. Create the organization

  • Go to github.com → top-right + icon → “New organization”
  • Choose the Free plan
  • Give it a name — this becomes part of every repo URL
  • You become the initial Owner of the org

Org roles vs repo roles: an org member is either Owner (full control: billing, all repos, members) or Member (no access until granted on a specific repo). Keep devs as Member, not Owner.

2. Org-level settings

Setting Where Recommended Why
Allow forking of private repos Org Settings → Member privileges Off No use case for a closed team project
Pages creation Org Settings → Member privileges Off Not hosting a public site through this org
App access requests Org Settings → Member privileges Members only No outside collaborators in this setup

3. Create the repository

  • Inside the org → “New repository”
  • Name it (anything — your project name)
  • Set visibility to Private
  • Initialize with a README (optional, easier to clone right away)

4. Repository permission roles

Role Can do Use for
Read Clone/pull, view & comment Outside viewers — not your devs
Triage Manage issues/PRs, no code push PM/QA roles
Write Push code, branches, open/merge PRs Backend & frontend devs — use this
Maintain Write + some repo settings A lead dev who isn't full admin
Admin Everything incl. delete/visibility You (org owner), for now

Practical setup: both devs = org Member + repo role Write on the one shared repo. Nothing higher.

5. Branching strategy (staging -> live)

  • Goal: nothing devs push goes live immediately — it lands in staging first.
  • staging — set as the default branch and the testing stage. Devs push their work directly here.
  • main — the live/production branch. Only updated by the admin promoting from staging.

Dev workflow: clone repo (defaults to staging) → work in your own folder (`frontend/` or `backend/`) → commit → push directly to staging (`git push origin staging`, no feature branch or PR needed) → once staging is tested and verified, admin opens a PR from staging into main and merges it themselves.

6. Set the default branch to staging

  • Repo → Settings → General → Default branch → switch to staging

7. Protecting the main branch — read this

Confirmed directly against GitHub's API: on the Free plan, GitHub blocks ALL forms of branch protection (classic rules AND Rulesets) on PRIVATE repositories — even basic force-push blocking. Returns: “Upgrade to GitHub Pro or make this repository public to enable this feature.” Applies to org-owned private repos too.

Option Cost Result
A. Upgrade to GitHub Team ~$4/user/month Real enforcement: required PR + approval, blocked direct/force pushes
B. Stay Free, process only $0 No technical block — team agrees by convention only admin merges to main
  • If going with Option A: Require PR before merging, require 1 approval, leave admin bypass allowed.

8. Invite the developers

  • Invite to the organization (as Member):
    • Org page → People → Invite member → enter GitHub username
    • They join with role Member (not Owner) — grants no repo access yet
  • Add as a collaborator on the repo:
    • Repo → Settings → Collaborators and teams → Add people
    • Select the dev → choose role Write. Repeat for the second dev.

Both the org invite and the repo collaborator invite must be individually accepted by the invited person.

10. Set up Claude Code for the team

  • Three project-level files control Claude Code's behavior in this repo.
  • All are normal files committed to the repo (except one) — every dev who clones it inherits the same setup automatically.
  • CLAUDE.md — project instructions/context, read automatically every session.
  • .claude/settings.json — shared, version-controlled tool permissions.
  • .claude/skills/ — custom reusable project skills shared with everyone.

10.1 CLAUDE.md

  • A file named exactly CLAUDE.md at the repo root.
  • Claude Code reads it automatically at the start of every session in that folder.
  • Use it for: folder structure, branching rules, who can merge where, conventions.
  • Commit it like any normal file so it travels with every clone.
# Project: <project name>
This file is read automatically by Claude Code whenever someone works
in this repo. Everyone follows the same rules below.
 
## Branching rules
- staging is the default branch and the testing stage. Devs push their
  work directly to staging — no personal feature branch or PR needed
  for this step.
- main is the live/production branch. It is only updated by the admin
  promoting from staging via a pull request, once staging has been
  tested and verified to work.
- Never push or merge directly into main — this is the only hard rule.
  The promotion to main always goes through a pull request opened and
  merged by the admin.
- If asked to "deploy", "go live", or "merge to main" — stop and confirm
  with the admin first. Do not do this automatically.

CLAUDE.md is not a security control. It only influences Claude Code's own behavior when someone uses it cooperatively. It does NOT stop a human (or an AI told to ignore it) from editing/deleting CLAUDE.md itself, or from pushing straight to main directly — a Write collaborator can still technically do both on the Free plan, since there is no branch protection enforcing it. The only way to actually close that gap technically is the GitHub Team plan upgrade. Treat CLAUDE.md as a convenience for AI-assisted work, not a replacement for real branch protection. This is still not the final CLAUDE.md; it is still missing the content of this project; however, it only mentions what's required for the repo to be organized without paying for the team organization subscription

10.2 .claude/settings.json (shared permissions)

  • .claude/settings.json → commit this one. Shared, team-wide permission baseline.
  • .claude/settings.local.json → do NOT commit. Personal overrides, add to .gitignore.
{
  "permissions": {
    "allow": [
      "Bash(git status:*)", "Bash(git diff:*)", "Bash(git log:*)",
      "Bash(git branch:*)", "Bash(git fetch:*)",
      "Bash(npm install:*)", "Bash(npm run:*)", "Bash(npm test:*)"
    ],
    "deny": [
      "Bash(git push --force:*)",
      "Bash(git push origin main)", "Bash(git push origin main:*)",
      "Bash(git reset --hard:*)", "Bash(rm -rf:*)"
    ]
  }
}

10.3 .claude/skills/ (shared custom skills)

  • Custom, reusable project workflows stored in .claude/skills/<name>/SKILL.md
  • Available to anyone working in the repo with Claude Code.
  • Useful for codifying repeatable project tasks once instead of every dev needing a copy.
---
name: promote-to-staging
description: Workflow for getting finished work into the staging branch. Use when a developer has finished a feature/fix and needs it in the project.
---
This skill is for the frontend and backend developers.
 
`staging` is the testing branch — push directly to it. No personal feature
branch or pull request is needed for this step.
 
1. Make your changes inside your own folder (`frontend/` or `backend/`).
2. Commit your changes.
3. Push directly to `staging`: `git push origin staging`.
 
**The only hard rule: never push or merge into `main`.** That branch is
admin-only — if asked to deploy, go live, or merge into `main`, refuse and
say that's the admin's job, not yours.

CLAUDE.md, .claude/settings.json, and .claude/skills/ are all committed and shared. Only .claude/settings.local.json stays personal and gitignored.

11. Tooling used to automate this setup

  • Install GitHub CLI (gh): cli.github.com, or winget install –id GitHub.cli -e
  • Authenticate: gh auth login → protocol HTTPS → log in via browser
  • Default scopes (repo, read:org, gist, workflow) cover day-to-day use
  • Inviting org members needs extra scope: gh auth refresh -h github.com -s admin:org
  • Clone: gh repo clone <org>/<repo>

12. Quick reference — commands

# Clone
gh repo clone ORG/REPO project-folder
 
# Create and push the staging branch with initial structure
git checkout -b staging
git add -A
git commit -m "Initial structure"
git push origin staging
 
# Open a PR from staging into main
gh pr create --base main --head staging --title "..." --body "..."
 
# Set staging as the default branch
gh repo edit ORG/REPO --default-branch staging
 
# Invite a user to the org (needs admin:org scope)
gh api orgs/ORG/invitations -F invitee_id=<user_id> -f role="direct_member"
 
# Add a user as a Write collaborator on the repo
gh api repos/ORG/REPO/collaborators/USERNAME -X PUT -f permission="push"

Summary checklist

  • Create org (Free plan), self as Owner
  • Set org privileges: forking off, Pages off, app access “Members only”
  • Create one private repo
  • Create staging branch, set as default; keep main as live branch
  • Invite each dev to org as Member
  • Add each dev as repo collaborator with Write role
  • Agree on process: devs push directly to staging (no PR needed); only admin opens a PR and merges staging → main
  • Decide: upgrade to Team plan for real enforcement, or proceed Free with process-only trust
  • Add CLAUDE.md at repo root with project rules, push to staging
  • Add .claude/settings.json (shared permissions); gitignore .claude/settings.local.json
  • Add the promote-to-staging skill under .claude/skills/ so Claude Code knows devs push straight to staging and never touch main
  • Each dev clones the repo locally and works in their own folder, then pushes their changes straight to staging

TL;DR

  • One org, one private repo, two branches: staging (default, devs work here) and main (live, admin-only).
  • Devs = org Member + repo Write. Nothing higher.
  • Workflow: clone → work locally → push straight to staging (no PR) → admin opens a PR and promotes staging → main when ready.
  • Free plan can't technically block direct pushes to main on a private repo — it's process/trust-based unless you pay for GitHub Team.
  • CLAUDE.md + .claude/settings.json + .claude/skills/ in the repo give every dev's Claude Code the same project rules and permissions automatically — but none of it is a real security control, just a convenience for cooperative AI-assisted work.
wiki/setup_guides/github_org_setup_guide.txt · Last modified: by walid