BuildGuard GitHub Action

Scan your GitHub organization for compliance policy violations using BuildGuard. Runs 5 built-in compliance policies and produces a rich job summary in the GitHub Actions UI.

Quick Start

name: Compliance Scan
on:
  schedule:
    - cron: '0 8 * * 1' # Weekly on Monday at 8 AM UTC
  workflow_dispatch:

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: Build-Flow-Labs/buildguard-action@v1
        with:
          github_token: ${{ secrets.BUILDGUARD_TOKEN }}
          organization: my-org

Note: The default ${{ github.token }} only has access to the current repository. To scan an entire organization, create a fine-grained personal access token with administration:read, contents:read, and metadata:read scoped to the target organization, and store it as a repository secret.

Inputs

Input	Required	Default	Description
github_token	Yes	${{ github.token }}	GitHub token with org read access
organization	Yes	—	GitHub organization to scan
config	No	''	Path to buildguard.json configuration file
version	No	latest	BuildGuard version (e.g., v0.1.0)
fail-below	No	0	Fail workflow if compliance score is below this (0–100). 0 = never fail

Outputs

Output	Description
compliance_score	Score as a percentage (e.g., 87.5)
score_label	PASS, WARN, or FAIL
repos_scanned	Number of repositories scanned
compliant_repos	Number of compliant repositories
non_compliant_repos	Number of non-compliant repositories
total_checks	Total policy checks run
passed_checks	Checks that passed
failed_checks	Checks that failed

Policies

BuildGuard scans for these compliance policies:

ID	Policy	Description
POL-SEC-01	Docker Root User	Detects containers running as root
POL-GOV-01	CODEOWNERS	Ensures CODEOWNERS file exists
POL-SEC-02	Secrets Detection	Scans for hardcoded secrets and credentials
POL-GOV-02	Branch Protection	Verifies branch protection rules
POL-SOX-01	SOX Separation of Duties	Enforces separation of duties controls

Examples

Fail on low compliance score

- uses: Build-Flow-Labs/buildguard-action@v1
  with:
    github_token: ${{ secrets.BUILDGUARD_TOKEN }}
    organization: my-org
    fail-below: 80

The workflow will fail with exit code 1 if the compliance score is below 80%.

Use outputs in downstream steps

- uses: Build-Flow-Labs/buildguard-action@v1
  id: buildguard
  with:
    github_token: ${{ secrets.BUILDGUARD_TOKEN }}
    organization: my-org

- name: Report results
  run: |
    echo "Score: ${{ steps.buildguard.outputs.compliance_score }}%"
    echo "Label: ${{ steps.buildguard.outputs.score_label }}"
    echo "Repos: ${{ steps.buildguard.outputs.repos_scanned }}"
    echo "Failed checks: ${{ steps.buildguard.outputs.failed_checks }}"

- name: Notify on failure
  if: steps.buildguard.outputs.score_label == 'FAIL'
  run: |
    curl -X POST "${{ secrets.SLACK_WEBHOOK }}" \
      -d '{"text":"BuildGuard: Compliance score dropped to ${{ steps.buildguard.outputs.compliance_score }}%"}'

Pin to a specific version

- uses: Build-Flow-Labs/buildguard-action@v1
  with:
    github_token: ${{ secrets.BUILDGUARD_TOKEN }}
    organization: my-org
    version: v0.1.0

Use a config file

- uses: actions/checkout@v4
- uses: Build-Flow-Labs/buildguard-action@v1
  with:
    github_token: ${{ secrets.BUILDGUARD_TOKEN }}
    organization: my-org
    config: ./buildguard.json

Job Summary

The action creates a Markdown summary in the GitHub Actions UI showing:

• Overall compliance score with pass/warn/fail indicator
• Summary table with repo and check counts
• Per-policy breakdown (when available)
• Links to BuildGuard documentation

Need more?

The free CLI includes 5 policies. BuildGuard Team & Enterprise adds:

• 20 compliance policies
• Web dashboard with trend analysis
• 6 compliance framework mappings (SOC2, SOX, NIST, ISO 27001, PCI-DSS, FedRAMP)
• PDF/HTML/JSON report exports
• Slack and email notifications
• Auto-remediation PRs
• Custom Rego policy support

License

This action wrapper is released under the MIT License. The BuildGuard binary it downloads is proprietary software — see its EULA for terms.