Skip to main content

Runbook: Dependabot PR CI Remediation

Purpose​

Provide a deterministic responder workflow for failing Dependabot pull requests across:

  • portfolio-docs (Docusaurus docs app)
  • portfolio-app (Next.js app)

This runbook is used when automation is insufficient and a maintainer must reproduce, fix, and push a patch to the Dependabot PR branch.

Scope​

Use when​

  • a Dependabot PR has one or more failed required checks
  • CI logs show non-transient failures (typecheck, lint, test, build, links)
  • re-running jobs does not resolve the failure

Do not use when​

  • a CI failure is unrelated to Dependabot PRs (use service-specific CI triage runbooks)
  • the PR is blocked by policy decisions (for example, major-version upgrade deferral)

Prereqs / Inputs​

  • GitHub access to view checks and push commits
  • local checkout with both repositories available
  • tooling:
    • gh
    • git
    • pnpm
    • Node 20 runtime (to match CI)

Procedure / Content​

1) Identify the failing check and failing step​

From local shell:

gh pr checks <PR_NUMBER> --repo bryce-seefieldt/<REPO>
gh pr view <PR_NUMBER> --repo bryce-seefieldt/<REPO> --json title,headRefName,author,statusCheckRollup

If needed, inspect failed step logs:

gh run list --repo bryce-seefieldt/<REPO> --branch <HEAD_BRANCH> --limit 5
gh run view <RUN_ID> --repo bryce-seefieldt/<REPO> --log-failed

Capture:

  • failing check name (ci / quality, ci / test, ci / link-validation, ci / build, secrets-scan)
  • failing step (typecheck, format:check, pnpm build, etc.)
  • first actionable error line

2) Checkout the Dependabot PR branch locally​

Preferred:

gh pr checkout <PR_NUMBER> --repo bryce-seefieldt/<REPO>

Fallback (if checkout helper fails):

git fetch origin pull/<PR_NUMBER>/head:dependabot-pr-<PR_NUMBER>
git checkout dependabot-pr-<PR_NUMBER>

3) Reproduce failure locally​

For portfolio-docs​

pnpm install --frozen-lockfile
pnpm verify

Targeted diagnosis:

pnpm lint
pnpm format:check
pnpm typecheck
pnpm audit --audit-level=high
pnpm build
pnpm policy:check

For portfolio-app​

pnpm install --frozen-lockfile
pnpm verify

Targeted diagnosis:

pnpm lint
pnpm format:check
pnpm typecheck
pnpm test:unit
pnpm test:e2e
pnpm registry:validate
pnpm build

4) Apply minimal fix for the failing class​

Decision matrix:

Failing checkTypical root causeFirst local commandFix strategy
ci / qualitylint, format, typecheckpnpm verify or targeted commandsfix code/config; avoid policy weakening
ci / testunit or E2E regression (portfolio-app)pnpm test:unit / pnpm test:e2eupdate code or tests to match intended behavior
ci / link-validationstale/missing docs evidence links (portfolio-app)pnpm registry:validatecorrect registry links and targets
ci / buildbroken build, invalid config, routing/link errorspnpm buildfix root cause; do not bypass build gate
secrets-scanverified secret in PR diffreview scan outputrotate/revoke secret and remove from history/content

5) Known pattern: TypeScript 6 deprecation failures (TS5101)​

Symptom example:

  • error TS5101: Option 'baseUrl' is deprecated and will stop functioning in TypeScript 7.0

Responder approach:

  1. confirm error appears in CI logs and local pnpm typecheck
  2. remove deprecated option when no longer needed, or migrate to supported alternatives
  3. use temporary suppression only if migration cannot be completed safely in the PR scope
  4. rerun full verification locally before push

6) Commit and push patch to Dependabot PR branch​

After local verification is green:

git add -A
git commit -m "fix(ci): resolve Dependabot PR failure"
git push

If direct push is rejected:

  1. create a maintainer branch from the checked-out state
  2. push that branch and open a replacement PR
  3. link back to the original Dependabot PR with rationale

7) Re-run checks and verify merge readiness​

  • re-run all jobs for transient flakes (GitHub Actions UI)
  • verify required checks are green
  • ensure no new warnings introduce policy drift

Validation / Expected outcomes​

  • local verification reproduces and then resolves the failure
  • Dependabot PR checks are green after patch push
  • merge gate is unblocked without reducing CI policy strictness

Rollback / Recovery​

If remediation introduces additional regressions:

  • revert the patch commit on the PR branch
  • re-open diagnosis with step-level logs
  • escalate to service-specific runbook if issue is broader than dependency update scope

References​

  • docs/50-operations/runbooks/rbk-docs-deploy.md
  • docs/50-operations/runbooks/rbk-portfolio-ci-triage.md
  • docs/30-devops-platform/ci-cd-pipeline-overview.md
  • docs/50-operations/incident-response/incident-handbook.md