docs: document one-time fork setup (Pages + Actions PRs + Template toggle) - #10
Conversation
Reverts the enablement: true in deploy-pages.yml because the default GITHUB_TOKEN can't create a Pages site (it would need administration: write, which violates the least-privilege stance we just adopted for the Token-Permissions Scorecard findings). Instead, document the one-time setup clearly: - README.md: new 'After forking: one-time repo setup' section right under the 'Use this template' call-out, covering Pages enablement, Actions-can-open-PRs, and the Template repository toggle. - BUILD_THE_GAME.md: same three settings as a table in Step 3.5, with CLI equivalents for users who prefer gh api. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
agjs
changed the title
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request adds documentation for essential one-time repository configuration steps required after forking, including settings for GitHub Pages, Actions permissions, and template repository status. These instructions are added to both README.md and BUILD_THE_GAME.md. The review feedback suggests improving the provided GitHub CLI commands by using :owner/:repo placeholders, which allows the CLI to automatically substitute the correct values for the user.
|
|
||
| ```sh | ||
| # Pages (Source = Actions) — needs a PAT with `administration: write` | ||
| gh api -X POST /repos/<owner>/<repo>/pages -f 'build_type=workflow' |
There was a problem hiding this comment.
Using the :owner/:repo placeholders in the gh api command allows the GitHub CLI to automatically substitute the current repository's owner and name. This makes the command copy-pasteable for users who have already cloned the repository, removing the need for manual string replacement.
| gh api -X POST /repos/<owner>/<repo>/pages -f 'build_type=workflow' | |
| gh api -X POST /repos/:owner/:repo/pages -f 'build_type=workflow' |
| gh api -X PUT /repos/<owner>/<repo>/actions/permissions/workflow \ | ||
| -f default_workflow_permissions=write -F can_approve_pull_request_reviews=true |
There was a problem hiding this comment.
Similar to the Pages setup, leveraging :owner/:repo here enables automatic substitution by the gh CLI, streamlining the setup process for developers.
| gh api -X PUT /repos/<owner>/<repo>/actions/permissions/workflow \ | |
| -f default_workflow_permissions=write -F can_approve_pull_request_reviews=true | |
| gh api -X PUT /repos/:owner/:repo/actions/permissions/workflow \ | |
| -f default_workflow_permissions=write -F can_approve_pull_request_reviews=true |
There was a problem hiding this comment.
Pull request overview
Documents the required one-time GitHub repository settings for new repos created from this template, and removes Pages auto-enablement in the Pages deploy workflow to maintain least-privilege GITHUB_TOKEN permissions.
Changes:
- Add “one-time repo setup” instructions to
README.mdafter the template usage callout. - Add a Step 3.5 settings table +
gh apiequivalents toBUILD_THE_GAME.md. - Remove
enablement: truefromdeploy-pages.ymland explain the manual Pages enablement requirement.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| README.md | Adds quick, prominent one-time repo setup steps for template users. |
| BUILD_THE_GAME.md | Adds detailed per-repo settings guidance + CLI alternatives. |
| .github/workflows/deploy-pages.yml | Stops auto-enabling Pages; adds rationale comment aligned with least privilege. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| ### After forking: one-time repo setup | ||
|
|
||
| 1. **Enable GitHub Pages** — `Settings → Pages → Build and deployment → Source: "GitHub Actions"`. Without this the `deploy-pages` workflow 404s on the first run. | ||
| 2. **Allow Actions to open PRs** (so release-please can cut release PRs) — `Settings → Actions → General → Workflow permissions → [x] Allow GitHub Actions to create and approve pull requests`. |
There was a problem hiding this comment.
The UI path for enabling release-please is missing the required “Workflow permissions: Read and write permissions” selection. If the repo default is read-only, the release-please workflow’s requested contents: write / pull-requests: write permissions won’t be granted, and it won’t be able to open/update the release PR. Suggest updating this step to mention selecting “Read and write permissions” (and optionally keeping the PR checkbox as a separate sub-step).
| 2. **Allow Actions to open PRs** (so release-please can cut release PRs) — `Settings → Actions → General → Workflow permissions → [x] Allow GitHub Actions to create and approve pull requests`. | |
| 2. **Allow Actions to open PRs** (so release-please can cut release PRs) — `Settings → Actions → General → Workflow permissions → Select "Read and write permissions"`, then enable `[x] Allow GitHub Actions to create and approve pull requests`. |
| | Setting | Path | Why | | ||
| | --- | --- | --- | | ||
| | **Pages** | Settings → Pages → Build and deployment → Source: **"GitHub Actions"** | The `deploy-pages` workflow 404s without this; the workflow can't enable Pages itself without a broader token. | | ||
| | **Actions may open PRs** | Settings → Actions → General → Workflow permissions → **[x] Allow GitHub Actions to create and approve pull requests** | So `release-please` can cut release PRs from conventional commits. | |
There was a problem hiding this comment.
This section points to the “Allow GitHub Actions to create and approve pull requests” checkbox, but it doesn’t mention setting “Workflow permissions” to “Read and write permissions”. With the default set to read-only, workflows can’t elevate to contents: write / pull-requests: write, which would break release-please PR creation. Suggest updating the row (or adding a note) to include both the read/write radio option and the checkbox.
| | **Actions may open PRs** | Settings → Actions → General → Workflow permissions → **[x] Allow GitHub Actions to create and approve pull requests** | So `release-please` can cut release PRs from conventional commits. | | |
| | **Actions may open PRs** | Settings → Actions → General → Workflow permissions → **Read and write permissions**; then **[x] Allow GitHub Actions to create and approve pull requests** | So workflows can actually get `contents: write` / `pull-requests: write`, and `release-please` can cut release PRs from conventional commits. | |
| > **Use this as a GitHub template.** Click **"Use this template"** on the repo page, fork it into a new repo for each game, then read [`BUILD_THE_GAME.md`](./BUILD_THE_GAME.md) to walk from empty fork to shipped feature. | ||
|
|
||
| ### After forking: one-time repo setup |
There was a problem hiding this comment.
This section says “After forking”, but the instructions immediately above are to use the repo as a template (“Use this template”), which creates a new repo rather than a GitHub fork. Consider renaming this heading/wording to “After creating your repo from the template” to avoid confusion (especially since GitHub’s UI distinguishes forks vs template-generated repos).
| > **Use this as a GitHub template.** Click **"Use this template"** on the repo page, fork it into a new repo for each game, then read [`BUILD_THE_GAME.md`](./BUILD_THE_GAME.md) to walk from empty fork to shipped feature. | |
| ### After forking: one-time repo setup | |
| > **Use this as a GitHub template.** Click **"Use this template"** on the repo page, create a new repo from this template for each game, then read [`BUILD_THE_GAME.md`](./BUILD_THE_GAME.md) to walk from empty repo to shipped feature. | |
| ### After creating your repo from the template: one-time repo setup |
Summary
Replaces the failed
enablement: trueapproach in #8 with honest documentation.The problem
actions/configure-pagescan't create a Pages site with the defaultGITHUB_TOKEN— that needsadministration: write, which we intentionally don't grant (would violate the Token-Permissions least-privilege posture we just landed).enablement: trueturned the old 404 ("no Pages site") into a 403 ("can't create"), not a fix.This PR
enablement: truefromdeploy-pages.yml, adds a comment explaining why.README.md: new "After forking: one-time repo setup" section under the template call-out.BUILD_THE_GAME.md: same three settings as a table in Step 3.5, with CLI equivalents.The three settings:
Test plan
deploy-pagesrun should succeed and publish tohttps://agjs.github.io/Phaser-TypeScript-AI-First-Starter/