Skip to main content

​
GitHub Actions

Add MergeGuide policy checks to your GitHub Actions workflows.

​
Quick Start

Add this workflow to .github/workflows/mergeguide.yml: 
name: MergeGuide Check

on:
  pull_request:
    branches: [main, develop]

jobs:
  policy-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Full history for diff

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install MergeGuide CLI
        run: npm install -g @mergeguide/cli

      - name: Run Policy Check
        env:
          MERGEGUIDE_API_KEY: ${{ secrets.MERGEGUIDE_API_KEY }}
        run: mergeguide check --format sarif > results.sarif

      - name: Upload SARIF results
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

​
Using the Official Action

Use the official MergeGuide GitHub Action for simpler setup: 
name: MergeGuide Check

on:
  pull_request:

jobs:
  policy-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: mergeguide/action@v1
        with:
          api-key: ${{ secrets.MERGEGUIDE_API_KEY }}

​
Action Inputs

InputDescriptionRequiredDefault
api-keyMergeGuide API keyYes-
fail-on-warningsFail if warnings foundNofalse
policiesComma-separated policy IDsNoAll enabled
config-filePath to config fileNo.mergeguide.yaml
sarif-outputOutput SARIF fileNo-

​
Action Outputs

OutputDescription
passedtrue if all checks passed
violations-countNumber of violations found
evaluation-idID of the evaluation

​
Workflow Examples

​
Basic PR Check

name: PR Policy Check

on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: mergeguide/action@v1
        with:
          api-key: ${{ secrets.MERGEGUIDE_API_KEY }}

​
Check with Branch Protection

name: Required Policy Check

on:
  pull_request:
    branches: [main]

jobs:
  policy-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: mergeguide/action@v1
        id: check
        with:
          api-key: ${{ secrets.MERGEGUIDE_API_KEY }}
          fail-on-warnings: true

      - name: Comment on PR
        if: failure()
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: '❌ Policy check failed. Please review the violations.'
            })

​
Security Scanning with SARIF

name: Security Scan

on:
  push:
    branches: [main]
  pull_request:

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

      - uses: mergeguide/action@v1
        with:
          api-key: ${{ secrets.MERGEGUIDE_API_KEY }}
          sarif-output: mergeguide-results.sarif

      - name: Upload to GitHub Security
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: mergeguide-results.sarif

​
Scheduled Compliance Scan

name: Weekly Compliance Scan

on:
  schedule:
    - cron: '0 9 * * 1'  # Every Monday at 9 AM

jobs:
  compliance:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install CLI
        run: npm install -g @mergeguide/cli

      - name: Run Full Scan
        env:
          MERGEGUIDE_API_KEY: ${{ secrets.MERGEGUIDE_API_KEY }}
        run: |
          mergeguide check --all --format json > results.json

      - name: Upload Report
        uses: actions/upload-artifact@v4
        with:
          name: compliance-report
          path: results.json

​
Matrix Strategy for Multiple Languages

name: Multi-Language Check

on:
  pull_request:

jobs:
  check:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        language: [javascript, python, java]
    steps:
      - uses: actions/checkout@v4

      - uses: mergeguide/action@v1
        with:
          api-key: ${{ secrets.MERGEGUIDE_API_KEY }}
          config-file: .mergeguide-${{ matrix.language }}.yaml

​
Setting Up Secrets

  1. Go to your repository’s Settings > Secrets and variables > Actions
  2. Click New repository secret
  3. Name: MERGEGUIDE_API_KEY
  4. Value: Your MergeGuide API key
  5. Click Add secret

​
Organization-Level Secrets

For multiple repositories, use organization secrets:
  1. Go to organization Settings > Secrets and variables > Actions
  2. Create MERGEGUIDE_API_KEY
  3. Set repository access policy

​
Branch Protection Rules

Require MergeGuide checks to pass:
  1. Go to repository Settings > Branches
  2. Add or edit branch protection rule for main
  3. Enable “Require status checks to pass”
  4. Search for and select “MergeGuide Check”
  5. Save changes

​
Caching for Faster Builds

Cache the CLI installation: 
- name: Cache MergeGuide CLI
  uses: actions/cache@v4
  with:
    path: ~/.npm
    key: ${{ runner.os }}-mergeguide-cli

- name: Install MergeGuide CLI
  run: npm install -g @mergeguide/cli

​
Troubleshooting

​
Check Not Running

  1. Verify workflow file is in .github/workflows/
  2. Check workflow triggers match your use case
  3. Verify YAML syntax is valid

​
Authentication Errors

  1. Verify MERGEGUIDE_API_KEY secret is set
  2. Check API key hasn’t expired
  3. Ensure key has required scopes

​
Timeout Issues

Increase timeout for large repositories: 
- uses: mergeguide/action@v1
  timeout-minutes: 15
  with:
    api-key: ${{ secrets.MERGEGUIDE_API_KEY }}

​
Debug Mode

Enable debug logging: 
- uses: mergeguide/action@v1
  env:
    MERGEGUIDE_DEBUG: 'true'
  with:
    api-key: ${{ secrets.MERGEGUIDE_API_KEY }}