GitHub Action Reference¶

aegis-governance/.github/actions/aegis-gate -- Reusable composite action for enforcing AEGIS governance gates in GitHub Actions workflows.

Overview¶

The AEGIS Governance Gate action evaluates a proposal against AEGIS governance gates by invoking the deployed AWS Lambda function. Use it in any repository to enforce governance checks before deployment, merging, or other critical operations.

The action:

Configures AWS credentials via OIDC
Invokes the AEGIS Lambda function with the proposal payload
Parses the decision response
Writes a summary table to the GitHub Actions step summary
Optionally fails the workflow if the decision is halt

Usage¶

- uses: undercurrentai/aegis-governance/.github/actions/aegis-gate@main
  with:
    proposal_summary: "Deploy new authentication service"
    estimated_impact: "high"
    risk_score: "0.4"
    complexity_score: "0.7"
    aws_role_arn: ${{ secrets.AEGIS_GATE_ROLE_ARN }}

Inputs¶

Input	Required	Default	Description
`proposal_summary`	Yes		Brief description of the proposed change
`estimated_impact`	Yes	`medium`	Impact level: `low`, `medium`, `high`, `critical`
`risk_score`	No	`0.0`	Risk score (0.0-1.0)
`risk_baseline`	No	`0.0`	Risk baseline (0.0-1.0)
`profit_proposed`	No	`0.0`	Proposed profit value
`profit_baseline`	No	`0.0`	Profit baseline value
`novelty_score`	No	`0.5`	Novelty score (0.0-1.0)
`complexity_score`	No	`0.5`	Complexity score (0.0-1.0, higher = simpler)
`quality_score`	No	`0.7`	Quality score (0.0-1.0)
`agent_id`	No	`github-actions`	Agent/caller identifier
`aws_role_arn`	Yes		AWS IAM role ARN for AEGIS API access (OIDC)
`aws_region`	No	`us-west-2`	AWS region where AEGIS is deployed
`aegis_function_name`	No	`aegis-evaluate-proposal-prod`	AEGIS Lambda function name
`fail_on_halt`	No	`true`	Fail the workflow if AEGIS returns HALT

Outputs¶

Output	Description
`status`	AEGIS decision status: `proceed`, `pause`, `halt`, `escalate`
`confidence`	Decision confidence score (0.0-1.0)
`rationale`	Human-readable decision rationale
`decision_json`	Full decision response as a JSON string

Example Workflows¶

Pre-Deployment Gate¶

Run AEGIS governance check before deploying to production:

name: Deploy with Governance Gate

on:
  push:
    branches: [main]

permissions:
  id-token: write
  contents: read

jobs:
  governance-gate:
    runs-on: ubuntu-latest
    outputs:
      status: ${{ steps.aegis.outputs.status }}
      confidence: ${{ steps.aegis.outputs.confidence }}
    steps:
      - name: AEGIS Governance Gate
        id: aegis
        uses: undercurrentai/aegis-governance/.github/actions/aegis-gate@main
        with:
          proposal_summary: "Deploy ${{ github.repository }} to production"
          estimated_impact: "high"
          risk_score: "0.3"
          complexity_score: "0.7"
          quality_score: "0.85"
          aws_role_arn: ${{ secrets.AEGIS_GATE_ROLE_ARN }}

  deploy:
    needs: governance-gate
    if: needs.governance-gate.outputs.status == 'proceed'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Deploy to production
        run: ./scripts/deploy.sh

PR Check (Non-Blocking)¶

Use as a PR status check without blocking on halt:

name: AEGIS PR Review

on:
  pull_request:
    branches: [main]

permissions:
  id-token: write
  contents: read
  pull-requests: write

jobs:
  aegis-review:
    runs-on: ubuntu-latest
    steps:
      - name: AEGIS Governance Review
        id: aegis
        uses: undercurrentai/aegis-governance/.github/actions/aegis-gate@main
        with:
          proposal_summary: "${{ github.event.pull_request.title }}"
          estimated_impact: "medium"
          risk_score: "0.2"
          aws_role_arn: ${{ secrets.AEGIS_GATE_ROLE_ARN }}
          fail_on_halt: "false"

      - name: Comment PR with decision
        uses: actions/github-script@v7
        with:
          script: |
            const status = '${{ steps.aegis.outputs.status }}';
            const confidence = '${{ steps.aegis.outputs.confidence }}';
            const rationale = `${{ steps.aegis.outputs.rationale }}`;

            const emoji = {
              proceed: ':white_check_mark:',
              pause: ':warning:',
              halt: ':no_entry:',
              escalate: ':rotating_light:'
            }[status] || ':question:';

            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body: `## ${emoji} AEGIS Governance Decision\n\n` +
                    `| Field | Value |\n|-------|-------|\n` +
                    `| **Status** | \`${status}\` |\n` +
                    `| **Confidence** | ${confidence} |\n` +
                    `| **Rationale** | ${rationale} |`
            });

Using Decision Outputs¶

Access the full decision JSON for custom logic:

- name: AEGIS Gate
  id: aegis
  uses: undercurrentai/aegis-governance/.github/actions/aegis-gate@main
  with:
    proposal_summary: "Infrastructure change"
    estimated_impact: "critical"
    risk_score: "0.6"
    aws_role_arn: ${{ secrets.AEGIS_GATE_ROLE_ARN }}
    fail_on_halt: "false"

- name: Process decision
  run: |
    echo '${{ steps.aegis.outputs.decision_json }}' | python3 -c "
    import json, sys
    decision = json.load(sys.stdin)
    if decision['status'] == 'escalate':
        print('Requires escalation to:', decision.get('override_requires', []))
    for gate_name, gate in decision.get('gates', {}).items():
        if not gate['passed']:
            print(f'  FAILED: {gate_name} (value={gate[\"value\"]}, threshold={gate[\"threshold\"]})')
    "

AWS Setup¶

IAM Role Requirements¶

The action uses OIDC-based authentication via aws-actions/configure-aws-credentials@v4. The IAM role needs:

Trust policy allowing GitHub Actions OIDC provider
Permission to invoke the AEGIS Lambda function

Example trust policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::ACCOUNT_ID:oidc-provider/token.actions.githubusercontent.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringLike": {
          "token.actions.githubusercontent.com:sub": "repo:your-org/your-repo:*"
        }
      }
    }
  ]
}

Example permissions policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "lambda:InvokeFunction",
      "Resource": "arn:aws:lambda:us-west-2:ACCOUNT_ID:function:aegis-evaluate-proposal-*"
    }
  ]
}

Lambda Endpoints¶

Environment	Function Name	Region
Development	`aegis-evaluate-proposal-dev`	`us-west-2`
Production	`aegis-evaluate-proposal-prod`	`us-west-2`

Override the function name with aegis_function_name input for non-default environments.

Step Summary¶

The action automatically writes an AEGIS Governance Decision summary table to the GitHub Actions step summary. This appears on the workflow run page and includes the status, confidence score, and rationale.

Security Considerations¶

No script injection: All inputs are passed via environment variables, not string interpolation, preventing shell injection attacks
OIDC authentication: Uses short-lived tokens via AWS OIDC, not long-lived access keys
Heredoc delimiters: Multi-line output values use heredoc delimiters to prevent injection into GITHUB_OUTPUT
Principle of least privilege: The IAM role only needs lambda:InvokeFunction permission on the specific AEGIS function