Early accessCodeGecko is opening to a first group of teams.Join the waitlist
Join the waitlist

Setup guide

Connect your site in about 10 minutes.

Five steps, from an empty project to your first verdict. You need access to your CI and your site’s <head>. If you don’t have CI access, there’s a fallback in step 2.

  • About 10 minutes
  • Any CI that can run curl
  • Any framework, one script tag
01Step 01

Create a project.

Sign in, name the project and enter your site’s origin, like https://shop.example. You get two keys. Both are shown once, so save them now.

  • Put the deployment secret in your CI secrets as CODEGECKO_SECRET.
  • Keep the project ID handy as CODEGECKO_PROJECT.
  • The public key goes in the script tag. It only works from your origin.

Deployment secret

Server only · CI

8f2a••••••••••••

Registers releases. Never put it in browser code.

Public key

Browser · script tag

cg_pub_8f2a••••

Sends visit data from your site. Rotate it any time from the Setup page.

02Step 02

Register each deploy.

After every production deploy, one CI step sends the live commit and its recent history. Each new commit becomes the next release. The dashboard has this step ready to copy, with your project ID filled in.

Run it once before step 3

Measurements that arrive before your first release is registered are rejected. Deploy once with the CI step, then add the script tag.

No access to CI?

Skip this step and add data-commit to the script tag in step 3. Unknown commits register themselves on first visit, up to 20 a day.

After your deploy stepBearer: deployment secret
# .github/workflows/deploy.yml, after your deploy step
- name: Tell CodeGecko what shipped
  env:
    CODEGECKO_SECRET: ${{ secrets.CODEGECKO_SECRET }}
    CODEGECKO_PROJECT: ${{ vars.CODEGECKO_PROJECT }}
  run: |
    git log -n 100 --format='%H%x09%P%x09%an%x09%s' |
    curl -X POST https://codegecko.vercel.app/api/releases \
      -H "Authorization: Bearer $CODEGECKO_SECRET" \
      -F projectId=$CODEGECKO_PROJECT -F commit=$GITHUB_SHA \
      -F 'commits=<-'
03Step 03

Add the collector.

Paste one script tag into the <head> of every page. It loads async, measures each page load and sends a small batch when the visitor leaves.

  • Next.js, Nuxt, Astro, plain HTML: wherever your shared layout or <head> lives.
  • No cookies. Query strings, fragments, IDs and emails never leave the browser.
  • Single-page apps: full page loads are measured, route changes aren’t yet.
On every page, in <head>Public key
<script async
  src="https://codegecko.vercel.app/collector.js"
  data-project="your-project-id"
  data-key="cg_pub_…"></script>

Optional attributes

data-routes"/blog/:id, /docs/:id"Your own page groups.
data-sample"0.25"Measure a share of page loads on busy sites.
data-commit"a3f9c1e"Only if you skipped step 2.
04Step 04

Check it’s working.

Deploy, visit a few pages yourself, and open the dashboard.

  • Your release is listedv1.0.0 appears under Releases with the deployed commit.
  • Measurements are arrivingOpen your site, then leave the tab. The count goes up within a minute.
  • Pages are grouped/products/blue-shoe-42 shows up as /products/:slug.

If nothing shows up

401Wrong public key for this projectRotate it on your project’s Setup page.
403Request came from an unregistered originCheck the origin in project settings, including www.
402Collection is turned offTurn it back on in the dashboard.
429A limit was reachedPer minute, per month, or new releases per day.
05Step 05

Ship twice.

Your first release is the starting point. Every release after it gets a verdict once each page and device has 30 visits on both sides.

How verdicts are decidedExplore the demo
  1. Next deploy

    First release

    Release one starts collecting.

  2. Deploy after that

    Compare

    Release two vs release one.

  3. ~30 visits per page

    First verdict

    Hours on busy pages.

Stuck on setup?

Tell us your framework and how you deploy, and we’ll help you get your first comparison running.

Contact us Docs