test+hardening: zero-dep bash test suite, strict lint, PAT docs

- tests/: unit (validation/injection guards) + e2e (merge/no-op/dry-run/reset/rebase/token-masking)
  running the real script against throwaway local git repos
- fix: rebase mode rewrites history -> force-push (lease) like reset (caught by tests)
- scripts/sync.sh now passes shellcheck --enable=all --severity=style
- CI runs shellcheck (strict) + actionlint + the test suite
- docs/github-pat-setup.md: click-by-click least-privilege fine-grained PAT guide
- README: dev/test section, sync-mode + token doc links

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: mikeumus

.github/workflows/ci.yml

@@ -14,11 +14,21 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - name: ShellCheck
-        run: shellcheck scripts/sync.sh
+      - name: ShellCheck — production script (all optional checks)
+        run: shellcheck --enable=all --severity=style scripts/sync.sh
+
+      - name: ShellCheck — test suite
+        run: shellcheck -x tests/*.sh
 
       - name: Bash syntax check
         run: bash -n scripts/sync.sh
 
       - name: actionlint
         uses: raven-actions/actionlint@v2
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run test suite
+        run: bash tests/run.sh

README.md

@@ -102,11 +102,12 @@ jobs:
 | Mode | What it does | When to use |
 |------|--------------|-------------|
 | `merge` *(default)* | Merges `upstream/<branch>` into your target, creating a merge commit when histories diverge. | You keep your own commits on the fork and want upstream changes merged in. |
-| `rebase` | Replays your target's commits on top of upstream. | You keep a small, linear set of changes on top of upstream. |
+| `rebase` | Replays your target's commits on top of upstream, then force-pushes (`--force-with-lease`). | You keep a small, linear set of changes on top of upstream. |
 | `reset` | Hard-resets the target to **exactly** match upstream, then force-pushes (`--force-with-lease`). | An "untouched" mirror fork — discard any divergence and track upstream verbatim. |
 
-> `reset` rewrites your branch history and force-pushes. Only use it on a branch
-> you keep pristine for upstream tracking.
+> Both `rebase` and `reset` rewrite the target branch's history and therefore
+> force-push (lease-guarded). Only use them on a branch you keep for upstream
+> tracking, not one others push to. `merge` never force-pushes.
 
 ## Recipe: auto-deploy a customer's Cloudflare Worker from a fork
 
@@ -116,10 +117,11 @@ The fork syncs itself (triggered instantly, or on a schedule) and Cloudflare
 Workers Builds deploys on the resulting push.
 
 See **[docs/cloudflare-fork-deploy.md](docs/cloudflare-fork-deploy.md)** for the
-full two-sided setup, including least-privilege token scopes and the
-`.github/workflows/` push caveat. Ready-to-copy workflows are in
-[`examples/origin-repo`](examples/origin-repo) and
-[`examples/customer-fork`](examples/customer-fork).
+full two-sided setup, including the `.github/workflows/` push caveat, and
+**[docs/github-pat-setup.md](docs/github-pat-setup.md)** for the click-by-click
+guide to creating the GitHub tokens with the right (least-privilege) scopes.
+Ready-to-copy workflows are in [`examples/origin-repo`](examples/origin-repo)
+and [`examples/customer-fork`](examples/customer-fork).
 
 ## Private upstreams
 
@@ -150,6 +152,20 @@ This action was written from scratch, inspired by the idea behind earlier
 fork-sync actions but sharing none of their code, specifically so the entire
 trust surface is a single short shell script you can review yourself.
 
+## Development
+
+The whole action is [`scripts/sync.sh`](scripts/sync.sh). Tests are plain bash
+with no dependencies — they run the real script against throwaway local git
+repos.
+
+```bash
+bash tests/run.sh          # unit (validation/injection) + e2e (merge/rebase/reset/dry-run)
+shellcheck --enable=all --severity=style scripts/sync.sh
+actionlint
+```
+
+CI runs all three on every push and PR.
+
 ## License
 
 [MIT](LICENSE) © Divinci AI

docs/cloudflare-fork-deploy.md

@@ -51,6 +51,9 @@ We trigger the fork with `workflow_dispatch` (Actions: write) rather than
 `repository_dispatch` (which would require the broader Contents: write) on
 purpose — the dispatch token can start a workflow but can touch nothing else.
 
+> **Creating these tokens:** see **[github-pat-setup.md](github-pat-setup.md)**
+> for the exact fine-grained PAT steps and per-token permission selections.
+
 ### The `.github/workflows/` push caveat
 
 A workflow's default `GITHUB_TOKEN` **cannot push changes to files under

docs/github-pat-setup.md

@@ -0,0 +1,119 @@
+# Creating the GitHub tokens (with the right scopes)
+
+This action moves commits between two repositories that GitHub treats as
+independent, so one or two scoped tokens cross the boundary. This page is the
+exact, click-by-click recipe for creating them as **fine-grained personal
+access tokens** with the **least privilege** that works.
+
+> **Use fine-grained tokens, not classic.** A classic PAT with the `repo` scope
+> would work, but it grants read/write to *every* repo the creator can access.
+> Fine-grained tokens are scoped to a single repository and a single
+> permission, which is what you want here.
+
+## Which token(s) you need
+
+| Token | Needed when | Created by | Lives in | Single permission |
+|-------|-------------|------------|----------|-------------------|
+| **`FORK_DISPATCH_TOKEN`** | Always (instant-dispatch trigger) | **Customer** | The **upstream** repo's Actions secrets | **Actions: Read and write** on the fork |
+| **`UPSTREAM_READ_TOKEN`** | Only if the upstream repo is **private** | **Divinci** | The **fork's** Actions secrets | **Contents: Read-only** on the upstream |
+| **`FORK_PUSH_TOKEN`** | Only if the upstream changes files under `.github/workflows/` | **Customer** | The **fork's** Actions secrets | **Contents: Read and write** + **Workflows: Read and write** on the fork |
+
+If you use the polling trigger instead of instant dispatch, you need **none**
+of these for a *public* upstream — the fork's built-in `GITHUB_TOKEN` is enough.
+
+---
+
+## Step 1 — Generate a fine-grained PAT
+
+The flow is identical for every token; only the **resource owner**,
+**repository**, and **permission** differ (see Step 2).
+
+1. Sign in as the account that should *own* the token (see the table — the
+   customer for `FORK_DISPATCH_TOKEN`, Divinci for `UPSTREAM_READ_TOKEN`).
+2. Go to **GitHub → your avatar → Settings → Developer settings → Personal
+   access tokens → Fine-grained tokens**
+   (direct link: <https://github.com/settings/personal-access-tokens/new>).
+3. **Token name:** something obvious, e.g. `sync-fork-dispatch (customer X)`.
+4. **Resource owner:** if the repo belongs to an organization, pick that org
+   here (not your personal account). Org-owned tokens may need an org admin to
+   approve them before they work.
+5. **Expiration:** set a real expiry (e.g. 90 days) and calendar a renewal.
+   Avoid "No expiration".
+6. **Repository access → Only select repositories →** choose the **single**
+   repository this token is for (the fork, or the upstream — see the table).
+7. Set the permission from **Step 2**, then **Generate token** and **copy it
+   now** (you can't see it again).
+
+> **SAML/SSO orgs:** after creating the token, you may need to click
+> **Configure SSO → Authorize** next to the token so it can access org repos.
+
+---
+
+## Step 2 — The exact permission per token
+
+Fine-grained tokens default every permission to **No access**. Change only the
+one listed below; leave everything else at No access.
+
+### `FORK_DISPATCH_TOKEN` (customer → upstream)
+- Repository access: **the customer's fork only**
+- **Repository permissions → Actions → Read and write**
+
+That is all it can do: start workflows. It **cannot read or modify code**. We
+trigger the fork with `workflow_dispatch` precisely so this token stays this
+small. (A `repository_dispatch` trigger would instead require the broader
+*Contents: write* — which is why we don't use it.)
+
+### `UPSTREAM_READ_TOKEN` (Divinci → fork) — private upstream only
+- Repository access: **the upstream (Divinci) repo only**
+- **Repository permissions → Contents → Read-only**
+
+Lets the fork `git fetch` the private upstream. Read, one repo, nothing else.
+
+### `FORK_PUSH_TOKEN` (customer → fork) — only if syncing workflow files
+- Repository access: **the customer's fork only**
+- **Repository permissions → Contents → Read and write**
+- **Repository permissions → Workflows → Read and write**
+
+Only needed because a workflow's built-in `GITHUB_TOKEN` is **not allowed to
+push changes to `.github/workflows/`**. If the upstream never changes its
+workflow files, you don't need this token.
+
+---
+
+## Step 3 — Store each token as a repository secret
+
+Put each token in the repo named in the table (**not** the repo where it was
+created, unless they're the same):
+
+1. Open that repo → **Settings → Secrets and variables → Actions**.
+2. **New repository secret**.
+3. **Name** it exactly as in the table (`FORK_DISPATCH_TOKEN`, etc.).
+4. Paste the token value → **Add secret**.
+
+The workflows reference them as `${{ secrets.FORK_DISPATCH_TOKEN }}` and so on.
+
+---
+
+## Step 4 — Verify
+
+Push a trivial commit to the upstream's default branch and watch:
+
+- Upstream **Actions** tab → `Notify forks` succeeds. If it 404s or says
+  "Resource not accessible", the `FORK_DISPATCH_TOKEN` is missing the
+  **Actions: write** permission, points at the wrong repo, or (org) needs SSO
+  authorization.
+- Fork **Actions** tab → `Sync from upstream` runs and pushes.
+- A `403`/`could not read Username` during the upstream fetch means the upstream
+  is private and `UPSTREAM_READ_TOKEN` is missing or under-scoped.
+- A push error mentioning `refusing to allow ... workflow` means a workflow file
+  changed and you need `FORK_PUSH_TOKEN` (see Step 2).
+
+---
+
+## Rotating and revoking
+
+- Tokens expire on the date you set — renew by generating a new one and updating
+  the secret. Nothing else changes.
+- To revoke immediately: the owning account → **Settings → Developer settings →
+  Fine-grained tokens →** the token → **Delete**. The dependent sync simply
+  stops working until replaced; nothing is damaged.

scripts/sync.sh

@@ -32,15 +32,19 @@ log() { echo "==> $*"; }
 # Masks the encoded credential so it never appears in logs.
 set_github_auth() {
   local token="$1"
-  [ -n "$token" ] || return 0
+  [[ -n "${token}" ]] || return 0
   local encoded
-  encoded="$(printf 'x-access-token:%s' "$token" | base64 | tr -d '\n')"
+  encoded="$(printf 'x-access-token:%s' "${token}" | base64 | tr -d '\n')"
   echo "::add-mask::${encoded}"
   git config --local "http.https://github.com/.extraheader" "AUTHORIZATION: basic ${encoded}"
 }
 
 emit_output() { echo "$1=$2" >> "${GITHUB_OUTPUT:-/dev/null}"; }
 
+# Branch names: allow common ref characters, but reject anything starting with
+# '-' (option injection) so they cannot be read as git flags.
+valid_ref() { [[ "$1" =~ ^[A-Za-z0-9._/-]+$ ]] && [[ "$1" != -* ]]; }
+
 # ----------------------------------------------------------------------------
 # Validate and normalize inputs
 # ----------------------------------------------------------------------------
@@ -50,30 +54,31 @@ TARGET_BRANCH="${INPUT_TARGET_BRANCH:-}"
 SYNC_MODE="${INPUT_SYNC_MODE:-merge}"
 DRY_RUN="${INPUT_DRY_RUN:-false}"
 
-[ -n "${INPUT_UPSTREAM_REPOSITORY:-}" ] || die 'Missing required input: upstream_repository'
-[ -n "$UPSTREAM_BRANCH" ] || die 'Missing required input: upstream_branch'
-[ -n "$TARGET_BRANCH" ]   || die 'Missing required input: target_branch'
+[[ -n "${INPUT_UPSTREAM_REPOSITORY:-}" ]] || die 'Missing required input: upstream_repository'
+[[ -n "${UPSTREAM_BRANCH}" ]] || die 'Missing required input: upstream_branch'
+[[ -n "${TARGET_BRANCH}" ]]   || die 'Missing required input: target_branch'
 
-# Resolve the upstream URL. Accept "owner/repo" or a full https URL only.
-# Patterns are held in variables to avoid shell-quoting surprises, and the URL
-# set is deliberately conservative (no shell metacharacters allowed).
-url_re='^https://[A-Za-z0-9._~:/?#@%-]+$'
+# Resolve the upstream URL. Accept "owner/repo", a full https URL, or a file://
+# URL (the last is used by the test suite to sync from a local repo). Patterns
+# are held in variables to avoid shell-quoting surprises, and the URL set is
+# deliberately conservative — no shell metacharacters are allowed.
+url_re='^(https|file)://[A-Za-z0-9._~:/?#@%-]+$'
 slug_re='^[A-Za-z0-9._-]+/[A-Za-z0-9._-]+$'
-if [[ "$INPUT_UPSTREAM_REPOSITORY" =~ $url_re ]]; then
-  UPSTREAM_URL="$INPUT_UPSTREAM_REPOSITORY"
-elif [[ "$INPUT_UPSTREAM_REPOSITORY" =~ $slug_re ]]; then
+if [[ "${INPUT_UPSTREAM_REPOSITORY}" =~ ${url_re} ]]; then
+  UPSTREAM_URL="${INPUT_UPSTREAM_REPOSITORY}"
+elif [[ "${INPUT_UPSTREAM_REPOSITORY}" =~ ${slug_re} ]]; then
   UPSTREAM_URL="https://github.com/${INPUT_UPSTREAM_REPOSITORY}.git"
 else
   die "Invalid upstream_repository: '${INPUT_UPSTREAM_REPOSITORY}'. Use 'owner/repo' or a full https URL."
 fi
 
-# Branch names: allow common ref characters, but reject anything starting with
-# '-' (option injection) so they cannot be read as git flags.
-valid_ref() { [[ "$1" =~ ^[A-Za-z0-9._/-]+$ ]] && [[ "$1" != -* ]]; }
-valid_ref "$UPSTREAM_BRANCH" || die "Invalid upstream_branch: '${UPSTREAM_BRANCH}'"
-valid_ref "$TARGET_BRANCH"   || die "Invalid target_branch: '${TARGET_BRANCH}'"
+# valid_ref is a pure predicate meant for use in conditionals (SC2310 N/A).
+# shellcheck disable=SC2310
+if ! valid_ref "${UPSTREAM_BRANCH}"; then die "Invalid upstream_branch: '${UPSTREAM_BRANCH}'"; fi
+# shellcheck disable=SC2310
+if ! valid_ref "${TARGET_BRANCH}";   then die "Invalid target_branch: '${TARGET_BRANCH}'"; fi
 
-case "$SYNC_MODE" in
+case "${SYNC_MODE}" in
   merge|rebase|reset) ;;
   *) die "Invalid sync_mode: '${SYNC_MODE}'. Expected merge, rebase, or reset." ;;
 esac
@@ -100,25 +105,25 @@ set_github_auth "${INPUT_GITHUB_TOKEN:-}"
 
 log "Adding upstream remote: ${UPSTREAM_URL}"
 git remote remove upstream >/dev/null 2>&1 || true
-git remote add upstream "$UPSTREAM_URL"
+git remote add upstream "${UPSTREAM_URL}"
 
 log "Fetching origin/${TARGET_BRANCH}"
-git fetch --no-tags origin "$TARGET_BRANCH"
+git fetch --no-tags origin "${TARGET_BRANCH}"
 
 log "Fetching upstream/${UPSTREAM_BRANCH}"
 # If an upstream_token is set, use it just for this fetch, then restore the
 # push token. Single auth header at all times — no double-Authorization.
-if [ -n "${INPUT_UPSTREAM_TOKEN:-}" ]; then
+if [[ -n "${INPUT_UPSTREAM_TOKEN:-}" ]]; then
   set_github_auth "${INPUT_UPSTREAM_TOKEN}"
 fi
 # shellcheck disable=SC2086  # intentional word-splitting of trusted fetch_args
-git fetch --no-tags ${INPUT_FETCH_ARGS:-} upstream "$UPSTREAM_BRANCH"
-if [ -n "${INPUT_UPSTREAM_TOKEN:-}" ]; then
+git fetch --no-tags ${INPUT_FETCH_ARGS:-} upstream "${UPSTREAM_BRANCH}"
+if [[ -n "${INPUT_UPSTREAM_TOKEN:-}" ]]; then
   set_github_auth "${INPUT_GITHUB_TOKEN:-}"
 fi
 
 # Reset our local target branch to match origin exactly, as the base to sync.
-git checkout -B "$TARGET_BRANCH" "origin/${TARGET_BRANCH}"
+git checkout -B "${TARGET_BRANCH}" "origin/${TARGET_BRANCH}"
 
 # ----------------------------------------------------------------------------
 # Determine whether there is anything to sync
@@ -127,10 +132,10 @@ git checkout -B "$TARGET_BRANCH" "origin/${TARGET_BRANCH}"
 UPSTREAM_SHA="$(git rev-parse "upstream/${UPSTREAM_BRANCH}")"
 COMMIT_COUNT="$(git rev-list --count "HEAD..upstream/${UPSTREAM_BRANCH}")"
 
-emit_output upstream_sha "$UPSTREAM_SHA"
-emit_output commit_count "$COMMIT_COUNT"
+emit_output upstream_sha "${UPSTREAM_SHA}"
+emit_output commit_count "${COMMIT_COUNT}"
 
-if [ "$COMMIT_COUNT" -eq 0 ]; then
+if [[ "${COMMIT_COUNT}" -eq 0 ]]; then
   log "Already up to date with upstream/${UPSTREAM_BRANCH}. Nothing to sync."
   emit_output has_new_commits false
   {
@@ -148,7 +153,7 @@ git --no-pager log --oneline "HEAD..upstream/${UPSTREAM_BRANCH}" | sed 's/^/
 # Dry run stops here
 # ----------------------------------------------------------------------------
 
-if [ "$DRY_RUN" = "true" ]; then
+if [[ "${DRY_RUN}" == "true" ]]; then
   log "dry_run=true — not integrating or pushing."
   {
     echo "### Sync Fork Action (dry run)"
@@ -162,7 +167,7 @@ fi
 # ----------------------------------------------------------------------------
 
 log "Integrating with sync_mode='${SYNC_MODE}'"
-case "$SYNC_MODE" in
+case "${SYNC_MODE}" in
   merge)
     # shellcheck disable=SC2086  # intentional word-splitting of trusted merge_args
     git merge --no-edit ${INPUT_MERGE_ARGS:-} "upstream/${UPSTREAM_BRANCH}"
@@ -174,15 +179,19 @@ case "$SYNC_MODE" in
   reset)
     git reset --hard "upstream/${UPSTREAM_BRANCH}"
     ;;
+  *)
+    die "Unreachable: unvalidated sync_mode '${SYNC_MODE}'"
+    ;;
 esac
 
 # ----------------------------------------------------------------------------
 # Push
 # ----------------------------------------------------------------------------
 
 PUSH_ARGS="${INPUT_PUSH_ARGS:-}"
-# reset mode rewrites history; force-push unless the caller already specified one.
-if [ "$SYNC_MODE" = "reset" ] && [[ "$PUSH_ARGS" != *--force* ]]; then
+# reset and rebase rewrite the target branch's history, so the push back is not
+# a fast-forward — add a (lease-guarded) force unless the caller specified one.
+if [[ "${SYNC_MODE}" == "reset" || "${SYNC_MODE}" == "rebase" ]] && [[ "${PUSH_ARGS}" != *--force* ]]; then
   PUSH_ARGS="--force-with-lease ${PUSH_ARGS}"
 fi