> ## Documentation Index
> Fetch the complete documentation index at: https://jonathansantilli-codegate-92.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflow audits

> How to use CodeGate's CI/CD audit pack to detect supply-chain, permissions, injection, and hygiene risks in GitHub Actions workflows, action definitions, and Dependabot configuration.

The workflow audit pack extends CodeGate's static analysis with a dedicated set of checks for GitHub Actions workflows, action definitions, and Dependabot configuration. Enable it with `--workflow-audits`.

```bash theme={null}
codegate scan . --workflow-audits
```

## Checks

<CardGroup cols={2}>
  <Card title="Supply chain" icon="link">
    Detects unpinned external action references (`uses: owner/repo@tag` instead of a full commit SHA), archived action references, stale action refs, floating action version tags, and — in online mode — known-vulnerable action references from the advisory registry.
  </Card>

  <Card title="Dangerous triggers" icon="bolt">
    Flags high-risk workflow trigger events: `pull_request_target` and `workflow_run`. These triggers run in the context of the base repository even when initiated by a fork, and can grant untrusted code write permissions if not carefully guarded.
  </Card>

  <Card title="Overly broad permissions" icon="shield-off">
    Reports `write-all` permission grants and explicit write grants on sensitive scopes. Also covers undocumented permissions blocks, overprovisioned secrets, `secrets: inherit` usage, and secrets referenced outside of environment blocks.
  </Card>

  <Card title="Template expression injection" icon="code">
    Detects `${{ }}` template expressions that interpolate untrusted context values (such as `github.event.pull_request.title` or `github.head_ref`) directly into `run:` steps or known sink inputs. Template injection is a common code-execution path in compromised workflows.
  </Card>

  <Card title="Dependabot checks" icon="clock">
    Cooldown checks flag Dependabot PRs merged before a configurable settling period. Execution-risk checks flag Dependabot configurations that allow auto-merge of updates with elevated execution risk. Auto-merge policy detection is also included.
  </Card>

  <Card title="Workflow hygiene" icon="broom">
    Covers concurrency gate absence (workflows that can run concurrent instances unexpectedly), obfuscation patterns in workflow definitions, unsafe conditional trust (`if:` conditions that can be bypassed), unsound `contains()` usage, bot-condition bypasses, and other hygiene signals.
  </Card>
</CardGroup>

## Collection modes

The `--collect` flag controls which artifact scope is included for auditing. It is repeatable.

| Value      | Description                                                                                             |
| ---------- | ------------------------------------------------------------------------------------------------------- |
| `default`  | Project-level artifacts only, same as `project`. This is the default when `--collect` is not specified. |
| `project`  | Collect workflows, actions, and Dependabot config from the scanned project.                             |
| `user`     | Include user-level GitHub Actions configuration.                                                        |
| `explicit` | Only include paths explicitly provided on the command line.                                             |
| `all`      | Collect from all available scopes.                                                                      |

```bash theme={null}
codegate scan . --workflow-audits --collect project
codegate scan . --workflow-audits --collect project --collect user
```

## Collection kinds

The `--collect-kind` flag restricts collection to specific artifact types. It is repeatable.

| Value        | Description                                               |
| ------------ | --------------------------------------------------------- |
| `workflows`  | GitHub Actions workflow files under `.github/workflows/`. |
| `actions`    | Action definition files (`action.yml` / `action.yaml`).   |
| `dependabot` | Dependabot configuration (`.github/dependabot.yml`).      |

```bash theme={null}
codegate scan . --workflow-audits --collect-kind workflows
codegate scan . --workflow-audits --collect-kind workflows --collect-kind actions
```

## Personas

The `--persona` flag adjusts audit sensitivity. Higher personas enable more checks.

| Value      | Description                                                                                      |
| ---------- | ------------------------------------------------------------------------------------------------ |
| `regular`  | Default. Runs checks suitable for everyday project review.                                       |
| `pedantic` | Enables additional checks that may produce more informational findings.                          |
| `auditor`  | Enables all checks, including low-signal hygiene findings. Suitable for formal security reviews. |

```bash theme={null}
codegate scan . --workflow-audits --persona auditor
```

## Runtime modes

The `--runtime-mode` flag controls whether checks that require network access are enabled.

| Value              | Description                                                                                                                                                                   |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `offline`          | Default. Only offline checks run. Known-vulnerable action lookups and other online-only checks are skipped.                                                                   |
| `online`           | All checks run, including those that perform live advisory lookups (known-vulnerable actions, archived actions, stale refs, impostor commit detection, ref/version mismatch). |
| `online-no-audits` | Network is available but audit-specific online checks are disabled.                                                                                                           |

```bash theme={null}
codegate scan . --workflow-audits --runtime-mode online
```

## Strict collection

Use `--strict-collection` to treat parse failures in collected workflow or action inputs as high-severity findings rather than silently skipping unparseable files:

```bash theme={null}
codegate scan . --workflow-audits --strict-collection
```

## Examples

Run the full audit pack on a project with online advisory lookups:

```bash theme={null}
codegate scan . --workflow-audits --collect project --persona auditor --runtime-mode online
```

Audit only Dependabot configuration:

```bash theme={null}
codegate scan . --workflow-audits --collect-kind dependabot
```

Audit workflows and action definitions in offline mode:

```bash theme={null}
codegate scan . --workflow-audits --collect-kind workflows --collect-kind actions
```

Emit results as SARIF for upload to GitHub Code Scanning:

```bash theme={null}
codegate scan . --workflow-audits --no-tui --format sarif --output codegate.sarif
```