Weekly pull requests: one SEO mission a week, opened for review

Weekly pull requests are Serpkin's hands-off mode. Every Monday, a GitHub Actions workflow asks Serpkin for your top mission, has Claude Code implement it on a new branch, and opens one draft pull request for you to review. Nothing is merged or deployed without you. This page explains what each run does, how to turn it on, what the pull request contains and when a run decides to stop.

#What happens each week

The default schedule is Mondays at 08:00 UTC. A run typically takes a few minutes. Your own CI and preview deployment then test the pull request, and the mission waits in Serpkin as implemented until you verify it after deploying. You can also start a run by hand from the Actions tab with workflow_dispatch, which is useful after changing secrets or checking that the setup works.

#Turn it on

1. Add the workflow files

   In your repository, run npx serpkin weekly. It writes .github/workflows/serpkin-weekly.yml and, if you don't have one yet, the preview SEO check at .github/workflows/serpkin.yml. Existing files are kept. --force replaces the weekly workflow, and in a monorepo you run the command from the app folder so the files land at the repository root.

2. Add two secrets and one variable

   The workflow needs a Serpkin agent key as SERPKIN_API_KEY, an Anthropic key as ANTHROPIC_API_KEY (or a Claude subscription token as CLAUDE_CODE_OAUTH_TOKEN), and your site id as the repository variable SERPKIN_SITE_ID. The command prints the exact gh secret set and gh variable set lines. gh asks for each value, so a key never lands in your shell history.

3. Commit, push, and run it once

   Commit the workflow files and push. Then run the workflow by hand once and read the log. When it succeeds, the pull request appears under Pull requests with the label serpkin, and the mission in Serpkin shows as implemented with the pull request URL attached.

The full setup, including the optional SERPKIN_PR_TOKEN for letting your CI run on the pull request, is in Serpkin in GitHub Actions. That page also has the complete workflow file if you prefer to copy it by hand.

#What the pull request contains

• A branch per run: named serpkin/<mission>-<run>. The workflow never pushes to your default branch.
• A title from the mission: SEO: <mission title>, trimmed to fit GitHub.
• A description in three parts: what changed and why, the files changed, and each acceptance check with how the agent met it.
• The label: serpkin, which is also how the next run knows a pull request is still waiting for you.
• A note at the bottom: a reminder that your CI and preview deployment test the change, and that you merge and deploy it yourself.

The pull request is a draft on purpose. Mark it ready when you have read the diff. If the mission can't be done safely in code, for example because it needs a DNS change or a new dependency, Claude Code changes no files and writes the reason to the run summary. The workflow then dismisses the mission in Serpkin with a note, so next week's run moves on instead of retrying the same blocked task. You can restore the mission in Serpkin and do it yourself.

#How it stays safe

Mission text can quote page titles, search queries and competitor copy from the web, so a page could try to steer the agent. The workflow is built so that even a misled agent cannot do damage. It runs in three separate jobs with different permissions:

The publish job rejects changes to .github/, git internals, package.json, lockfiles, env files, deploy configuration such as vercel.json, symlinks and submodules. It also refuses a patch or description that looks like it contains a key or token, before anything is pushed. The patch is built in a fresh checkout with git hooks and user config disabled, so the agent cannot plant settings that the workflow would then trust. Actions are pinned to commit SHAs, every job has a timeout, and a concurrency group stops two runs from overlapping.

#Review, merge, then verify

1. Read the description and the diff

   Start with the three sections in the description, then check the diff against the mission steps. The change should be focused on one mission. If it isn't, close the pull request and dismiss the mission with a reason instead of editing it into shape.

2. Let CI and the preview check finish

   Your normal CI runs on the branch. If the preview SEO check is installed, it compares the preview with production and fails on regressions such as a new noindex, a removed canonical or a broken sitemap. A red check is information, not a blocker you should ignore.

3. Merge and deploy

   Mark the draft ready, merge it, and deploy the way you normally do. Serpkin does not deploy anything for you and does not need deploy access.

4. Verify the mission in production

   Ask your agent to verify the mission, or run npx serpkin check <production-url> first. A passed verification starts the measurement window, with results at 14 and 28 days. See Verification and results.

Weekly runs use no Serpkin credits. Missions, submissions and verification are included in your plan. GitHub Actions minutes and Anthropic usage are billed by those providers, not by Serpkin.

#When a run skips or stops

GitHub can delay scheduled runs when Actions is busy. In public repositories it also turns scheduled workflows off after 60 days without repository activity, so run the workflow by hand to wake it up. If your team works in several time zones, change the cron line to a time that suits the person who reviews the pull request.

#Change the schedule and scope

The schedule is a starting point, not a rule. Teams that review quickly often run it twice a week; teams that deploy rarely leave it weekly and let a pull request stay open until they have time. The one-open-pull-request guardrail keeps either rhythm from piling up work.