From cfd282180cca58895ee2d833d987400b303d9798 Mon Sep 17 00:00:00 2001 From: sabith Date: Fri, 13 Nov 2026 12:55:15 -0800 Subject: [PATCH 1/2] docs: add LLM navigation support --- docs/README.md | 1 + docs/index.html | 3 + docs/index.md | 170 +++++++++++++++++++++++++++++++++++++++++++++++ docs/llms.txt | 41 ++++++++++++ docs/robots.txt | 4 ++ docs/sitemap.xml | 6 ++ 6 files changed, 225 insertions(+) create mode 100644 docs/index.md create mode 100644 docs/llms.txt create mode 100644 docs/robots.txt create mode 100644 docs/sitemap.xml diff --git a/docs/README.md b/docs/README.md index 1926d28..ecd6d74 100644 --- a/docs/README.md +++ b/docs/README.md @@ -18,6 +18,7 @@ Open . ## Update the site - Edit `index.html` for content and `assets/styles.css` for presentation. +- Keep `index.md` as the clean Markdown equivalent for agents and users who prefer plain text. `llms.txt` is the concise, curated site index; do not turn it into a dump of the entire site. - Keep examples aligned with the versioned files in `../examples/`. - Link to the action README for exhaustive input/output tables rather than duplicating every option on the landing page. diff --git a/docs/index.html b/docs/index.html index a5a7556..6382f0a 100644 --- a/docs/index.html +++ b/docs/index.html @@ -10,6 +10,8 @@ CCE Action — Cloud API evidence in GitHub Actions + + @@ -306,6 +308,7 @@

Make cloud usage easier to see, share, and review.

Repository Inputs & outputs Issues + For LLM agents License diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..a9fc7e4 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,170 @@ +# CCE Action developer guide + +> Turn source code into Cloud API evidence with GitHub Actions: inventories, PR diffs, IAM access requests, SARIF, and custom lenses. + +CCE Action runs [StackGen CCE](https://appcd-dev.github.io/cce/) against the repository where a GitHub workflow is running. It supports Go, Python, Java, and JavaScript. No CCE account is required, field diagnostics are off by default, and reports remain available as workflow artifacts. + +## Quick start + +Create `.github/workflows/cce.yml`: + +```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 +``` + +Open the workflow run and download the `cce-results` artifact. Use `@v0.3.0` instead of `@v1` when you want an exact action release. + +## Use inside an existing job + +```yaml +- uses: actions/checkout@v4 +- uses: stackgenhq/cce-action@v1 + id: cce + with: + language: AUTO + filter: cloud +- uses: actions/upload-artifact@v4 + with: + name: cce-results + path: cce-results/* +``` + +The reusable workflows perform checkout and artifact upload themselves. Composite actions require `actions/checkout` first. + +## Workflows + +### Scan + +Produces a JSON Cloud API report and, by default, attempts AWS IAM, GCP IAM, Azure RBAC, and cloud-neutral E-SBOM exports. Strict GCP and Azure exports do not publish unverified inferred permissions; check the relevant output path before consuming a role. + +Example: + +### Pull-request review + +Scans the base and head revisions, posts one sticky Cloud API diff, and publishes JSON, Markdown, and optional SARIF evidence. + +```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 + fail-new: false +``` + +Set `comment: false` or `upload-sarif: false` to disable either publication. Fork PRs skip comment and SARIF writes when the normal token cannot publish safely; artifacts and summaries remain available. + +Example: + +### IAM access request + +Creates a versioned `cce-access-request/v1` JSON artifact containing deduplicated provider/resource/operation evidence, call-site counts, service, commit, and mapping provenance. + +```yaml +jobs: + request: + uses: stackgenhq/cce-action/.github/workflows/access-request.yml@v1 + with: + path: . + service: payments-api +``` + +The default flow needs no cross-repository token. Download the artifact and attach it to your IAM review process. + +Example: + +### Quickstart bundle + +Creates a Cloud API BOM, self-contained HTML report, SARIF, lens lockfile, and suggested CI workflow: + +```yaml +jobs: + quickstart: + uses: stackgenhq/cce-action/.github/workflows/quickstart.yml@v1 + with: + path: . +``` + +Example: + +### Lens Gate 0 + +Compares current and candidate lenses against committed fixtures. It reports newly mapped and regressed rows and uploads verdict JSON even when a regression fails the job. + +```yaml +jobs: + verify: + uses: stackgenhq/cce-action/.github/workflows/lens-verify.yml@v1 + with: + fixture: testdata/lens-fixture + current: current.yaml + candidate: candidate.yaml + language: AUTO + fail-regression: true +``` + +Example: + +## Custom lenses + +A lens is YAML that teaches CCE to recognize internal SDKs, legacy clients, or organization-specific patterns. Local checkout lenses are hashed automatically. HTTPS lenses require `lens-sha256`; non-HTTPS remote URLs are rejected. + +```yaml +- uses: actions/checkout@v4 +- uses: stackgenhq/cce-action@v1 + with: + language: AUTO + lens: .cce/internal-platform.yaml + filter: all + lens-required: true +``` + +Use `filter: all` for custom providers such as `TECH_DEBT`. `lens-required: true` compares against a built-in baseline and fails when the lens adds no unique operations. Outputs include `lens-file-sha256` and `lens-new-operation-count`. + +## Requirements and common inputs + +- Linux runner with Docker; `ubuntu-latest` is the simplest choice. +- CCE 0.0.38 or newer for PR review, access requests, quickstart, lens verification, and lens hash pinning. +- `path`: directory to scan; defaults to `.`. +- `language`: `AUTO`, `GO`, `PYTHON`, `JAVA`, or `JAVASCRIPT`. +- `filter`: `cloud` or `all`. +- `output-dir`: report directory; defaults to `cce-results` for scans. +- `scan-timeout`: optional wall-clock limit for large scans. +- `image`: optional CCE image override; action releases default to the CCE version their self-tests exercised. + +For large repositories, scan a subdirectory or set `scan-timeout` so CI remains bounded. + +## Important boundaries + +- Static analysis can miss dynamic, reflected, or unrecognized wrapped calls. +- An empty report does not prove that no Cloud APIs or permissions are used. +- IAM access requests are review input, not ready-to-deploy policies. +- Reviewers remain responsible for resource scope, runtime needs, and final approval. +- Field diagnostics are disabled unless `diagnostics: true` is explicitly set. + +## References + +- [Action repository](https://github.com/stackgenhq/cce-action) +- [Complete inputs and outputs](https://github.com/stackgenhq/cce-action#inputs) +- [CCE documentation](https://appcd-dev.github.io/cce/) +- [Plain-language lens guide](https://appcd-dev.github.io/cce/guides/lenses/) +- [Known CCE limitations](https://appcd-dev.github.io/cce/reference/known-limitations/) +- [LLM site index](llms.txt) diff --git a/docs/llms.txt b/docs/llms.txt new file mode 100644 index 0000000..2dcb09e --- /dev/null +++ b/docs/llms.txt @@ -0,0 +1,41 @@ +# CCE Action + +> CCE Action turns Go, Python, Java, and JavaScript source into Cloud API evidence inside GitHub Actions, including inventories, PR diffs, IAM access requests, SARIF, and custom lens verification. + +Use this file to choose the smallest useful document. The developer guide is clean Markdown. Workflow examples and action references link directly to raw YAML so agents can inspect exact inputs without parsing HTML. + +CCE Action requires no CCE account. Diagnostics are off by default. Static results are review evidence, not proof of runtime coverage or ready-to-deploy IAM policy. Use `filter: all` for custom lens providers. Remote lenses require HTTPS and a SHA-256 pin. + +## Start here + +- [CCE Action developer guide](https://stackgenhq.github.io/cce-action/index.md): Quick start, capabilities, requirements, examples, security defaults, and limitations in Markdown. +- [Action README](https://raw.githubusercontent.com/stackgenhq/cce-action/main/README.md): Complete scan inputs, outputs, exports, versioning, and operating notes. + +## Workflow examples + +- [Repository scan](https://raw.githubusercontent.com/stackgenhq/cce-action/main/examples/scan.yml): Reusable scan workflow and composite action alternatives. +- [Cloud API pull-request review](https://raw.githubusercontent.com/stackgenhq/cce-action/main/examples/pr-review.yml): Sticky Markdown diff, SARIF, artifacts, and optional gates. +- [IAM access request](https://raw.githubusercontent.com/stackgenhq/cce-action/main/examples/access-request.yml): Artifact-first `cce-access-request/v1` generation without a cross-repository token. +- [Quickstart artifact bundle](https://raw.githubusercontent.com/stackgenhq/cce-action/main/examples/quickstart.yml): Cloud API BOM, HTML, SARIF, lens lockfile, and suggested workflow. +- [Lens Gate 0](https://raw.githubusercontent.com/stackgenhq/cce-action/main/examples/lens-verify.yml): Fixture comparison with newly mapped and regressed evidence. + +## Exact action contracts + +- [Scan composite action](https://raw.githubusercontent.com/stackgenhq/cce-action/main/action.yml): Authoritative composite input and output definitions. +- [Reusable scan workflow](https://raw.githubusercontent.com/stackgenhq/cce-action/main/.github/workflows/scan.yml): Reusable scan inputs and outputs. +- [Access-request composite action](https://raw.githubusercontent.com/stackgenhq/cce-action/main/access-request/action.yml): IAM artifact inputs and outputs. +- [Quickstart composite action](https://raw.githubusercontent.com/stackgenhq/cce-action/main/quickstart/action.yml): First-run artifact inputs and outputs. +- [Lens verification composite action](https://raw.githubusercontent.com/stackgenhq/cce-action/main/lens-verify/action.yml): Gate 0 inputs and verdict outputs. + +## Related documentation + +- [CCE llms.txt](https://appcd-dev.github.io/cce/llms.txt): Curated index for the CCE CLI, lenses, recipes, diffs, exports, and limitations. +- [CCE capabilities and examples](https://appcd-dev.github.io/cce/capabilities/index.md): Clean Markdown examples for the underlying CLI. + +## Optional + +- [PR-review reusable workflow](https://raw.githubusercontent.com/stackgenhq/cce-action/main/.github/workflows/pr-review.yml): Full base/head review contract and publication controls. +- [Access-request reusable workflow](https://raw.githubusercontent.com/stackgenhq/cce-action/main/.github/workflows/access-request.yml): Checkout and artifact-upload wrapper. +- [Quickstart reusable workflow](https://raw.githubusercontent.com/stackgenhq/cce-action/main/.github/workflows/quickstart.yml): Quickstart wrapper contract. +- [Lens verification reusable workflow](https://raw.githubusercontent.com/stackgenhq/cce-action/main/.github/workflows/lens-verify.yml): Lens Gate 0 wrapper contract. +- [Source repository](https://github.com/stackgenhq/cce-action): Issues, releases, license, and implementation source. diff --git a/docs/robots.txt b/docs/robots.txt new file mode 100644 index 0000000..e64acea --- /dev/null +++ b/docs/robots.txt @@ -0,0 +1,4 @@ +User-agent: * +Allow: / + +Sitemap: https://stackgenhq.github.io/cce-action/sitemap.xml diff --git a/docs/sitemap.xml b/docs/sitemap.xml new file mode 100644 index 0000000..8d0ff85 --- /dev/null +++ b/docs/sitemap.xml @@ -0,0 +1,6 @@ + + + + https://stackgenhq.github.io/cce-action/ + + From 4e2ab69d7b2d20f55834ce70c4f03ae460afaada Mon Sep 17 00:00:00 2001 From: sabith Date: Fri, 13 Nov 2026 13:14:15 -0800 Subject: [PATCH 2/2] docs: add worked public repository example --- docs/index.html | 65 +++++++++++++++++++++++++++++++++++++++ docs/index.md | 66 ++++++++++++++++++++++++++++++++++++++++ docs/llms.txt | 2 ++ examples/public-repo.yml | 25 +++++++++++++++ 4 files changed, 158 insertions(+) create mode 100644 examples/public-repo.yml diff --git a/docs/index.html b/docs/index.html index 6382f0a..0e3b77c 100644 --- a/docs/index.html +++ b/docs/index.html @@ -25,6 +25,7 @@