Getting started

The IronBee GitHub Action verifies every push and pull request against your running application and reports the result on the pull request. It can run the verification in one of two places:

On IronBee: IronBee verifies the change on its own infrastructure. Nothing is installed on your runner.
On your GitHub runner: the verification runs inside your workflow with your own Anthropic access.

When the verification finds a problem, the action can report it, or also write the fix and commit it. This guide gets the action running in a few minutes. For the mechanics behind it, see How it works.

Prerequisites

An IronBee account and your account API key. Owners and admins find it in the console under Settings > Account. Other members can ask an owner or admin for it.
To verify on IronBee: the IronBee GitHub App installed on the repository. A public repository also works without it.
To verify on your GitHub runner, or to have findings fixed: an Anthropic API key from console.anthropic.com, or a Claude Code OAuth token from claude setup-token.

Set it up from the console

The fastest path is the console, which writes the workflow for you.

Connect GitHub

During onboarding, or later from Setup in the top bar, choose Connect GitHub. Install the IronBee GitHub App on the organization you deploy from, and choose the repositories it can see.

Answer three questions

In the IronBee Action step:

Repository: the repository the workflow file and the secrets go into.
Where it runs: On IronBee (recommended) or On your GitHub runner.
On a finding: Report it, or Fix it too.

The IronBee Action step: the repository acme / web picked, Where it runs open with On IronBee (recommended) selected and On your GitHub runner, and On a finding set to Report it

Set it up on GitHub

Fill in how your app starts, add the repository secrets the console lists, then click Create the file on GitHub. Committing the file is a push, and that push starts your first verification.

The rest of this page builds the same workflow by hand.

Add the workflow

Create .github/workflows/ironbee.yml with one of the two starter workflows below. The action is also listed on the GitHub Marketplace.

On IronBee, report only
On your runner, fixing too

name: IronBee Verification

on:
  push:
    branches: [main]
  pull_request:
    types: [opened, synchronize]

permissions:
  contents: write
  pull-requests: write
  issues: write

concurrency:
  group: ironbee-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: true

jobs:
  verify:
    runs-on: ubuntu-latest
    timeout-minutes: 90
    steps:
      - uses: actions/checkout@v4
      - uses: ironbee-ai/ironbee-action@v1.1.0
        with:
          ironbee_api_key: ${{ secrets.IRONBEE_API_KEY }}
          verification_mode: platform
          verification_apply_fix: false
          # Where the app runs during the workflow: on this runner ...
          app_install_command: npm ci
          app_build_command: npm run build
          app_start_command: npm run start
          app_port: 3000
          # ... or at a preview URL instead of the four lines above:
          # app_url: https://preview.example.com

name: IronBee Verification

on:
  push:
    branches: [main]
  pull_request:
    types: [opened, synchronize]

permissions:
  contents: write
  pull-requests: write
  issues: write

concurrency:
  group: ironbee-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: true

jobs:
  verify:
    runs-on: ubuntu-latest
    timeout-minutes: 90
    steps:
      - uses: actions/checkout@v4
      - uses: ironbee-ai/ironbee-action@v1.1.0
        with:
          ironbee_api_key: ${{ secrets.IRONBEE_API_KEY }}
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          verification_mode: local
          verification_apply_fix: true
          # Where the app runs during the workflow: on this runner ...
          app_install_command: npm ci
          app_build_command: npm run build
          app_start_command: npm run start
          app_port: 3000
          # ... or at a preview URL instead of the four lines above:
          # app_url: https://preview.example.com

Replace the four app_* lines with your own install, build and start commands and the port your app listens on. If your app is already deployed at a public preview URL, delete the four lines and set app_url instead. The action needs one of the two: without a target the run stops before it verifies anything. See Verifying your application. To have findings fixed while verifying on IronBee, add an Anthropic credential and set verification_apply_fix: true.

At the start of every run, the action logs the timeout-minutes its configuration needs. If that is more than your job allows, raise timeout-minutes. When GitHub stops a job mid-run, the verification is cancelled with it.

Add the secrets

In your repository, open Settings > Secrets and variables > Actions and click New repository secret for each one:

Secret	Value	Needed for
`IRONBEE_API_KEY`	Your IronBee account API key	Every run
`ANTHROPIC_API_KEY`	An Anthropic API key	Verifying on your runner, or fixing
`CLAUDE_CODE_OAUTH_TOKEN`	A Claude Code OAuth token, instead of `ANTHROPIC_API_KEY`	Verifying on your runner, or fixing

Pass the Claude Code token with claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} instead of anthropic_api_key. Your Anthropic key or token stays in GitHub: the action uses it on your runner, and IronBee receives only the verification result. The next push or pull request starts a verification run.

Required permissions

The action needs these GitHub token permissions:

Permission	Purpose
`contents: write`	Commit fixes to the pull request branch and create fix branches
`pull-requests: write`	Post the verification report and open fix pull requests
`issues: write`	Update the report comment, and react to comment commands

A pull request from a fork receives no secrets, so no verification can run there. The action detects it and says so instead of failing on an empty key.

Next steps

Platform and local verification

How the action decides where the verification runs.

Running in CI

How the action behaves on each trigger and what it reports.

Verify from a comment

Start a verification with /ironbee-verify on a pull request.

Configuration

Every input and output, with defaults.

​Prerequisites

​Set it up from the console

​Add the workflow

​Add the secrets

​Required permissions

​Next steps

Platform and local verification

Running in CI

Verify from a comment

Configuration

Prerequisites

Set it up from the console

Add the workflow

Add the secrets

Required permissions

Next steps