webscan

Webscan Documentation

Lesson 9 · Connect your source code

Phase 2 · Triage & the fix workflow — Lesson 9 of 21 · All lessons

Objective: understand why webscan wants your source code, connect a GitHub repository (or paste a file), let webscan draft and sandbox-verify a code fix, and open a pull request — safely.

Before you start: an issue from a code-based (automated) finding (Lesson 7). This lesson involves real GitHub access, so use a repository you own or maintain.

Why connect source code at all?

So far webscan has seen your site as a browser sees it — the rendered page. To propose an actual code fix, it needs to see the source: the file a developer would edit. Connecting your code lets webscan:

  • draft a fix against the real file, not a guess;
  • verify that fix works before anyone touches your codebase;
  • open a pull request so a human can review and merge it.

First, three terms:

  • Repository (repo) — the folder of source code for your project, stored on a host like GitHub.
  • Pull request (PR) — GitHub's mechanism for proposing a change: it bundles your edits on a separate branch so a person can review them before they're merged into the main code. A PR changes nothing until someone approves and merges it.
  • Sandbox — an isolated throwaway environment where webscan can render a candidate fix and re-run the check, without affecting your site or your codebase.

Step 1 · Give webscan the source file

On the issue page, in the source section, you have two options:

  • Connect GitHub repository — link the repo (its owner, name, and branch) and provide an access credential. Then Import from GitHub and Import selected source to pull in the specific file the finding relates to.
  • Or paste source manually — if you'd rather not connect GitHub, use Attach source evidence to paste the relevant file's contents directly.

Credentials are yours to enter. When webscan asks for a GitHub token, you type it into the form — never share it in chat, and never ask anyone else to enter it for you. Later you can Replace GitHub credential / Replace repository credential to rotate it. A token is like a password for your repo; treat it that way.

Step 2 · Draft and sandbox-verify a fix

With a source file imported and an AI model provider configured, use Auto-fix in sandbox (verify before PR). Here's exactly what that does, in order:

  1. Drafts a source-code fix for the finding (a Propose a source-code fix draft, as in Lesson 8).
  2. Renders the fixed code in the sandbox.
  3. Re-checks the finding against that rendered result.

Only if the check now passes does the draft earn a Sandbox-verified badge. If it doesn't, you'll see Sandbox: still failing — the proposed fix didn't actually resolve the barrier, so it shouldn't go further. This "verify before PR" step is what stops webscan from proposing changes that merely look right.

(You can also generate a plain code-fix draft without the sandbox step; the sandbox route just adds the automated verification.)

Step 3 · Open a pull request

Once a code-fix draft is Approved (your human sign-off from Lesson 8) and has proposed changes, choose Apply via GitHub pull request. Webscan then:

  • creates a new branch,
  • makes one commit with the change, and
  • opens a draft pull request.

It never writes directly to your default branch — the change waits in a PR for a human to review and merge. You'll get a View draft pull request #N link to open it on GitHub.

Step 4 · Merge, then verify

Webscan doesn't merge the PR for you — a person always does that on GitHub. After you merge, come back and run Auto-verify (the next lesson) so a fresh scan can confirm the barrier is genuinely gone. When it does, the draft gets a Verified by re-scan badge — an honest statement that the scanner no longer sees the violation, not a claim that webscan merged anything.

Safety, in plain terms

This whole flow is built so automation never does anything irreversible on its own:

  • webscan proposes; humans approve and merge;
  • fixes are verified in a sandbox before a PR, and by a re-scan after merge;
  • PRs land on a branch, never straight onto your main code.

Tips & pitfalls

  • Use a repo you control, ideally a test one, while learning this flow.
  • A "Sandbox: still failing" result is useful, not a failure of the tool. It's telling you the suggested fix doesn't work — better to learn that before the PR.
  • Review the PR like any other. Sandbox verification checks the accessibility rule; it doesn't guarantee the change fits your codebase's style or logic.
  • Rotate credentials with the Replace credential actions if a token is ever exposed.

Recap

  • Connecting your repository (or pasting a file) lets webscan draft a fix against real source.
  • Auto-fix in sandbox drafts → renders → re-checks, earning Sandbox-verified only if the fix actually resolves the finding.
  • Apply via GitHub pull request opens a draft PR on a new branch — never touching your default branch; a human merges it.
  • After merging, Auto-verify confirms the fix by re-scan (Verified by re-scan).

Try it yourself

On a test repo, connect it to an issue and import the relevant file. Run Auto-fix in sandbox and note whether the draft becomes Sandbox-verified. If you're comfortable, approve it and open the draft PR — then read the PR on GitHub and confirm it's on its own branch.

Previous: ← Lesson 8 · AI remediation assistance Next: Lesson 10 · Retests & auto-verify →