Release Gates

Enforce quality standards with automated checks and manual approvals before releasing to production.

Overview

Release gates are quality checkpoints that must pass before a release can proceed to the next stage. They prevent broken code, security vulnerabilities, and performance regressions from reaching production.

Gates can be:

Automated - Tests, validations, and scans that run automatically
Manual - Human reviews and approvals
Policy-based - Rules that enforce organizational standards

M3 Forge provides a configurable gate framework that integrates with your existing CI/CD pipeline.

Gate Types

Validation Gates

Validate workflow and agent definitions for correctness:

Gate	Description	Failure Condition
DAG validation	Check workflow is valid directed acyclic graph	Contains cycles, unreachable nodes
Schema validation	Verify node configs match schemas	Invalid types, missing required fields
JSONPath validation	Check all variable references are valid	References non-existent nodes
Node registry check	Ensure all node types exist	Unknown node type

Configuration:


{
  "gates": {
    "validation": {
      "enabled": true,
      "fail_on_warnings": false,
      "check_dag_cycles": true,
      "check_node_schemas": true,
      "check_jsonpath": true
    }
  }
}

Test Gates

Execute automated tests to verify functionality:

Gate	Description	Failure Condition
Unit tests	Test individual node implementations	Any test fails
Integration tests	Test full workflow end-to-end	Workflow execution fails
Regression tests	Compare outputs with baseline	Output differs from expected
Performance tests	Benchmark execution time	Latency exceeds threshold

Configuration:


{
  "gates": {
    "tests": {
      "enabled": true,
      "unit_tests": {
        "required_pass_rate": 100,
        "timeout_seconds": 300
      },
      "integration_tests": {
        "required_pass_rate": 95,
        "timeout_seconds": 600
      },
      "performance_tests": {
        "max_p95_latency_ms": 5000,
        "max_error_rate": 2.0
      }
    }
  }
}

Security Gates

Scan for vulnerabilities and policy violations:

Gate	Description	Failure Condition
Secret scanning	Detect hardcoded credentials	API keys, passwords in code
Dependency scanning	Check for vulnerable dependencies	Known CVEs in packages
PII detection	Identify personally identifiable information	PII in workflow definitions
SAST (Static Analysis)	Code quality and security checks	High-severity issues found

Configuration:


{
  "gates": {
    "security": {
      "enabled": true,
      "secret_scanning": {
        "block_on_secrets": true,
        "patterns": ["api_key", "password", "token"]
      },
      "dependency_scanning": {
        "block_severity": ["critical", "high"],
        "ignore_dev_dependencies": true
      },
      "pii_detection": {
        "block_on_pii": true,
        "entities": ["email", "ssn", "credit_card"]
      }
    }
  }
}

Security gates are mandatory for production deployments and cannot be disabled without admin override.

Approval Gates

Require human review and approval:

Gate	Description	Configuration
Code review	Peer review of changes	Min 1 approval, max 1 rejection
Deployment approval	Manual sign-off before deploy	2 approvals for production
Emergency bypass	Allow skipping gates in emergencies	Requires admin role + justification

Configuration:


{
  "gates": {
    "approvals": {
      "code_review": {
        "min_approvals": 1,
        "max_rejections": 0,
        "require_approval_from_owners": true
      },
      "deployment_approval": {
        "environments": {
          "staging": {"min_approvals": 1},
          "production": {"min_approvals": 2}
        },
        "allowed_approvers": ["maintainer", "admin"],
        "timeout_hours": 24
      }
    }
  }
}

Compliance Gates

Enforce organizational policies and compliance requirements:

Gate	Description	Failure Condition
Change ticket	Require Jira/ServiceNow ticket	No ticket associated with change
Documentation	Ensure docs are updated	README missing or outdated
Audit trail	Verify all changes are logged	Missing audit events
Ownership	Check workflows have assigned owner	Workflow has no owner

Configuration:


{
  "gates": {
    "compliance": {
      "enabled": true,
      "require_change_ticket": {
        "environments": ["production"],
        "ticket_systems": ["jira", "servicenow"]
      },
      "require_documentation": {
        "files": ["README.md", "CHANGELOG.md"],
        "check_updated": true
      },
      "require_ownership": {
        "owner_field": "metadata.owner",
        "valid_owners": ["team-a", "team-b"]
      }
    }
  }
}

Gate Configuration

Configure gates at different levels of the release pipeline:

Global Gates

Apply to all releases across all environments:


{
  "global_gates": {
    "validation": {"enabled": true},
    "security": {"enabled": true},
    "tests": {"enabled": true}
  }
}

Environment-Specific Gates

Different gates for different environments:


{
  "environments": {
    "development": {
      "gates": {
        "validation": {"enabled": true},
        "tests": {"unit_tests": {"enabled": true}}
      }
    },
    "staging": {
      "gates": {
        "validation": {"enabled": true},
        "tests": {
          "unit_tests": {"enabled": true},
          "integration_tests": {"enabled": true}
        },
        "security": {"enabled": true}
      }
    },
    "production": {
      "gates": {
        "validation": {"enabled": true},
        "tests": {
          "unit_tests": {"enabled": true},
          "integration_tests": {"enabled": true},
          "performance_tests": {"enabled": true}
        },
        "security": {"enabled": true},
        "approvals": {"deployment_approval": {"min_approvals": 2}},
        "compliance": {"enabled": true}
      }
    }
  }
}

Production has the strictest gates, development has the most lenient.

Workflow-Specific Gates

Override gates for specific critical workflows:


{
  "workflows": {
    "invoice-extraction": {
      "gates": {
        "tests": {
          "required_pass_rate": 100,
          "regression_tests": {"enabled": true}
        },
        "approvals": {
          "deployment_approval": {"min_approvals": 3}
        }
      }
    }
  }
}

Running Gates

Gates execute at different points in the pipeline:

On Pull Request

When a PR is opened or updated:

Trigger CI/CD pipeline

GitHub Actions, GitLab CI, or Jenkins runs.

Execute validation gates

DAG validation
Schema validation
JSONPath validation

Run unit tests

Execute tests for changed workflows and nodes.

Run security scans

Secret scanning
Dependency scanning
SAST

Report results

Post status checks back to GitHub/Gitea.

Example GitHub Actions workflow:


name: Release Gates
 
on:
  pull_request:
    branches: [main]
 
jobs:
  validation:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Validate workflows
        run: m3 validate workflows/
      - name: Run unit tests
        run: m3 test --unit
      - name: Security scan
        run: m3 security scan

On Deployment

Before deploying a version to an environment:

Select version to deploy

In the Release Pipeline, click “Deploy” on a version.

Execute pre-deployment gates

Integration tests in target environment
Performance tests
Compliance checks

Request approvals (if required)

Send notifications to approvers.

Wait for approvals

Deployment is blocked until min approvals received.

Execute deployment

Once all gates pass and approvals granted.

Gate Results

Gates produce pass/fail results with detailed reports:

Gate Status

Status	Description	Icon
Passed	Gate completed successfully	✓
Failed	Gate found issues that block release	✗
Warning	Gate found non-blocking issues	⚠️
Skipped	Gate was disabled or not applicable	⊘
Running	Gate is currently executing	⏳

Gate Report

Each gate produces a structured report:


{
  "gate": "validation",
  "status": "passed",
  "started_at": "2024-03-19T14:23:15Z",
  "completed_at": "2024-03-19T14:23:18Z",
  "duration_seconds": 3,
  "checks": [
    {
      "name": "DAG validation",
      "status": "passed",
      "message": "All workflows are valid DAGs"
    },
    {
      "name": "Schema validation",
      "status": "passed",
      "message": "All node configs match schemas"
    }
  ]
}

Viewing Gate Results

In the Release Pipeline, expand a PR or release to see gate results:


✓ Validation (3s)
  ✓ DAG validation
  ✓ Schema validation
  ✓ JSONPath validation

✓ Tests (2m 15s)
  ✓ Unit tests: 47/47 passed
  ✓ Integration tests: 12/12 passed

✗ Security (45s)
  ⚠️ Secret scanning: 1 warning (API key in comment)
  ✓ Dependency scanning: No vulnerabilities
  ✗ PII detection: Email address found in test data

⏳ Approvals
  ✓ alice approved (1 hour ago)
  ⏳ Waiting for 1 more approval

Click any gate to see full logs and error details.

Bypassing Gates

In emergency situations, gates can be bypassed with proper authorization:

Emergency Override

Request override

Click “Request Emergency Override” in the Release Pipeline.

Provide justification


{
  "reason": "Critical production outage - invoice processing down",
  "ticket": "INC-12345",
  "impact": "All customers unable to submit invoices",
  "estimated_duration": "2 hours"
}

Admin approval

An admin must approve the override request.

Deploy with override

Gates are skipped and deployment proceeds.

Emergency overrides are logged in the audit trail and reviewed in post-incident analysis. Frequent overrides indicate gates are too strict or processes need improvement.

Override Audit

All gate overrides are logged:


{
  "event": "gate.override",
  "gate": "security",
  "version": "v1.3.1",
  "environment": "production",
  "requested_by": "alice",
  "approved_by": "bob",
  "reason": "Critical production outage",
  "ticket": "INC-12345",
  "timestamp": "2024-03-19T15:00:00Z"
}

Custom Gates

Create custom gates for organization-specific requirements:

Webhook Gate

Call external API to validate release:


{
  "gates": {
    "custom": {
      "webhook": {
        "url": "https://your-api.com/validate-release",
        "method": "POST",
        "headers": {
          "Authorization": "Bearer ${WEBHOOK_TOKEN}"
        },
        "body": {
          "version": "{{version}}",
          "environment": "{{environment}}",
          "changes": "{{changes}}"
        },
        "success_condition": "response.approved == true",
        "timeout_seconds": 30
      }
    }
  }
}

The external API returns:


{
  "approved": true,
  "message": "Release approved by compliance team",
  "reviewer": "compliance-bot"
}

Script Gate

Execute custom validation script:


{
  "gates": {
    "custom": {
      "script": {
        "path": "./scripts/validate-workflows.sh",
        "args": ["--environment", "{{environment}}"],
        "working_directory": "/path/to/repo",
        "timeout_seconds": 300,
        "success_exit_code": 0
      }
    }
  }
}

Example script:


#!/bin/bash
# validate-workflows.sh
 
ENV=$1
 
# Check workflow naming conventions
for file in workflows/*.json; do
  if [[ ! $file =~ ^workflows/[a-z-]+\.json$ ]]; then
    echo "Invalid filename: $file"
    exit 1
  fi
done
 
# Check all workflows have owner
jq -e '.metadata.owner' workflows/*.json || exit 1
 
echo "All validations passed"
exit 0

Gate Metrics

Track gate performance to optimize release velocity:

Metric	Description	Target
Gate pass rate	Percentage of gates that pass	> 95%
Mean time to pass gates	Average time to pass all gates	< 10 minutes
Gate failure rate by type	Which gates fail most often	Identify bottlenecks
Override rate	How often gates are bypassed	< 5%

View metrics in Monitoring → Release Gates.

Best Practices

Fast Feedback

Gates should fail fast:

Run validation gates first (seconds)
Run unit tests next (minutes)
Run integration tests last (minutes to hours)

This gives developers quick feedback on simple issues before waiting for slow tests.

Actionable Failures

Gate failure messages should be clear and actionable:

✓ Good: “Workflow ‘invoice-extraction’ has invalid JSONPath: $.nodes.missing_node.output does not exist”

✗ Bad: “Validation failed”

Incremental Strictness

Start with lenient gates and tighten over time:

Week 1 - Enable validation gates with warnings only
Week 2 - Enable validation gates with failures
Week 3 - Add unit test gates
Week 4 - Add security gates
Month 2 - Add integration tests and approvals

This gives teams time to fix existing issues before blocking releases.

Gate Ownership

Assign ownership for each gate type:

Validation gates - Platform team
Test gates - QA team
Security gates - Security team
Compliance gates - Compliance team

Owners are responsible for maintaining gates and addressing failures.

Troubleshooting

Gate Stuck in “Running”

If a gate is stuck:

Check gate logs

View real-time logs to see where it’s stuck.

Check timeout

Ensure gate timeout is appropriate for gate complexity.

Retry gate

Click “Retry” to re-run the gate.

Contact gate owner

If issue persists, contact gate owner for investigation.

Gate Failing Inconsistently

For flaky gates:

Increase timeout - Gate may be timing out inconsistently
Check external dependencies - Gate may depend on flaky service
Add retries - Configure automatic retry on transient failures
Investigate test - Test itself may be non-deterministic

Too Many Gate Failures

If gates fail frequently:

Review gate configuration - Gates may be too strict
Improve documentation - Developers may not understand requirements
Add pre-commit hooks - Catch issues before PR submission
Provide tooling - Auto-fix common issues (linting, formatting)

Next Steps

Configure gates in Environments
Set up the Release Pipeline to use gates
Monitor gate performance in Monitoring
Learn about Publishing after gates pass