Workflow Compliance

What is the Compliance Center?

The Compliance Center helps you ensure your CI/CD workflows follow your organization's best practices and compliance requirements. Using AI-powered analysis, it automatically evaluates your workflows against configurable rules and provides detailed reports with actionable recommendations.

Key Benefits

• Automated Compliance Checking: Instantly evaluate workflows against your organization's standards
• Multi-Level Visibility: Monitor compliance across your entire organization, individual projects, repositories, and workflows
• Real-Time Monitoring: Track evaluation progress with automatic updates
• Actionable Insights: Get specific recommendations for improving compliance
• Prioritized Issues: Focus on critical issues first with importance-based categorization

Getting Started

Accessing the Compliance Center

Navigate to the Compliance Center from your organization settings:

1. Go to your Organization Settings
2. Select Compliance from the navigation menu
3. You'll see two main tabs:
   • Dashboard: View compliance scores and evaluation results
   • Settings: Manage compliance rules and categories

Understanding Compliance Levels

You can view compliance at three different levels:

1. Organization Level (/orgs/{orgId}/compliance)

   • Overall compliance across all projects
   • Common issues affecting multiple workflows
   • Organization-wide trends

2. Project Level (/projects/{projectId}/guardrails)

   • Compliance for all workflows in a specific project
   • Project-specific compliance summary

3. Repository Level (/repos/{repoId}/guardrails)

   • All workflows within a single repository
   • Repository compliance overview

Compliance Guardrails and Categories

Compliance Guardrails are individual rules that are used to evaluate whether or not a given GitHub Actions Workflow is compliance with organizational standards. These rules are generally evaluated based on the source code of the workflow, but can also include other information including dependabot configurations. Here is an example rule:

Every GitHub Actions Workflow must explicitly define minimum required permissions for GITHUB_TOKEN at the workflow job level. Default permissions or "write-all" violate least privilege principle.

Individual GitHub Actions Workflows can be scored against a centralized list of these rules to determine their compliance score. This is useful information that serves two purposes:

1. Developers - see which rules a workflow failed so they can implement fixes
2. Administrators - see aggregated compliance scores to gain a strategic view of the organization's automations

How Guardrails Work

Compliance rules are organized into categories that apply to different types of workflow files. Each rule:

• Has a clear description of the requirement
• Includes an importance level (Critical, High, Medium, or Low)
• Is evaluated automatically by AI
• Provides specific feedback when workflows don't comply

Rule Importance Levels

Rules are prioritized to help you focus on what matters most:

Category Conditions

Categories use file path patterns to determine which rules apply to specific workflows. For example:

• **/*.yml - Applies to all YAML files
• .github/workflows/*.yml - Applies only to GitHub Actions workflow files

This ensures that workflows are only evaluated against relevant rules.

Running Compliance Evaluations

Triggering an Evaluation

You can evaluate workflows on-demand from any compliance dashboard:

1. Locate the workflow in the compliance table
2. Click "Run Evaluation" next to the workflow
3. The evaluation status will change to "Pending"

Monitoring Progress

Evaluations run automatically and update in real-time:

• Pending: Evaluation is queued and waiting to start
• Running: AI is actively analyzing your workflow
• Complete: Evaluation finished successfully
• Failed: An error occurred during evaluation

The dashboard automatically refreshes every 5 seconds while evaluations are in progress.

Understanding Your Results

Compliance Scores

Your compliance score is calculated as:

Score = (Passing Rules / Total Applicable Rules) × 100

Important Notes:

• Scores range from 0% to 100%
• Rules marked as "Not Applicable" or "Unknown" are excluded from the calculation
• Color coding helps you quickly identify issues:
  • Green (≥80%): Good compliance
  • Yellow (60-79%): Needs attention
  • Red (<60%): Requires immediate action

Rule Evaluation Results

Each rule in your evaluation will have one of four results:

Understanding Failure Comments

When a rule fails, the AI provides a specific explanation of why. For example:

Rule: "Production deployments must have manual approval steps" Result: Fail Comment: "No approval gate found for production deployments. The workflow deploys directly to the 'prod' environment without requiring manual approval."

These comments help you understand exactly what needs to be fixed.

Developers - Compliance Scores in Projects

Individual developers can see compliance scores in their project dashboard, under the "Guardrails" section. If a workflow has a compliance score, it will be populated on that dashboard. If a workflow does not have a compliance score, you can click the "Run Evaluation" button to calculate the score which takes about a minute to execute. Developers can click on each workflow to see which rules pass/failed, then enter the GenAI Editor to implement fixes.

Administrators - Aggregated Compliance Scores

Administrators can access the Compliance Center on the left-navbar of the application to view a high-level status of the organization's workflow compliance scores. The dashboard shows score over time, the current score, and major violations. CodeCargo comes built-in with about 30 industry-standard recommendations for GitHub Actions Workflow compliance.