Using PR Policies as Control Gates in GitHub Workflows

​

Overview

• Code reviews are properly conducted
• PRs have meaningful descriptions and linked issues
• Security requirements like code owner approval are satisfied
• Conversation resolution and stale review dismissal rules are followed

​

Available PR Policies

​

How It Works

1. Automatic PR Detection: The Chainloop CLI automatically detects when running in a pull request context and gathers PR metadata
2. Material Collection: PR information is collected as a CHAINLOOP_PR_INFO material type
3. Policy Evaluation: Attached PR policies evaluate the gathered metadata
4. Control Gate: If a policy is configured as a gate and fails, the workflow is blocked (exit code != 0)

​

Quick Start

​

Prerequisites

• Chainloop CLI Enterprise Edition (EE) with runner context gathering enabled
• A GitHub or GitLab access token configured (see Runner Context guide)
• A workflow contract configured in Chainloop

​

Step 1: Create a Contract with PR Policies

apiVersion: chainloop.dev/v1
kind: Contract
metadata:
  name: pr-quality-gate
  description: Enforce PR quality standards before merge
spec:
  policies:
    materials:
      # Require at least 2 reviewers
      - ref: pr-review-required
        gate: true
        with:
          min_reviewers: "2"
          branches: "main,release/*"

      # Require code owner approval
      - ref: pr-code-owner-review-required
        gate: true
        with:
          branches: "release/*"

      # Require meaningful PR description
      - ref: pr-description-required
        gate: true
        with:
          min_length: "50"
          allow_empty: "false"

      # Require linked issue or user story
      - ref: pr-user-story-linked
        gate: true
        with:
          patterns: "[A-Z]+-[0-9]+,#[0-9]+"

​

Step 2: Set Up GitHub Workflow

name: PR Quality Gate

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

jobs:
  pr-quality-check:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Install Chainloop CLI EE
        run: |
          curl -sfL https://dl.chainloop.dev/cli/install.sh | bash -s -- --ee

      - name: Initialize attestation (gathers PR info automatically)
        env:
          CHAINLOOP_TOKEN: ${{ secrets.CHAINLOOP_TOKEN }}
        run: |
          chainloop attestation init \
            --workflow pr-quality-gate \
            --project my-project

      - name: Push attestation
        env:
          CHAINLOOP_TOKEN: ${{ secrets.CHAINLOOP_TOKEN }}
        run: |
          # Push attestation - this will evaluate control gates
          chainloop attestation push

​

Step 3: Configure Control Gate Enforcement

chainloop org update --name my-org --block

​

Policy Configuration Examples

​

Example 1: Branch-specific Review Requirements

policies:
  materials:
    # Stricter requirements for main branch
    - ref: pr-review-required
      gate: true
      with:
        min_reviewers: "3"
        branches: "main"

    # Lighter requirements for feature branches
    - ref: pr-review-required
      gate: true
      with:
        min_reviewers: "1"
        branches: "feature/*"

​

Example 2: Enforce Conversation Resolution

policies:
  materials:
    - ref: pr-conversation-resolution-required
      gate: true
      with:
        branches: "main,release/*"

​

Example 3: Require Meaningful PR Descriptions

policies:
  materials:
    - ref: pr-description-required
      gate: true
      with:
        min_length: "100"
        allow_empty: "false"
        required_sections: "summary,testing,motivation"

​

Example 4: Ensure Stale Reviews Are Dismissed

policies:
  materials:
    - ref: pr-stale-reviews-dismissed
      gate: true
      with:
        branches: "main"

​

Handling Policy Failures

1. The workflow is blocked: chainloop attestation push returns a non-zero exit code
2. The attestation is still recorded: Chainloop tracks the non-compliant activity for audit purposes
3. Developers see clear error messages: Policy violations are displayed in the CLI output

INF push completed
┌───────────────────────────┬─────────────────────────────────────────────────────────────────────────┐
│ Initialized At            │ 26 Dec 25 10:37 UTC                                                     │
├───────────────────────────┼─────────────────────────────────────────────────────────────────────────┤
│ Attestation ID            │ 1ecd79e7-2886-46e5-901b-a9a66482187c                                    │
│ Digest                    │ sha256:f78bd5337ae68ec58b14fffb0e5317f9ecf3d5ee61afd615a165b3243fbcb045 │
│ Organization              │ my-org                                                                  │
│ Name                      │ pr-quality-gate                                                         │
│ Project                   │ my-project                                                              │
│ Version                   │ v1.65.0+next (prerelease)                                               │
│ Contract                  │ pr-quality-gate (revision 1)                                            │
│ Policy violation strategy │ ADVISORY                                                                │
│ Policies                  │ ------                                                                  │
│                           │ pr-review-required (gate): Branch feature-1 in corp/my-repo has 1       │
│                           │    reviewers, minimum should be 2                                       │
└───────────────────────────┴─────────────────────────────────────────────────────────────────────────┘
ERR the policy "pr-review-required" is configured as a gate and has violations

​

Bypassing Control Gates (Emergency Use)

chainloop attestation push --exception-bypass-policy-check

​

Best Practices

1. Start with non-blocking policies: Test policies without gate: true first to ensure they work as expected
2. Use branch-specific requirements: Apply stricter rules to production branches (main, release/*) and lighter rules to development branches
3. Combine multiple policies: Use multiple PR policies together for comprehensive quality checks
4. Monitor policy violations: Review Chainloop’s UI regularly to identify patterns in policy failures
5. Document bypass procedures: Establish clear guidelines for when and how to use --exception-bypass-policy-check
6. Keep policies updated: Review and adjust policy parameters based on team feedback and compliance requirements

​

Troubleshooting

​

PR Info Not Being Gathered

• Ensure you’re using Chainloop CLI Enterprise Edition (EE)
• Check that the workflow is triggered by a pull request event

​

Policy Always Passes Despite Invalid PR State

• Verify the policy’s branches parameter includes the target branch
• Check that the PR metadata is being gathered correctly (inspect attestation in Chainloop UI)
• Review policy parameters in the contract’s with section
• Ensure the policy is compatible with your CI/CD platform (GitHub vs GitLab)

​

Control Gate Not Blocking Workflow

• Verify gate: true is set in the policy attachment
• Check organization-wide enforcement settings (chainloop org describe)
• Ensure you’re not using --exception-bypass-policy-check flag
• Confirm the workflow doesn’t have error handling that catches the non-zero exit code

​

Additional Resources

• Control Gates Concept
• Policies Concept
• Custom Policies Guide
• Branch Protection Policies Reference