> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mergeguide.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub

> Run MergeGuide on pull requests with the GitHub Action and upload results to code scanning.

Add MergeGuide to GitHub with the official Action. It runs your policy checks on
pushes and pull requests, and can upload SARIF results to GitHub code scanning so
findings appear in the **Security** tab.

## Add the Action

Create `.github/workflows/mergeguide.yml` in your repository:

```yaml .github/workflows/mergeguide.yml theme={null}
name: MergeGuide Policy Check

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  policy-check:
    name: Policy Check
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Run MergeGuide
        uses: MergeGuide/mergeguide/action@v1
        with:
          paths: '.'
```

## Action inputs

| Input             | Description                                         | Default               |
| ----------------- | --------------------------------------------------- | --------------------- |
| `paths`           | Files or directories to check (space-separated).    | `.`                   |
| `format`          | Output format: `text`, `json`, `sarif`, `markdown`. | `text`                |
| `policy`          | Path to custom policy file(s) (space-separated).    | —                     |
| `no-defaults`     | Skip the default policies.                          | `false`               |
| `fail-on-warning` | Exit with an error if warnings are found.           | `false`               |
| `sarif-file`      | Path to write SARIF output for code scanning.       | —                     |
| `github-token`    | Token used to upload SARIF results.                 | `${{ github.token }}` |

## Action outputs

| Output       | Description                                                |
| ------------ | ---------------------------------------------------------- |
| `passed`     | Whether all checks passed (`true` / `false`).              |
| `violations` | Number of violations found.                                |
| `report`     | Path to the output report file (when `sarif-file` is set). |

## Upload to GitHub code scanning

To make findings appear in the repository's **Security** tab, write SARIF and
upload it. Grant the job `security-events: write`:

```yaml .github/workflows/mergeguide.yml theme={null}
name: MergeGuide Security Scan

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  security-scan:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    steps:
      - uses: actions/checkout@v4

      - name: Run MergeGuide
        id: mergeguide
        uses: MergeGuide/mergeguide/action@v1
        with:
          paths: 'src/'
          sarif-file: 'mergeguide-results.sarif'

      - name: Upload SARIF
        if: always()
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: 'mergeguide-results.sarif'
          category: 'mergeguide'

      - name: Fail if violations found
        if: steps.mergeguide.outputs.passed == 'false'
        run: |
          echo "::error::MergeGuide found policy violations"
          exit 1
```

## Block merges on findings

To hold a merge until blocking findings are resolved, add the MergeGuide job to
your branch's **required status checks** in **Settings → Branches**. Once required,
a pull request can't merge while the check is failing. See
[Set up the PR gate](/install/pr-gate).

## Next steps

<CardGroup cols={2}>
  <Card title="PR gate" icon="code-pull-request" href="/install/pr-gate">
    Block merges on blocking findings.
  </Card>

  <Card title="CI/CD patterns" icon="arrows-spin" href="/integrations/ci-cd-patterns">
    Wire MergeGuide into any pipeline.
  </Card>
</CardGroup>