GitHub Actions

Gomboc provides two GitHub Actions that integrate security policy scanning directly into your pull request and scheduled workflows. Both actions scan your infrastructure-as-code files and report policy violations — the difference is in how they run, how they authenticate, and how results are surfaced.

For a full overview of how Gomboc interacts with your CI pipeline, see CI Pipeline Configuration.

Which action should I use?

	CLI-based (on-pull-request, on-schedule)	ORL Runner (on-pull-request-runner)
How it works	Runs the Gomboc CLI inside the workflow	Runs ORL rules in isolated Docker containers
Authentication	OIDC (no long-lived secrets needed)	Personal Access Token (GOMBOC_ACCESS_TOKEN)
Findings output	Gomboc Portal + PR status check	Inline PR review comments + Gomboc Portal
Auto-remediation	Opens a stacked PR with fixes	Opens a stacked PR with fixes
Scheduled scans	Yes (on-schedule action)	No
Pipeline blocking	Via effect: submit-for-review	Via fail-on-findings: true
Recommended for	Most teams — simpler setup, OIDC auth	Teams that want inline per-line PR comments

---

CLI-based actions

The CLI-based actions (on-pull-request and on-schedule) use the Gomboc CLI to scan your repository. Authentication is handled via OIDC — no long-lived secrets required.

Pull Request Pipeline

The examples below show how to run Gomboc on every pull request. Blocking is the recommended configuration when you want to enforce security policies in CI.

Blocking (default — recommended):

name: Gomboc.AI Terraform

permissions:
  id-token: write
  contents: read

on:
  pull_request:

jobs:
  gomboc:
    runs-on: ubuntu-latest
    steps:
      - name: Gomboc.AI - Terraform Remediate
        uses: Gomboc-AI/actions/on-pull-request@main
        with:
          effect: submit-for-review
          iac: terraform cloudformation
          cli-version: 'latest'

Non-blocking (audit only):

name: Gomboc.AI Terraform

permissions:
  id-token: write
  contents: read

on:
  pull_request:

jobs:
  gomboc:
    runs-on: ubuntu-latest
    steps:
      - name: Gomboc.AI - Audit Only
        uses: Gomboc-AI/actions/on-pull-request@main
        with:
          effect: audit
          iac: terraform cloudformation
          cli-version: 'latest'

Blocking vs. non-blocking pipelines

Use the effect input to control whether Gomboc findings block your CI pipeline.

effect	Creates remediation PR	Blocks pipeline when remediable fixes are found
submit-for-review (default)	Yes	Yes — the workflow step fails
audit	No	No — findings are reported, pipeline passes

How blocking works

When effect is submit-for-review and Gomboc finds remediable policy violations:

1. Gomboc runs the scan on files changed in the pull request.

2. Gomboc opens a stacked remediation pull request with the proposed fixes.

3. The GitHub Actions step exits with a non-zero status.

4. The workflow job is marked as failed, which blocks the pipeline.

To unblock the pipeline, review and merge the remediation PR (or update the original PR so violations are resolved), then re-run the workflow.

When effect is audit, Gomboc still runs the scan and records results in the Gomboc Portal, but the step always succeeds even when findings are present. Use this mode during initial rollout or testing.

Enforce with branch protection (recommended)

To prevent merging until Gomboc passes:

1. Go to Settings → Branches in your GitHub repository.

2. Edit or create a branch protection rule for your target branch (e.g. main).

3. Enable Require status checks to pass before merging.

4. Add your Gomboc job as a required status check (the check name matches the job id, e.g. gomboc).

Scheduled Pipeline

The on-schedule action supports scheduled scans to detect remediations triggered by changes in IaC modules or improvements in Gomboc remediation coverage. The cron value follows standard crontab syntax — use crontab.guru to generate one.

Note: Replace target-directory: tf with the path in your repository that contains IaC files.

name: Gomboc.AI Terraform Scheduled

permissions:
  id-token: write
  contents: read

on:
  schedule:
    - cron: '0 0 * * *'

jobs:
  gomboc:
    runs-on: ubuntu-latest
    steps:
      - name: Gomboc.AI - Terraform Remediate
        uses: Gomboc-AI/actions/on-schedule@main
        with:
          effect: submit-for-review
          target-directory: tf
          recurse: false
          iac: terraform cloudformation
          cli-version: 'latest'

Notes

• Workflows triggered by gomboc-ai[bot] are skipped automatically to avoid remediation loops.

• Use cli-version: 'latest' to always run with the most recent CLI version.

• For the full list of action inputs, see the Gomboc-AI/actions repository.

Need more flexibility? If you need to run the Gomboc CLI directly, Docker images are available on DockerHub under gombocai/cli.

---

ORL Runner (on-pull-request-runner)

The on-pull-request-runner action uses ORL (Open Remediation Language) to scan the files changed in a pull request. Unlike the CLI-based action above, it runs ORL rules in isolated Docker containers and surfaces findings as inline review comments directly on the changed lines in your PR.

Authentication: this action uses a Personal Access Token. Store it as GOMBOC_ACCESS_TOKEN in your repository or organisation secrets.

Audit vs Remediate — feature comparison

Feature	Audit	Remediate
Inline review comments on changed lines	yes	no
Summary PR comment	yes	no
Stacked remediation PR (with fixes)	no	yes
Integrations telemetry	yes	yes
fail-on-findings to block the pipeline	yes	no
Fork PR push	n/a	skipped

Audit mode

Runs ORL on the PR diff and posts findings as inline review comments and a summary PR comment. The job passes by default even when findings are present.

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write
  packages: read

jobs:
  gomboc-orl-audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          ref: ${{ github.event.pull_request.head.sha }}
          fetch-depth: 0

      - uses: gomboc-ai/actions/on-pull-request-runner@main
        with:
          mode: audit
        env:
          GOMBOC_ACCESS_TOKEN: ${{ secrets.GOMBOC_ACCESS_TOKEN }}

Remediate mode

When ORL produces fixes, the action pushes a bot branch and opens a stacked pull request with the applied fixes targeting your feature branch.

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: write
  pull-requests: write
  packages: read

jobs:
  gomboc-orl-remediate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          ref: ${{ github.event.pull_request.head.sha }}
          fetch-depth: 0

      - uses: gomboc-ai/actions/on-pull-request-runner@main
        with:
          mode: remediate
        env:
          GOMBOC_ACCESS_TOKEN: ${{ secrets.GOMBOC_ACCESS_TOKEN }}

Fork PRs: if the PR originates from a fork (pull_request.head.repo.full_name != github.repository), the push step is skipped with a warning. Do not use pull_request_target to work around this unless you understand the security tradeoffs.

No remediation PR opened? Check the job log for ORL report totals: findings=…, fixes=…, changes=…. If fixes=0 and changes=0, ORL found violations but could not auto-remediate them — there is nothing to commit.

Blocking the pipeline on findings

By default, the action exits successfully even when ORL reports findings. Set fail-on-findings: true to fail the job and block the pipeline:

- uses: gomboc-ai/actions/on-pull-request-runner@main
  with:
    mode: audit
    fail-on-findings: true
  env:
    GOMBOC_ACCESS_TOKEN: ${{ secrets.GOMBOC_ACCESS_TOKEN }}

Then protect your branch in Settings → Branches → Branch protection rules by requiring the gomboc-orl-audit status check before merging.

How it works

1. Resolve rules channel from JWT (or orl-channel input)

2. Pull ORL rules into a local cache

3. git diff PR base..head → list of changed files

4. Detect language and workspaces per changed file

5. Run orl remediate in parallel per workspace (default concurrency: 3)

6. POST scan results to Gomboc Integrations

7. Audit: post inline review comments + summary comment → upload artifacts

8. Remediate: copy fixes → push bot branch → open stacked PR → upload artifacts

All inputs

Input	Default	Description
mode	(required)	audit or remediate
fail-on-findings	false	Fail the job when findings or changes are greater than zero (audit only)
max-changed-files	50	Maximum PR-changed paths to process
orl-channel	(from token)	Rules channel; empty = resolved from GOMBOC_ACCESS_TOKEN JWT
orl-version	(latest)	ORL Docker image tag
orl-image	""	Full Docker image ref — overrides orl-version when set
rules-service-url	https://rules.app.gomboc.ai	Gomboc Rules Service base URL
integrations-service-url	https://integrations.app.gomboc.ai	Gomboc Integrations base URL
portal-service-url	https://app.gomboc.ai	Portal base URL for rule links in inline comments
integrations-enabled	true	Set false to skip posting results to Integrations
scan-timeout-seconds	(no limit)	Timeout per ORL remediate run (seconds)
orl-timeout	(no limit)	ORL --timeout
orl-rule-timeout	10s	ORL --default-rule-timeout
remediation-branch-prefix	gomboc/orl-remediation	Branch prefix for stacked remediation PRs
comment-max-per-pr	50	Maximum inline review comments per PR