# Sq Site Dependabot

> 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.

- Skill: `neilotoole/sq-site-dependabot` (Agent Skill, multi-file: 11 files)
- Install (CLI): `npx skillmds@latest add neilotoole/sq-site-dependabot`
- Raw SKILL.md: https://api.skillmd.com/api/skills/neilotoole/sq-site-dependabot/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: neilotoole (https://skillmd.com/u/neilotoole)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/neilotoole/sq-site-dependabot

---


# sq-site-dependabot

Maintainer workflow for Dependabot PRs touching [`site/`](../../../site/) or
`site/bun.lock`. Read [AGENTS.md](../../../AGENTS.md#agent-skills-contributors)
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.

```bash
# 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](references/tool-bootstrap.md).

## Phase 1 — Discovery

From repository root:

```bash
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](references/ci-and-checks.md).

## Phase 2 — Risk classification

Read [references/risk-tiers.md](references/risk-tiers.md) before ordering merges.
Package notes: [references/high-risk-packages.md](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/`:

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

Pin Bun to [`site/netlify.toml`](../../../site/netlify.toml) `BUN_VERSION` and
[site-ci.yml](../../../.github/workflows/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](references/netlify-build-debug.md);
recovery steps in [references/merge-failures.md](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):

```bash
# 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](references/netlify-cli-validate.md).

**Full mode sequence:**

```text
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`):

```bash
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](references/merge-failures.md).

## Phase 5 — Verdict template

Per PR (GitHub comment or chat):

```markdown
## 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)](../../../.github/workflows/site-publish-release.yml))
  or manual [Site Publish (dispatch)](../../../.github/workflows/site-publish-dispatch.yml).
  Use dispatch when dependency changes should go live before the next release.

## Repo cross-links

- [site/README.md](../../../site/README.md) — testing, `site-netlify-validate`
- [site/Makefile](../../../site/Makefile) — `check`, `ci`, validate, Lighthouse
- [site/netlify.toml](../../../site/netlify.toml) — Bun/Hugo pins, preview build

## Reference index

- [tool-bootstrap.md](references/tool-bootstrap.md)
- [risk-tiers.md](references/risk-tiers.md)
- [high-risk-packages.md](references/high-risk-packages.md)
- [ci-and-checks.md](references/ci-and-checks.md)
- [netlify-cli-validate.md](references/netlify-cli-validate.md)
- [merge-failures.md](references/merge-failures.md)
- [netlify-build-debug.md](references/netlify-build-debug.md)