Surveyor

GitHub Actions

The Spice Labs Surveyor action runs an inventory survey or an image survey in your workflow and uploads the results to your Topographer project. Add it after your build step so every push or release is surveyed.

Set up the action

Store your Spice Pass as a secret

Generate a Spice Pass for the project the surveys should go to, and choose an Expires in that suits a pipeline. In your repository, open Settings, then Secrets and variables, then Actions, and select New repository secret. Name it SPICE_PASS and paste the Spice Pass as its value.

Add the workflow

Create .github/workflows/spice-survey.yml:

name: Spice Labs survey

on:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  survey:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build
        run: ./gradlew build

      - name: Survey build output
        uses: spice-labs-inc/action-spice-labs-surveyor@v5
        with:
          subject: payments-api
          input: ./build/libs
          spice_pass: ${{ secrets.SPICE_PASS }}

Replace the build step with your own, and point input at the folder your build writes its artifacts to.

Commit and push

The next push to main runs the survey. The survey appears in your project when the upload finishes.

The action installs the Surveyor CLI and runs it in Docker, so use a Linux runner such as ubuntu-latest.

Inputs

Input	Required	Default	Description
`subject`	Yes, for files		The name you choose for this application in Spice Labs. Keep it the same on every run. With `image`, it defaults to the image name without its tag
`spice_pass`	Yes		Your Spice Pass. Pass it from a secret. If it is empty, the action stops before it surveys, with an error that names `spice_pass`.
`input`	No	`.`	Path to the files to survey. Ignored when `image` is set.
`image`	No		Container image reference to survey instead of local files, for example `ghcr.io/myorg/app:2.3.0`
`log_level`	No	`info`	`debug`, `info`, `warn` or `error`
`cli_image`	No	`spicelabs/spice-labs-cli`	The CLI image to run. Add a tag or digest to pin a version, for example `spicelabs/spice-labs-cli:1.9.3`.

The action has no outputs. It runs spice survey inventory, with docker://<image> as the input when image is set. For runtime surveys, --no-upload, --tag-json or other options, run the CLI directly.

Survey a container image

Set image to survey an image from its registry instead of local files. For a private registry, log in first:

- uses: docker/login-action@v3
  with:
    registry: ghcr.io
    username: ${{ github.actor }}
    password: ${{ secrets.GITHUB_TOKEN }}

- uses: spice-labs-inc/action-spice-labs-surveyor@v5
  with:
    subject: payments-api
    image: ghcr.io/myorg/app:${{ github.sha }}
    spice_pass: ${{ secrets.SPICE_PASS }}

The CLI uses the runner’s Docker credentials to pull the image. When you use GITHUB_TOKEN to read packages, give the job packages: read permission. See Image surveys.

Survey several components

Survey each component under its own subject, so each one has its own results in the dashboard:

jobs:
  survey-frontend:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: spice-labs-inc/action-spice-labs-surveyor@v5
        with:
          subject: frontend
          input: ./frontend/dist
          spice_pass: ${{ secrets.SPICE_PASS }}

  survey-backend:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: spice-labs-inc/action-spice-labs-surveyor@v5
        with:
          subject: backend
          input: ./backend/build/libs
          spice_pass: ${{ secrets.SPICE_PASS }}

Pin the CLI version

The action installs the newest wrapper script and, by default, runs the latest CLI image. To keep results repeatable between runs, name the CLI image with its version in cli_image:

with:
  subject: payments-api
  spice_pass: ${{ secrets.SPICE_PASS }}
  cli_image: spicelabs/spice-labs-cli:1.9.3

To run the CLI from your own copy of the image, name that copy the same way, for example cli_image: registry.example.com/mirror/spice-labs-cli:1.9.3. A digest works in place of the tag.

Run the CLI directly

When you need an option the action does not expose, install the CLI in a step and run spice yourself:

jobs:
  survey:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build
        run: ./gradlew build

      - name: Install the Surveyor CLI
        run: |
          curl -sSfL https://install.spicelabs.io | bash
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"

      - name: Survey build output
        env:
          SPICE_PASS: ${{ secrets.SPICE_PASS }}
          SPICE_IMAGE_TAG: "1.9.2"
        run: spice survey inventory payments-api ./build/libs --tag-json='{"branch":"${{ github.ref_name }}"}'

SPICE_IMAGE_TAG pins the CLI version here. It applies only while SPICE_IMAGE is unset: if you set SPICE_IMAGE, put the tag in it (spicelabs/spice-labs-cli:1.9.2). On a self-hosted runner that already has the image, you can set SPICE_LABS_CLI_SKIP_PULL=1 to skip the pull and the update check. See Configuration.

Keep the pipeline secure

Pass the Spice Pass only from a secret, never in the workflow file.
Give the workflow the least permissions it needs, such as contents: read.
A Spice Pass works for one project only. Use a separate secret for each project you survey into.
When the Spice Pass expires, uploads stop working. Generate a new one and update the secret, or revoke the old one on the Credentials page if it leaks.

Inventory surveys What a survey finds and its options. Spice Passes and credentials Generate, review and revoke Spice Passes. Troubleshooting Messages the CLI prints and what to do.