sq-site-dependabot

Maintainer workflow for Dependabot PRs touching site/ or site/bun.lock. Read AGENTS.md for skill install paths.

Do not merge site Dependabot PRs in bulk without rebasing between merges (shared bun.lock).

Operating modes

Default to Audit unless the user says "merge", "clear them", or "full".

Phase 0 — Tool bootstrap

Run first in every mode. Stop on failure.

# gh auth + site deps (bun install if needed) + make check
.agents/skills/sq-site-dependabot/scripts/check-tools.sh
# Full / Layer B (+ NETLIFY_* via make check-netlify):
.agents/skills/sq-site-dependabot/scripts/check-tools.sh --netlify
# Or: gh api user -q .login && cd site && bun install && make check-netlify

check-tools.sh runs bun install in site/ when bun x netlify-cli is missing (fresh clone, agent sandbox). Needs network. SKIP_SITE_DEPS=1 skips that step. Layer B (site-netlify-validate) always uses bun x netlify-cli — a global/brew CLI does not replace bun install.

Details: references/tool-bootstrap.md.

Phase 1 — Discovery

From repository root:

gh pr list --author 'app/dependabot' --state open \
  --json number,title,headRefName,mergeable,statusCheckRollup,createdAt \
  --jq '.[] | select(.headRefName | test("^dependabot/"))'

Confirm each candidate touches site/ (gh pr diff <n> --name-only). Treat the list as candidates — refine by path if the filter is too broad.

For each PR:

• Confirm changes are under site/.
• Record mergeable state, Site CI, Netlify deploy-preview URL, Lighthouse if present.
• Flag false-positive Site CI noise (external link crawl) — see references/ci-and-checks.md.

Phase 2 — Risk classification

Read references/risk-tiers.md before ordering merges. Package notes: references/high-risk-packages.md.

Produce an ordered plan (T0 → T1 → T2; hold T3/T4).

Phase 3 — Local validation

Checkout the PR branch. From site/:

make deps    # if needed after checkout
make ci      # matches Site CI (necessary, not sufficient for Netlify)

Pin Bun to site/netlify.toml BUN_VERSION and site-ci.yml.

Optional: make site-lighthouse for T2+ when preview Lighthouse is unclear.

Netlify validation before merge

Layer A — PR deploy preview (Git integration)

After make ci on the PR branch:

1. Stale-head guard: gh pr view <n> --json headRefOid,mergeable,statusCheckRollup
2. gh pr checks <n> — Netlify check success on current headRefOid
3. Open deploy-preview URL; confirm published (not building/failed)
4. T1+: review @netlify/plugin-lighthouse on preview if available

If pending: poll ~5 min. If failed: do not merge; run debug-netlify-pr.sh <n> or see references/netlify-build-debug.md; recovery steps in references/merge-failures.md.

Layer B — Netlify CLI (required in Full mode)

From site/ on the PR branch (after Layer A is green on the same head):

# site/.env from .env.example (see tool-bootstrap.md)
export MESSAGE="PR #NNN dependabot <package>"   # optional
make site-netlify-validate

See references/netlify-cli-validate.md.

Full mode sequence:

check-tools --netlify → make ci → Layer A → site-netlify-validate → merge

Without site/.env, do not run Full automation; document degraded path in the verdict.

Phase 4 — Merge automation (consent-gated)

Only with explicit user consent per PR or batch.

Template script (sets CONFIRM_MERGE=1 only after consent). Checkout the PR first; working tree must match headRefOid (clean tree, or ALLOW_DIRTY_TREE=1):

gh pr checkout 573
CONFIRM_MERGE=1 PR=573 MESSAGE="dependabot shx" \
  ./.agents/skills/sq-site-dependabot/scripts/merge-next.sh

merge-next.sh enforces Layer A (gh pr checks), HEAD = headRefOid, then Layer B.

Happy path:

1. Stale-head guard (re-check headRefOid)
2. Layer A green on current head
3. make site-netlify-validate (Layer B)
4. gh pr review <n> --approve --body "…"
5. gh pr merge <n> --squash --delete-branch (default; no --admin)
6. gh pr comment <next> --body "@dependabot rebase"
7. Poll gh pr view <next> --json mergeable every 10s (max ~5 min)

Admin merge only when user explicitly requests and checks are green but merge is blocked: gh pr merge <n> --squash --admin --delete-branch.

Failures: references/merge-failures.md.

Phase 5 — Verdict template

Per PR (GitHub comment or chat):

## Dependabot PR #NNN — <package>

- **Tier:** T0–T4
- **Site CI:** pass / fail (root cause)
- **Netlify preview (A):** URL + check on head SHA
- **Netlify CLI (B):** deploy_id, deploy_url, state (or skipped)
- **Lighthouse:** perf/a11y/bp/seo deltas (or N/A)
- **Local `make ci`:** pass / fail
- **Verdict:** merge | hold | close + migration PR
- **Next step:** …

Phase 6 — Post-batch cleanup

• List remaining open site Dependabot PRs.
• Note stale local branches for prune.
• Remind: merging Dependabot PRs does not update https://sq.io. Production updates on a stable sq release (Site Publish (release)) or manual Site Publish (dispatch). Use dispatch when dependency changes should go live before the next release.

Repo cross-links

• site/README.md — testing, site-netlify-validate
• site/Makefile — check, ci, validate, Lighthouse
• site/netlify.toml — Bun/Hugo pins, preview build

Reference index

• tool-bootstrap.md
• risk-tiers.md
• high-risk-packages.md
• ci-and-checks.md
• netlify-cli-validate.md
• merge-failures.md
• netlify-build-debug.md