Allow writes in CI for analysis.json to be commited

Author: Svilen-Stefanov

.github/workflows/codeboarding.yml

@@ -11,7 +11,9 @@ on:
     types: [created]
 
 permissions:
-  contents: read
+  # write: the action commits the generated .codeboarding/analysis.json back to the
+  # PR branch so the webview can open this PR's diff at the head SHA (same-repo PRs).
+  contents: write
   pull-requests: write
   issues: write
 

README.md

@@ -69,7 +69,9 @@ on:
     types: [created]
 
 permissions:
-  contents: read
+  # write lets the action commit analysis.json to the PR branch so the comment can
+  # link to the webview diff. Drop to `read` to keep the comment without that link.
+  contents: write
   pull-requests: write
   issues: write
 
@@ -156,6 +158,7 @@ The command needs the `issue_comment` trigger and runs from your default branch
 | `llm_api_key` | required | Your LLM provider API key (see `llm_provider`). |
 | `llm_provider` | `openrouter` | Provider for the key, mapped to `<NAME>_API_KEY` (e.g. `anthropic`, `openai`, `google`). |
 | `github_token` | `${{ github.token }}` | Token used to post or update the PR comment. |
+| `push_token` | `${{ github.token }}` | Token used to push the generated `analysis.json` to the PR branch (for the webview link). The workflow token can push when the workflow grants `permissions: contents: write`. Separate from `github_token` so commenting can use a GitHub App token while the push uses the workflow token. |
 | `engine_ref` | `v0.12.0` | CodeBoarding engine ref. Pin for reproducibility. |
 | `depth_level` | `1` | Analysis depth, 1 to 3. Higher is slower and richer. |
 | `render_depth` | `1` | Display depth for the PR diagram. Keep `1` for a clean top-level view. |

action.yml

@@ -18,6 +18,10 @@ inputs:
     description: 'GITHUB_TOKEN used to post the PR comment. Defaults to the workflow token.'
     required: false
     default: ${{ github.token }}
+  push_token:
+    description: 'Token used to push the generated .codeboarding/analysis.json to the PR branch (for the webview link). 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
@@ -605,7 +609,10 @@ runs:
       shell: bash
       working-directory: target-repo
       env:
-        GH_TOKEN: ${{ inputs.github_token }}
+        # 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 }}
@@ -636,14 +643,16 @@ runs:
 
         # Push to the PR head branch. The checkout used persist-credentials:false, so
         # authenticate the push explicitly with the workflow token (same-repo only).
+        # Requires `contents: write` on the job's token — a read-only token (the
+        # default) is rejected here; the push error below names the cause.
         AUTH_URL="https://x-access-token:${GH_TOKEN}@${SERVER_URL#https://}/${REPOSITORY}.git"
-        if git push "$AUTH_URL" "HEAD:refs/heads/${HEAD_REF}" 2>/dev/null; then
+        if git push "$AUTH_URL" "HEAD:refs/heads/${HEAD_REF}"; then
           NEW_SHA="$(git rev-parse HEAD)"
           echo "webview_sha=$NEW_SHA" >> "$GITHUB_OUTPUT"
           echo "ready=true" >> "$GITHUB_OUTPUT"
           echo "Committed head analysis to ${HEAD_REF} as ${NEW_SHA}."
         else
-          echo "::warning::Could not push head analysis to ${HEAD_REF}; the webview link will be omitted."
+          echo "::warning::Could not push head analysis to ${HEAD_REF}; the webview link will be omitted. Most likely the job's token lacks 'contents: write' (add 'permissions: contents: write' to the calling workflow), or the branch is protected against this pusher."
         fi
 
     - name: Diff analyses → Mermaid

scripts/build_cta.py

@@ -159,11 +159,20 @@ def main() -> int:
         issues = int(args.issues or 0)
     except ValueError:
         issues = 0
-    print(build_cta(
-        args.cta_base, args.owner, args.repo, args.pr, args.repo_path, issues,
-        webview_base=args.webview_base, head_sha=args.head_sha, base_sha=args.base_sha,
-        webview_ready=args.webview_ready,
-    ))
+    print(
+        build_cta(
+            args.cta_base,
+            args.owner,
+            args.repo,
+            args.pr,
+            args.repo_path,
+            issues,
+            webview_base=args.webview_base,
+            head_sha=args.head_sha,
+            base_sha=args.base_sha,
+            webview_ready=args.webview_ready,
+        )
+    )
     return 0
 
 

tests/test_build_cta.py

@@ -98,8 +98,16 @@ def test_link_none_without_head_sha_or_base(self):
 
     def test_cta_emits_webview_line_when_ready(self):
         out = bc.build_cta(
-            "", "Org", "Repo", "9", repo_with(), issues=0,
-            webview_base=self.WV, head_sha="headsha", base_sha="basesha", webview_ready=True,
+            "",
+            "Org",
+            "Repo",
+            "9",
+            repo_with(),
+            issues=0,
+            webview_base=self.WV,
+            head_sha="headsha",
+            base_sha="basesha",
+            webview_ready=True,
         )
         self.assertIn("Explore this PR", out)
         self.assertIn("ref=headsha", out)
@@ -108,17 +116,33 @@ def test_cta_emits_webview_line_when_ready(self):
     def test_cta_omits_webview_line_when_not_ready(self):
         # Fork PR / head analysis not committed -> webview can't fetch at head SHA.
         out = bc.build_cta(
-            "", "Org", "Repo", "9", repo_with(), issues=0,
-            webview_base=self.WV, head_sha="headsha", base_sha="basesha", webview_ready=False,
+            "",
+            "Org",
+            "Repo",
+            "9",
+            repo_with(),
+            issues=0,
+            webview_base=self.WV,
+            head_sha="headsha",
+            base_sha="basesha",
+            webview_ready=False,
         )
         self.assertNotIn("Explore this PR", out)
         # Editor CTA is still present regardless.
         self.assertIn("Open in VS Code", out)
 
     def test_cta_omits_webview_line_when_ready_but_no_base_url(self):
         out = bc.build_cta(
-            "", "Org", "Repo", "9", repo_with(), issues=0,
-            webview_base="", head_sha="headsha", base_sha="basesha", webview_ready=True,
+            "",
+            "Org",
+            "Repo",
+            "9",
+            repo_with(),
+            issues=0,
+            webview_base="",
+            head_sha="headsha",
+            base_sha="basesha",
+            webview_ready=True,
         )
         self.assertNotIn("Explore this PR", out)