Connect your CI/CD pipeline

How it works, in plain words. Your pipeline (CI/CD) already builds your site and puts it live. You add one more step at the end. That step runs a small program called the PixyScan CLI. The CLI tells PixyScan which branch was just deployed. PixyScan scans the address that branch lives at, and the CLI prints the result in your build log.

If the health score is lower than the number you chose, called the score gate, the CLI ends with exit code 1. Every CI treats an exit code other than 0 as a failed step, so the build stops. Nothing is changed on your site, and nothing comments on your pull requests. The build log and the exit code are the whole result.

Plan

Basic, Pro or Enterprise

Needs

Node.js 18 or later in the CI job

Uses

One URL credit per page scanned, like any scan

Waits

Up to 5 minutes for the scan, unless you change it

1. 1

   Open the site's CLI & CI/CD settings

   Open the site in PixyScan. In the sidebar, choose Settings under Manage, then open the CLI & CI/CD tab.

2. 2

   Press Create the secret

   It is on the Client secret card. A window opens with your new secret. It starts with sk_live_, followed by a long string of letters and numbers.

3. 3

   Press Copy

   This is the only time the secret is shown. PixyScan keeps only a one-way fingerprint of it, so nobody can show it to you again, our support team included.

   Go straight on to step 2 and save it in your CI. If you need a minute, paste it into a password manager, not into a chat, an email or a file in your repository.

4. 4

   Press I have stored it, close

   The button only works once you have copied the secret. The card now shows the start of the secret, when it was created, and when a pipeline last used it. Until your first run, Last used says Never.

app.pixyscan.com/w/…/s/…/settings?tab=sdk

Menus in these tools change from time to time. If one does not match, look for Secrets or Variables in your project's settings.

The name is up to you, as long as your pipeline step in step 5 uses the same one. This page uses PIXYSCAN_SECRET.

Your production branch always scans the site's own URL, the one you entered when you added the site. Every other branch you deploy needs an environment: a name, a branch and the address that branch is deployed to. If you only deploy one branch, check the production branch and go on to step 4.

1. 1

   Check the production branch

   On the Production branch and the gate card, make sure Production branch is the branch that deploys your live site, such as main or master. If you change it, press Save settings.

2. 2

   Press Add environment

   It is on the Which URL each branch scans card. Add one environment for each other branch you deploy, such as staging or a preview branch.

3. 3

   Fill in the three fields

   Name is a label, such as Staging. It is shown in scan history and in the report the CLI prints.

   Branch is the branch name, such as develop, or a pattern, such as release/*.

   URL to scan is the address that branch is deployed to, such as https://staging.example.com. PixyScan must be able to reach it from the internet, so private and local addresses are refused. If the site is behind a password, add its sign-in details on the Crawl tab. See Site settings.

4. 4

   Press Add environment to save it

   It appears as a row in the table. A site can have up to 20 environments. To change one later, edit its row and press Save environment.

1. 1

   Find today's score

   Open the site's Overview and note the health score of the latest scan, for example 82.

2. 2

   Type it in Score gate and press Save settings

   Score gate is on the Production branch and the gate card. It takes a whole number from 0 to 100. A scan passes when its score is the same as the gate or higher.

3. 3

   Optional: add checks that fail the build

   Under Checks that fail the build, open Add a check… and choose one, such as Broken internal links and pages. If a scan finds that check on any page, the build fails, whatever the score. The list saves as soon as you change it. Leave it empty to fail on the score alone.

4. 4

   Optional: exempt some pages from a check

   Press the pencil on the check's row. Type a part of an address, such as /legacy/, or a pattern, such as /blog/*, and press Enter. Press Save exemptions when the list is done.

   Exemptions only change the build. The problem is still reported on those pages in the app, and still counts towards the health score.

Put the PixyScan step after the step that deploys your site, and give it the secret you saved in step 2. Find your CI below.

GitHub Actions. Add the step to the job that deploys your site, after the deploy and after a step that sets up Node.js. To watch it, open the repository's Actions tab and choose the run.

GitLab CI. Add a stage after your deploy stage. Stages run in order, so the scan starts only once the deploy has finished. GitLab gives every job the variables you saved, so there is nothing else to add. To watch it, open Build → Pipelines in the project and choose the PixyScan job.

Bitbucket Pipelines. Add a step after the deploy step. Steps run one after the other. By default the step runs on every branch, so limit it to the branches you deploy if you only want to scan those.

CircleCI. Add a job for the scan, and make it wait for the deploy job to finish.

Jenkins and other CIs. It works on any CI with Node.js 18 or later. The CLI reads the branch by itself only on GitHub Actions, GitLab CI, CircleCI, Bitbucket Pipelines and Vercel. Anywhere else it assumes main, so send the branch, and the commit, yourself. On Jenkins, add a stage after your deploy stage, in a multibranch pipeline whose agent has Node.js, and read the secret from the credential you saved in step 2.

While the scan runs, the log shows progress lines that start with [pixyscan-sdk]: Starting scan, Crawling pages with a count of pages, Analysing results, and finally Scan complete. How long it takes depends on how many pages the scan covers.

When it finishes, the CLI prints the PixyScan SEO Scan Report:

The report gives counts, not the list of problems. To see each problem, open the site in PixyScan. The scan is in Scan history with the trigger CLI, named CI/CD Scan followed by the environment, the branch and the time. Then work through it from Issues, the same as any other scan.

Put the file in the folder your pipeline step runs from, which is usually the top folder of your repository. The CLI finds it by itself and prints Using pixyscan-settings.json in the log.

{
  "version": 1,
  "minScore": 85,
  "failOnIssues": [
    "Broken internal links and pages",
    {
      "issue": "Pages with no canonical tag",
      "excludePages": ["/legacy/*"]
    }
  ]
}

Each value in the file replaces the site's setting for that run only. The list replaces the site's list as a whole: the two are not merged. A check title PixyScan does not recognise stops the run with exit code 2 and suggests the closest name.

The CLI reads the commit on GitHub Actions, GitLab CI, Bitbucket Pipelines, CircleCI, Vercel and Netlify, with a link to it where the CI gives one. A tag build is also labelled with its tag, such as v2.4.0. The label is information only: it never changes the scan or whether the build passes.

With Search Console connected, each deploy of your production branch is marked on the site's clicks trend with its commit. If clicks drop sharply in the 3 days after a deploy, you get an alert. See Search impact.