Metadata-Version: 2.4
Name: surak
Version: 0.2.1
Summary: The Github Actions Policy Engine - Apply and configure prebuilt policies.
Project-URL: Homepage, https://github.com/spockops/surak
Project-URL: Documentation, https://github.com/spockops/surak
Project-URL: Repository, https://github.com/spockops/surak
Project-URL: Issues, https://github.com/spockops/surak/issues
Author-email: Sash Nortier <surak@spockops.com>
License: Apache-2.0
License-File: LICENSE
Keywords: cicd,devops,github-actions,pac,policy,policy-engine
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.11
Requires-Dist: click>=8.1.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0
Requires-Dist: python-dateutil>=2.8.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: all
Requires-Dist: black>=23.0.0; extra == 'all'
Requires-Dist: mypy>=1.5.0; extra == 'all'
Requires-Dist: pytest-cov>=4.1.0; extra == 'all'
Requires-Dist: pytest>=7.4.0; extra == 'all'
Requires-Dist: ruff>=0.1.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: mypy>=1.5.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# SURAK

**The GitHub Actions Policy Engine**

[![SpockOps](https://img.shields.io/badge/SpockOps-FFE200?style=flat&logoColor=black)](https://spockops.com)
[![PyPI](https://img.shields.io/pypi/v/surak)](https://pypi.org/project/surak/)
[![Python](https://img.shields.io/pypi/pyversions/surak)](https://pypi.org/project/surak/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)

Surak enforces policies on your GitHub Actions workflows. Define what's allowed in `.surak/` — who can trigger a workflow, which runners are permitted, which branch it must run from, which checks must pass, and which environments must be declared. Any run that doesn't comply is blocked.

---

## Setup

**1. Create `.surak/governance.yml` in your repo:**

```yaml
surak: v2
id: runner-governance
name: Runner Governance

applies-to: "*"

policies:
  runner_type:
    enabled: true
    require: github-hosted

  runner_os:
    enabled: true
    allow:
      - Linux
```

**2. Add the policy gate to your workflow:**

```yaml
jobs:
  policy-gate:
    runs-on: ubuntu-22.04
    permissions:
      contents: read
      checks: read
    steps:
      - uses: actions/checkout@v4

      - uses: spockops/surak-action@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

  build:
    needs: policy-gate
    runs-on: ubuntu-22.04
    steps:
      - run: echo "policy gate passed"
```

That's it.

---

## Policies

Policies live in `.surak/` at your repo root. Each policy file can define multiple policies — runner rules, actor allowlists, branch requirements, required checks, and environment gates. Surak evaluates them all before your workflow runs.

**Defined means enforced. Undefined means ignored.** Surak only evaluates what you declare — if `runner_os` isn't in your policy file, Surak doesn't care what OS the runner uses. This makes policies opt-in and composable: start with one rule, add more as you need them.

| Policy | |
|---|---|
| `actor_allowlist` | Who can trigger the workflow. Supports globs: `bot-*` |
| `runner_type` | `github-hosted` or `self-hosted` |
| `runner_os` | `Linux`, `Windows`, `macOS` |
| `runner_arch` | `X64`, `ARM64` |
| `runner_image` | Runner image version: `ubuntu-22.04`, `macos-14`. Supports `skip_if_self_hosted` |
| `branch_protection` | Required branch or pattern: `main`, `release/*` |
| `required_checks` | Check suites that must have passed before proceeding |
| `environments` | Permitted environment names. Fails if `environment:` isn't declared or isn't in the list |

### Environment policies

Use `environments` to restrict which GitHub environments are permitted and enforce that `environment:` is declared in the workflow job.

```yaml
# .surak/production.yml
surak: v2
id: prod-deployment
name: Production Deployment Policy

applies-to:
  - .github/workflows/deploy.yml

environments:
  - production

policies:
  actor_allowlist:
    enabled: true
    allow:
      - your-github-username

  branch_protection:
    enabled: true
    require: main

  required_checks:
    enabled: true
    checks:
      - Tests
      - Security Scan
```

```yaml
# .github/workflows/deploy.yml
jobs:
  deploy:
    runs-on: ubuntu-22.04
    environment: production   # must be declared — Surak will fail if missing or not permitted
    steps:
      - run: echo "deploying"
```

See [Policy Reference](docs/policies.md) for full documentation.

---

## Local testing

```bash
pip install surak

# see which policies apply to a workflow
surak check .surak/ --workflow .github/workflows/deploy.yml

# evaluate with dummy context
surak eval .surak/ --workflow .github/workflows/deploy.yml --dummy
```

---

```
"Logic over chaos,
Policies enforce the rules —
Wisdom guards your builds."
```