Website team setup — from one owner to a team, once
new-website scaffolds every site with an AGENTS.md (the working rules: fetch the
latest state first, pull request instead of a direct push, when a merge is allowed,
never invent facts, the new-page checklist) and a CLAUDE.md that imports it. Those
rules already work for one person. This skill does the part that only a team needs,
in the order we had to do it on a real site, with the traps we hit written in.
Human-in-the-loop. Inviting people, accepting invitations, the Cloudflare
dashboard, and any plan-dependent GitHub setting are the owner's clicks. You draft
every value and run every command that gh can run; you never handle the owner's
credentials or 2FA, and never drive a dashboard through blind screen control.
Language. Talk to the owner in their language. AGENTS.md stays English on every
site, like the skills: agents read it, and its Language rule has them reply in the
person's language. TEAM-GUIDE.md is for people: translate it in-session when the
team's language is not English (rules and commands intact), as new-website does
for PUBLISHING.md.
Prerequisites: the site is on GitHub with .github/workflows/ci.yml from the kit, and
AGENTS.md exists. If it does not (a site scaffolded before the template existed),
copy new-website/templates/AGENTS.md + templates/CLAUDE.md in first and fill the
[BRACKET] slots per the note at its top, then continue here. Claude Code sites also
need the sync hook that AGENTS.md §1 relies on: if .claude/hooks/git-stand.mjs is
missing, copy it from new-website/templates/claude/hooks/ and merge the hooks block of
new-website/templates/claude/settings.json into the site's .claude/settings.json.
An owner who works alone but runs several assistant sessions at once, or lets the assistant
merge, may run §4 and §5 on their own, without the rest of this skill: set OWNER and REPO
as §2 does first, and run §3's first command (it turns on the Update branch button) if
the ruleset keeps the "up to date" requirement, which it does by default.
Work on a branch and finish with a pull request — the rule the setup installs applies
to the setup itself. Say in the pull request that it touches scripts/ (the hook) and
AGENTS.md.
1. Decide with the owner first (five questions)
Ask, one at a time, offer the options, record the answers — they feed §§2, 7, 8:
- Who joins? GitHub usernames of the collaborators (they need accounts first; a
free account is enough).
- Rights level for collaborators, written into
AGENTS.md §5:
content (texts, images, collection entries) · content + design (also
navigation, components, layouts, styles, existing pages, src/config.ts,
BRAND.md) ·
everything the owner may change (also new pages, tests, scripts, CI, settings).
The reference site started at "content" and widened to "everything" within a day;
pick what fits now, it is one line to change later. If only the owner publishes
(Q4), say that "everything" includes ship.sh, the hook and the CI file, which a
collaborator could then change and merge.
- Merge rule. Default and recommended: a collaborator merges their own pull
request when the checks are green, no placeholders remain and it is not a draft;
other people's pull requests only after asking. Alternative: the owner merges
everything. Lands in
AGENTS.md §5 (the "Merge rule" line) and in the guide's
Merge row.
- Who publishes live — two-stage sites only (
main = preview, production =
live, npm run ship). Offer owner only as the default, or every
collaborator. Single-stage sites skip this: a merge is live there, and the merge
rule is the whole gate.
- How will they work? Codex in the browser (nothing to install; GitHub connection
in Codex), Codex or Claude Code locally (needs
SETUP.md's tools), or both. Decides
what TEAM-GUIDE.md (§8) says.
2. Invite the collaborators
OWNER=<github-owner>; REPO=<repo>
# On a personal-account repo a collaborator always gets write access (push branches,
# open/merge pull requests; not admin): GitHub has no other level there, and the API's
# `permission` field applies to organization repos only.
gh api -X PUT "repos/$OWNER/$REPO/collaborators/<username>"
gh api "repos/$OWNER/$REPO/invitations" --jq '.[] | "\(.invitee.login) \(.permissions) pending"'
Dashboard path: repo → Settings → Collaborators → Add people. The invitee gets an
email and must accept it; until then collaborators does not list them. Tell the
owner to ask for the acceptance and re-check before assuming anyone can push:
gh api "repos/$OWNER/$REPO/collaborators" --jq '.[].login'.
Re-run safe: an existing collaborator is a no-op; a pending invitation is listed, not
duplicated.
3. Repository settings (one command)
gh repo edit "$OWNER/$REPO" --allow-update-branch --delete-branch-on-merge
gh api "repos/$OWNER/$REPO" --jq '{allow_update_branch, delete_branch_on_merge}'
allow_update_branch shows the "Update branch" button on every pull request
that is behind main. This is what makes "a second person opens a pull request while
the first one merges" a one-click situation instead of a git lesson: press it, CI
runs again on the merged state, then merge. Required: with a ruleset that demands
up-to-date branches (§5) GitHub refuses to merge a stale one otherwise.
delete_branch_on_merge removes the head branch after a merge, so the branch
list stays readable for people who never learned to prune. GitHub never deletes a
base branch, so production is safe. Pair it with git config --global fetch.prune true on each machine (SETUP.md §3 says so).
Dashboard path: Settings → General → Pull Requests → tick both.
3b. The remaining settings — what a clean team setup looks like on a personal-account repo
None of these blocks a team; each removes a trap we either hit or saw coming. Read
the current value first, change only what differs, and say what you changed.
| Setting |
Set it to |
Why |
How |
| Merge method |
one method only; keep merge commits, turn off rebase (squash is fine if the owner prefers one commit per pull request) |
Rebase-merging rewrites the collaborators' commits, so the SHAs in their clones no longer match GitHub's, and the "Update branch" button then produces conflicts. One method means the button labels never change under a non-technical user. |
gh repo edit --enable-rebase-merge=false (add --enable-squash-merge=false to keep merge commits only) |
| Auto-merge |
off |
"Enable auto-merge" merges the moment CI turns green, skipping the preview look that AGENTS.md §2 requires. |
gh repo edit --enable-auto-merge=false |
| Collaborator permission |
write, never maintain or admin |
Write can push branches, open and merge pull requests; admin could change the settings this skill sets, or delete the repo. |
§2 |
| Visibility |
private (client work) |
A public repo exposes drafts, "[MISSING: …]" placeholders and client photos before they are meant to be seen. Note: this is also what decides whether §5-A's ruleset is available for free. |
gh repo view --json visibility |
| Actions permissions |
Allow all, or narrow to GitHub-owned and verified |
The kit's ci.yml uses only actions/checkout and actions/setup-node, so the narrow setting costs nothing and stops a collaborator's future workflow pulling an unvetted action. |
Settings → Actions → General |
| Actions minutes (private repos) |
know the budget: 2 000 free minutes/month on GitHub Free; the repo's Actions tab shows what each run takes. With no payment method on the account, GitHub blocks Actions once they are used up and charges nothing. An Actions budget of 0 US dollars with Stop usage already on the account blocks private-repo jobs the same way, payment method or not, with a message that reads like a failed payment ("recent account payments have failed or your spending limit needs to be increased") and jobs that start zero steps. Check Budgets and alerts for an existing Actions budget. If the owner wants CI to keep running past the free minutes, edit it to a small cap they choose (say $10) with Stop usage when budget limit is reached kept on; create one only if none is there. Do not pick the "Copilot AI Credits" budget, a different product that the list may show first. Whether CI starts again after the change is confirmed only by the next push (GitHub Actions billing, budgets) |
Every push to a pull request or to main starts a run, and the minutes add up; at the limit CI either starts costing money or silently stops, and then "green before merge" stops meaning anything. The concurrency block in the kit's ci.yml cancels a superseded run on the same branch, so a quick second push stops the first run instead of letting it finish. |
https://github.com/settings/billing → Budgets and alerts; usage on the same billing pages |
| Fork workflows |
leave the default (require approval for first-time contributors) |
Collaborators push branches, not forks, so this never triggers for them; it only guards against a stranger's fork running CI on your minutes. |
Settings → Actions → General |
| Workflow token |
leave read-only (default) |
The kit's CI writes nothing to the repo. |
Settings → Actions → General |
| Dependabot |
security updates on; version updates: the starter ships a monthly grouped .github/dependabot.yml; keep it if someone merges the pull request, delete it if not (ask the owner who that is); a new major of any package but the two held back comes as its own pull request and may stay open |
Security updates arrive as ordinary pull requests that CI checks; the monthly pull request is only worth having if someone reads it, and without the file security updates stay on. |
Settings → Code security; .github/dependabot.yml |
| Secret scanning + push protection |
on where the plan offers it (free on public repos; paid on private) |
Catches a token pasted into a commit before it lands; the kit's .gitignore is the backstop either way. |
Settings → Code security |
production branch (two-stage) |
protect against deletion and force-push only — no pull-request rule |
npm run ship pushes main:production directly (a fast-forward push); a pull-request rule on production would break it. No ship has been seen through these two rules on a real site yet, so after the first one, check that it went through. By GitHub's documentation a fast-forward push is not a force push, "Block force pushes" stops force pushes only, and creating a branch is a separate rule ("Restrict creations") that this set does not use, so a normal ship should pass. Rulesets need a public repo or a paid plan: on a free private repo this one is refused like §5-A's, and production has no server-side protection at all. Where rulesets are available, GitHub documents a Restrict updates rule (only bypass actors may push) and lists the repository admin role as a bypass actor, which would make "who may ship" (§1 Q4) enforced; this is not yet tested on a real site, so until it is, "who may ship" stays a written rule in AGENTS.md. |
second ruleset, §5-A shape with only the deletion and non_fast_forward rules, include: ["refs/heads/production"] |
| Cloudflare GitHub App |
access to this repo only |
The app gets read access to every repo it is granted; least privilege. |
GitHub → Settings → Applications → Cloudflare Workers and Pages → Configure (see §6.2) |
| 2FA |
recommended, not required: each collaborator turns on two-factor sign-in and adds a passkey |
The website is the owner's, and anyone who gets into a collaborator's account can change it, so recommend it to each collaborator in those words. Never make it a condition: a personal-account repo cannot require it (only organizations can), and GitHub itself requires it only for some accounts (it tells those by email and on the site). Do not count on GitHub prompting a collaborator who only edits content; TEAM-GUIDE.md gives them the link. There is nothing to check from your side: gh api users/<login> shows nothing about 2FA, and GitHub documents no 2FA marker on Settings → Collaborators for a personal-account repo, so if the owner wants to know, ask. |
the collaborator, at https://github.com/settings/security |
| Watching |
each collaborator watches the repo (at least "Participating and @mentions", the default) |
Otherwise nobody sees a review comment or a failed check on their pull request. |
the "Watch" button on the repo |
Skipped on purpose: CODEOWNERS with required code-owner review (needs the paid
ruleset option on private repos and adds a review step the team did not ask for);
merge queues (paid); organization-level policies (this skill targets a repo on a
personal account — an organization owner has the equivalent settings under the
organization).
4. Prove that CI starts on its own (do not skip)
On the reference site the kit's workflow file had been on main for three weeks and
had never run: pushes to main produced no run at all, so "green checks before
merging" was an empty rule. What got it going was one manual start followed by a
throwaway pull request; afterwards every push and pull request ran normally. The root
cause was not pinned down (Actions permissions looked normal), so this skill does not
claim to prevent it — it checks, and if the check fails it does what worked:
# a) Are Actions allowed at all?
gh api "repos/$OWNER/$REPO/actions/permissions" --jq '{enabled, allowed_actions}'
# b) Is the workflow listed, and active (not disabled_manually / disabled_inactivity)?
gh workflow list --all
gh workflow enable ci.yml # only if it shows as disabled
# c) Has it EVER run on a pull_request event? (push runs prove the file works, not the
# trigger the merge gate relies on — a workflow whose pull_request trigger is broken
# still shows green push runs on main)
gh run list --workflow ci.yml --event pull_request --limit 5
gh run list --workflow ci.yml --limit 5 # any run at all?
While the throwaway pull request is open, look at its check list: if Cloudflare is
already connected (§6), it also proves "no leftover Workers Builds check" — see §6.2.
If Cloudflare is connected later, §6.2 opens a second one.
5. Block direct pushes to main
Two mechanisms, chosen by what the plan allows. Try the server-side one first: it is
the only one nobody can bypass.
A. Ruleset (public repo, or private repo on a paid plan). Pull request required,
the CI job required to pass on an up-to-date branch, no force push, no deletion.
test is the job id in the kit's ci.yml; use the job's name: instead if one is set.
# Re-run safe: create only if no ruleset of that name exists yet.
gh api "repos/$OWNER/$REPO/rulesets" --jq 'map(select(.name=="protect main")) | length'
# 0 → create:
gh api -X POST "repos/$OWNER/$REPO/rulesets" --input - <<'JSON'
{
"name": "protect main",
"target": "branch",
"enforcement": "active",
"bypass_actors": [],
"conditions": { "ref_name": { "include": ["~DEFAULT_BRANCH"], "exclude": [] } },
"rules": [
{ "type": "deletion" },
{ "type": "non_fast_forward" },
{ "type": "pull_request",
"parameters": { "required_approving_review_count": 0,
"dismiss_stale_reviews_on_push": false, "require_code_owner_review": false,
"require_last_push_approval": false, "required_review_thread_resolution": false } },
{ "type": "required_status_checks",
"parameters": { "strict_required_status_checks_policy": true,
"required_status_checks": [ { "context": "test" } ] } }
]
}
JSON
gh api "repos/$OWNER/$REPO/rulesets" --jq '.[] | "\(.name) \(.enforcement)"'
A ruleset that already exists is not proof. A "protect main" left behind by an
earlier attempt, or edited in the dashboard since, may be looser than the one above
(a different check name, no up-to-date requirement, a bypass actor). So when the count
is not 0, read every one of them back (leftovers come in twos) and compare each with
the JSON above, rule by rule:
for id in $(gh api "repos/$OWNER/$REPO/rulesets" --jq '.[] | select(.name=="protect main") | .id'); do
echo "== ruleset $id"
gh api "repos/$OWNER/$REPO/rulesets/$id" \
--jq '{enforcement, bypass_actors, conditions, rules: [.rules[] | {type, parameters}]}'
done
GitHub's answer also carries keys the recipe never sent. Those defaults are not
differences: in the pull_request rule allowed_merge_methods (all three),
required_reviewers (empty) and require_extra_approval_for_unattributed_changes (true),
in the required_status_checks rule do_not_enforce_on_create (false). GitHub's
REST reference lists all four. The
extra-approval key makes a pull request that Copilot opened for no person need one more
approval than the count; GitHub's rules page says it has no effect while the count is 0,
as here, and it starts to apply once the owner raises it. A value other than those defaults is a difference: ask the
owner if it is on purpose. Put all four keys in the PUT body, so the PUT does not decide
them: with the values the read-back showed, or the default for a key the owner says was
not on purpose. What a PUT that leaves them out does to them has not been checked.
Anything that differs — enforcement not active, a non-empty bypass_actors, a
missing rule, a strict_required_status_checks_policy that is not the owner's choice
(true unless the next paragraph applies), a context that is not the CI job's name — is fixed with
gh api -X PUT "repos/$OWNER/$REPO/rulesets/$id" --input -
and the same JSON body plus the four keys (it carries "bypass_actors": [] explicitly, so a bypass list
is cleared rather than left as GitHub found it). Read it back once more after the PUT.
"Up to date" may be switched off, as the owner's choice. With it on, every merge
leaves each other open pull request behind main: it needs Update branch and a new
CI run before it can merge. An owner who works alone but runs several assistant
sessions, each with its own pull request, pays that after every merge. With it off
("strict_required_status_checks_policy": false) a pull request merges once its own CI
passed, and GitHub warns that checks may fail after the merge if two changes do not fit
(Available rules for rulesets, "Loose");
the kit's ci.yml also runs on pushes to main, which usually shows such a failure (a
newer push can cancel a run, and a change to docs only skips the tests). Ask
the owner, don't decide. If they choose off, send false in the body, write the choice
in AGENTS.md §2 beside the merge rule, and let the read-back accept false where that
line is. We have not measured how much the requirement costs with several pull requests
open.
Two rulesets of that name: bring one in line, then delete the other with the owner's
go-ahead (gh api -X DELETE "repos/$OWNER/$REPO/rulesets/<other id>") — two rulesets
on the same branch both apply, and the looser one still blocks nothing. Confirm the
context against the job in ci.yml (test unless the site renamed it); a wrong
name blocks every merge, because a check that never reports never passes.
No bypass list: the rule applies to the owner too, which is the point. Dashboard
path: Settings → Rules → Rulesets → New branch ruleset. An approving review count of
0 keeps the gate "green CI + a human decided to merge", matching §1's merge rule; raise it
only if the owner wants a second pair of eyes on every change.
B. The refusal. On a private repo on a free plan the request comes back
403 with an "upgrade" message: GitHub offers no server-side branch protection
there. Say so plainly, then enable the local guard the kit already ships:
scripts/hooks/pre-push contains a commented-out PR-only main block (the six
lines from while read to done, marked OPTIONAL). First read the current state —
re-runs must not edit twice, and a site scaffolded before the block existed has no
block to uncomment at all:
grep -n '^while read -r _lref' scripts/hooks/pre-push && echo "already enabled"
grep -Eq '^(# )?while read -r _lref' scripts/hooks/pre-push || echo "no block in this hook — older kit; merge the kit's templates/astro/scripts/hooks/pre-push in first"
The second grep looks for the block's own first line, commented out or not — not for
the ALLOW_MAIN_PUSH word, which the prose comment above the block also contains.
No block (the second line fires): bring the site's hook up to the kit's
templates/astro/scripts/hooks/pre-push by hand in the setup pull request, the
way whats-new.sh treats every drift-tracked file (it reports the hook, never
rewrites it — same as ci.yml in §6.8). Diff the two first: on a stock hook they
differ by four additions — the stdin capture, the block, the deletion-only skip and
the publish-classifier step — and the order matters: the skip sits below the block,
or a push deleting main gets past it; the capture sits above both, or the skip
never fires. A site
that added a step of its own keeps it. Re-stamp afterwards, as for any hand-merged tracked
file. Then continue. Found this on the first real site the skill ran on: its hook
predated the block.
If it is not enabled: remove the leading # from those six lines and replace only
the first sentence of the comment above them ("OPTIONAL: PR-only main flow …") with
the date and why it is on — keep the rest of that comment: it says why the block must
stay above the build steps. The hook's comments, its header and this one, are the
source of truth for what bypasses the block: ALLOW_MAIN_PUSH=1, the deliberate
override (above the block); git push --no-verify and unsetting core.hooksPath
(header); a clone that never ran npm install, since the prepare script is what
wires the hook; and a site that is not the root of its git repo, where prepare leaves
the hook unwired. Commit that in the setup pull request. Then
tell the owner, and write into AGENTS.md §2, what it is: a local convention,
with the bypasses quoted from the hook's comments, not from memory. PUBLISHING.md
tells the owner to push to main directly (to publish on a single-stage site, to
update the preview on a two-stage one), which the block now refuses: in the setup pull
request, point those steps at a pull request, with ALLOW_MAIN_PUSH=1 named as the
owner's deliberate exception. It does not touch
npm run ship (which pushes main:production), nor GitHub's own merges, nor Codex
in the cloud (which only ever creates pull requests). It is the best a free private
repo gets, and it is enough when everyone follows AGENTS.md.
Verify — and not with a no-op push. git push origin main with nothing to push
hands the hook nothing and sends GitHub nothing ("Everything up-to-date"), so it
"passes" both mechanisms without testing either. Instead:
# Ruleset (§5-A): read the effective rules back — must list pull_request and
# required_status_checks. A dry-run push never reaches GitHub's rules, so this
# read-back is the whole verification on a ruleset site.
gh api "repos/$OWNER/$REPO/rules/branches/main" --jq '.[].type'
# Hook (§5-B ONLY — on a ruleset site the hook is off by design and this would
# print "NOT blocked"): a dry run of a real ref update — the hook runs, nothing is
# transferred. Branch from the SETUP branch, not origin/main: git runs the hook from
# the checked-out files, and until the setup pull request merges, origin/main still
# has the block commented out, so a check from there always says "NOT blocked".
git switch --no-track -c setup/push-check setup/team # the setup branch, block enabled
git commit --allow-empty -m "push-block check (never pushed)"
# The push is EXPECTED to fail, so test it as a condition — in a script run under
# `set -e` a bare failing push would abort before the cleanup line runs. Only the
# hook's own message counts as "blocked": a push can fail for other reasons.
if out="$(git push --dry-run origin HEAD:main 2>&1)"; then
echo "NOT blocked — the hook is not active in this clone (npm install run? hooksPath set? site at the root of its repo?)"
elif grep -qF "Direct push to 'main' blocked" <<<"$out"; then
echo "blocked as expected"
else
echo "push failed for another reason — read it: $out"
fi
git switch - && git branch -D setup/push-check
6. Cloudflare: connect the repo to GitHub — with the traps
new-website/references/CLOUDFLARE_FIRST_DEPLOY.md has the bootstrap paths; a team
wants a project connected to GitHub (push-to-deploy, one preview address per pull
request). A site made with kit 0.35 or later is a Worker; a site made before may
still be on Pages (AGENTS.md and PUBLISHING.md say which; a wrangler.jsonc at
the repo root with assets in it is a Worker). The setup script there ("S") does not make the Worker or
connect the repository: with no Worker yet it says how to connect it in the dashboard (the
steps below, with the build command of item 4 and the production branch of item 5), and once a
build has made the Worker it reads it, changes the domain's settings and attaches the domain on
launch day. It does not create the production branch (item 5) or touch the checks of
items 2 and 8. The connection is B, Workers Builds (a site still on Pages: "Sites already on
Pages" in the same guide, and the Pages form of each item below): walk the owner through it
with these warnings ahead of each click:
- The right project type. In the Cloudflare dashboard, Workers & Pages → Create
opens on the Workers tab, and its "Import a repository" creates a Worker with
Workers Builds: the right type for a new site. For a site that is on Pages, use the
Pages tab and Connect to Git instead; Cloudflare cannot turn one into the other
(item 9). If the owner already runs other Workers in the account, the build token
(item 4) reaches all of them: a separate Cloudflare account for the site is the safe
way, and it is the owner's call.
- The wrong type leaves a check behind. A Worker made for a site that is on Pages (or a
Pages project made for a Worker site) keeps posting its build check on every pull request,
pending or failing forever, even after the project is deleted. Disconnect it first (a
Worker: Settings → Builds → disconnect; a Pages project: delete it), then prove the
pull request shows only the CI check and the one Cloudflare build check of this
site's type: open a throwaway pull request after connecting (the §4 recipe: empty
commit, close and delete afterwards). The check's exact name on a Worker is not checked.
If the other type's check is still there, the GitHub App installation still carries the
trigger: GitHub → Settings → Applications → Cloudflare Workers and Pages →
Configure → check which repos it may access, and remove and re-add the repo if
needed.
- The name and the preview address. A Worker's name comes from
name in
wrangler.jsonc; it must be unique only inside the account. Its Preview links look like
https://<prefix>-<worker>.<account>.workers.dev: read one on the Worker's page (or in
the setup script's report), and write it into AGENTS.md (header + §2), PUBLISHING.md
and the README's deploy section. A Pages project's name is global instead:
<name>.pages.dev is one namespace across all Cloudflare accounts, so the obvious name
may be taken with no explanation beyond a validation error. Pick a short alternative; it
only changes the preview address, which is not always the name followed by .pages.dev:
read it on the project's page. Either way, search the repo for the old address
(git grep -n '<old-name>.pages.dev', a site may have it in src/config.ts), so nobody
quotes a preview address that does not exist.
- Build settings. A Worker: build command
npm run build; what to deploy comes from
wrangler.jsonc. The build token: pick Create new token in the build's token field,
not an existing one, and cut it down in place (the guide's B section names the rows). Node
version comes from the repo's .nvmrc (Workers Builds reading it is from the docs, not seen
on a build). A Pages project: framework preset Astro, build command npm run build,
output directory dist, Node from .nvmrc.
- Production branch = the publish model. Two-stage:
production (create the
branch first if it does not exist yet, see new-website §4), so main stays the
noindexed preview. Single-stage: main — and then set PROD_BRANCH = 'main' in
src/config.ts in the setup pull request (the kit ships 'production'), because
analytics, once switched on, fires only when the two agree, silently never
otherwise. AGENTS.md §2 must keep the block that matches (the other one is
deleted at scaffold time — check it was).
- Pull request previews. Once connected, every pull request gets its own preview
address from its build: a Worker's Preview link (where Cloudflare posts it is not
checked), or on Pages "Cloudflare Pages" → View deployment, plus the stable alias
<branch>.<project>.pages.dev. AGENTS.md §2 tells collaborators to look there before
merging. A Worker's previews carry noindex from Cloudflare, a Pages site's from the
kit's functions/_middleware.ts (a site made before 0.35); both are public-by-URL (see
PUBLISHING.md).
- Single-stage sites: a merge publishes. Anything that runs only in
npm run ship on this site must now run in CI, or it never runs. The kit's own
ship.sh runs no tests (the pre-push hook and CI do), so a stock site has nothing
to move; a site that added a ship-only gate of its own moves that command into
ci.yml in the setup pull request.
- Placeholder gate — check the site actually has it. The kit's
ci.yml greps
src/ and public/ for "[MISSING: …]" before the build, but only sites
scaffolded after that step existed carry it: whats-new.sh reports drift in
ci.yml, it never rewrites it. So AGENTS.md's merge rule ("no placeholder is
left") is enforced only if the step is there. First find out which token this
site uses: AGENTS.md §4 names it, and a site with non-English content may use its own word
(a German site might write "[FEHLT: …]"); the kit's step greps for [MISSING:
and matches nothing else. Then check for the step itself — its grep -rnI line,
not any mention of the word in a comment — add it if missing with the site's
token in the pattern, and prove it fires before calling the setup done:grep -nF "grep -rnI" .github/workflows/ci.yml \
|| echo "placeholder step missing — copy it from the kit's templates/astro/.github/workflows/ci.yml and put this site's token in the pattern"
Then plant one: a scratch branch with the site's own token ("[MISSING: probe]",
or "[FEHLT: probe]" on that German site) in any page, push it and open a draft
pull request from it (the kit's CI runs on pushes only for main and production,
so a pushed branch alone starts no check), watch the check turn red at the step
No unfilled "[MISSING:" placeholders, then close the pull request and delete the
branch. Red only later, at npm test, is tests/placeholders.spec.ts speaking: the
grep step is missing or greps for another word. A push the hook refuses means the
site's token is not the one in that spec's DRAFT_TOKEN; set it there too. A gate that has never fired is a hypothesis, and a gate
probed with the wrong token proves the wrong thing.
- A project of the other kind, or a direct-upload one, already exists. Cloudflare cannot
turn a direct-upload project into a git-connected one, nor a Pages project into a Worker.
A Worker first deployed by command: whether it can be connected to the repository later is not
checked; the safe route is a new Worker connected to the repository, then move
the custom domain. A Pages site: create the git-connected project under a new name, let it
build once, remove the domain from the old project (one Pages project at a time), attach it
to the new one (Custom domains → Set up a domain), wait for Active, and only then delete the
old project. Do it in a quiet moment and check the live domain with a cache-bust
(
PUBLISHING.md § "For AI assistants"). The Pages sequence follows Cloudflare's
documentation and was not exercised on the reference site.
Verify: after the first merge, <live-or-preview-url>/build.txt shows the merge
commit id (the kit's build marker). Say which address is the preview and which is
live every time you quote one (PUBLISHING.md § "For AI assistants").
7. Rights and publish rights in AGENTS.md
Rewrite the four lines at the top of §5 from the §1 answers: collaborators (GitHub
usernames only, no emails), rights level, merge rule, and who publishes live
(two-stage) — or delete the publish line on a single-stage site. If §5-B enabled the
hook, add one sentence to §2 saying the block is local, with the bypasses quoted
from the hook's own comment block (§5-B). If §2 still says "The assistant never
merges" (a site scaffolded before the assistant could merge on request), replace that
bullet with the template's "Merging" bullet, or the guide in §8 promises what
AGENTS.md forbids. Read the whole
file once more: no [BRACKET] slot and no scaffold note may remain, and the publish
model block must match Cloudflare's production branch (§6.5).
8. The collaborators' guide
Copy templates/TEAM-GUIDE.md from this skill into the repo root as TEAM-GUIDE.md,
keep the part(s) that match §1's answer 5 (browser / local / both), fill every
[BRACKET] slot — site name, owner/repo, the owner's name for "who to ask" (a name,
never an email), the merge step in the numbered instructions and the Merge row
([MERGE_STEP], [MERGE_RULE], both from §1 answer 3), and the "what merge does"
line ([MERGE_MEANS] with [PREVIEW_URL], [LIVE_URL], [SHIP_RIGHTS] from
answer 4; single-stage sites keep the "goes live" half) — and translate if the team's
language is not English. It is deliberately one page: where to start, the four moves
per task, when to ask.
9. Hand over
- Open the setup pull request (branch
setup/team), describe in plain words: who was
invited, which settings are on, how CI was proven, which push block is active and
what it covers, the Cloudflare project and its addresses, the rights level, the
publish rule. Note the scripts/ and AGENTS.md changes explicitly (AGENTS.md §5).
- The owner merges it per the new rule, on GitHub or by telling the assistant to (this
skill does not merge it unasked), then tells the
collaborators to accept the invitation and read
TEAM-GUIDE.md. Their first task: something small, so the whole loop (fetch, branch,
pull request, green checks, preview, merge) is exercised once with the owner around.
Re-running the skill is safe: every step reports the current state before changing
anything, and none of §§2–6 creates a second copy of what exists.
1---2name: website-team-setup3description: >4 Turn a one-owner new-website repo into one several people and AI assistants5 (Codex, Claude Code) can work on at once without overwriting each other: invite6 collaborators, set the repo settings, prove the CI workflow starts on its own7 (the fix for a silent one is bundled), block direct pushes to `main`, connect8 Cloudflare (a Worker, or Pages for an older site) to GitHub without the known traps, write rights, merge rule and9 who publishes live into `AGENTS.md`, hand the team a one-page guide. Run once,10 when a second person joins. Use it whenever the user mentions a colleague, client11 or second assistant joining a site repo, inviting someone to GitHub, "Update12 branch", pull requests not running CI, or connecting Cloudflare to the repo, even13 without the word "team". Trigger phrases: "set up the team", "my colleague will14 work on the site", "invite a collaborator", "block pushes to main", "CI is not15 running on pull requests".16metadata:17 source: https://skillmd.com/skills/karero/website-team-setup18---1920# Website team setup — from one owner to a team, once2122`new-website` scaffolds every site with an `AGENTS.md` (the working rules: fetch the23latest state first, pull request instead of a direct push, when a merge is allowed,24never invent facts, the new-page checklist) and a `CLAUDE.md` that imports it. Those25rules already work for one person. This skill does the part that only a **team** needs,26in the order we had to do it on a real site, with the traps we hit written in.2728> **Human-in-the-loop.** Inviting people, accepting invitations, the Cloudflare29> dashboard, and any plan-dependent GitHub setting are the owner's clicks. You draft30> every value and run every command that `gh` can run; you never handle the owner's31> credentials or 2FA, and never drive a dashboard through blind screen control.3233> **Language.** Talk to the owner in their language. `AGENTS.md` stays English on every34> site, like the skills: agents read it, and its Language rule has them reply in the35> person's language. `TEAM-GUIDE.md` is for people: translate it in-session when the36> team's language is not English (rules and commands intact), as `new-website` does37> for `PUBLISHING.md`.3839Prerequisites: the site is on GitHub with `.github/workflows/ci.yml` from the kit, and40`AGENTS.md` exists. If it does not (a site scaffolded before the template existed),41copy `new-website/templates/AGENTS.md` + `templates/CLAUDE.md` in first and fill the42`[BRACKET]` slots per the note at its top, then continue here. Claude Code sites also43need the sync hook that `AGENTS.md` §1 relies on: if `.claude/hooks/git-stand.mjs` is44missing, copy it from `new-website/templates/claude/hooks/` and merge the `hooks` block of45`new-website/templates/claude/settings.json` into the site's `.claude/settings.json`.4647An owner who works alone but runs several assistant sessions at once, or lets the assistant48merge, may run §4 and §5 on their own, without the rest of this skill: set `OWNER` and `REPO`49as §2 does first, and run §3's first command (it turns on the **Update branch** button) if50the ruleset keeps the "up to date" requirement, which it does by default.5152Work on a branch and finish with a pull request — the rule the setup installs applies53to the setup itself. Say in the pull request that it touches `scripts/` (the hook) and54`AGENTS.md`.5556## 1. Decide with the owner first (five questions)5758Ask, one at a time, offer the options, record the answers — they feed §§2, 7, 8:59601. **Who joins?** GitHub usernames of the collaborators (they need accounts first; a61 free account is enough).622. **Rights level** for collaborators, written into `AGENTS.md` §5:63 **content** (texts, images, collection entries) · **content + design** (also64 navigation, components, layouts, styles, existing pages, `src/config.ts`,65 `BRAND.md`) ·66 **everything** the owner may change (also new pages, tests, scripts, CI, settings).67 The reference site started at "content" and widened to "everything" within a day;68 pick what fits now, it is one line to change later. If only the owner publishes69 (Q4), say that "everything" includes `ship.sh`, the hook and the CI file, which a70 collaborator could then change and merge.713. **Merge rule.** Default and recommended: a collaborator merges their **own** pull72 request when the checks are green, no placeholders remain and it is not a draft;73 other people's pull requests only after asking. Alternative: the owner merges74 everything. Lands in `AGENTS.md` §5 (the "Merge rule" line) and in the guide's75 Merge row.764. **Who publishes live** — two-stage sites only (`main` = preview, `production` =77 live, `npm run ship`). Offer **owner only** as the default, or **every78 collaborator**. Single-stage sites skip this: a merge is live there, and the merge79 rule is the whole gate.805. **How will they work?** Codex in the browser (nothing to install; GitHub connection81 in Codex), Codex or Claude Code locally (needs `SETUP.md`'s tools), or both. Decides82 what `TEAM-GUIDE.md` (§8) says.8384## 2. Invite the collaborators8586```bash87OWNER=<github-owner>; REPO=<repo>88# On a personal-account repo a collaborator always gets write access (push branches,89# open/merge pull requests; not admin): GitHub has no other level there, and the API's90# `permission` field applies to organization repos only.91gh api -X PUT "repos/$OWNER/$REPO/collaborators/<username>"92gh api "repos/$OWNER/$REPO/invitations" --jq '.[] | "\(.invitee.login) \(.permissions) pending"'93```94Dashboard path: repo → **Settings → Collaborators → Add people**. The invitee gets an95email and must **accept** it; until then `collaborators` does not list them. Tell the96owner to ask for the acceptance and re-check before assuming anyone can push:97`gh api "repos/$OWNER/$REPO/collaborators" --jq '.[].login'`.9899Re-run safe: an existing collaborator is a no-op; a pending invitation is listed, not100duplicated.101102## 3. Repository settings (one command)103104```bash105gh repo edit "$OWNER/$REPO" --allow-update-branch --delete-branch-on-merge106gh api "repos/$OWNER/$REPO" --jq '{allow_update_branch, delete_branch_on_merge}'107```108- **`allow_update_branch`** shows the **"Update branch"** button on every pull request109 that is behind `main`. This is what makes "a second person opens a pull request while110 the first one merges" a one-click situation instead of a git lesson: press it, CI111 runs again on the merged state, then merge. Required: with a ruleset that demands112 up-to-date branches (§5) GitHub refuses to merge a stale one otherwise.113- **`delete_branch_on_merge`** removes the head branch after a merge, so the branch114 list stays readable for people who never learned to prune. GitHub never deletes a115 *base* branch, so `production` is safe. Pair it with `git config --global116 fetch.prune true` on each machine (`SETUP.md` §3 says so).117118Dashboard path: **Settings → General → Pull Requests** → tick both.119120### 3b. The remaining settings — what a clean team setup looks like on a personal-account repo121122None of these blocks a team; each removes a trap we either hit or saw coming. Read123the current value first, change only what differs, and say what you changed.124125| Setting | Set it to | Why | How |126|---|---|---|---|127| **Merge method** | one method only; keep **merge commits**, turn off rebase (squash is fine if the owner prefers one commit per pull request) | Rebase-merging rewrites the collaborators' commits, so the SHAs in their clones no longer match GitHub's, and the "Update branch" button then produces conflicts. One method means the button labels never change under a non-technical user. | `gh repo edit --enable-rebase-merge=false` (add `--enable-squash-merge=false` to keep merge commits only) |128| **Auto-merge** | **off** | "Enable auto-merge" merges the moment CI turns green, skipping the preview look that `AGENTS.md` §2 requires. | `gh repo edit --enable-auto-merge=false` |129| **Collaborator permission** | **write**, never maintain or admin | Write can push branches, open and merge pull requests; admin could change the settings this skill sets, or delete the repo. | §2 |130| **Visibility** | **private** (client work) | A public repo exposes drafts, `"[MISSING: …]"` placeholders and client photos before they are meant to be seen. Note: this is also what decides whether §5-A's ruleset is available for free. | `gh repo view --json visibility` |131| **Actions permissions** | **Allow all**, or narrow to **GitHub-owned and verified** | The kit's `ci.yml` uses only `actions/checkout` and `actions/setup-node`, so the narrow setting costs nothing and stops a collaborator's future workflow pulling an unvetted action. | Settings → Actions → General |132| **Actions minutes** (private repos) | know the budget: 2 000 free minutes/month on GitHub Free; the repo's **Actions** tab shows what each run takes. With **no payment method** on the account, GitHub blocks Actions once they are used up and charges nothing. **An Actions budget of 0 US dollars with Stop usage already on the account blocks private-repo jobs the same way, payment method or not**, with a message that reads like a failed payment ("recent account payments have failed or your spending limit needs to be increased") and jobs that start zero steps. Check **Budgets and alerts** for an existing **Actions** budget. If the owner wants CI to keep running past the free minutes, edit it to a small cap they choose (say $10) with **Stop usage when budget limit is reached** kept on; create one only if none is there. Do not pick the "Copilot AI Credits" budget, a different product that the list may show first. Whether CI starts again after the change is confirmed only by the next push ([GitHub Actions billing](https://docs.github.com/en/billing/concepts/product-billing/github-actions), [budgets](https://docs.github.com/en/billing/how-tos/set-up-budgets)) | Every push to a pull request or to `main` starts a run, and the minutes add up; at the limit CI either starts costing money or silently stops, and then "green before merge" stops meaning anything. The `concurrency` block in the kit's `ci.yml` cancels a superseded run on the same branch, so a quick second push stops the first run instead of letting it finish. | https://github.com/settings/billing → **Budgets and alerts**; usage on the same billing pages |133| **Fork workflows** | leave the default (require approval for first-time contributors) | Collaborators push branches, not forks, so this never triggers for them; it only guards against a stranger's fork running CI on your minutes. | Settings → Actions → General |134| **Workflow token** | leave **read-only** (default) | The kit's CI writes nothing to the repo. | Settings → Actions → General |135| **Dependabot** | **security updates on**; version updates: the starter ships a monthly grouped `.github/dependabot.yml`; keep it if someone merges the pull request, delete it if not (ask the owner who that is); a new major of any package but the two held back comes as its own pull request and may stay open | Security updates arrive as ordinary pull requests that CI checks; the monthly pull request is only worth having if someone reads it, and without the file security updates stay on. | Settings → Code security; `.github/dependabot.yml` |136| **Secret scanning + push protection** | **on** where the plan offers it (free on public repos; paid on private) | Catches a token pasted into a commit before it lands; the kit's `.gitignore` is the backstop either way. | Settings → Code security |137| **`production` branch** (two-stage) | protect against **deletion and force-push only** — no pull-request rule | `npm run ship` pushes `main:production` directly (a fast-forward push); a pull-request rule on `production` would break it. No ship has been seen through these two rules on a real site yet, so after the first one, check that it went through. By GitHub's documentation a fast-forward push is not a force push, "Block force pushes" stops force pushes only, and creating a branch is a separate rule ("Restrict creations") that this set does not use, so a normal ship should pass. Rulesets need a public repo or a paid plan: on a free private repo this one is refused like §5-A's, and `production` has no server-side protection at all. Where rulesets are available, GitHub documents a **Restrict updates** rule (only bypass actors may push) and lists the repository admin role as a bypass actor, which would make "who may ship" (§1 Q4) enforced; this is not yet tested on a real site, so until it is, "who may ship" stays a written rule in `AGENTS.md`. | second ruleset, §5-A shape with only the `deletion` and `non_fast_forward` rules, `include: ["refs/heads/production"]` |138| **Cloudflare GitHub App** | access to **this repo only** | The app gets read access to every repo it is granted; least privilege. | GitHub → Settings → Applications → Cloudflare Workers and Pages → Configure (see §6.2) |139| **2FA** | recommended, not required: each collaborator turns on two-factor sign-in and adds a passkey | The website is the owner's, and anyone who gets into a collaborator's account can change it, so recommend it to each collaborator in those words. Never make it a condition: a personal-account repo cannot require it (only organizations can), and GitHub itself requires it only for some accounts (it tells those by email and on the site). Do not count on GitHub prompting a collaborator who only edits content; `TEAM-GUIDE.md` gives them the link. There is nothing to check from your side: `gh api users/<login>` shows nothing about 2FA, and GitHub documents no 2FA marker on Settings → Collaborators for a personal-account repo, so if the owner wants to know, ask. | the collaborator, at https://github.com/settings/security |140| **Watching** | each collaborator watches the repo (at least "Participating and @mentions", the default) | Otherwise nobody sees a review comment or a failed check on their pull request. | the "Watch" button on the repo |141142Skipped on purpose: CODEOWNERS with required code-owner review (needs the paid143ruleset option on private repos and adds a review step the team did not ask for);144merge queues (paid); organization-level policies (this skill targets a repo on a145personal account — an organization owner has the equivalent settings under the146organization).147148## 4. Prove that CI starts on its own (do not skip)149150On the reference site the kit's workflow file had been on `main` for three weeks and151**had never run**: pushes to `main` produced no run at all, so "green checks before152merging" was an empty rule. What got it going was one manual start followed by a153throwaway pull request; afterwards every push and pull request ran normally. The root154cause was not pinned down (Actions permissions looked normal), so this skill does not155claim to prevent it — it **checks**, and if the check fails it does what worked:156157```bash158# a) Are Actions allowed at all?159gh api "repos/$OWNER/$REPO/actions/permissions" --jq '{enabled, allowed_actions}'160# b) Is the workflow listed, and active (not disabled_manually / disabled_inactivity)?161gh workflow list --all162gh workflow enable ci.yml # only if it shows as disabled163# c) Has it EVER run on a pull_request event? (push runs prove the file works, not the164# trigger the merge gate relies on — a workflow whose pull_request trigger is broken165# still shows green push runs on main)166gh run list --workflow ci.yml --event pull_request --limit 5167gh run list --workflow ci.yml --limit 5 # any run at all?168```169- (a) `enabled: false` → the owner turns it on: **Settings → Actions → General → Allow170 all actions**. GitHub also disables scheduled workflows after 60 days without repo171 activity; that does not apply to push/pull_request triggers, but a manually disabled172 workflow stays disabled until enabled.173- (c) no `pull_request` run → the throwaway pull request (step 2 below) is the174 proof; do step 1 as well when there is no run of any kind:175 ```bash176 gh workflow run ci.yml --ref main # 1. one manual start177 sleep 15 # the run takes a few seconds to appear; `gh run watch` needs its id178 id=$(gh run list --workflow ci.yml --event workflow_dispatch --limit 1 \179 --json databaseId --jq '.[0].databaseId')180 gh run watch "$id" --exit-status181 git switch --no-track -c ci/trigger-test origin/main # 2. throwaway pull request182 git commit --allow-empty -m "CI trigger test (will be closed)"183 git push -u origin ci/trigger-test184 gh pr create --title "CI trigger test (will be closed)" \185 --body "Empty commit; only checks whether pull_request triggers CI."186 sleep 20 # the first check run takes a moment to be reported; too early = "no checks reported"187 gh pr checks ci/trigger-test --watch188 ```189 A run with `event: pull_request` must appear:190 `gh run list --workflow ci.yml --branch ci/trigger-test --event pull_request`.191 Then close the pull request and delete the branch:192 `gh pr close ci/trigger-test --delete-branch`.193 The first manual run may be **red** for a real reason (a type error nobody had seen194 because the suite never ran in CI) — that is a finding, not a trigger problem; fix it195 in its own pull request.196- Still nothing after both steps → stop and report; do not declare CI working. A team197 merging on "green" that never runs is worse than no rule.198199While the throwaway pull request is open, look at its check list: if Cloudflare is200already connected (§6), it also proves "no leftover Workers Builds check" — see §6.2.201If Cloudflare is connected later, §6.2 opens a second one.202203## 5. Block direct pushes to `main`204205Two mechanisms, chosen by what the plan allows. Try the server-side one first: it is206the only one nobody can bypass.207208**A. Ruleset (public repo, or private repo on a paid plan).** Pull request required,209the CI job required to pass on an up-to-date branch, no force push, no deletion.210`test` is the job id in the kit's `ci.yml`; use the job's `name:` instead if one is set.211212```bash213# Re-run safe: create only if no ruleset of that name exists yet.214gh api "repos/$OWNER/$REPO/rulesets" --jq 'map(select(.name=="protect main")) | length'215# 0 → create:216gh api -X POST "repos/$OWNER/$REPO/rulesets" --input - <<'JSON'217{218 "name": "protect main",219 "target": "branch",220 "enforcement": "active",221 "bypass_actors": [],222 "conditions": { "ref_name": { "include": ["~DEFAULT_BRANCH"], "exclude": [] } },223 "rules": [224 { "type": "deletion" },225 { "type": "non_fast_forward" },226 { "type": "pull_request",227 "parameters": { "required_approving_review_count": 0,228 "dismiss_stale_reviews_on_push": false, "require_code_owner_review": false,229 "require_last_push_approval": false, "required_review_thread_resolution": false } },230 { "type": "required_status_checks",231 "parameters": { "strict_required_status_checks_policy": true,232 "required_status_checks": [ { "context": "test" } ] } }233 ]234}235JSON236gh api "repos/$OWNER/$REPO/rulesets" --jq '.[] | "\(.name) \(.enforcement)"'237```238**A ruleset that already exists is not proof.** A "protect main" left behind by an239earlier attempt, or edited in the dashboard since, may be looser than the one above240(a different check name, no up-to-date requirement, a bypass actor). So when the count241is not 0, read every one of them back (leftovers come in twos) and compare each with242the JSON above, rule by rule:243```bash244for id in $(gh api "repos/$OWNER/$REPO/rulesets" --jq '.[] | select(.name=="protect main") | .id'); do245 echo "== ruleset $id"246 gh api "repos/$OWNER/$REPO/rulesets/$id" \247 --jq '{enforcement, bypass_actors, conditions, rules: [.rules[] | {type, parameters}]}'248done249```250GitHub's answer also carries keys the recipe never sent. Those defaults are not251differences: in the `pull_request` rule `allowed_merge_methods` (all three),252`required_reviewers` (empty) and `require_extra_approval_for_unattributed_changes` (true),253in the `required_status_checks` rule `do_not_enforce_on_create` (false). GitHub's254[REST reference](https://docs.github.com/en/rest/repos/rules) lists all four. The255extra-approval key makes a pull request that Copilot opened for no person need one more256approval than the count; GitHub's rules page says it has no effect while the count is 0,257as here, and it starts to apply once the owner raises it. A value other than those defaults is a difference: ask the258owner if it is on purpose. Put all four keys in the PUT body, so the PUT does not decide259them: with the values the read-back showed, or the default for a key the owner says was260not on purpose. What a PUT that leaves them out does to them has not been checked.261Anything that differs — `enforcement` not `active`, a non-empty `bypass_actors`, a262missing rule, a `strict_required_status_checks_policy` that is not the owner's choice263(`true` unless the next paragraph applies), a `context` that is not the CI job's name — is fixed with264`gh api -X PUT "repos/$OWNER/$REPO/rulesets/$id" --input -`265and the same JSON body plus the four keys (it carries `"bypass_actors": []` explicitly, so a bypass list266is cleared rather than left as GitHub found it). Read it back once more after the PUT.267268**"Up to date" may be switched off, as the owner's choice.** With it on, every merge269leaves each other open pull request behind `main`: it needs **Update branch** and a new270CI run before it can merge. An owner who works alone but runs several assistant271sessions, each with its own pull request, pays that after every merge. With it off272(`"strict_required_status_checks_policy": false`) a pull request merges once its own CI273passed, and GitHub warns that checks may fail after the merge if two changes do not fit274([Available rules for rulesets](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets), "Loose");275the kit's `ci.yml` also runs on pushes to `main`, which usually shows such a failure (a276newer push can cancel a run, and a change to docs only skips the tests). Ask277the owner, don't decide. If they choose off, send `false` in the body, write the choice278in `AGENTS.md` §2 beside the merge rule, and let the read-back accept `false` where that279line is. We have not measured how much the requirement costs with several pull requests280open.281Two rulesets of that name: bring one in line, then delete the other with the owner's282go-ahead (`gh api -X DELETE "repos/$OWNER/$REPO/rulesets/<other id>"`) — two rulesets283on the same branch both apply, and the looser one still blocks nothing. Confirm the284`context` against the job in `ci.yml` (`test` unless the site renamed it); a wrong285name blocks every merge, because a check that never reports never passes.286287No bypass list: the rule applies to the owner too, which is the point. Dashboard288path: **Settings → Rules → Rulesets → New branch ruleset**. An approving review count of2890 keeps the gate "green CI + a human decided to merge", matching §1's merge rule; raise it290only if the owner wants a second pair of eyes on every change.291292**B. The refusal.** On a **private repo on a free plan** the request comes back293`403` with an "upgrade" message: GitHub offers no server-side branch protection294there. Say so plainly, then enable the local guard the kit already ships:295`scripts/hooks/pre-push` contains a commented-out **PR-only main** block (the six296lines from `while read` to `done`, marked OPTIONAL). First read the current state —297re-runs must not edit twice, and a site scaffolded before the block existed has no298block to uncomment at all:299```bash300grep -n '^while read -r _lref' scripts/hooks/pre-push && echo "already enabled"301grep -Eq '^(# )?while read -r _lref' scripts/hooks/pre-push || echo "no block in this hook — older kit; merge the kit's templates/astro/scripts/hooks/pre-push in first"302```303The second grep looks for the block's own first line, commented out or not — not for304the `ALLOW_MAIN_PUSH` word, which the prose comment above the block also contains.305No block (the second line fires): bring the site's hook up to the kit's306`templates/astro/scripts/hooks/pre-push` **by hand** in the setup pull request, the307way `whats-new.sh` treats every drift-tracked file (it reports the hook, never308rewrites it — same as `ci.yml` in §6.8). Diff the two first: on a stock hook they309differ by four additions — the stdin capture, the block, the deletion-only skip and310the publish-classifier step — and the order matters: the skip sits below the block,311or a push deleting `main` gets past it; the capture sits above both, or the skip312never fires. A site313that added a step of its own keeps it. Re-stamp afterwards, as for any hand-merged tracked314file. Then continue. Found this on the first real site the skill ran on: its hook315predated the block.316If it is not enabled: remove the leading `# ` from those six lines and replace only317the first sentence of the comment above them ("OPTIONAL: PR-only main flow …") with318the date and why it is on — keep the rest of that comment: it says why the block must319stay above the build steps. The hook's comments, its header and this one, are the320**source of truth for what bypasses the block**: `ALLOW_MAIN_PUSH=1`, the deliberate321override (above the block); `git push --no-verify` and unsetting `core.hooksPath`322(header); a clone that never ran `npm install`, since the `prepare` script is what323wires the hook; and a site that is not the root of its git repo, where `prepare` leaves324the hook unwired. Commit that in the setup pull request. Then325tell the owner, and write into `AGENTS.md` §2, what it is: a **local convention**,326with the bypasses quoted from the hook's comments, not from memory. `PUBLISHING.md`327tells the owner to push to `main` directly (to publish on a single-stage site, to328update the preview on a two-stage one), which the block now refuses: in the setup pull329request, point those steps at a pull request, with `ALLOW_MAIN_PUSH=1` named as the330owner's deliberate exception. It does not touch331`npm run ship` (which pushes `main:production`), nor GitHub's own merges, nor Codex332in the cloud (which only ever creates pull requests). It is the best a free private333repo gets, and it is enough when everyone follows `AGENTS.md`.334335**Verify — and not with a no-op push.** `git push origin main` with nothing to push336hands the hook nothing and sends GitHub nothing ("Everything up-to-date"), so it337"passes" both mechanisms without testing either. Instead:338```bash339# Ruleset (§5-A): read the effective rules back — must list pull_request and340# required_status_checks. A dry-run push never reaches GitHub's rules, so this341# read-back is the whole verification on a ruleset site.342gh api "repos/$OWNER/$REPO/rules/branches/main" --jq '.[].type'343344# Hook (§5-B ONLY — on a ruleset site the hook is off by design and this would345# print "NOT blocked"): a dry run of a real ref update — the hook runs, nothing is346# transferred. Branch from the SETUP branch, not origin/main: git runs the hook from347# the checked-out files, and until the setup pull request merges, origin/main still348# has the block commented out, so a check from there always says "NOT blocked".349git switch --no-track -c setup/push-check setup/team # the setup branch, block enabled350git commit --allow-empty -m "push-block check (never pushed)"351# The push is EXPECTED to fail, so test it as a condition — in a script run under352# `set -e` a bare failing push would abort before the cleanup line runs. Only the353# hook's own message counts as "blocked": a push can fail for other reasons.354if out="$(git push --dry-run origin HEAD:main 2>&1)"; then355 echo "NOT blocked — the hook is not active in this clone (npm install run? hooksPath set? site at the root of its repo?)"356elif grep -qF "Direct push to 'main' blocked" <<<"$out"; then357 echo "blocked as expected"358else359 echo "push failed for another reason — read it: $out"360fi361git switch - && git branch -D setup/push-check362```363364## 6. Cloudflare: connect the repo to GitHub — with the traps365366`new-website/references/CLOUDFLARE_FIRST_DEPLOY.md` has the bootstrap paths; a team367wants a project connected to GitHub (push-to-deploy, one preview address per pull368request). A site made with kit 0.35 or later is a **Worker**; a site made before may369still be on **Pages** (`AGENTS.md` and `PUBLISHING.md` say which; a `wrangler.jsonc` at370the repo root with `assets` in it is a Worker). The setup script there ("S") does not make the Worker or371connect the repository: with no Worker yet it says how to connect it in the dashboard (the372steps below, with the build command of item 4 and the production branch of item 5), and once a373build has made the Worker it reads it, changes the domain's settings and attaches the domain on374launch day. It does not create the `production` branch (item 5) or touch the checks of375items 2 and 8. The connection is **B, Workers Builds** (a site still on Pages: "Sites already on376Pages" in the same guide, and the Pages form of each item below): walk the owner through it377with these warnings ahead of each click:3783791. **The right project type.** In the Cloudflare dashboard, **Workers & Pages → Create**380 opens on the **Workers** tab, and its "Import a repository" creates a **Worker** with381 *Workers Builds*: the right type for a new site. For a site that is on Pages, use the382 **Pages** tab and **Connect to Git** instead; Cloudflare cannot turn one into the other383 (item 9). If the owner already runs other Workers in the account, the build token384 (item 4) reaches all of them: a separate Cloudflare account for the site is the safe385 way, and it is the owner's call.3862. **The wrong type leaves a check behind.** A Worker made for a site that is on Pages (or a387 Pages project made for a Worker site) keeps posting its build check on every pull request,388 pending or failing forever, even after the project is deleted. Disconnect it first (a389 Worker: **Settings → Builds → disconnect**; a Pages project: delete it), then prove the390 pull request shows only the **CI** check and the one Cloudflare build check of this391 site's type: open a throwaway pull request **after** connecting (the §4 recipe: empty392 commit, close and delete afterwards). The check's exact name on a Worker is not checked.393 If the other type's check is still there, the GitHub App installation still carries the394 trigger: GitHub → **Settings → Applications → Cloudflare Workers and Pages →395 Configure** → check which repos it may access, and remove and re-add the repo if396 needed.3973. **The name and the preview address.** A Worker's name comes from `name` in398 `wrangler.jsonc`; it must be unique only inside the account. Its Preview links look like399 `https://<prefix>-<worker>.<account>.workers.dev`: read one on the Worker's page (or in400 the setup script's report), and write it into `AGENTS.md` (header + §2), `PUBLISHING.md`401 and the README's deploy section. A **Pages** project's name is global instead:402 `<name>.pages.dev` is one namespace across all Cloudflare accounts, so the obvious name403 may be taken with no explanation beyond a validation error. Pick a short alternative; it404 only changes the preview address, which is not always the name followed by `.pages.dev`:405 read it on the project's page. Either way, search the repo for the old address406 (`git grep -n '<old-name>.pages.dev'`, a site may have it in `src/config.ts`), so nobody407 quotes a preview address that does not exist.4084. **Build settings.** A Worker: build command `npm run build`; what to deploy comes from409 `wrangler.jsonc`. **The build token:** pick **Create new token** in the build's token field,410 not an existing one, and cut it down in place (the guide's B section names the rows). Node411 version comes from the repo's `.nvmrc` (Workers Builds reading it is from the docs, not seen412 on a build). A Pages project: framework preset **Astro**, build command `npm run build`,413 output directory `dist`, Node from `.nvmrc`.4145. **Production branch = the publish model.** Two-stage: **`production`** (create the415 branch first if it does not exist yet, see `new-website` §4), so `main` stays the416 noindexed preview. Single-stage: `main` — and then set `PROD_BRANCH = 'main'` in417 `src/config.ts` in the setup pull request (the kit ships `'production'`), because418 analytics, once switched on, fires only when the two agree, silently never419 otherwise. `AGENTS.md` §2 must keep the block that matches (the other one is420 deleted at scaffold time — check it was).4216. **Pull request previews.** Once connected, every pull request gets its own preview422 address from its build: a Worker's Preview link (where Cloudflare posts it is not423 checked), or on Pages "Cloudflare Pages" → *View deployment*, plus the stable alias424 `<branch>.<project>.pages.dev`. `AGENTS.md` §2 tells collaborators to look there before425 merging. A Worker's previews carry `noindex` from Cloudflare, a Pages site's from the426 kit's `functions/_middleware.ts` (a site made before 0.35); both are public-by-URL (see427 `PUBLISHING.md`).4287. **Single-stage sites: a merge publishes.** Anything that runs only in429 `npm run ship` on this site must now run in CI, or it never runs. The kit's own430 `ship.sh` runs no tests (the pre-push hook and CI do), so a stock site has nothing431 to move; a site that added a ship-only gate of its own moves that command into432 `ci.yml` in the setup pull request.4338. **Placeholder gate — check the site actually has it.** The kit's `ci.yml` greps434 `src/` and `public/` for `"[MISSING: …]"` before the build, but only sites435 scaffolded after that step existed carry it: `whats-new.sh` reports drift in436 `ci.yml`, it never rewrites it. So `AGENTS.md`'s merge rule ("no placeholder is437 left") is enforced only if the step is there. First find out which **token** this438 site uses: `AGENTS.md` §4 names it, and a site with non-English content may use its own word439 (a German site might write `"[FEHLT: …]"`); the kit's step greps for `[MISSING:`440 and matches nothing else. Then check for the step itself — its `grep -rnI` line,441 not any mention of the word in a comment — add it if missing with the site's442 token in the pattern, and prove it fires before calling the setup done:443 ```bash444 grep -nF "grep -rnI" .github/workflows/ci.yml \445 || echo "placeholder step missing — copy it from the kit's templates/astro/.github/workflows/ci.yml and put this site's token in the pattern"446 ```447 Then plant one: a scratch branch with the site's own token (`"[MISSING: probe]"`,448 or `"[FEHLT: probe]"` on that German site) in any page, push it and open a **draft**449 pull request from it (the kit's CI runs on pushes only for `main` and `production`,450 so a pushed branch alone starts no check), watch the check turn red **at the step451 `No unfilled "[MISSING:" placeholders`**, then close the pull request and delete the452 branch. Red only later, at `npm test`, is `tests/placeholders.spec.ts` speaking: the453 grep step is missing or greps for another word. A push the hook refuses means the454 site's token is not the one in that spec's `DRAFT_TOKEN`; set it there too. A gate that has never fired is a hypothesis, and a gate455 probed with the wrong token proves the wrong thing.4569. **A project of the other kind, or a direct-upload one, already exists.** Cloudflare cannot457 turn a direct-upload project into a git-connected one, nor a Pages project into a Worker.458 A Worker first deployed by command: whether it can be connected to the repository later is not459 checked; the safe route is a new Worker connected to the repository, then move460 the custom domain. A Pages site: create the git-connected project under a new name, let it461 build once, remove the domain from the old project (one Pages project at a time), attach it462 to the new one (Custom domains → Set up a domain), wait for Active, and only then delete the463 old project. Do it in a quiet moment and check the live domain with a cache-bust464 (`PUBLISHING.md` § "For AI assistants"). The Pages sequence follows Cloudflare's465 documentation and was not exercised on the reference site.466467Verify: after the first merge, `<live-or-preview-url>/build.txt` shows the merge468commit id (the kit's build marker). Say which address is the **preview** and which is469**live** every time you quote one (`PUBLISHING.md` § "For AI assistants").470471## 7. Rights and publish rights in `AGENTS.md`472473Rewrite the four lines at the top of §5 from the §1 answers: collaborators (GitHub474usernames only, no emails), rights level, merge rule, and who publishes live475(two-stage) — or delete the publish line on a single-stage site. If §5-B enabled the476hook, add one sentence to §2 saying the block is local, with the bypasses quoted477from the hook's own comment block (§5-B). If §2 still says "The assistant never478merges" (a site scaffolded before the assistant could merge on request), replace that479bullet with the template's "Merging" bullet, or the guide in §8 promises what480`AGENTS.md` forbids. Read the whole481file once more: no `[BRACKET]` slot and no scaffold note may remain, and the publish482model block must match Cloudflare's production branch (§6.5).483484## 8. The collaborators' guide485486Copy `templates/TEAM-GUIDE.md` from this skill into the repo root as `TEAM-GUIDE.md`,487keep the part(s) that match §1's answer 5 (browser / local / both), fill every488`[BRACKET]` slot — site name, owner/repo, the owner's name for "who to ask" (a name,489never an email), the merge step in the numbered instructions and the Merge row490(`[MERGE_STEP]`, `[MERGE_RULE]`, both from §1 answer 3), and the "what merge does"491line (`[MERGE_MEANS]` with `[PREVIEW_URL]`, `[LIVE_URL]`, `[SHIP_RIGHTS]` from492answer 4; single-stage sites keep the "goes live" half) — and translate if the team's493language is not English. It is deliberately one page: where to start, the four moves494per task, when to ask.495496## 9. Hand over497498- Open the setup pull request (branch `setup/team`), describe in plain words: who was499 invited, which settings are on, how CI was proven, which push block is active and500 what it covers, the Cloudflare project and its addresses, the rights level, the501 publish rule. Note the `scripts/` and `AGENTS.md` changes explicitly (`AGENTS.md` §5).502- The owner merges it per the new rule, on GitHub or by telling the assistant to (this503 skill does not merge it unasked), then tells the504 collaborators to accept the invitation and read505 `TEAM-GUIDE.md`. Their first task: something small, so the whole loop (fetch, branch,506 pull request, green checks, preview, merge) is exercised once with the owner around.507508Re-running the skill is safe: every step reports the current state before changing509anything, and none of §§2–6 creates a second copy of what exists.