CI/CD Integrations

Shannon runs continuously against deployed staging and development environments through official integrations for GitHub Actions and GitLab CI/CD. Both integrations:

analyze the checked-out source repository while attacking a running target;
preserve PDF, Markdown, and SARIF reports as pipeline artifacts;
preserve scan and agent logs for debugging, including incomplete runs;
support pull-request, release, and scheduled pentests;
distinguish an incomplete assessment from a completed scan with no findings; and
optionally fail the pipeline when Shannon exploits a vulnerability at or above a severity you set.

name: Shannon Pentest

on:
  workflow_dispatch:

permissions:
  security-events: write

jobs:
  pentest:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Run Shannon
        uses: KeygraphHQ/shannon-action@v1
        with:
          url: https://staging.example.com
          api-key: ${{ secrets.SHANNON_AI_API_KEY }}
          fail-on-severity: high
          upload-sarif: true

The Action defaults repo to the checked-out workspace. It uploads one artifact with the security assessment reports and SARIF, plus a separate run artifact with scan and agent logs. Enabling upload-sarif publishes findings to GitHub code scanning, which needs the security-events: write permission.

Store your provider key as a masked CI/CD variable named SHANNON_AI_API_KEY, then include the component:

include:
  - component: gitlab.com/KeygraphHQ/shannon-ci/pentest@1
    inputs:
      url: $STAGING_URL
      fail-on-severity: critical

shannon-pentest:
  timeout: 12h

The component defaults repo to $CI_PROJECT_DIR and workspace to the pipeline ID. Set upload-sarif: true to ingest report.sarif into the merge request security widget and the Security tab. The file is a downloadable artifact either way.

Requirements

GitHub Actions
GitLab CI/CD

A private repository. Reports and logs can contain sensitive findings about your application.
A runner with Docker and Docker Compose v2, with access to Docker Hub. ubuntu-latest works out of the box.
Network access from the runner to the running staging or development target.
A model-provider credential stored as a GitHub Actions secret.

Job timeout: jobs get 6 hours by default, which covers most scans. GitHub-hosted runners are capped at 6 hours, so use a self-hosted runner for larger repositories or slower model providers.

A private project. The component runs only on private projects, since its reports and artifacts can contain sensitive findings.
A self-hosted runner using the shell executor, with Docker Engine running (runner user in the docker group), Node.js LTS, and zip installed. The runner user must be non-root.
docker:dind and gitlab.com shared runners do not work: a separate-container daemon cannot see the checked-out repo.

Job timeout: a full scan runs far longer than GitLab’s default 60-minute timeout. Raise it to 12 hours in two places, since the lower one wins: the runner’s Maximum job timeout, and the job itself (the timeout: 12h override above, or the project’s pipeline timeout).

Pass and fail

The job passes only on a complete assessment, where every vulnerability class was assessed. It fails when the scan produced no report, or when some class could not be assessed (a partial run). No findings for a class that was never checked is not a clean result.

Finding vulnerabilities does not fail the job by itself. To gate on demonstrated impact, set fail-on-severity to low, medium, high, or critical. The gate counts only findings with status: exploited, so a code-analysis hypothesis never fails the pipeline, and an analysis-only scan (exploit: "false") never trips it.

When the gate fails it reports how many findings crossed the threshold, not their details. If you use it to block merges, also enable upload-sarif so the findings appear with their code locations.

Inputs

Both integrations take the same core inputs:

Input	Default	Description
`url`	required	Target URL of the running staging or development environment.
`repo`	checked-out workspace	Source repository to analyze.
`config`		Path to a Shannon configuration file (authentication, scope, report options).
`workspace`	run or pipeline ID	Named workspace. Set a stable value to resume a scan across runs.
`model`	`anthropic:claude-sonnet-4-6`	`<provider>:<model-id>`, as in `SHANNON_AI_MODEL`.
`api-key`		Provider API key. Always pass a secret or variable reference, never a literal.
`base-url`		Provider endpoint override for a proxy or LLM gateway.
`aws-bearer-token-bedrock`, `aws-region`		Bedrock credentials, required for `amazon-bedrock:` models.
`fail-on-severity`	`none`	Fail on an exploited finding at or above this severity.
`upload-sarif`	`false`	Publish SARIF to GitHub code scanning or the GitLab Security tab.
`pipeline-testing`	`false`	Minimal prompts for fast pipeline testing.
`version`	`3.0.0`	The `@keygraph/shannon` version to run.
`stage`	`test`	GitLab only: pipeline stage for the job.

The integrations expose the workspace directory and report paths for downstream steps: the workspace-dir, report-pdf, report-md, and sarif outputs on GitHub, and the SHANNON_WORKSPACE_DIR, SHANNON_REPORT_PDF, SHANNON_REPORT_MD, and SHANNON_SARIF dotenv variables on GitLab.

For the full option list, see the Shannon GitHub Action (also on the GitHub Marketplace) and the Shannon GitLab component.

Other CI systems

On any other CI system, run Shannon headlessly with the CLI. Expose your provider key from a secret as SHANNON_AI_API_KEY (and set SHANNON_AI_MODEL if you are not using the default), then:

npx @keygraph/shannon@latest start -u "$STAGING_URL" -r . --follow

--follow streams the scan log until it finishes and exits on the scan’s outcome. Exploit-mode scans write report.sarif by default, ready for any SARIF consumer.

Reference: CLI commands
How-to: Configuration
Explanation: Safety & Limitations