| name | sq-site-dependabot |
| description | Reviews, validates, and safely merges Dependabot pull requests for the sq.io site (site/, Bun lockfile). Use when clearing site dependency PRs, triaging Dependabot failures, or checking Lighthouse impact before merge. |
| license | MIT |
| compatibility | Requires gh CLI (authenticated), Bun 1.2+, make, jq, curl, and network access to GitHub and Netlify. Full merges need NETLIFY_AUTH_TOKEN and NETLIFY_SITE_ID for make site-netlify-validate. |
| metadata | {"author":"Todd Papaioannou","homepage":"https://sq.io","version":"0.2.1"} |
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
| Mode | Actions | Merge |
|---|
| Audit | List/classify; CI; ordered plan | No |
| Validate | Branch checkout; make ci | No |
| Full | Audit + validate + merge loop | Consent |
Default to Audit unless the user says "merge", "clear them", or "full".
Phase 0 — Tool bootstrap
Run first in every mode. Stop on failure.
.agents/skills/sq-site-dependabot/scripts/check-tools.sh
.agents/skills/sq-site-dependabot/scripts/check-tools.sh --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
make ci
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:
- Stale-head guard:
gh pr view <n> --json headRefOid,mergeable,statusCheckRollup
gh pr checks <n> — Netlify check success on current headRefOid- Open deploy-preview URL; confirm published (not building/failed)
- 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):
export MESSAGE="PR #NNN dependabot <package>"
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:
- Stale-head guard (re-check
headRefOid)
- Layer A green on current head
make site-netlify-validate (Layer B)gh pr review <n> --approve --body "…"gh pr merge <n> --squash --delete-branch (default; no --admin)gh pr comment <next> --body "@dependabot rebase"- 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
Reference index
