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:
| Secret | Value |
|---|---|
WISEC_PROJECT_ID | Your numeric project ID |
AGENT_PRIVATE_KEY_HEX | Your Ed25519 private key |
WISEC_API_ENDPOINT | https://api.wisec.io/api/v1/events |
3. Two-stage setup
The agent works in two independent steps with distinct roles:
| Step | When | What it does |
|---|---|---|
wisec-notify | Early (alongside build/test) | Notarizes the build (SLSA, Rekor, dashboard) and starts CVE analysis in the background. Never blocks. |
wisec-gate | Last | Waits 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.
# .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
| Variable | Default | Description |
|---|---|---|
WISEC_GATE_TIMEOUT | 120 | Max seconds to wait for analysis to complete |
WISEC_STRICT | false | If 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:
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
- 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.
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.