GitHub Actions Integration

This guide explains how to integrate Wisec into your GitHub Actions workflows using the two-stage setup: notarization + policy enforcement.

1. Prerequisites

  • A Wisec account and project.
  • Your Project ID from the dashboard.
  • Your Agent Signing Key (private key) generated from Settings → Signing Keys.

2. Configure GitHub Secrets

Settings > Secrets and variables > Actions - add the following repository secrets:

SecretValue
WISEC_PROJECT_IDYour numeric project ID
AGENT_PRIVATE_KEY_HEXYour Ed25519 private key
WISEC_API_ENDPOINThttps://api.wisec.io/api/v1/events

3. Two-stage setup

The agent works in two independent steps with distinct roles:

StepWhenWhat it does
wisec-notifyEarly (alongside build/test)Notarizes the build (SLSA, Rekor, dashboard) and starts CVE analysis in the background. Never blocks.
wisec-gateLastWaits for the analysis, then enforces your policies - fails the job (exit 1) if a policy is violated.

The wisec-gate step is required for policy enforcement. Policies (secrets, CVE, risk score…) are evaluated and recorded by wisec-notify, but they only ever block your pipeline through the gate. If you omit the gate step, a build that violates a block policy will still pass. Keep the gate if you rely on policies; wisec-notify alone gives you notarization only.

While wisec-notify runs alongside your build and tests, the CVE scan completes in the background. By the time wisec-gate runs, the analysis is usually already done - added latency is close to zero.

yaml
# .github/workflows/wisec.yml

name: Wisec Security

on:
  push:
    branches: [ "main", "master" ]
  pull_request:
    branches: [ "main", "master" ]

jobs:
  # Step 1 - Submit build record (runs early, non-blocking)
  wisec-notify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Wisec Agent
        env:
          WISEC_PROJECT_ID: ${{ secrets.WISEC_PROJECT_ID }}
          AGENT_PRIVATE_KEY_HEX: ${{ secrets.AGENT_PRIVATE_KEY_HEX }}
          WISEC_API_ENDPOINT: ${{ secrets.WISEC_API_ENDPOINT }}
        run: |
          curl -fsSLO https://wisec-downloads.s3.fr-par.scw.cloud/wisec-agent-v1.5.0-linux-amd64
          curl -fsSL https://wisec-downloads.s3.fr-par.scw.cloud/wisec-agent-v1.5.0-linux-amd64.sha256 | sha256sum -c -
          mv wisec-agent-v1.5.0-linux-amd64 wisec-agent
          chmod +x wisec-agent
          ./wisec-agent

  # Your build and test jobs run here in parallel...

  # Step 2 - Policy gate (runs last, blocking)
  wisec-gate:
    runs-on: ubuntu-latest
    needs: [wisec-notify]   # runs after notify; add your test jobs here too
    steps:
      - uses: actions/checkout@v4
      - name: Wisec Policy Gate
        env:
          WISEC_PROJECT_ID: ${{ secrets.WISEC_PROJECT_ID }}
          AGENT_PRIVATE_KEY_HEX: ${{ secrets.AGENT_PRIVATE_KEY_HEX }}
          WISEC_API_ENDPOINT: ${{ secrets.WISEC_API_ENDPOINT }}
          WISEC_GATE_TIMEOUT: "120"
          WISEC_STRICT: "false"
        run: |
          curl -fsSLO https://wisec-downloads.s3.fr-par.scw.cloud/wisec-agent-v1.5.0-linux-amd64
          curl -fsSL https://wisec-downloads.s3.fr-par.scw.cloud/wisec-agent-v1.5.0-linux-amd64.sha256 | sha256sum -c -
          mv wisec-agent-v1.5.0-linux-amd64 wisec-agent
          chmod +x wisec-agent
          ./wisec-agent --gate

Gate environment variables

VariableDefaultDescription
WISEC_GATE_TIMEOUT120Max seconds to wait for analysis to complete
WISEC_STRICTfalseIf true, fails the gate when analysis times out. If false, passes silently - your CI is never broken by a Wisec outage

Policies evaluated in the gate

Post-analysis policies (cve_severity, risk_threshold) are evaluated once the CVE scan completes. Configure them in Dashboard → Policies.

4. Gitleaks (secret scanning)

Add gitleaks to the wisec-notify step:

yaml
  wisec-notify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Gitleaks
        run: |
          wget -q https://github.com/gitleaks/gitleaks/releases/download/v8.30.1/gitleaks_8.30.1_linux_x64.tar.gz
          tar -xzf gitleaks_8.30.1_linux_x64.tar.gz && chmod +x gitleaks && sudo mv gitleaks /usr/local/bin/
      - name: Run Wisec Agent
        env:
          WISEC_PROJECT_ID: ${{ secrets.WISEC_PROJECT_ID }}
          AGENT_PRIVATE_KEY_HEX: ${{ secrets.AGENT_PRIVATE_KEY_HEX }}
          WISEC_API_ENDPOINT: ${{ secrets.WISEC_API_ENDPOINT }}
        run: |
          curl -fsSLO https://wisec-downloads.s3.fr-par.scw.cloud/wisec-agent-v1.5.0-linux-amd64
          curl -fsSL https://wisec-downloads.s3.fr-par.scw.cloud/wisec-agent-v1.5.0-linux-amd64.sha256 | sha256sum -c -
          mv wisec-agent-v1.5.0-linux-amd64 wisec-agent
          chmod +x wisec-agent
          ./wisec-agent

5. SARIF report import

yaml
      - name: Run Wisec Agent
        env:
          WISEC_PROJECT_ID: ${{ secrets.WISEC_PROJECT_ID }}
          AGENT_PRIVATE_KEY_HEX: ${{ secrets.AGENT_PRIVATE_KEY_HEX }}
          WISEC_API_ENDPOINT: ${{ secrets.WISEC_API_ENDPOINT }}
          WISEC_SCAN_REPORT_PATH: "${{ github.workspace }}/results.sarif"
        run: |
          # semgrep --sarif --output results.sarif .
          ./wisec-agent

6. Binding the proof to the delivered artifact (optional)

By default, the provenance identifies the build by its source commit. To have it name the file you deliver, run the agent after the build and set WISEC_BINARY_PATH to that file. The installation guide explains what this changes, and its limits. Container images your build pushes can be named as well, with WISEC_IMAGE_DIGESTS (agent v1.3.0 or later): see Container images.

yaml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build
        run: make build        # produces dist/myapp
      - name: Run Wisec Agent
        env:
          WISEC_PROJECT_ID: ${{ secrets.WISEC_PROJECT_ID }}
          AGENT_PRIVATE_KEY_HEX: ${{ secrets.AGENT_PRIVATE_KEY_HEX }}
          WISEC_API_ENDPOINT: ${{ secrets.WISEC_API_ENDPOINT }}
          WISEC_BINARY_PATH: dist/myapp
        run: |
          curl -fsSLO https://wisec-downloads.s3.fr-par.scw.cloud/wisec-agent-v1.5.0-linux-amd64
          curl -fsSL https://wisec-downloads.s3.fr-par.scw.cloud/wisec-agent-v1.5.0-linux-amd64.sha256 | sha256sum -c -
          mv wisec-agent-v1.5.0-linux-amd64 wisec-agent
          chmod +x wisec-agent
          ./wisec-agent

  wisec-gate:
    runs-on: ubuntu-latest
    needs: [build]
    # ... unchanged

GitHub Actions jobs do not share files, so the simplest way is to run the agent as a step of the build job, right after compiling. The wisec-gate job then depends on build.

To check it worked, open the attestation from the dashboard: its subject reads artifact sha256:…. If it reads source commit …, the agent did not find the file.