-
Notifications
You must be signed in to change notification settings - Fork 1
Expand file tree
/
Copy pathaction.yml
More file actions
1385 lines (1309 loc) · 71.8 KB
/
Copy pathaction.yml
File metadata and controls
1385 lines (1309 loc) · 71.8 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
name: 'CodeBoarding Action'
description: '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.'
author: 'CodeBoarding'
branding:
icon: 'git-pull-request'
color: 'blue'
inputs:
llm_api_key:
description: 'Your LLM provider API key (see llm_provider). Required.'
required: true
llm_provider:
description: '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.'
required: false
default: 'openrouter'
github_token:
description: 'GITHUB_TOKEN used to post the PR comment. Defaults to the workflow token.'
required: false
default: ${{ github.token }}
push_token:
description: 'Token used for git pushes: in review mode the generated .codeboarding/analysis.json to the PR branch (for the webview link), in sync mode the architecture 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).'
required: false
default: ${{ github.token }}
engine_ref:
description: 'Git ref (tag/branch/SHA) of CodeBoarding/CodeBoarding used as the analysis engine. Pinned to a release for reproducibility; override to track a newer ref.'
required: false
default: 'v0.12.1'
depth_level:
description: 'Analysis depth (1-3). Higher is slower, costlier, and more detailed. Use the SAME value in your review and sync workflows: review mode reuses the committed baseline only when it is no deeper than this, regenerating it otherwise. Lower to 1 for cheaper, faster runs.'
required: false
default: '2'
agent_model:
description: '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.'
required: false
default: ''
parsing_model:
description: '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.'
required: false
default: ''
comment_header:
description: 'Review mode: header line used inside the sticky PR comment.'
required: false
default: 'Architecture review'
diagram_direction:
description: 'Review mode: Mermaid layout direction: LR, TD, TB, RL, or BT.'
required: false
default: 'LR'
changed_only:
description: 'Review mode: render only changed components and their incident edges (also auto-applied when the full graph exceeds GitHub''s Mermaid limit).'
required: false
default: 'false'
render_depth:
description: '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.'
required: false
default: '1'
cta_base_url:
description: '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.'
required: false
default: ''
webview_base_url:
description: 'Review mode: base URL of the hosted webview (default https://app.codeboarding.org). The PR comment adds an "explore in browser" link deep-linking to this PR''s head-vs-base architecture diff. Requires the head analysis.json to be committed to the PR branch (commit_head_analysis), so it is omitted on fork PRs. Set empty to disable the webview link.'
required: false
default: 'https://app.codeboarding.org'
commit_head_analysis:
description: 'Review mode: commit the generated head .codeboarding/analysis.json (+ health report) back to the PR branch so the webview can fetch it at the head SHA. Same-repo PRs only (the token is read-only on forks). Required for the webview "explore in browser" link. Needs contents: write on the workflow.'
required: false
default: 'true'
trigger_command:
description: '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.'
required: false
default: '/codeboarding'
feedback_command:
description: '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.'
required: false
default: '/codeboarding-feedback'
feedback_max_chars:
description: 'Review mode: maximum number of feedback characters sent from /codeboarding-feedback (the text is truncated past this).'
required: false
default: '4000'
mode:
description: '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.'
required: false
default: 'review'
output_dir:
description: '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.'
required: false
default: '.codeboarding'
output_format:
description: 'Sync mode: rendered docs format. Currently only .md is supported.'
required: false
default: '.md'
target_branch:
description: 'Sync mode: branch the generated docs are pushed to.'
required: false
default: ${{ github.ref_name }}
write_architecture_md:
description: 'Sync mode: also write docs/development/architecture.md (all rendered docs concatenated, overview first).'
required: false
default: 'true'
commit_message:
description: '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.'
required: false
default: 'chore(codeboarding): sync architecture baseline'
force_full:
description: '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).'
required: false
default: 'false'
outputs:
diagram_md:
description: 'Review mode: path to the rendered ```mermaid block (in the runner workspace).'
value: ${{ steps.diagram.outputs.diagram_md }}
n_changed:
description: 'Review mode: number of components added/modified/deleted, counted recursively.'
value: ${{ steps.diagram.outputs.n_changed }}
truncated:
description: 'Review mode: true if the diagram was reduced to changed-only to fit GitHub''s Mermaid limit.'
value: ${{ steps.diagram.outputs.truncated }}
analysis_mode:
description: 'Sync mode: "full" or "incremental".'
value: ${{ steps.sync_analyze.outputs.analysis_mode }}
files_written:
description: 'Sync mode: number of rendered markdown files in output_dir.'
value: ${{ steps.sync_commit.outputs.files_written }}
committed:
description: 'Sync mode: true when a docs commit was created and pushed.'
value: ${{ steps.sync_commit.outputs.committed }}
runs:
using: 'composite'
# One spine, two heads. Steps run in four phases; every mode-specific step is
# gated `if: steps.guard.outputs.mode == 'review' | 'sync'`, and the two modes
# interleave only because they share the LLM-key lifecycle, NOT because they
# are unrelated:
# 1. GUARD — resolve mode + event eligibility + SHAs (one source of truth)
# 2. SHARED SETUP — checkout engine + target, Python/Node/uv, caches, LLM-key prep
# 3. ANALYSIS (key live) — review: base/seed/head/health ; sync: seed/analyze
# 4. Drop LLM key, then OUTPUT (no key) — review: diff→comment ; sync: render→commit
# The binding between the modes is the committed .codeboarding/analysis.json
# baseline: sync (phase 3/4) writes it, review (phase 3) reads it as the PR base.
steps:
- name: Guard — resolve mode and target
id: guard
shell: bash
env:
GH_TOKEN: ${{ inputs.github_token }}
# Read from env, NEVER interpolated into the script — a comment body is
# untrusted input and must not reach the shell as code (injection).
COMMENT_BODY: ${{ github.event.comment.body }}
AUTHOR_ASSOC: ${{ github.event.comment.author_association }}
TRIGGER: ${{ inputs.trigger_command }}
# Feedback path (/codeboarding-feedback): a lightweight branch that sends
# the comment text to PostHog and exits before any checkout/engine setup.
# The script reads CODEBOARDING_POSTHOG_KEY/HOST and the opt-outs
# DO_NOT_TRACK / CODEBOARDING_TELEMETRY straight from the caller's env: a
# composite action inherits the calling workflow/job `env:` as real env
# vars, so those need no re-mapping here. POSTHOG_KEY/HOST below are a
# redundant alias the script only falls back to if the canonical vars are
# unset — kept as a hint that the destination is overridable.
FEEDBACK_COMMAND: ${{ inputs.feedback_command }}
FEEDBACK_MAX_CHARS: ${{ inputs.feedback_max_chars }}
POSTHOG_KEY: ${{ env.CODEBOARDING_POSTHOG_KEY }}
POSTHOG_HOST: ${{ env.CODEBOARDING_POSTHOG_HOST }}
SENDER_LOGIN: ${{ github.event.sender.login }}
SENDER_ID: ${{ github.event.sender.id }}
COMMENT_ID: ${{ github.event.comment.id }}
COMMENT_URL: ${{ github.event.comment.html_url }}
REPOSITORY_ID: ${{ github.event.repository.id }}
RUN_ATTEMPT: ${{ github.run_attempt }}
ACTION_PATH: ${{ github.action_path }}
ACTION_REF: ${{ github.action_ref || github.sha }}
EVENT: ${{ github.event_name }}
REPOSITORY: ${{ github.repository }}
PR_NUMBER_PULL: ${{ github.event.pull_request.number }}
PULL_BASE_SHA: ${{ github.event.pull_request.base.sha }}
PULL_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
PULL_HEAD_REF: ${{ github.event.pull_request.head.ref }}
PULL_BASE_REF: ${{ github.event.pull_request.base.ref }}
PULL_BASE_REPO: ${{ github.event.pull_request.base.repo.full_name }}
PULL_HEAD_REPO: ${{ github.event.pull_request.head.repo.full_name }}
ISSUE_NUMBER: ${{ github.event.issue.number }}
ISSUE_PR_URL: ${{ github.event.issue.pull_request.url }}
MODE: ${{ inputs.mode }}
REF_TYPE: ${{ github.ref_type }}
TARGET_SHA: ${{ github.sha }}
TARGET_BRANCH: ${{ inputs.target_branch }}
OUTPUT_DIR: ${{ inputs.output_dir }}
OUTPUT_FORMAT: ${{ inputs.output_format }}
WRITE_ARCH: ${{ inputs.write_architecture_md }}
DEPTH: ${{ inputs.depth_level }}
HEAD_AUTHOR_EMAIL: ${{ github.event.head_commit.author.email }}
run: |
set -uo pipefail
skip() { echo "::notice::$1 Skipping."; echo "skip=true" >> "$GITHUB_OUTPUT"; exit 0; }
# Misconfigured inputs hard-fail; event mismatches soft-skip (a workflow
# may legitimately deliver events the selected mode doesn't handle).
case "$MODE" in
review|sync) ;;
*) echo "::error::mode must be 'review' or 'sync' (got '$MODE')."; exit 1 ;;
esac
case "$DEPTH" in
1|2|3) ;;
*) echo "::error::depth_level must be 1, 2, or 3."; exit 1 ;;
esac
echo "mode=$MODE" >> "$GITHUB_OUTPUT"
if [ "$MODE" = "sync" ]; then
# Sync mode: analyze the pushed/selected commit and push generated docs
# to target_branch. Sync is an explicit opt-in (never inferred from the
# event) and accepts only non-PR triggers — a branch-pushing mode must
# not be reachable from a workflow run over PR-head code.
case "$EVENT" in
push|workflow_dispatch|schedule) ;;
*) skip "Unsupported event '$EVENT' in sync mode (use push, workflow_dispatch, or schedule; mode: review handles pull_request)." ;;
esac
if [ "$EVENT" = "push" ] && [ "$REF_TYPE" = "tag" ]; then
skip "Sync mode runs on branch pushes, not tag pushes."
fi
# Regen-loop guard: never re-analyze our OWN baseline commit. Sync
# commits as codeboarding[bot]; if a push's head commit is ours, skip.
# This holds even if a consumer omits the workflow's paths-ignore (the
# primary guard), and replaces the old "[skip ci]" marker — which
# leaked into squash-merge commit messages and wrongly skipped the
# workflows real merges should run (sync itself, release tooling, CI).
if [ "$EVENT" = "push" ] && [ "$HEAD_AUTHOR_EMAIL" = "codeboarding[bot]@users.noreply.github.com" ]; then
skip "Push head commit is CodeBoarding's own baseline commit; not re-analyzing (loop guard)."
fi
case "$OUTPUT_FORMAT" in
.md) ;;
*) echo "::error::output_format must be .md."; exit 1 ;;
esac
case "$OUTPUT_DIR" in
""|/*|..|../*|*/../*|*/..) echo "::error::output_dir must be a relative path inside the repository."; exit 1 ;;
esac
case "$WRITE_ARCH" in
true|false) ;;
*) echo "::error::write_architecture_md must be true or false."; exit 1 ;;
esac
[ -n "$TARGET_BRANCH" ] || { echo "::error::target_branch is empty."; exit 1; }
{
echo "skip=false"
echo "target_sha=$TARGET_SHA"
echo "target_branch=$TARGET_BRANCH"
echo "start_ts=$(date +%s)"
echo "checkout_repo=$REPOSITORY"
echo "checkout_sha=$TARGET_SHA"
} >> "$GITHUB_OUTPUT"
echo "Sync mode: analyzing ${REPOSITORY}@${TARGET_SHA}, pushing docs to ${TARGET_BRANCH} (via $EVENT)"
exit 0
fi
# Review mode from here down.
# Sticky-comment targeting. Written up front so the failure-comment step
# always has a header even if PR resolution below fails. Automatic
# pull_request runs reuse one stable header → the comment is updated in
# place. An on-demand /codeboarding run uses a run-unique header so it
# posts a NEW comment and never touches comments from earlier runs; its
# own in-progress→result→failure steps still share it (one comment per
# invocation). Re-running the same run keeps the same run id, so a re-run
# updates that invocation's comment rather than spawning another.
if [ "$EVENT" = "issue_comment" ]; then
echo "sticky_header=codeboarding-architecture-diff-run-${GITHUB_RUN_ID}" >> "$GITHUB_OUTPUT"
else
echo "sticky_header=codeboarding-architecture-diff" >> "$GITHUB_OUTPUT"
fi
if [ "$EVENT" = "pull_request" ]; then
PR_NUMBER="$PR_NUMBER_PULL"
BASE_SHA="$PULL_BASE_SHA"
HEAD_SHA="$PULL_HEAD_SHA"
HEAD_REF="$PULL_HEAD_REF"
BASE_REF="$PULL_BASE_REF"
BASE_REPO="$PULL_BASE_REPO"
HEAD_REPO="$PULL_HEAD_REPO"
elif [ "$EVENT" = "pull_request_target" ]; then
skip "pull_request_target is not supported because it can expose secrets to PR-head code; use pull_request or trusted issue_comment."
elif [ "$EVENT" = "issue_comment" ]; then
# On-demand "/codeboarding" command. Must be a PR comment whose first
# word is the trigger; the payload lacks SHAs so we query the API.
[ -n "$ISSUE_PR_URL" ] || skip "Comment is on a plain issue, not a PR."
FIRST_WORD="$(printf '%s' "$COMMENT_BODY" | tr -d '\r' | awk 'NR==1{print $1; exit}')"
# Feedback command: forward the comment text to PostHog, then stop BEFORE
# the trusted-association check, checkout, engine setup, and LLM key.
# Sending user-written feedback runs no PR code, so it doesn't need the
# collaborator gate the analysis path does — the workflow's own `if:`
# decides who can reach this step. The script swallows its own failures
# and the guard has no `set -e`, so feedback can never block the action.
if [ "$FIRST_WORD" = "$FEEDBACK_COMMAND" ]; then
python3 "$ACTION_PATH/scripts/submit_feedback.py"
echo "skip=true" >> "$GITHUB_OUTPUT"
echo "feedback_received=true" >> "$GITHUB_OUTPUT"
exit 0
fi
[ "$FIRST_WORD" = "$TRIGGER" ] || skip "Comment does not start with '$TRIGGER'."
# SECURITY (pwn-request guard): issue_comment runs in the base repo WITH
# secrets for ANY commenter. Only a trusted collaborator may trigger an
# analysis that checks out + runs over PR-head code with the LLM key present.
case "$AUTHOR_ASSOC" in
OWNER|MEMBER|COLLABORATOR) : ;;
*) skip "Commenter is '$AUTHOR_ASSOC' (not OWNER/MEMBER/COLLABORATOR)." ;;
esac
PR_NUMBER="$ISSUE_NUMBER"
PR_JSON="$(gh api "repos/${REPOSITORY}/pulls/${PR_NUMBER}" 2>/dev/null)" || skip "Could not fetch PR #$PR_NUMBER from the API."
BASE_SHA="$(printf '%s' "$PR_JSON" | python3 -c 'import json,sys;print(json.load(sys.stdin)["base"]["sha"])' 2>/dev/null)" || skip "Could not parse base SHA from the PR API."
HEAD_SHA="$(printf '%s' "$PR_JSON" | python3 -c 'import json,sys;print(json.load(sys.stdin)["head"]["sha"])' 2>/dev/null)" || skip "Could not parse head SHA from the PR API."
HEAD_REF="$(printf '%s' "$PR_JSON" | python3 -c 'import json,sys;print(json.load(sys.stdin)["head"]["ref"])' 2>/dev/null)" || HEAD_REF=""
BASE_REF="$(printf '%s' "$PR_JSON" | python3 -c 'import json,sys;print(json.load(sys.stdin)["base"]["ref"])' 2>/dev/null)" || BASE_REF=""
BASE_REPO="$(printf '%s' "$PR_JSON" | python3 -c 'import json,sys;print(json.load(sys.stdin)["base"]["repo"]["full_name"])' 2>/dev/null)" || skip "Could not parse base repo from the PR API."
HEAD_REPO="$(printf '%s' "$PR_JSON" | python3 -c 'import json,sys;print(json.load(sys.stdin)["head"]["repo"]["full_name"])' 2>/dev/null)" || skip "Could not parse head repo from the PR API."
[ "$HEAD_REPO" = "$REPOSITORY" ] || skip "On-demand runs with secrets are disabled for fork PRs."
else
skip "Unsupported event '$EVENT' in review mode (use pull_request or issue_comment; set mode: sync to version your architecture on push)."
fi
{ [ -n "$PR_NUMBER" ] && [ -n "$BASE_SHA" ] && [ -n "$HEAD_SHA" ] && [ -n "$BASE_REPO" ] && [ -n "$HEAD_REPO" ]; } || skip "Could not resolve PR/base/head SHAs/repos."
{
echo "skip=false"
echo "pr_number=$PR_NUMBER"
echo "base_sha=$BASE_SHA"
echo "head_sha=$HEAD_SHA"
echo "head_ref=$HEAD_REF"
echo "base_ref=$BASE_REF"
echo "base_repo=$BASE_REPO"
echo "head_repo=$HEAD_REPO"
echo "checkout_repo=$HEAD_REPO"
echo "checkout_sha=$HEAD_SHA"
# same_repo gates pushing the head analysis: forks give a read-only token.
if [ "$HEAD_REPO" = "$REPOSITORY" ]; then echo "same_repo=true"; else echo "same_repo=false"; fi
} >> "$GITHUB_OUTPUT"
echo "Resolved PR #$PR_NUMBER (base=$BASE_REPO@$BASE_SHA head=$HEAD_REPO@$HEAD_SHA) via $EVENT"
# Feedback exits the guard with skip=true, so the analysis "Acknowledge
# command" step below (gated on skip != 'true') never fires for it; this one
# reacts instead, keyed on the feedback_received flag the guard set.
- name: Acknowledge feedback
if: steps.guard.outputs.feedback_received == 'true'
shell: bash
env:
GH_TOKEN: ${{ inputs.github_token }}
REPOSITORY: ${{ github.repository }}
COMMENT_ID: ${{ github.event.comment.id }}
run: |
# 👍 react to the feedback comment so the user knows it was received.
gh api -X POST "repos/${REPOSITORY}/issues/comments/${COMMENT_ID}/reactions" \
-f content='+1' >/dev/null 2>&1 || true
- name: Acknowledge command
if: steps.guard.outputs.skip != 'true' && github.event_name == 'issue_comment'
shell: bash
env:
GH_TOKEN: ${{ inputs.github_token }}
REPOSITORY: ${{ github.repository }}
COMMENT_ID: ${{ github.event.comment.id }}
run: |
# 👀 react to the triggering comment so the user knows it was picked up.
gh api -X POST "repos/${REPOSITORY}/issues/comments/${COMMENT_ID}/reactions" \
-f content=eyes >/dev/null 2>&1 || true
- name: Post in-progress comment
if: steps.guard.outputs.skip != 'true' && steps.guard.outputs.mode == 'review'
continue-on-error: true
uses: marocchino/sticky-pull-request-comment@v2
with:
header: ${{ steps.guard.outputs.sticky_header }}
number: ${{ steps.guard.outputs.pr_number }}
message: |
### ${{ inputs.comment_header }} · analyzing…
⏳ CodeBoarding is analyzing the architecture changes in this PR. This usually takes a few minutes.
<sub>codeboarding-action · run ${{ github.run_id }}</sub>
GITHUB_TOKEN: ${{ inputs.github_token }}
- name: Checkout CodeBoarding engine
if: steps.guard.outputs.skip != 'true'
uses: actions/checkout@v4
with:
repository: CodeBoarding/CodeBoarding
ref: ${{ inputs.engine_ref }}
path: codeboarding-engine
persist-credentials: false
# Review mode: the PR head repo at the head SHA. Sync mode: this repo at the
# pushed/selected SHA. Always credential-free — both pushes (head analysis to
# the PR branch, docs to target_branch) authenticate explicitly via push_token.
- name: Checkout target repository
if: steps.guard.outputs.skip != 'true'
uses: actions/checkout@v4
with:
repository: ${{ steps.guard.outputs.checkout_repo }}
path: target-repo
fetch-depth: 0
ref: ${{ steps.guard.outputs.checkout_sha }}
persist-credentials: false
- name: Ensure PR base commit is fetched
if: steps.guard.outputs.skip != 'true' && steps.guard.outputs.mode == 'review'
shell: bash
working-directory: target-repo
env:
BASE_SHA: ${{ steps.guard.outputs.base_sha }}
BASE_REPO: ${{ steps.guard.outputs.base_repo }}
run: |
git fetch origin "$BASE_SHA" --depth=1 || true
if ! git cat-file -e "$BASE_SHA" 2>/dev/null; then
git remote add base "https://github.com/${BASE_REPO}.git" 2>/dev/null || git remote set-url base "https://github.com/${BASE_REPO}.git"
git fetch base "$BASE_SHA" --depth=1 || true
fi
git cat-file -e "$BASE_SHA" && echo "Base commit reachable." || \
(echo "::error::Base commit $BASE_SHA is not reachable." && exit 1)
- name: Set up Python 3.13
if: steps.guard.outputs.skip != 'true'
uses: actions/setup-python@v5
with:
python-version: '3.13'
- name: Set up Node.js 20
if: steps.guard.outputs.skip != 'true'
uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install uv
if: steps.guard.outputs.skip != 'true'
uses: astral-sh/setup-uv@v4
with:
enable-cache: true # cache ~/.cache/uv (wheels/builds) for fast cold installs
- name: Cache uv venv (engine)
if: steps.guard.outputs.skip != 'true'
uses: actions/cache@v4
with:
path: codeboarding-engine/.venv
# No restore-keys: a lockfile change must force a clean cold venv, not
# restore a venv built from a different lock (`uv pip install -e .` won't
# downgrade/sync already-installed transitive deps back to this uv.lock).
key: cb-uv-${{ runner.os }}-${{ hashFiles('codeboarding-engine/pyproject.toml', 'codeboarding-engine/uv.lock') }}
- name: Cache LSP servers
if: steps.guard.outputs.skip != 'true'
uses: actions/cache@v4
with:
path: |
codeboarding-engine/static_analyzer/servers/node_modules
codeboarding-engine/static_analyzer/servers/bin
key: cb-lsp-${{ runner.os }}-v1
restore-keys: |
cb-lsp-${{ runner.os }}-
- name: Install Python dependencies
if: steps.guard.outputs.skip != 'true'
shell: bash
working-directory: codeboarding-engine
run: |
test -d .venv || uv venv # reuse the cached venv instead of wiping it (--clear defeated the cache)
uv pip install -e .
- name: Install LSP servers
if: steps.guard.outputs.skip != 'true'
shell: bash
working-directory: codeboarding-engine
run: |
uv run python install.py --auto-install-npm
- name: Prepare & verify LLM key
if: steps.guard.outputs.skip != 'true'
id: llm
shell: bash
env:
RAW_KEY: ${{ inputs.llm_api_key }}
RAW_PROVIDER: ${{ inputs.llm_provider }}
RAW_AGENT_MODEL: ${{ inputs.agent_model }}
RAW_PARSING_MODEL: ${{ inputs.parsing_model }}
run: |
set -euo pipefail
AUTH_FILE="${RUNNER_TEMP}/openrouter-auth.json"
trap 'rm -f "$AUTH_FILE"' EXIT
if [ -z "$RAW_KEY" ]; then
echo "::error::llm_api_key is empty. On fork PRs, repo secrets are withheld by GitHub."
exit 1
fi
# Resolve the provider -> the env var the engine reads. Convention is
# <NAME>_API_KEY; two providers don't follow it. The engine is the source
# of truth: an unknown provider just yields an env var it won't recognize,
# and the engine errors with the list of valid keys.
PROVIDER="$(printf '%s' "$RAW_PROVIDER" | tr '[:upper:]' '[:lower:]' | tr -cd 'a-z0-9_')"
PROVIDER="${PROVIDER:-openrouter}"
case "$PROVIDER" in
aws_bedrock) PROVIDER_ENV="AWS_BEARER_TOKEN_BEDROCK" ;;
ollama) PROVIDER_ENV="OLLAMA_BASE_URL" ;;
*) PROVIDER_ENV="$(printf '%s' "$PROVIDER" | tr '[:lower:]' '[:upper:]')_API_KEY" ;;
esac
# Normalize a pasted key: strip whitespace/quotes and a leading `<ENV>=`.
_strip() { printf '%s' "$1" | tr -d '[:space:]' | sed -e 's/^"//;s/"$//' -e "s/^'//;s/'\$//"; }
# Cache keys reject some characters (model slugs carry '/'); sanitize for them.
_safe() { printf '%s' "$1" | tr -c 'A-Za-z0-9._-' '_'; }
KEY="$(_strip "$RAW_KEY")"
case "$KEY" in "${PROVIDER_ENV}="*) KEY="${KEY#${PROVIDER_ENV}=}";; esac
KEY="$(_strip "$KEY")"
AGENT_MODEL="$(_strip "$RAW_AGENT_MODEL")"
PARSING_MODEL="$(_strip "$RAW_PARSING_MODEL")"
echo "::add-mask::$KEY"
echo "Provider: $PROVIDER -> $PROVIDER_ENV; key length: ${#KEY}"
if [ "$PROVIDER" = "openrouter" ]; then
# Default models on OpenRouter when the user didn't pin one (cheap Gemini).
# Other providers fall through to the engine's own per-provider default.
AGENT_MODEL="${AGENT_MODEL:-google/gemini-3-flash-preview}"
PARSING_MODEL="${PARSING_MODEL:-google/gemini-3.1-flash-lite-preview}"
# OpenRouter-only checks. The litellm 'openrouter/...' model prefix 400s
# the engine's native OpenRouter call; other providers use native ids.
for M in "$AGENT_MODEL" "$PARSING_MODEL"; do
case "$M" in
openrouter/*)
echo "::error::Invalid model '$M': drop the 'openrouter/' prefix and use a bare OpenRouter slug, e.g. anthropic/claude-sonnet-4."
exit 1 ;;
esac
done
# Cheap preflight; other providers are validated by the engine at run time.
STATUS=$(curl -sS -o "$AUTH_FILE" -w "%{http_code}" \
-H "Authorization: Bearer $KEY" --max-time 10 \
https://openrouter.ai/api/v1/auth/key || echo "curl-fail")
echo "OpenRouter /auth/key response: HTTP $STATUS"
if [ "$STATUS" != "200" ]; then
# Surface the upstream error MESSAGE only — never the whole auth body (avoid leaking).
MSG="$(AUTH_FILE="$AUTH_FILE" python3 -c 'import json,os;print(json.load(open(os.environ["AUTH_FILE"])).get("error",{}).get("message",""))' 2>/dev/null || true)"
echo "::error::OpenRouter rejected the API key (HTTP $STATUS). ${MSG:-Verify the OPENROUTER_API_KEY secret.}"
exit 1
fi
fi
# Store key material in runner-temp files. Later shell steps read these
# explicitly; third-party post-comment actions do not inherit the LLM key.
umask 077
printf '%s' "$KEY" > "${RUNNER_TEMP}/cb-llm-key"
printf '%s' "$PROVIDER_ENV" > "${RUNNER_TEMP}/cb-provider-env"
printf '%s' "$AGENT_MODEL" > "${RUNNER_TEMP}/cb-agent-model"
printf '%s' "$PARSING_MODEL" > "${RUNNER_TEMP}/cb-parsing-model"
# Sanitized copies for use inside actions/cache keys (sync mode).
{
echo "cache_provider=$(_safe "$PROVIDER")"
echo "cache_agent_model=$(_safe "${AGENT_MODEL:-default}")"
echo "cache_parsing_model=$(_safe "${PARSING_MODEL:-default}")"
} >> "$GITHUB_OUTPUT"
- name: Resolve base analysis (committed baseline)
if: steps.guard.outputs.skip != 'true' && steps.guard.outputs.mode == 'review'
id: base
shell: bash
working-directory: target-repo
env:
BASE_SHA: ${{ steps.guard.outputs.base_sha }}
ACTION_PATH: ${{ github.action_path }}
DEPTH: ${{ inputs.depth_level }}
run: |
BASE_DIR="${RUNNER_TEMP}/cb-base"
HEAD_DIR="${RUNNER_TEMP}/cb-head"
mkdir -p "$BASE_DIR" "$HEAD_DIR"
echo "base_dir=$BASE_DIR" >> $GITHUB_OUTPUT
echo "head_dir=$HEAD_DIR" >> $GITHUB_OUTPUT
if git show "${BASE_SHA}:.codeboarding/analysis.json" > "${BASE_DIR}/analysis.json" 2>/dev/null; then
if python3 "$ACTION_PATH/scripts/engine_adapter.py" validate-base \
--analysis "${BASE_DIR}/analysis.json" \
--expected-sha "$BASE_SHA" \
--expected-depth "$DEPTH"; then
echo "committed=true" >> $GITHUB_OUTPUT
echo "Using committed .codeboarding/analysis.json at ${BASE_SHA}."
else
rm -f "${BASE_DIR}/analysis.json"
echo "committed=false" >> $GITHUB_OUTPUT
echo "Committed baseline at ${BASE_SHA} is stale; will generate a fresh base analysis."
fi
else
rm -f "${BASE_DIR}/analysis.json"
echo "committed=false" >> $GITHUB_OUTPUT
echo "No committed baseline at ${BASE_SHA}; will generate one via a full analysis on the base commit."
fi
- name: Restore base artifacts (keyed by base SHA)
if: steps.guard.outputs.skip != 'true' && steps.guard.outputs.mode == 'review'
id: basecache
uses: actions/cache/restore@v4
with:
path: ${{ runner.temp }}/cb-base
key: cb-base-v2-${{ runner.os }}-${{ steps.guard.outputs.base_sha }}-d${{ inputs.depth_level }}-${{ inputs.engine_ref }}-${{ inputs.llm_provider }}-${{ inputs.agent_model }}-${{ inputs.parsing_model }}
# A committed analysis.json gives the head analysis stable component ids,
# but the engine's incremental path ALSO needs the base static_analysis.pkl
# with its cluster baseline — which git can't provide (the pkl is never
# committed, by design). Build it here deterministically: LSP + Leiden
# clustering, no LLM key read. Fail-open: a failed seed degrades to exactly
# the previous behavior (the head run falls back to a full analysis).
- name: Seed base static-analysis cache (committed baseline, no cached pkl)
if: steps.guard.outputs.skip != 'true' && steps.guard.outputs.mode == 'review' && steps.base.outputs.committed == 'true' && steps.basecache.outputs.cache-hit != 'true'
id: seedbase
continue-on-error: true
shell: bash
working-directory: codeboarding-engine
env:
STATIC_ANALYSIS_CONFIG: ${{ github.workspace }}/codeboarding-engine/static_analysis_config.yml
PROJECT_ROOT: ${{ github.workspace }}/codeboarding-engine
CACHING_DOCUMENTATION: 'false'
ENABLE_MONITORING: 'false'
ACTION_PATH: ${{ github.action_path }}
TARGET: ${{ github.workspace }}/target-repo
BASE_DIR: ${{ steps.base.outputs.base_dir }}
BASE_SHA: ${{ steps.guard.outputs.base_sha }}
run: |
# Clean up any stale registration before re-adding (rm -rf alone leaves a
# dangling worktree entry that makes a retry's `worktree add` fail).
BASE_SRC="${RUNNER_TEMP}/base-src"
git -C "$TARGET" worktree remove --force "$BASE_SRC" 2>/dev/null || true
git -C "$TARGET" worktree prune
rm -rf "$BASE_SRC"
git -C "$TARGET" worktree add --detach "$BASE_SRC" "$BASE_SHA"
if uv run python "$ACTION_PATH/scripts/engine_adapter.py" seed \
--repo "$BASE_SRC" \
--out "$BASE_DIR" \
--source-sha "$BASE_SHA" \
&& [ -f "$BASE_DIR/static_analysis.pkl" ] && [ -f "$BASE_DIR/static_analysis.sha" ]; then
echo "seed_ok=true" >> "$GITHUB_OUTPUT"
echo "::notice::Seeded base static-analysis cache for ${BASE_SHA}; head analysis can run incrementally."
else
# Never leave a partial pkl/sha pair behind: the save step below would
# cache it under this base SHA's key and suppress every retry.
rm -f "$BASE_DIR/static_analysis.pkl" "$BASE_DIR/static_analysis.sha"
echo "seed_ok=false" >> "$GITHUB_OUTPUT"
echo "::warning::Base static-analysis seeding failed; head analysis will fall back to a full run."
fi
git -C "$TARGET" worktree remove --force "$BASE_SRC" 2>/dev/null || true
- name: Generate base analysis (no committed baseline)
if: steps.guard.outputs.skip != 'true' && steps.guard.outputs.mode == 'review' && steps.base.outputs.committed == 'false' && steps.basecache.outputs.cache-hit != 'true'
shell: bash
working-directory: codeboarding-engine
env:
STATIC_ANALYSIS_CONFIG: ${{ github.workspace }}/codeboarding-engine/static_analysis_config.yml
PROJECT_ROOT: ${{ github.workspace }}/codeboarding-engine
DIAGRAM_DEPTH_LEVEL: ${{ inputs.depth_level }}
CACHING_DOCUMENTATION: 'false'
ENABLE_MONITORING: 'false'
ACTION_PATH: ${{ github.action_path }}
TARGET: ${{ github.workspace }}/target-repo
BASE_DIR: ${{ steps.base.outputs.base_dir }}
REPO_NAME: ${{ github.event.repository.name }}
RUN_ID_BASE: ${{ github.run_id }}-${{ github.run_attempt }}-base
DEPTH: ${{ inputs.depth_level }}
BASE_SHA: ${{ steps.guard.outputs.base_sha }}
run: |
# Export the key under the selected provider's env var (only this one),
# so the engine auto-selects that provider.
PROVIDER_ENV="$(cat "${RUNNER_TEMP}/cb-provider-env")"
export "$PROVIDER_ENV"="$(cat "${RUNNER_TEMP}/cb-llm-key")"
# Export the model env only when the user set it; empty -> the engine uses
# its own valid per-provider default (no stale hardcoded model id to rot).
AGENT_MODEL="$(cat "${RUNNER_TEMP}/cb-agent-model")"
PARSING_MODEL="$(cat "${RUNNER_TEMP}/cb-parsing-model")"
if [ -n "$AGENT_MODEL" ]; then export AGENT_MODEL; fi
if [ -n "$PARSING_MODEL" ]; then export PARSING_MODEL; fi
BASE_SRC="${RUNNER_TEMP}/base-src"
# Clean up any stale registration before re-adding (rm -rf alone leaves a
# dangling worktree entry that makes a retry's `worktree add` fail).
git -C "$TARGET" worktree remove --force "$BASE_SRC" 2>/dev/null || true
git -C "$TARGET" worktree prune
rm -rf "$BASE_SRC"
git -C "$TARGET" worktree add --detach "$BASE_SRC" "$BASE_SHA"
uv run python "$ACTION_PATH/scripts/engine_adapter.py" base \
--repo "$BASE_SRC" \
--out "$BASE_DIR" \
--name "$REPO_NAME" \
--run-id "$RUN_ID_BASE" \
--depth "$DEPTH" \
--source-sha "$BASE_SHA"
git -C "$TARGET" worktree remove --force "$BASE_SRC" 2>/dev/null || true
if [ ! -f "$BASE_DIR/analysis.json" ]; then
echo "::error::Base full analysis ran but analysis.json is missing."
exit 1
fi
# Covers both base-artifact producers: the full analysis (no committed
# baseline) and the seeded pkl (committed baseline). The seed_ok gate is
# load-bearing — caching a pkl-less dir under this base SHA's key would
# permanently suppress seeding retries for it.
- name: Save generated base artifacts
if: steps.guard.outputs.skip != 'true' && steps.guard.outputs.mode == 'review' && steps.basecache.outputs.cache-hit != 'true' && (steps.base.outputs.committed == 'false' || steps.seedbase.outputs.seed_ok == 'true')
uses: actions/cache/save@v4
with:
path: ${{ runner.temp }}/cb-base
key: cb-base-v2-${{ runner.os }}-${{ steps.guard.outputs.base_sha }}-d${{ inputs.depth_level }}-${{ inputs.engine_ref }}-${{ inputs.llm_provider }}-${{ inputs.agent_model }}-${{ inputs.parsing_model }}
- name: Analyze PR head (incremental from base)
if: steps.guard.outputs.skip != 'true' && steps.guard.outputs.mode == 'review'
id: analyze
shell: bash
working-directory: codeboarding-engine
env:
STATIC_ANALYSIS_CONFIG: ${{ github.workspace }}/codeboarding-engine/static_analysis_config.yml
PROJECT_ROOT: ${{ github.workspace }}/codeboarding-engine
DIAGRAM_DEPTH_LEVEL: ${{ inputs.depth_level }}
CACHING_DOCUMENTATION: 'false'
ENABLE_MONITORING: 'false'
ACTION_PATH: ${{ github.action_path }}
TARGET_REPO: ${{ github.workspace }}/target-repo
BASE_DIR: ${{ steps.base.outputs.base_dir }}
HEAD_DIR: ${{ steps.base.outputs.head_dir }}
REPO_NAME: ${{ github.event.repository.name }}
RUN_ID_HEAD: ${{ github.run_id }}-${{ github.run_attempt }}-head
DEPTH: ${{ inputs.depth_level }}
BASE_SHA: ${{ steps.guard.outputs.base_sha }}
HEAD_SHA: ${{ steps.guard.outputs.head_sha }}
run: |
# Export the key under the selected provider's env var (only this one),
# so the engine auto-selects that provider.
PROVIDER_ENV="$(cat "${RUNNER_TEMP}/cb-provider-env")"
export "$PROVIDER_ENV"="$(cat "${RUNNER_TEMP}/cb-llm-key")"
# Export the model env only when the user set it; empty -> the engine uses
# its own valid per-provider default (no stale hardcoded model id to rot).
AGENT_MODEL="$(cat "${RUNNER_TEMP}/cb-agent-model")"
PARSING_MODEL="$(cat "${RUNNER_TEMP}/cb-parsing-model")"
if [ -n "$AGENT_MODEL" ]; then export AGENT_MODEL; fi
if [ -n "$PARSING_MODEL" ]; then export PARSING_MODEL; fi
# Seed the head dir from the base analysis so incremental stitches
# component ids from the baseline (stable diff). Base dir is left
# untouched as the "before" snapshot for the diff.
cp -a "$BASE_DIR"/. "$HEAD_DIR"/ 2>/dev/null || true
rm -rf "$HEAD_DIR/health"
uv run python "$ACTION_PATH/scripts/engine_adapter.py" head \
--repo "$TARGET_REPO" \
--out "$HEAD_DIR" \
--name "$REPO_NAME" \
--run-id "$RUN_ID_HEAD" \
--depth "$DEPTH" \
--base-ref "$BASE_SHA" \
--target-ref "$HEAD_SHA" \
--source-sha "$HEAD_SHA"
if [ ! -f "$HEAD_DIR/analysis.json" ]; then
echo "::error::Head analysis ran but analysis.json is missing."
exit 1
fi
echo "base_analysis=$BASE_DIR/analysis.json" >> $GITHUB_OUTPUT
echo "head_analysis=$HEAD_DIR/analysis.json" >> $GITHUB_OUTPUT
- name: Architecture health check (best-effort)
if: steps.guard.outputs.skip != 'true' && steps.guard.outputs.mode == 'review'
id: health
continue-on-error: true
shell: bash
working-directory: codeboarding-engine
env:
STATIC_ANALYSIS_CONFIG: ${{ github.workspace }}/codeboarding-engine/static_analysis_config.yml
PROJECT_ROOT: ${{ github.workspace }}/codeboarding-engine
ACTION_PATH: ${{ github.action_path }}
ARTIFACT_DIR: ${{ steps.base.outputs.head_dir }}
TARGET_REPO: ${{ github.workspace }}/target-repo
REPO_NAME: ${{ github.event.repository.name }}
run: |
rm -f /tmp/cb-issues.txt
# engine_adapter writes the WARNING/CRITICAL count (0 on any failure — best-effort).
uv run python "$ACTION_PATH/scripts/engine_adapter.py" health \
--artifact-dir "$ARTIFACT_DIR" \
--repo "$TARGET_REPO" \
--name "$REPO_NAME" \
--issues-out /tmp/cb-issues.txt || true
ISSUE_COUNT=$(cat /tmp/cb-issues.txt 2>/dev/null || echo 0)
echo "issues=$ISSUE_COUNT" >> $GITHUB_OUTPUT
echo "Architecture issues: $ISSUE_COUNT"
# ---- Sync mode: analyze the target commit (mirrors the review pipeline's
# baseline/seed/incremental strategy, but against the committed analysis.json
# in the working tree instead of the PR base). ----
- name: Seed sync workdir from committed baseline
if: steps.guard.outputs.skip != 'true' && steps.guard.outputs.mode == 'sync'
id: sync_seed
shell: bash
working-directory: target-repo
env:
OUTPUT_DIR: ${{ inputs.output_dir }}
ACTION_PATH: ${{ github.action_path }}
run: |
set -euo pipefail
ANALYSIS_DIR="${RUNNER_TEMP}/cb-sync"
RENDER_DIR="${RUNNER_TEMP}/cb-sync-render"
ARCHITECTURE_FILE="${RUNNER_TEMP}/cb-architecture.md"
rm -rf "$ANALYSIS_DIR" "$RENDER_DIR"
mkdir -p "$ANALYSIS_DIR" "$RENDER_DIR"
{
echo "cb_dir=$ANALYSIS_DIR"
echo "render_dir=$RENDER_DIR"
echo "arch_file=$ARCHITECTURE_FILE"
} >> "$GITHUB_OUTPUT"
if [ -f "$OUTPUT_DIR/analysis.json" ]; then
cp "$OUTPUT_DIR/analysis.json" "$ANALYSIS_DIR/analysis.json"
# baseline-info parses metadata.commit_hash and emits it ONLY when it is
# present and SHA-shaped, so an unusable/injected value never reaches
# GITHUB_OUTPUT, the cache key, or git. (Pure stdlib — no engine venv.)
BASELINE_SHA="$(python3 "$ACTION_PATH/scripts/engine_adapter.py" baseline-info \
--analysis "$ANALYSIS_DIR/analysis.json" | sed -n 's/^commit_hash=//p')"
if [ -n "$BASELINE_SHA" ]; then
echo "baseline_present=true" >> "$GITHUB_OUTPUT"
echo "baseline_sha=$BASELINE_SHA" >> "$GITHUB_OUTPUT"
echo "Using committed baseline generated for $BASELINE_SHA."
else
rm -f "$ANALYSIS_DIR/analysis.json"
echo "baseline_present=false" >> "$GITHUB_OUTPUT"
echo "baseline_sha=none" >> "$GITHUB_OUTPUT"
echo "::warning::Committed analysis.json has no usable metadata.commit_hash; a full analysis will run."
fi
else
echo "baseline_present=false" >> "$GITHUB_OUTPUT"
echo "baseline_sha=none" >> "$GITHUB_OUTPUT"
echo "No committed baseline found; a full analysis will run."
fi
- name: Restore sync static-analysis cache
if: steps.guard.outputs.skip != 'true' && steps.guard.outputs.mode == 'sync' && steps.sync_seed.outputs.baseline_present == 'true'
id: sync_cache
uses: actions/cache/restore@v4
with:
path: |
${{ runner.temp }}/cb-sync/static_analysis.pkl
${{ runner.temp }}/cb-sync/static_analysis.sha
key: cb-sync-${{ runner.os }}-${{ inputs.engine_ref }}-d${{ inputs.depth_level }}-${{ steps.llm.outputs.cache_provider }}-${{ steps.llm.outputs.cache_agent_model }}-${{ steps.llm.outputs.cache_parsing_model }}-${{ steps.sync_seed.outputs.baseline_sha }}
# Same rationale as the review pipeline's seed step: the committed
# analysis.json supplies component ids, but the incremental path also needs
# the baseline static_analysis.pkl (LSP + clustering, no LLM). Fail-open.
- name: Seed sync static-analysis cache at baseline SHA
if: steps.guard.outputs.skip != 'true' && steps.guard.outputs.mode == 'sync' && steps.sync_seed.outputs.baseline_present == 'true' && steps.sync_cache.outputs.cache-hit != 'true'
id: sync_seedcache
continue-on-error: true
shell: bash
working-directory: codeboarding-engine
env:
STATIC_ANALYSIS_CONFIG: ${{ github.workspace }}/codeboarding-engine/static_analysis_config.yml
PROJECT_ROOT: ${{ github.workspace }}/codeboarding-engine
# The seed subcommand defaults to github_action attribution; sync-mode
# telemetry must report as sync (setdefault never clobbers this).
CODEBOARDING_SOURCE: 'sync'
CACHING_DOCUMENTATION: 'false'
ENABLE_MONITORING: 'false'
ACTION_PATH: ${{ github.action_path }}
TARGET_REPO: ${{ github.workspace }}/target-repo
ANALYSIS_DIR: ${{ steps.sync_seed.outputs.cb_dir }}
BASELINE_SHA: ${{ steps.sync_seed.outputs.baseline_sha }}
run: |
set -euo pipefail
echo "seed_ok=false" >> "$GITHUB_OUTPUT"
if ! git -C "$TARGET_REPO" cat-file -e "${BASELINE_SHA}^{commit}" 2>/dev/null; then
echo "::warning::Baseline commit $BASELINE_SHA is not reachable; analysis will fall back to full if needed."
exit 0
fi
# Clean up any stale registration before re-adding (rm -rf alone leaves a
# dangling worktree entry that makes a retry's `worktree add` fail).
BASE_SRC="${RUNNER_TEMP}/cb-sync-base-src"
git -C "$TARGET_REPO" worktree remove --force "$BASE_SRC" 2>/dev/null || true
git -C "$TARGET_REPO" worktree prune
rm -rf "$BASE_SRC"
git -C "$TARGET_REPO" worktree add --detach "$BASE_SRC" "$BASELINE_SHA"
if uv run python "$ACTION_PATH/scripts/engine_adapter.py" seed \
--repo "$BASE_SRC" \
--out "$ANALYSIS_DIR" \
--source-sha "$BASELINE_SHA" \
&& [ -f "$ANALYSIS_DIR/static_analysis.pkl" ] && [ -f "$ANALYSIS_DIR/static_analysis.sha" ]; then
echo "seed_ok=true" >> "$GITHUB_OUTPUT"
echo "::notice::Seeded static-analysis cache for $BASELINE_SHA."
else
rm -f "$ANALYSIS_DIR/static_analysis.pkl" "$ANALYSIS_DIR/static_analysis.sha"
echo "::warning::Static-analysis seeding failed; analysis may fall back to full."
fi
git -C "$TARGET_REPO" worktree remove --force "$BASE_SRC" 2>/dev/null || true
- name: Analyze target repository (sync)
if: steps.guard.outputs.skip != 'true' && steps.guard.outputs.mode == 'sync'
id: sync_analyze
shell: bash
working-directory: codeboarding-engine
env:
STATIC_ANALYSIS_CONFIG: ${{ github.workspace }}/codeboarding-engine/static_analysis_config.yml
PROJECT_ROOT: ${{ github.workspace }}/codeboarding-engine
DIAGRAM_DEPTH_LEVEL: ${{ inputs.depth_level }}
CACHING_DOCUMENTATION: 'false'
ENABLE_MONITORING: 'false'
ACTION_PATH: ${{ github.action_path }}
TARGET_REPO: ${{ github.workspace }}/target-repo
ANALYSIS_DIR: ${{ steps.sync_seed.outputs.cb_dir }}
REPO_NAME: ${{ github.event.repository.name }}
RUN_ID_SYNC: ${{ github.run_id }}-${{ github.run_attempt }}-sync
TARGET_SHA: ${{ steps.guard.outputs.target_sha }}
DEPTH: ${{ inputs.depth_level }}
FORCE_FULL: ${{ inputs.force_full }}
run: |
set -euo pipefail
# Export the key under the selected provider's env var (only this one),
# so the engine auto-selects that provider.
PROVIDER_ENV="$(cat "${RUNNER_TEMP}/cb-provider-env")"
export "$PROVIDER_ENV"="$(cat "${RUNNER_TEMP}/cb-llm-key")"
# Export the model env only when the user set it; empty -> the engine uses
# its own valid per-provider default (no stale hardcoded model id to rot).
AGENT_MODEL="$(cat "${RUNNER_TEMP}/cb-agent-model")"
PARSING_MODEL="$(cat "${RUNNER_TEMP}/cb-parsing-model")"
if [ -n "$AGENT_MODEL" ]; then export AGENT_MODEL; fi
if [ -n "$PARSING_MODEL" ]; then export PARSING_MODEL; fi
args=(
--repo "$TARGET_REPO"
--out "$ANALYSIS_DIR"
--name "$REPO_NAME"
--run-id "$RUN_ID_SYNC"
--source-sha "$TARGET_SHA"
--depth "$DEPTH"
)
[ "$FORCE_FULL" = "true" ] && args+=(--force-full)
LOG="${RUNNER_TEMP}/cb-sync-analyze.log"
uv run python "$ACTION_PATH/scripts/engine_adapter.py" analyze "${args[@]}" | tee "$LOG"
MODE="$(sed -n 's/^analysis_mode=//p' "$LOG" | tail -1)"
MODE="${MODE:-unknown}"
echo "analysis_mode=$MODE" >> "$GITHUB_OUTPUT"
echo "analysis_path=$ANALYSIS_DIR/analysis.json" >> "$GITHUB_OUTPUT"
[ -f "$ANALYSIS_DIR/analysis.json" ] || { echo "::error::Analysis ran but analysis.json is missing."; exit 1; }
- name: Drop LLM key material
if: always() && steps.guard.outputs.skip != 'true'
shell: bash
run: |
rm -f "${RUNNER_TEMP}/cb-llm-key" \
"${RUNNER_TEMP}/cb-provider-env" \
"${RUNNER_TEMP}/cb-agent-model" \
"${RUNNER_TEMP}/cb-parsing-model"
# Commit the generated head analysis (+ health report) to the PR branch so the
# hosted webview can fetch .codeboarding/analysis.json at the head SHA and open
# this PR's head-vs-base diff. Same-repo PRs only — the token is read-only on
# forks (the step is skipped there and the webview link is omitted). The push
# creates a NEW head commit; its SHA (webview_sha) is what the comment links to.
- name: Commit head analysis to PR branch
id: commit_head
if: >-
steps.guard.outputs.skip != 'true'
&& steps.guard.outputs.mode == 'review'
&& inputs.commit_head_analysis == 'true'
&& steps.guard.outputs.same_repo == 'true'
&& inputs.webview_base_url != ''
shell: bash
working-directory: target-repo
env:
# Push with push_token (defaults to the workflow github.token, gated by the
# consumer's `permissions: contents: write`) — NOT github_token, which may be
# a GitHub App token used only for commenting and need not have write access.
GH_TOKEN: ${{ inputs.push_token }}
HEAD_DIR: ${{ steps.base.outputs.head_dir }}
HEAD_REF: ${{ steps.guard.outputs.head_ref }}
HEAD_SHA: ${{ steps.guard.outputs.head_sha }}
REPOSITORY: ${{ github.repository }}
SERVER_URL: ${{ github.server_url }}
run: |
echo "ready=false" >> "$GITHUB_OUTPUT"
echo "webview_sha=$HEAD_SHA" >> "$GITHUB_OUTPUT"
[ -n "$HEAD_REF" ] || { echo "::notice::No head branch ref resolved; skipping head-analysis commit."; exit 0; }
[ -f "$HEAD_DIR/analysis.json" ] || { echo "::notice::No head analysis.json to commit."; exit 0; }
mkdir -p .codeboarding/health
cp "$HEAD_DIR/analysis.json" .codeboarding/analysis.json
if [ -f "$HEAD_DIR/health/health_report.json" ]; then
cp "$HEAD_DIR/health/health_report.json" .codeboarding/health/health_report.json
fi
git add .codeboarding/analysis.json .codeboarding/health/health_report.json 2>/dev/null || git add .codeboarding/analysis.json
if git diff --cached --quiet; then
echo "::notice::Head analysis unchanged; nothing to commit."
echo "ready=true" >> "$GITHUB_OUTPUT" # already committed at this SHA → webview can read it
exit 0
fi
# Same architecture, only volatile metadata differs: don't commit. The
# ignored fields must cover EVERY per-run field, or the loop below stays
# open: generated_at and the health timestamp, AND commit_hash — which
# tracks the analyzed head SHA, so on a synchronize re-run (whose head IS
# our previous bot commit) it changes even when the architecture didn't.
# The bot commit carries no "[skip ci]" (it would leak through squash-
# merges and skip real merges' workflows), so without ignoring all three
# a synchronize-triggered re-run would re-commit a fresh SHA/timestamp
# forever. ready=true: the analysis already committed serves the webview.
if git diff --cached --quiet -I '"generated_at"' -I '"timestamp"' -I '"commit_hash"'; then
git reset -q
echo "::notice::Head analysis differs only in volatile metadata (timestamps/commit_hash); nothing to commit."
echo "ready=true" >> "$GITHUB_OUTPUT"
exit 0
fi
git config user.name "codeboarding[bot]"
git config user.email "codeboarding[bot]@users.noreply.github.com"