prpl
Sign in
← All documentation
Scan repositories

Schedule recurring scans

Cover cadence selection, pause/resume, last-run state, and schedule failures.

userorg admin capture: recurring-scans

Outcome

You will have a recurring scan cadence on a repository — prpl starts a scan of your chosen ref automatically every day, week, or month — and you will know how to pause it, read its last-run state, and recover from a skipped cycle.

Each scheduled cycle runs the same launch as Start scan: it prepares a fresh environment from the scheduled ref, with the build-plan gate approved automatically (the run carries an AUTO tag) so it proceeds unattended. Hunts against the refreshed environment are launched the same way as for any environment — see Run a security scan.

Who can do it

  • Scheduling requires the same capability as launching an environment build on that repository: customer accounts for their own repositories, organization members with the repository granted plus a build-capable seat grant or the Repo owner role, and site admins anywhere.
  • Only GitHub-hosted repositories can be scheduled.
  • A scheduled run clones with the scheduling user's stored GitHub token — never the organization owner's broader credential — and the resulting scan is attributed to the repository's namespace owner.

Before you begin

  • The repository has been scanned at least once — the schedule control lives on its repository page.
  • For a private repository, a GitHub token is saved on your account (Connect GitHub authentication). The panel confirms with GitHub token on file ✓; public repositories need no token (Public repo — no token needed.).
  • Every cycle incurs the cost of a full scan launch.

Steps

  1. Open Attack surface, select the repository, and click + Scan this repository to open the scan panel.
  2. At the bottom of the panel, expand Recurring scan. Its badge shows the current state: off, paused, or the active cadence with its next fire time (for example daily · next 2026-07-11 09:00 UTC).
  3. Choose a Frequency — Off, Daily, Weekly, or Monthly (monthly runs on a fixed 30-day interval).
  4. Set the Ref to scan each cycle (default HEAD, which resolves to the branch tip at fire time — a schedule may track a moving ref, unlike a manual scan) and pick a Profile.
  5. Click Save schedule. The page confirms with “Recurring scan schedule saved.”
    The Recurring scan section with Frequency, Ref, and Profile set; call out the single Save schedule button.
  6. The first automatic scan fires one full interval after you save — never immediately. Each later cycle anchors on the previous fired run.
  7. To suspend without losing the cadence, click Pause schedule; the badge switches to paused and Resume schedule appears.
    The Recurring scan section in the paused state; call out the single Resume schedule control.
  8. To stop scheduling entirely, set Frequency to Off and click Save schedule — confirmed by “Recurring scan schedule turned off.”

Verify

  • Immediately after saving, the Recurring scan badge shows the cadence and the computed next fire time in UTC.
  • After the next fire time passes, the panel shows Last auto-scan: with a link to the new run, and a new build job appears on the repository's Build jobs tab.
  • The auto-scan run proceeds without waiting at plan review (it is auto-approved) and is visible on Jobs like any other run.

Troubleshooting

A cycle that could not run records its reason in the panel as “Last cycle skipped: …” — a skipped cycle is never silent.

The Recurring scan section showing a “Last cycle skipped:” message; call out the skip-reason line.

“no GitHub token on file — connect a token to resume”

The scheduled run had no stored token to clone a private GitHub repository. Connect a token (Connect GitHub authentication); the schedule retries on the next dispatcher pass once a token is present. The panel warns ahead of time: “No GitHub token on file for this repo — scheduled scans will be skipped until a token is connected.”

“a scan for this repo is already running”

A build for this repository (manual or scheduled) was still in flight at fire time, so the cycle stepped aside rather than stack a second build. No action needed — the next cycle fires normally.

“the scheduling user no longer has access to this repository”

The account that saved the schedule lost its scan grant (for example the member was disabled or the repository grant was revoked). Have a user who currently holds scan access re-save the schedule, or restore the original member's access (Assign repository access and roles).

“agent profile unavailable: …”

The saved Profile has since been disabled by policy. Re-open the schedule and save it with a profile that is currently offered in the dropdown.

“runner dispatch failed: …”

An infrastructure error prevented the launch. The schedule retries on the next pass; if the same reason persists across cycles, see Troubleshooting.

Nothing has fired yet

Check the badge: the first run comes one full interval after saving, so a daily schedule saved at 09:00 UTC first fires around 09:00 UTC the next day. Also confirm the schedule isn't paused.

Next steps

Keep an eye on the auto-scans as they land: Monitor environments and scan jobs. Extend cadence coverage to the rest of your estate with Add and scan more repositories.

Last verified against commit c0bf54d on 2026-07-10 · capture scenario: recurring-scans