How to Add an AI Security Check to Your GitHub Actions Workflow

#ai #agents #security #githubactions

Humanbound has an official GitHub Action, humanbound/actions, that runs adversarial security tests against an AI agent inside a GitHub Actions workflow and fails the build when findings cross a severity threshold you set. It wraps the same OWASP-aligned testing engine as the hb test CLI command and uploads results to GitHub's native Security tab as SARIF, so a jailbreak shows up as a code scanning alert, not a separate report nobody opens.

Why gate a build on agent security at all?

Almost no CI pipeline today fails a build because an AI agent can be jailbroken, even though the same pipeline already fails on a broken unit test or a linting error. Most teams shipping agents have a CI process gating dependency vulnerabilities and code quality, but the agent itself gets its first real adversarial test from a user finding the hole in production. GitHub Actions is the natural place to close that gap, since it's already where most of these builds run.

How does the GitHub Action gate a build?

The humanbound/actions Action installs the Humanbound CLI, runs adversarial tests against your agent's endpoint, and fails the workflow when a finding matches the severity threshold you specify:

# .github/workflows/security-test.yml
name: AI Security Tests
on: [pull_request]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - run: docker compose up -d agent # boot your agent, reachable on localhost

      - uses: humanbound/actions@v1
        with:
          endpoint: |
            {
              "streaming": null,
              "chat_completion": {
                "endpoint": "http://localhost:8000/chat",
                "payload": { "content": "$PROMPT" }
              }
            }
          provider-api-key: ${{ secrets.OPENAI_API_KEY }}
          model: gpt-4.1
          fail-on: high

fail-on accepts critical, high, medium, low, or any. A build that trips the threshold fails the same way a broken unit test would, and findings land in GitHub's Security tab as SARIF with a severity summary on the run page, so nobody has to leave GitHub to see what broke.

What happens if the scan itself fails?

hb test exits with code 2, not 0, if the scan itself fails, distinct from exit code 1 for a normal fail-on match. This distinction matters because without it, a broken scan (bad endpoint config, expired API key, agent never came up) would silently exit 0 and read as a clean pass. Exit code 2 covers a run that ended with status Failed, or one where every conversation errored so nothing was actually tested. A security gate that a broken scan can quietly satisfy is not a security gate.

Local mode vs platform mode: which should you use?

Local mode needs nothing but your own LLM provider key; platform mode adds a persistent Humanbound dashboard on top of the same test. The Action runs one of two ways depending on which credential you set:

Mode	Credential	Where it runs	Result
Local	`provider-api-key` (your own LLM key)	in the runner	job output + SARIF, no account needed
Platform	`api-key` (a Humanbound `hb_…` key)	on humanbound.ai	your dashboard, plus SARIF

Local mode is the zero-signup path: a workflow file and an API key a team already has. Platform mode is worth it once you want posture trending across builds instead of a single pass/fail per pull request.

Does this work outside GitHub?

Yes. For GitLab, Jenkins, CircleCI, or any other CI system, the same test runs via the hb CLI directly or the official ghcr.io/humanbound/humanbound Docker image, with no Python install needed on the runner:

# .gitlab-ci.yml
security-test:
  stage: test
  image: python:3.12
  variables:
    HB_PROVIDER: openai
    HB_API_KEY: $OPENAI_API_KEY
    HB_MODEL: gpt-4.1
  script:
    - pip install "humanbound[engine]"
    - hb test --local --endpoint ./agent-config.json --wait --fail-on high

The GitHub Action is the polished, zero-config path. The underlying mechanism, and the guarantee that a broken scan can't pass, is identical everywhere.

How do I add this to an existing pipeline?

Add humanbound/actions@v1 to the same pull request workflow that already runs tests and linting.
Set fail-on: high (or whatever threshold matches your risk tolerance) so the build fails the same way any other broken check does.
Review findings in the Security tab alongside existing dependency and code scanning alerts, one place, not a separate login.
Move to platform mode later if you want posture trending across builds instead of a per-PR pass/fail.

FAQ

Is there an official GitHub Action for Humanbound?
Yes. humanbound/actions wraps hb test: it installs the CLI, runs the adversarial scan, gates the build with fail-on, and uploads findings to the GitHub Security tab as SARIF. Reference it in a workflow as uses: humanbound/actions@v1.

What does the fail-on flag do?
It causes the scan to exit with a non-zero status when vulnerabilities at or above the specified severity are found. The thresholds are critical, high, medium, low, and any, so a team can tune how strict the security gate is.

Does the GitHub Action require a Humanbound account?
No. Local mode runs entirely on a provided LLM provider key (provider-api-key) with no sign-up. Platform mode adds a Humanbound api-key for a persistent dashboard, but it's optional.

Can this run somewhere other than GitHub Actions?
Yes. The same hb test engine runs on GitLab CI, Jenkins, CircleCI, or any CI system, either via the CLI directly or the official ghcr.io/humanbound/humanbound Docker image.

Sources:

DEV Community