CI/CD integration: GitHub Actions, GitLab CI, Jenkins
Run a Pentrova CI check from your pipeline with POST /api/ci/scan, fail the build on a severity threshold, and upload SARIF or JUnit results.
Reading mode
A CI check runs Pentrova against a staging or preview deployment from your pipeline and fails the build when findings exceed the thresholds you set. CI checks are part of the Continuous plan for the target; a CI check is not a full pentest. Plan details are on the pricing page.
The CI/CD Integration page in the app has copy-ready snippets for GitHub Actions, GitLab CI, Jenkins, Azure DevOps, CircleCI, Bitbucket Pipelines and a generic shell script. The steps below use GitHub Actions; the API calls are the same everywhere.
Set up once#
- Verify the domain of the staging or preview host on the Targets page. CI checks are refused for hosts outside your verified domains.
- Create an API key under Profile & Settings → API keys. Keep the default Read and Create scans permissions. The key acts with your role, so create it from an account that will stay in the organization.
- Add repository secrets:
PENTROVA_API_KEY: the key from step 2.PENTROVA_URL:https://app.pentrova.ai.STAGING_URL: the URL the check should run against.
GitHub Actions workflow#
Save as .github/workflows/security-scan.yml. It starts the check without holding the request open ("wait": false), polls the status endpoint, fails on the verdict, then uploads SARIF to GitHub code scanning.
name: Pentrova CI check
on:
pull_request:
branches: [main]
jobs:
pentrova:
runs-on: ubuntu-latest
timeout-minutes: 90
permissions:
contents: read
actions: read # needed by upload-sarif on private repositories
security-events: write # needed by upload-sarif
steps:
- name: Start the check and wait for the verdict
id: scan
run: |
BODY=$(curl -sS -X POST "${{ secrets.PENTROVA_URL }}/api/ci/scan" \
-H "X-API-Key: ${{ secrets.PENTROVA_API_KEY }}" \
-H "Content-Type: application/json" \
-d '{"target_url": "${{ secrets.STAGING_URL }}", "scan_type": "web",
"fail_on": {"critical": 0, "high": 0}, "wait": false}')
SCAN_ID=$(echo "$BODY" | jq -r '.scan_id // empty')
[ -n "$SCAN_ID" ] || { echo "$BODY"; exit 1; }
DEADLINE=$(( $(date +%s) + 3600 ))
while : ; do
BODY=$(curl -sS -H "X-API-Key: ${{ secrets.PENTROVA_API_KEY }}" \
"${{ secrets.PENTROVA_URL }}/api/ci/scan/$SCAN_ID/status") || BODY=""
STATUS=$(echo "$BODY" | jq -r '.status // "unknown"' 2>/dev/null || echo unknown)
case "$STATUS" in
completed|failed|cancelled|incomplete) break ;;
esac
[ "$(date +%s)" -lt "$DEADLINE" ] || { echo "Timed out"; exit 1; }
sleep 10
done
echo "sarif_url=$(echo "$BODY" | jq -r '.sarif_url // ""')" >> "$GITHUB_OUTPUT"
echo "$BODY" | jq '{status, pass, reason, severity_counts, scan_url}'
[ "$(echo "$BODY" | jq -r '.pass')" = "true" ]
- name: Download SARIF
if: always() && steps.scan.outputs.sarif_url != ''
run: |
CODE=$(curl -sS -w '%{http_code}' -o results.sarif \
-H "X-API-Key: ${{ secrets.PENTROVA_API_KEY }}" \
"${{ steps.scan.outputs.sarif_url }}") || CODE=000
if [ "$CODE" != "200" ]; then
echo "SARIF download failed (HTTP $CODE)"
cat results.sarif 2>/dev/null || true; echo
rm -f results.sarif; exit 1
fi
- name: Upload SARIF to GitHub code scanning
if: always() && hashFiles('results.sarif') != ''
uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: results.sarif
category: pentrova-security
Why poll instead of waiting#
"wait": true asks the server to hold one request open until the check finishes, for up to the timeout you set. Many proxies and load balancers close idle connections much sooner, so the pipeline would fail with a network error while the check itself finished. Polling /status every few seconds avoids that.
Setting the gate#
fail_on sets the maximum number of findings allowed per severity: 0 fails on any finding at that level and a number allows up to that many. null ignores a level. A missing medium or low is ignored, but a missing critical or high stays 0, so the default is {"critical": 0, "high": 0}.
{ "critical": 0, "high": 0, "medium": 10 }
Signed-in checks#
To check the pages behind your login, add "scan_mode": "AUTH_LLM_LOGIN" with login_url, username and password from repository secrets. For API checks, use "scan_type": "api" with a spec_url and an auth_config. All fields are in the CI API reference.
Other CI systems#
- GitLab CI: call the same endpoints from a job and publish the JUnit file (
/api/ci/scan/{scan_id}/junit) as ajunitreport artifact. - Jenkins: add a stage that calls the endpoints and publish the JUnit file as a test report.
SARIF and JUnit availability#
SARIF and JUnit come with a Pentest or a plan. When a check does not include them, the endpoint answers 402 with a message and a link to unlock the report; the download step above prints that message and fails.
Uploading SARIF to GitHub code scanning on a private repository needs GitHub’s code scanning to be available for that repository (GitHub Code Security).