Integrating Security Gates Into GitHub Actions Workflows

GitHub Actions is where most teams run their CI pipelines. Adding a security scanning step as a required check ensures that every pull request is analyzed before merge.

Basic integration

A security gate in GitHub Actions follows the same pattern as any other CI check:

1. Trigger on pull request events.
2. Run the scan against the PR diff.
3. Report results as a check status.
4. Block merge if the policy is violated.

name: Security Gate
on:
  pull_request:
    branches: [main]

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

      - name: Run security scan
        run: npx secbez scan --diff origin/main...HEAD

      - name: Evaluate policy
        run: npx secbez gate --policy .secbez/policy.yml

Making it a required check

After the workflow runs successfully once:

1. Go to repository Settings > Branches > Branch protection rules.
2. Enable "Require status checks to pass before merging."
3. Add your security scan job as a required check.

This ensures no PR can merge without passing the security gate.

Handling findings

When the scanner finds issues, the workflow should:

• Annotate the PR with findings linked to specific lines.
• Provide remediation guidance in the check output.
• Distinguish blocking from advisory findings based on policy.

      - name: Annotate PR
        if: failure()
        uses: actions/github-script@v7
        with:
          script: |
            // Post findings as PR review comments
            // linked to specific file and line numbers

Performance considerations

Security scans should not double your CI time. Keep scan times low by:

• Scanning only the diff, not the entire repository.
• Running detectors in parallel.
• Caching analysis results for unchanged files.
• Setting a reasonable timeout (60 seconds is achievable for most PRs).

Progressive rollout

Do not make the check required on day one. Start with an optional check that reports results without blocking. Once the team trusts the results, escalate to a required check.

This matches the shadow-warn-enforce pattern described in progressive rollout strategies. Build trust before enforcement.