Skip to main content
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:
.github/workflows/mergeguide.yml
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

InputDescriptionDefault
pathsFiles or directories to check (space-separated)..
formatOutput format: text, json, sarif, markdown.text
policyPath to custom policy file(s) (space-separated).—
no-defaultsSkip the default policies.false
fail-on-warningExit with an error if warnings are found.false
sarif-filePath to write SARIF output for code scanning.—
github-tokenToken used to upload SARIF results.${{ github.token }}

​
Action outputs

OutputDescription
passedWhether all checks passed (true / false).
violationsNumber of violations found.
reportPath 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:
.github/workflows/mergeguide.yml
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.

​
Next steps

PR gate

Block merges on blocking findings.

CI/CD patterns

Wire MergeGuide into any pipeline.