Check a release from your pipeline

Plans. Business and Pro. A client website an agency puts on Business or Pro has this too. Starter and Plus do not, including a client website an agency puts on Starter or Plus.

A pipeline is the script that runs when you publish a new version. GitHub, GitLab, Jenkins, and Azure DevOps can all run that script. SiteScan does not replace those tools. The script asks SiteScan one question about the website you choose.

The question is: did staging add a critical or serious bug that was not already on the live site?

Before you start

1. Open the website this check is for. If you are an agency, open that client website first. The token belongs to the website that is open. Each website has its own pages, its own score, and its own token.
2. Add the staging address in Settings → Company if it is not there yet. SiteScan must be able to open that address from the internet. A staging site that only works on your office network will not pass.
3. The pages to check are the pages already on the list for that website. Add any missing page on Pages before you rely on the check. SiteScan needs one finished scan of each of those pages on the live site, so it can ignore bugs that were already there.

Create the token

Open Settings → Extensions. Pipeline uses the staging address you saved in Company.

The account owner creates the token. Press Create a token. Copy it straight away. This page shows the secret once.

Put the secret in the pipeline as a secret named SITESCAN_API_KEY. Do not write it in the project. Do not put it in the web address. Do not send it in a chat.

Creating a new token stops the old one. Tick The old token will stop working before you replace it, then update the secret in the pipeline.

Ask the question

After staging is deployed, the script sends a request to the private address shown on the Pipeline page. The address looks like this:

https://v1.accessux.com.au/api/audit/sitescan/check

Send two headers:

• Content-Type: application/json so SiteScan accepts the request.
• Authorization: Bearer followed by the secret.

A copy-ready example is on the Pipeline page:

curl -sS -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $SITESCAN_API_KEY" https://v1.accessux.com.au/api/audit/sitescan/check

Use the private address shown on your Pipeline page. The example above is the live beta. If Settings shows a different address, use that one.

SiteScan then opens the pages already listed for that website, on the staging address. It does not scan a page that is not on the list.

Run the command

On your computer, after staging is deployed, run:

sitescan scan https://staging.example.com

Replace the address with the staging site for this release. The token stays in SITESCAN_API_KEY. Point SITESCAN_URL at the SiteScan address that runs the check, when that is not this computer.

The command writes JSON. Exit code 0 means no new critical or serious bug, so the release can continue. Exit code 1 means stop the release. Exit code 2 means the check itself failed, so production does not go ahead.

A new minor or moderate bug is listed in the JSON and does not stop the release. To also stop when a critical bug is still open, add --fail-on-open-critical. To set a ceiling, add --max-critical 0 or --max-serious 3.

A Docker image starts this same command. It asks SiteScan. It does not scan the site itself.

On GitHub

GitHub runs the same command. The pipeline gives the staging address and the secret SITESCAN_API_KEY.

name: SiteScan
on:
  pull_request:
jobs:
  sitescan:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - uses: AccessUX-gerry/accessux-v2/.github/actions/sitescan@v1
        with:
          staging-address: https://staging.example.com
        env:
          SITESCAN_API_KEY: ${{ secrets.SITESCAN_API_KEY }}
          SITESCAN_URL: https://v1.accessux.com.au

Put that file in the website's GitHub repository. GitHub can run it when the check is on the SiteScan address in SITESCAN_URL.

Use the staging address for that release. In the repository settings, require the SiteScan check before merging.

The command also writes two files when you ask for them:

sitescan scan https://staging.example.com --sarif sitescan.sarif --note sitescan-note.md

sitescan-note.md is the note on the pull request. It names the page, the element, the three lines, and whether the bug is new. sitescan.sarif is the file GitHub code scanning reads. A new minor or moderate bug is in both, and it does not stop the release.

What done looks like

The answer is no when staging did not add a new critical or serious bug. The release can continue. An old critical or serious bug, already on the live site for that same element, does not fail the check.

The answer is yes when staging did add one. The result names the page, the element, and three lines: who is affected, what to change, and how to check the fix.

You do not get a yes or no when SiteScan cannot open the staging address, when the website has no pages yet, or when a listed page has never been scanned on the live site. The message says what to fix. Fix that, then run the check again.

A new minor or moderate bug does not fail this check. The command lists it. The pull request note lists it too. It still shows in SiteScan when you scan that page.

On GitHub, a required SiteScan check blocks the pull request when the exit code is 1 or 2. The note on the pull request and GitHub code scanning both show the bug.