rodri-oliveira-dev · Oct 30, 2026 · Oct 30, 2026 · Oct 30, 2026 · Oct 30, 2026 · Oct 30, 2026
diff --git a/website/README.md b/website/README.md
@@ -1,6 +1,6 @@
 # Complexity Analyzers documentation portal
 
-This directory contains the static Astro + Starlight portal for the Analyzer, CLI, and MCP products. English is served at `/complexity-analyzers/` and Brazilian Portuguese at `/complexity-analyzers/pt-br/`.
+This directory contains the static Astro + Starlight portal for the Analyzer, CLI, and MCP products plus the separately maintained Complexity Analysis GitHub Action. English is served at `/complexity-analyzers/` and Brazilian Portuguese at `/complexity-analyzers/pt-br/`.
 
 The planned production URL is `https://rodri-oliveira-dev.github.io/complexity-analyzers/`. Do not describe the portal as published until the GitHub Pages deployment job succeeds.
 
@@ -44,7 +44,7 @@ The Lighthouse workflow uses the official Lighthouse CLI for three independent m
 
 Portal-owned editorial content lives in `src/content/docs/`, with Portuguese counterparts under `src/content/docs/pt-br/`. Keep equivalent routes and technical meaning in both languages.
 
-Repository technical documentation remains authoritative under `../docs/en/` and `../docs/pt-BR/`. `scripts/sync-docs.mjs` maps selected source documents to portal routes, adds deterministic frontmatter, rewrites mapped Markdown links and images, and emits ignored files before development, checks, tests, and builds.
+Repository technical documentation remains authoritative under `../docs/en/` and `../docs/pt-BR/`. The Action reference is synchronized from `github-action.md` in each language, while the product introduction lives in the portal's editorial `action/index.md` pages. `scripts/sync-docs.mjs` maps selected source documents to portal routes, adds deterministic frontmatter, rewrites mapped Markdown links and images, and emits ignored files before development, checks, tests, and builds.
 
 Do not edit a generated page carrying the **Source synced** or **Fonte sincronizada** badge. Edit its source in `docs/`, run `npm run sync:docs`, and review both generated locales locally.
 
@@ -69,4 +69,4 @@ Starlight's `splash` layout omits the sidebar that normally exposes theme and la
 
 `.github/workflows/documentation-portal.yml` validates pull requests but builds and deploys the Pages artifact only from `main`. Separate workflows cover SEO/HTML/spelling, automated accessibility, and Lighthouse budgets.
 
-In repository **Settings → Pages**, configure **Source = GitHub Actions** once. No custom domain is required for the planned project URL. Publishing the portal does not change Analyzer, CLI, or MCP release workflows.
+In repository **Settings → Pages**, configure **Source = GitHub Actions** once. No custom domain is required for the planned project URL. Publishing the portal does not change Analyzer, CLI, MCP, or GitHub Action release workflows. The Action has independent versioning and is not claimed as a Marketplace listing before approval.
diff --git a/website/astro.config.mjs b/website/astro.config.mjs
@@ -45,6 +45,7 @@ export default defineConfig({
         { label: 'Roslyn Analyzer', items: [{ autogenerate: { directory: 'analyzer' } }] },
         { label: 'CLI', items: [{ autogenerate: { directory: 'cli' } }] },
         { label: 'MCP Server', translations: { 'pt-BR': 'Servidor MCP' }, items: [{ autogenerate: { directory: 'mcp' } }] },
+        { label: 'GitHub Action', items: [{ autogenerate: { directory: 'action' } }] },
         { label: 'Examples', translations: { 'pt-BR': 'Exemplos' }, items: [{ autogenerate: { directory: 'examples' } }] },
         { label: 'Reference', translations: { 'pt-BR': 'Referência' }, items: [{ autogenerate: { directory: 'reference' } }] }
       ]

diff --git a/website/scripts/check-routes.mjs b/website/scripts/check-routes.mjs
@@ -28,6 +28,7 @@ const required = [
   'learn', 'learn/complexity-models', 'learn/operations-recursion-unknown', 'learn/cognitive-complexity', 'learn/halstead-metrics',
   'analyzer', 'analyzer/installation', 'analyzer/diagnostics', 'analyzer/configuration',
   'cli', 'cli/github-actions', 'cli/reference',
+  'action', 'action/reference',
   'mcp', 'mcp/agent-workflows', 'mcp/reference',
   'examples', 'examples/collection-and-linq-costs', 'examples/recursion-and-cognition', 'examples/refactoring', 'examples/snapshot-comparison',
   'reference', 'reference/report-contracts', 'reference/architecture', 'reference/security-baseline', 'reference/development-quality-gates', 'reference/releases', 'reference/releases/mcp-1-0-0', 'reference/releases/mcp-1-0-1', 'reference/contributing'

diff --git a/website/scripts/sync-docs.mjs b/website/scripts/sync-docs.mjs
@@ -15,6 +15,7 @@ const englishMappings = [
   ['docs/en/cognitive-complexity.md', 'learn/cognitive-complexity.md'],
   ['docs/en/halstead-metrics.md', 'learn/halstead-metrics.md'],
   ['docs/en/project-tooling.md', 'cli/reference.md'],
+  ['docs/en/github-action.md', 'action/reference.md'],
   ['docs/en/mcp-server.md', 'mcp/reference.md'],
   ['docs/en/architecture.md', 'reference/architecture.md'],
   ['docs/en/development/security-baseline.md', 'reference/security-baseline.md'],

diff --git a/website/src/components/PortalHome.astro b/website/src/components/PortalHome.astro
@@ -23,20 +23,22 @@ const t = pt ? {
     ['Estrutura que pesa', 'Acompanhe complexidade ciclomática, cognitiva e profundidade sem confundi-las com Big-O.'],
     ['Limites explícitos', 'Veja Unknown quando uma conclusão segura não pode ser provada pelo subconjunto suportado.']
   ],
-  productsTitle: 'Três superfícies, um modelo de análise.', productsText: 'Escolha a integração pelo momento em que você precisa da evidência.',
+  productsTitle: 'Quatro integrações, um modelo de análise.', productsText: 'Escolha a integração pelo momento em que você precisa da evidência.',
   products: [
     ['Analyzer', 'Feedback no build e na IDE', 'Diagnósticos BIG* e thresholds via .editorconfig.', 'analyzer/'],
     ['CLI', 'Relatórios e quality gates', 'Console, JSON, SARIF, snapshots e comparação determinística.', 'cli/'],
-    ['MCP', 'Contexto para agentes locais', 'Ferramentas somente leitura sobre stdio, com limites e evidências.', 'mcp/']
+    ['MCP', 'Contexto para agentes locais', 'Ferramentas somente leitura sobre stdio, com limites e evidências.', 'mcp/'],
+    ['Action', 'Qualidade no GitHub CI', 'Gates, relatórios e regressões em pull requests usando a CLI.', 'action/']
   ],
   metricsTitle: 'Leia o código por mais de uma lente.', metricsText: 'O suporte é deliberadamente documentado e cada resultado preserva suas hipóteses.',
-  chooseTitle: 'Escolha pelo fluxo de trabalho.', chooseText: 'Os pacotes são independentes. Você pode adotar um deles ou combinar as três superfícies.',
+  chooseTitle: 'Escolha pelo fluxo de trabalho.', chooseText: 'Os pacotes e a Action têm versões independentes. Combine as integrações conforme a necessidade.',
   choices: [
     ['IDE', 'Use o Analyzer', 'quando o feedback precisa acompanhar compilação e edição.'],
     ['CI', 'Use a CLI', 'quando você precisa de relatórios, snapshots e gates explícitos.'],
-    ['AGENT', 'Use o MCP', 'quando um agente precisa consultar análise e evidências locais.']
+    ['AGENT', 'Use o MCP', 'quando um agente precisa consultar análise e evidências locais.'],
+    ['CI', 'Use a GitHub Action', 'quando quiser checks e comparações de PRs sem scripts próprios.']
   ],
-  ciTitle: 'Da revisão local ao gate de CI.', ciText: 'A CLI retorna códigos de saída estáveis; gates são opt-in e resultados Unknown não viram regressões provadas.',
+  ciTitle: 'Da revisão local ao gate de CI.', ciText: 'A CLI e a GitHub Action compartilham as regras de análise. Gates são opt-in e Unknown não significa regressão comprovada.',
   finalTitle: 'Comece com o produto que encontra seu código onde ele já está.', finalText: 'Instale, gere o primeiro resultado e aprofunde-se nos modelos, contratos e limites técnicos.',
   quick: 'Instalação rápida', reference: 'Explorar a referência'
 } : {
@@ -51,20 +53,22 @@ const t = pt ? {
     ['Structure that weighs', 'Track cyclomatic, cognitive, and nesting measures without confusing them with Big-O.'],
     ['Explicit limits', 'See Unknown when the supported subset cannot prove a safe conclusion.']
   ],
-  productsTitle: 'Three surfaces, one analysis model.', productsText: 'Choose the integration by when and where you need evidence.',
+  productsTitle: 'Four integrations, one analysis model.', productsText: 'Choose the integration by when and where you need evidence.',
   products: [
     ['Analyzer', 'Build and IDE feedback', 'BIG* diagnostics and thresholds through .editorconfig.', 'analyzer/'],
     ['CLI', 'Reports and quality gates', 'Console, JSON, SARIF, snapshots, and deterministic comparison.', 'cli/'],
-    ['MCP', 'Context for local agents', 'Read-only tools over stdio, with limits and evidence.', 'mcp/']
+    ['MCP', 'Context for local agents', 'Read-only tools over stdio, with limits and evidence.', 'mcp/'],
+    ['Action', 'Quality checks in GitHub CI', 'Gates, reports, and pull-request regressions through the CLI.', 'action/']
   ],
   metricsTitle: 'Read code through more than one lens.', metricsText: 'Support is deliberately documented, and every result preserves its assumptions.',
-  chooseTitle: 'Choose by workflow.', chooseText: 'The packages are independent. Adopt one surface or combine all three.',
+  chooseTitle: 'Choose by workflow.', chooseText: 'The packages and Action are independently versioned. Combine integrations where they help.',
   choices: [
     ['IDE', 'Use the Analyzer', 'when feedback must travel with compilation and editing.'],
     ['CI', 'Use the CLI', 'when you need reports, snapshots, and explicit gates.'],
-    ['AGENT', 'Use MCP', 'when an agent needs local analysis and evidence.']
+    ['AGENT', 'Use MCP', 'when an agent needs local analysis and evidence.'],
+    ['CI', 'Use the GitHub Action', 'when you want reusable PR checks without custom scripts.']
   ],
-  ciTitle: 'From local review to a CI gate.', ciText: 'The CLI returns stable exit codes; gates are opt-in, and Unknown results do not become proven regressions.',
+  ciTitle: 'From local review to a CI gate.', ciText: 'The CLI and GitHub Action share analysis rules. Gates are opt-in, and Unknown does not mean a proven regression.',
   finalTitle: 'Start with the product that meets your code where it already lives.', finalText: 'Install it, produce the first result, then explore the models, contracts, and technical limits.',
   quick: 'Quick installation', reference: 'Explore the reference'
 };
@@ -96,7 +100,7 @@ const t = pt ? {
 
   <section class="cx-section tinted" aria-labelledby="products-title">
     <div class="cx-heading"><h2 id="products-title">{t.productsTitle}</h2><p>{t.productsText}</p></div>
-    <div class="cx-grid">{t.products.map(([name, title, text, route]) => <a class="portal-card product-card" href={`${prefix}/${route}`}><span class="kicker">{name}</span><h3>{title}</h3><p>{text}</p></a>)}</div>
+    <div class="cx-grid products-grid">{t.products.map(([name, title, text, route]) => <a class="portal-card product-card" href={`${prefix}/${route}`}><span class="kicker">{name}</span><h3>{title}</h3><p>{text}</p></a>)}</div>
   </section>
 
   <section class="cx-section" aria-labelledby="metrics-title">
@@ -115,7 +119,7 @@ const t = pt ? {
 
   <section class="cx-section tinted"><div class="cx-decision"><div><h2>{t.chooseTitle}</h2><p>{t.chooseText}</p></div><div class="choice-list">{t.choices.map(([tag, title, text]) => <article class="choice"><b>{tag}</b><div><h3>{title}</h3><p>{text}</p></div></article>)}</div></div></section>
 
-  <section class="cx-section dark"><div class="cx-ci"><div><h2>{t.ciTitle}</h2><p>{t.ciText}</p><a class="button primary" href={`${prefix}/cli/github-actions/`}>GitHub Actions</a></div><pre><code>dotnet tool restore
+  <section class="cx-section dark"><div class="cx-ci"><div><h2>{t.ciTitle}</h2><p>{t.ciText}</p><div class="cx-actions"><a class="button primary" href={`${prefix}/action/`}>GitHub Action</a><a class="button secondary" href={`${prefix}/cli/github-actions/`}>{pt ? 'Workflow com CLI' : 'CLI workflow'}</a></div></div><pre><code>dotnet tool restore
 mkdir -p artifacts
 dotnet complexity-analysis analyze App.slnx \
   --format sarif \

diff --git a/website/src/content/docs/action/index.md b/website/src/content/docs/action/index.md
@@ -0,0 +1,79 @@
+---
+title: GitHub Action
+description: Analyze C# complexity in GitHub CI, compare pull-request regressions, and apply opt-in quality gates.
+sidebar:
+  order: 1
+---
+
+The **Complexity Analysis Action** brings the published [project-level CLI](/complexity-analyzers/cli/) into reusable GitHub Actions workflows. It is useful when you want complexity evidence during a pull request without maintaining your own CLI setup and reporting scripts.
+
+The Action lives in a [separate repository](https://github.com/rodri-oliveira-dev/complexity-analysis-action) and uses the same analysis engine as the CLI, Roslyn Analyzer, and MCP server. It does **not** implement a second complexity model.
+
+:::caution[Release status]
+The first stable Action release, `v1.0.0`, is **planned but not yet published** at the time of this update. Do not use `@v1` or `@v1.0.0` until those tags exist. The GitHub Marketplace listing is not yet available. For evaluation, pin a **reviewed full commit SHA** from the [Action repository](https://github.com/rodri-oliveira-dev/complexity-analysis-action) and check its current status.
+:::
+
+## When to choose the Action
+
+| Your workflow | Prefer |
+| --- | --- |
+| Live feedback in the editor or compiler | [Roslyn Analyzer](/complexity-analyzers/analyzer/) |
+| Local scripts or custom CI orchestration | [CLI](/complexity-analyzers/cli/) |
+| Reusable GitHub CI checks and PR regression feedback | **GitHub Action** |
+| Read-only analysis from compatible AI agents | [MCP Server](/complexity-analyzers/mcp/) |
+
+All four integrations serve different workflows. The Action invokes a pinned published version of `ComplexityAnalysis.Tool`; the Action, CLI, Analyzer, and MCP have independent release versions.
+
+## What you can configure
+
+- **Quality gates:** optional Big-O, cyclomatic and cognitive complexity, nesting depth, method NLOC, and duplication thresholds.
+- **PR regressions:** compare baseline and current snapshots, and fail only on regressions that the CLI can prove.
+- **Reporting:** JSON, SARIF 2.1.0, GitHub Job Summary, optional Code Scanning upload and bounded PR feedback.
+- **Failure policy:** keep an absolute threshold violation separate from a change relative to the PR base.
+
+Unknown or incomparable evidence is not automatically treated as a regression, and complexity estimates are **not runtime performance benchmarks**.
+
+## Example: read-only PR analysis
+
+Create `.github/workflows/complexity.yml` in your C# repository. Replace the placeholder with a **real reviewed 40-character commit SHA**, and the solution name with your own path:
+
+```yaml
+name: Complexity review
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  complexity:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+        with:
+          persist-credentials: false
+      - id: analysis
+        uses: rodri-oliveira-dev/complexity-analysis-action@REVIEWED_FULL_40_CHARACTER_SHA
+        with:
+          path: MySolution.slnx
+          max-cyclomatic-complexity: '15'
+          max-cognitive-complexity: '20'
+          compare-with-base: 'true'
+          fail-on-regression: 'true'
+```
+
+This is an **illustrative template, not directly executable** while the SHA remains a placeholder. The sample intentionally uses read-only permissions and does not post comments. To retain reports, add an artifact-upload step after analysis using the documented output paths.
+
+## Requirements and security
+
+The current release candidate supports **Ubuntu runners**, requires access to NuGet.org, and installs .NET SDK 10. Its default published CLI dependency is `ComplexityAnalysis.Tool` `1.0.1`. Windows and macOS support are not claimed without equivalent end-to-end evidence.
+
+Simple analysis and comparisons need only `contents: read`. SARIF upload additionally requires `security-events: write`. Direct comments require `pull-requests: write`, which should **not** be exposed to untrusted PR analysis. For fork contributions, use isolated read-only analysis and a separate trusted publishing workflow.
+
+Loading MSBuild projects can execute project-controlled logic. The Action is not a process sandbox; never run untrusted PR code using `pull_request_target`.
+
+## Continue learning
+
+For every supported input, output, comparison status, and troubleshooting scenario, see the [full Action reference](/complexity-analyzers/action/reference/). For a workflow that installs the CLI manually instead, see the [CLI GitHub Actions guide](/complexity-analyzers/cli/github-actions/).
+
+Source and detailed examples: [Complexity Analysis Action repository](https://github.com/rodri-oliveira-dev/complexity-analysis-action).
diff --git a/website/src/content/docs/cli/github-actions.md b/website/src/content/docs/cli/github-actions.md
@@ -1,10 +1,12 @@
 ---
 title: GitHub Actions integration
-description: Pin the CLI, generate artifacts, and enforce explicit complexity gates in CI.
+description: Run the Complexity Analysis CLI manually in GitHub Actions, with pinned tools and explicit quality gates.
 sidebar:
   order: 2
 ---
 
+This page shows a **manual CLI workflow**. If you prefer a reusable Action with built-in reports and PR regression options, see the [Complexity Analysis GitHub Action](/complexity-analyzers/action/). Its first stable release is planned but not yet published.
+
 Use a repository-local tool manifest so the workflow restores a reviewed version.
 
 ```bash

diff --git a/website/src/content/docs/getting-started.md b/website/src/content/docs/getting-started.md
@@ -1,17 +1,18 @@
 ---
 title: Ecosystem overview
-description: Understand the Analyzer, CLI, and MCP surfaces and the evidence they share.
+description: Understand Roslyn, CLI, MCP, and GitHub Action integration and the evidence they share.
 sidebar:
   order: 1
 ---
 
-Complexity Analyzers is a C# analysis ecosystem with three independently installed products. They share an analysis model, but meet you at different points in the development workflow.
+Complexity Analyzers is a C# analysis ecosystem with three independent NuGet products and a separately maintained GitHub Action built on the CLI. They share an analysis model but fit different development workflows.
 
 | Product | Best fit | Runs when | Primary output |
 | --- | --- | --- | --- |
 | `ComplexityAnalysis.Analyzers` | IDE and build feedback | Roslyn compilation | `BIG*` diagnostics |
 | `ComplexityAnalysis.Tool` | Review, automation, and CI | Explicit CLI invocation | Console, JSON, or SARIF reports |
 | `ComplexityAnalysis.Mcp` | Local AI-agent workflows | MCP client invokes a tool | Structured analysis and evidence |
+| [Complexity Analysis Action](/complexity-analyzers/action/) | Reusable GitHub CI and PR checks | Workflow invokes the published CLI | Quality gates, reports, and regression summaries |
 
 ## What the ecosystem analyzes
 
@@ -23,6 +24,7 @@ The analysis is static and conservative. It does not execute the program, profil
 
 - The analyzer package targets `netstandard2.0` and is consumed by compatible Roslyn hosts.
 - The CLI and MCP server are .NET 10 tools and require the .NET 10 runtime.
+- The Action currently supports Ubuntu runners and installs .NET 10; its stable v1.0.0 release is planned, not yet published.
 - Project and solution analysis supports `.csproj`, `.sln`, and `.slnx` inputs where documented.
 
 Continue with [quick installation](/complexity-analyzers/getting-started/quick-install/) or [choose the right product](/complexity-analyzers/getting-started/choose-product/).