# GitHub Actions

Use the public [`stackgenhq/cce-action`](https://github.com/stackgenhq/cce-action) composite actions or reusable workflows to scan the repository where your workflow runs. The action uses a tested CCE image (currently `ghcr.io/stackgenhq/cce:0.0.38`), writes a JSON entitlement report, and (by default) exports AWS IAM, GCP IAM, Azure RBAC, and cloud-neutral E-SBOM artifacts. The `image` input remains available when you deliberately need a different CCE version.

## Scan on pushes and pull requests

```yaml
name: CCE
on: [push, pull_request]
permissions:
  contents: read
  packages: read
jobs:
  scan:
    uses: stackgenhq/cce-action/.github/workflows/scan.yml@v1
    with:
      language: AUTO
      filter: cloud
```

For a version-pinned supply chain, replace `@v1` with an exact action release such as `@v0.3.0`.

### Composite action

Use the composite action when other steps in the same job need the report:

```yaml
- uses: actions/checkout@v4
- uses: stackgenhq/cce-action@v1
  id: cce
  with:
    language: GO
    filter: cloud
- uses: actions/upload-artifact@v4
  with:
    name: cce-results
    path: cce-results/*
```

## PR review: Cloud API diff

The reusable PR-review workflow scans the base and head revisions with identical settings, then publishes one sticky `<!-- cce-api-diff -->` comment. The Markdown diff includes added/removed operations, `file:line` evidence, provider deltas, and policy violations. JSON, Markdown, and SARIF evidence is uploaded even when the optional policy gate fails.

```yaml
name: CCE Cloud API review
on: [pull_request]
permissions:
  contents: read
  packages: read
  pull-requests: write
  security-events: write
jobs:
  review:
    uses: stackgenhq/cce-action/.github/workflows/pr-review.yml@v1
    with:
      language: AUTO
      filter: cloud
      # Optional: fail after publishing evidence when operations are added.
      fail-new: false
      # Optional policy and lens paths are relative to the caller checkout.
      # policy: .cce/policy.yaml
      # lens: .cce/cloud.yaml
```

The workflow defaults `base-ref` to the pull request's base branch. Set `comment: false` or `upload-sarif: false` to disable either publication. Fork pull requests skip comment and SARIF writes because the normal token cannot safely publish them; artifacts and the job summary remain available.

## Custom lenses and provenance

Pass `lens` to the scan or PR-review workflow. Local checkout lenses are hashed automatically; HTTPS lenses require `lens-sha256`, and non-HTTPS remote URLs are rejected. Use `filter: all` when a lens emits custom providers such as `TECH_DEBT`.

```yaml
- uses: stackgenhq/cce-action@v1
  with:
    language: AUTO
    filter: all
    lens: .cce/internal-platform.yaml
    # Optional even for a local lens; a mismatch fails before rules load.
    # lens-sha256: 9f2c...
    # Optional: compare against built-ins and require at least one new tuple.
    lens-required: true
```

Outputs include `lens-file-sha256` and `lens-new-operation-count`. Remote lenses are not silently trusted merely because their URL contains a version.

## Other native entry points

| Goal | Reusable workflow | Published evidence |
|------|-------------------|--------------------|
| First-run inventory | `stackgenhq/cce-action/.github/workflows/quickstart.yml@v1` | API BOM, HTML, SARIF, lens lockfile, suggested workflow |
| IAM review request | `stackgenhq/cce-action/.github/workflows/access-request.yml@v1` | Versioned `cce-access-request/v1` JSON and summary |
| Lens Gate 0 | `stackgenhq/cce-action/.github/workflows/lens-verify.yml@v1` | Newly mapped/regressed rows and verdict JSON |

Each also has a matching composite subaction (`quickstart`, `access-request`, or `lens-verify`) for use inside an existing job. See the [cross-repository IAM guide](cross-repo-iam-review.md) and [enterprise lens guide](enterprise-lenses-and-catalogs.md) for complete examples.

## Diagnostics

Field diagnostics are **off by default**. Set `diagnostics: true` only when you intentionally want unresolved method signatures posted to StackGen catalog-gap ingest. Leave them off for normal product CI.

## Requirements

- Linux runner (`ubuntu-latest`)
- CCE 0.0.38 or newer for PR review, access requests, quickstart, lens verification, and lens hash pinning; older preinstalled binaries receive an explicit capability error
- See the [action README](https://github.com/stackgenhq/cce-action#readme) for all inputs, outputs, and copy-paste examples
