====== 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: 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//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 /'' ===== 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= -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.