codeboarding/CodeBoarding Action

Visual system-design review on PRs and a versioned architecture baseline kept current on your branch: a Mermaid diff comment on every pull request, and the architecture synced to your branch on push.

View on GitHub

Trust Signals

Scorecard Score: not yet scored
Maintenance Recency: Activelast commit Jun 30, 2026
License: MIT

Pinned Snippet

workflow.ymlSHA-pinned

uses: codeboarding/codeboarding-action@2627b167018466365c769dd9d3fba839d42888a1 # v1.7.0

tags can be moved; commit SHAs can't. why a SHA?

Inputs

name	description	required	default
llm_api_key	Your LLM provider API key (see llm_provider). Optional: when empty, the action runs on the free hosted tier via a GitHub OIDC token (requires "permissions: id-token: write"). Set it (e.g. secrets.OPENROUTER_API_KEY) for unmetered usage or a non-OpenRouter provider.	no	""
llm_provider	Provider for llm_api_key. The key is handed to the engine as that provider's env var (anthropic -> ANTHROPIC_API_KEY, openai -> OPENAI_API_KEY, ...; aws_bedrock -> AWS_BEARER_TOKEN_BEDROCK, ollama -> OLLAMA_BASE_URL) and the engine auto-selects it. Default openrouter. Ignored on the free hosted tier (always OpenRouter via the proxy).	no	openrouter
proxy_url	Base URL of the CodeBoarding hosted LLM proxy used for the free tier (no llm_api_key) and for license_key mode. The engine's OPENROUTER_BASE_URL is pointed here; the proxy verifies the GitHub OIDC token, meters per repo owner, and swaps in the real key. Override only to point at a self-hosted/dev proxy.	no	https://auduihjmm4b735zci7vyabuikq0hppqn.lambda-url.us-east-1.on.aws
license_key	A CodeBoarding license key (e.g. secrets.CODEBOARDING_LICENSE) for unmetered hosted usage via proxy_url. Requires "permissions: id-token: write" — the license rides the OIDC bearer (the proxy still verifies the OIDC identity, then the license skips the quota). Takes precedence over the free OIDC tier; ignored when llm_api_key is set (BYO key talks to the provider directly).	no	""
github_token	GITHUB_TOKEN used to post the PR comment. Defaults to the workflow token.	no	${{ github.token }}
push_token	Token used for sync-mode git pushes to target_branch. Defaults to the workflow github.token, which can push when the calling workflow grants "permissions: contents: write". Kept separate from github_token so commenting can use a GitHub App token while the push uses the workflow token (whose write access the consumer controls).	no	${{ github.token }}
codeboarding_version	CodeBoarding PyPI package version used as the analysis engine. Pin for reproducibility; set to a newer released version to opt into newer engine releases.	no	0.13.2
depth_level	Analysis depth for cold-start or force_full rebuilds. Max depends on tier: 3 on the free hosted tier, 10 with a CodeBoarding license or your own llm_api_key. Once .codeboarding/analysis.json exists, its metadata.depth_level is the source of truth: sync runs incremental at the baseline depth, and review analyzes the PR head at the committed baseline depth so the diff is apples-to-apples (clamped to the tier max). Empty (default): 2 for cold starts.	no	""
agent_model	Analysis model (AGENT_MODEL env var). A bare OpenRouter slug. Defaults to google/gemini-3-flash-preview on OpenRouter; for other providers, empty uses the engine's per-provider default.	no	""
parsing_model	Parsing model (PARSING_MODEL env var). A bare OpenRouter slug. Defaults to google/gemini-3.1-flash-lite-preview on OpenRouter; for other providers, empty uses the engine's per-provider default.	no	""
comment_header	Review mode: header line used inside the sticky PR comment.	no	Architecture review
diagram_direction	Review mode: Mermaid layout direction: LR, TD, TB, RL, or BT.	no	LR
changed_only	Review mode: render only changed components and their incident edges (also auto-applied when the full graph exceeds GitHub's Mermaid limit).	no	false
render_depth	Review mode: component levels to DRAW in the PR Mermaid (independent of depth_level): 1 = top-level flat (default), 2 = +one nesting level as subgraphs, etc. Lets you analyze deep (depth_level=2) but display a clean level-1 diagram.	no	1
cta_base_url	Review mode: base URL of the click proxy (e.g. https://go.codeboarding.org). When set, the editor link deep-links into VS Code/Cursor via the proxy and a "get the extension" link is added (owner/repo/pr tracked). Empty (default) links to the extension listing instead, since GitHub strips vscode:/cursor: schemes from comment links.	no	""
webview_base_url	Review mode: hosted webview base URL. The PR comment links to an artifact-backed head-vs-comparison-branch architecture diff; review mode does not commit generated files to PR branches. Set empty to disable the browser link.	no	https://app.codeboarding.org
trigger_command	Review mode: slash-command that triggers the action from a PR comment (issue_comment event). A comment whose first word is this runs the diagram on-demand.	no	/codeboarding
feedback_command	Review mode: slash-command for submitting explicit feedback to CodeBoarding. The command and following text are sent to CodeBoarding via PostHog (not anonymous telemetry, and no analysis runs). Opt out with CODEBOARDING_TELEMETRY=false or DO_NOT_TRACK=1.	no	/codeboarding-feedback
feedback_max_chars	Review mode: maximum number of feedback characters sent from /codeboarding-feedback (the text is truncated past this).	no	4000
mode	What the action does. "review" (default): post a Mermaid architecture-diff comment on the PR (pull_request / issue_comment events). "sync": analyze on push and commit the architecture (analysis.json + rendered docs) to target_branch, keeping it versioned and current (the baseline review mode diffs against). Events: push / workflow_dispatch / schedule. Run the two modes from separate workflow files with least-privilege permissions each.	no	review
output_dir	Sync mode: directory where the rendered docs and analysis metadata are committed. The action OWNS this directory: pre-existing top-level markdown files in it are deleted on every run, so do not point it at a directory with hand-written docs.	no	.codeboarding
output_format	Sync mode: rendered docs format. Currently only .md is supported.	no	.md
target_branch	Sync mode: branch the generated docs are pushed to.	no	${{ github.ref_name }}
write_architecture_md	Sync mode: also write docs/development/architecture.md (all rendered docs concatenated, overview first).	no	true
commit_message	Sync mode: commit message for the generated docs. Deliberately carries no "[skip ci]" — the regen loop is prevented by the workflow's paths-ignore plus the action's own bot-commit guard, so the marker is unneeded and (via squash-merge) would skip the workflows real merges should run.	no	chore(codeboarding): sync architecture baseline
force_full	Sync mode: ignore any committed baseline and run a full analysis from scratch. Use to rebuild a stale or corrupt baseline (the manual escape hatch that replaces the old refresh-baseline workflow).	no	false

Outputs

name	description
diagram_md	Review mode: path to the rendered ```mermaid block (in the runner workspace).
n_changed	Review mode: number of components added/modified/deleted, counted recursively.
truncated	Review mode: true if the diagram was reduced to changed-only to fit GitHub's Mermaid limit.
analysis_mode	Sync mode: "full" or "incremental".
files_written	Sync mode: number of rendered markdown files in output_dir.
committed	Sync mode: true when a docs commit was created and pushed.
review_artifact_url	Review mode: GitHub Actions artifact URL containing the PR-head analysis.json and metadata.