Continuous Integration

Scanning in CI keeps the shared graph current without anyone running the CLI by hand: every push to a repository’s primary branch updates its services in the graph.

Requirements

Any CI system works. The job needs to:

1. Run on pushes to the primary branch. Scans of other branches cannot join the shared graph.
2. Check out the full history. A shallow clone, which many CI systems make by default, cannot join the shared graph, because ProtoMap cannot tell the commit’s place in history. The origin remote’s branches must be fetched too.
3. Reach your ProtoMap Server over the network.
4. Authenticate with an organization API key. An Admin creates one under Settings › API Keys. See API Keys.

GitHub Actions

Store the server’s address as the PROTOMAP_URL variable and the key as the PROTOMAP_API_KEY secret of the repository or organization, then add a workflow:

.github/workflows/protomap.yml

name: ProtoMap

on:
  push:
    branches: [main]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - name: Check out the full history
        uses: actions/checkout@v7
        with:
          fetch-depth: 0

      - name: Install the ProtoMap CLI
        run: |
          curl -fsSL https://protomap.ai/install.sh | sh
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"

      - name: Scan
        run: protomap scan
        env:
          PROTOMAP_URL: ${{ vars.PROTOMAP_URL }}
          PROTOMAP_API_KEY: ${{ secrets.PROTOMAP_API_KEY }}

Replace main with your primary branch. To keep the CLI on the release your server runs, pass the version to the install script: sh -s -- 1.2.3.

Other CI Systems

The steps are the same everywhere:

bash

# Install the CLI (pass a version, such as `sh -s -- 1.2.3`, to pin it)
curl -fsSL https://protomap.ai/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"

# Scan, with the server's address and an organization API key from the CI system's secrets
PROTOMAP_URL=https://protomap.example.com PROTOMAP_API_KEY="$PROTOMAP_API_KEY" protomap scan

Checking the Result

The last line of the scan’s output says where the scan went. In CI, it should read Accepted into the shared graph, or say the same result was stored before. Otherwise it reads The server did not keep the scan, with the reason, such as a shallow clone or a commit that is not on the primary branch. See Who Sees a Scan.

A scan that cannot upload, such as when the server is unreachable or the key is wrong, fails the job.