> For the complete documentation index, see [llms.txt](https://docs.gomboc.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.gomboc.ai/integrations/continuous-integration-ci-build-systems/github-actions.md).

# 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](https://docs.gomboc.ai/integrations/continuous-integration-ci-build-systems/ci-pipeline-configuration).

### Which action should I use?

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

***

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

```yaml
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):**

```yaml
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](https://crontab.guru) to generate one.

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

```yaml
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](https://github.com/Gomboc-AI/actions).

> **Need more flexibility?** If you need to run the Gomboc CLI directly, Docker images are available on DockerHub under [`gombocai/cli`](https://hub.docker.com/r/gombocai/cli).

***

### ORL Runner (`on-pull-request-runner`)

The `on-pull-request-runner` action uses [ORL (Open Remediation Language)](https://github.com/Gomboc-AI/orl) 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

<table><thead><tr><th width="413.875">Feature</th><th>Audit</th><th>Remediate</th></tr></thead><tbody><tr><td>Inline review comments on changed lines</td><td>yes</td><td>no</td></tr><tr><td>Summary PR comment</td><td>yes</td><td>no</td></tr><tr><td>Stacked remediation PR (with fixes)</td><td>no</td><td>yes</td></tr><tr><td>Integrations telemetry</td><td>yes</td><td>yes</td></tr><tr><td><code>fail-on-findings</code> to block the pipeline</td><td>yes</td><td>no</td></tr><tr><td>Fork PR push</td><td>n/a</td><td>skipped</td></tr></tbody></table>

#### 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.

```yaml
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.

```yaml
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:

```yaml
- 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                                    |