For the complete documentation index, see llms.txt. This page is also available as Markdown.

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):

Non-blocking (audit only):

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.

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.

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.

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:

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

Last updated