Doc: Add spec for AI primitives

[laurent22]

No description provided.

[coderabbitai]

.

[coderabbitai]

.

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Guard on both required secrets before minting the App token.

At the moment, Line 28 only validates APP_ID. If Line 41’s private key secret is missing, the workflow still proceeds and fails in the token step. Check both secrets in the gate step.

Suggested fix

       - name: Check secrets availability
         id: check-secrets
         env:
           APP_ID: ${{ secrets.CODERABBIT_CLEANUP_APP_ID }}
+          APP_PRIVATE_KEY: ${{ secrets.CODERABBIT_CLEANUP_APP_PRIVATE_KEY }}
         run: |
-          if [ -z "$APP_ID" ]; then
-            echo "App secrets not available (likely a fork PR event); skipping."
+          if [ -z "$APP_ID" ] || [ -z "$APP_PRIVATE_KEY" ]; then
+            echo "Required App secrets not available; skipping."
             echo "available=false" >> "$GITHUB_OUTPUT"
           else
             echo "available=true" >> "$GITHUB_OUTPUT"
           fi

Also applies to: 40-41

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/delete-coderabbit-comments.yml around lines 25 - 33, The
workflow only checks APP_ID before proceeding but must validate both secrets;
add the private key env (e.g., PRIVATE_KEY: ${{
secrets.CODERABBIT_CLEANUP_PRIVATE_KEY }}) and update the gate in the run block
to test both variables (if either -z "$APP_ID" || -z "$PRIVATE_KEY") and emit
"available=false" when either is missing, otherwise "available=true"; apply the
same dual-secret check where the token is minted (the second gate around the
token step) so both APP_ID and the private key are validated before attempting
to mint the App token.

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

FILE=".github/workflows/delete-coderabbit-comments.yml"
if [ ! -f "$FILE" ]; then
  echo "Missing file: $FILE" >&2
  exit 1
fi

# Show around the referenced line
nl -ba "$FILE" | sed -n '1,120p' | sed -n '30,70p'

Repository: laurent22/joplin

Length of output: 104

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

FILE=".github/workflows/delete-coderabbit-comments.yml"
[ -f "$FILE" ] || { echo "Missing file: $FILE" >&2; exit 1; }

# Print line-numbered section around the original range
awk 'NR>=25 && NR<=60 { printf "%d:%s\n", NR, $0 }' "$FILE"

# Also search for the action usage anywhere in the workflow file
echo "---- matches ----"
rg -n "actions/create-github-app-token" "$FILE" || true

Repository: laurent22/joplin

Length of output: 1758

---

Pin actions/create-github-app-token to an immutable commit SHA.

delete-coderabbit-comments.yml uses the mutable tag actions/create-github-app-token@v1 (line 38), which can be retagged upstream; pin to a full commit SHA for supply-chain safety.

Suggested fix

-        uses: actions/create-github-app-token@v1
+        uses: actions/create-github-app-token@<full_commit_sha>

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	uses: actions/create-github-app-token@v1
	uses: actions/create-github-app-token@<actual_commit_sha_here>

🧰 Tools

🪛 zizmor (1.25.2)

[error] 38-38: unpinned action reference (unpinned-uses): action is not pinned to a hash (required by blanket policy)

(unpinned-uses)

---

[error] 38-38: dangerous use of GitHub App tokens (github-app): app token inherits blanket installation permissions

(github-app)

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/delete-coderabbit-comments.yml at line 38, Replace the
mutable action ref "actions/create-github-app-token@v1" with an immutable full
commit SHA to prevent supply-chain attacks; locate the workflow step that uses
the action (the uses: "actions/create-github-app-token@v1" line) and update it
to "actions/create-github-app-token@<full-commit-sha>" after verifying the
correct commit on the action's repository, then run CI to ensure the workflow
still functions.

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Locate the workflow file and print the relevant section with line numbers
FILE=".github/workflows/delete-coderabbit-comments.yml"
echo "== File: $FILE =="
stat "$FILE" || true
nl -ba "$FILE" | sed -n '1,160p'

# Extract any create-github-app-token usage blocks (with some surrounding context)
echo "== create-github-app-token usages =="
rg -n "create-github-app-token" -n "$FILE" || true
nl -ba "$FILE" | sed -n '1,200p' | rg -n "create-github-app-token|permission-|app-token|permission" || true

Repository: laurent22/joplin

Length of output: 225

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

FILE=".github/workflows/delete-coderabbit-comments.yml"
echo "== Existence check =="
ls -la .github/workflows || true
ls -la "$FILE" || true

echo
echo "== create-github-app-token usages =="
rg -n "create-github-app-token" "$FILE" || true
echo
rg -n "permission-" "$FILE" || true
echo
rg -n "app-token" "$FILE" || true

echo
echo "== File contents (numbered) - first 200 lines =="
python3 - <<'PY'
path = ".github/workflows/delete-coderabbit-comments.yml"
with open(path, "r", encoding="utf-8") as f:
    lines = f.readlines()
for i, line in enumerate(lines[:200], start=1):
    print(f"{i:4d}\t{line.rstrip()}")
PY

Repository: laurent22/joplin

Length of output: 4350

---

🌐 Web query:

actions/create-github-app-token v1 inputs permission-pull-requests permission-issues

💡 Result:

The action input is permission-issues (note: plural “issues”), and it controls the permission level the generated GitHub App installation token grants for issues and related features. In actions/create-github-app-token v1, the input permission-issues sets whether the token has read or write access for issues and related comments, assignees, labels, and milestones [1]. It follows the action’s general pattern: to grant a specific permission, you prefix the GitHub permission name with permission- (e.g., pull-requests → permission-pull-requests) [2]. Also, setting a permission that the GitHub App installation doesn’t actually have will cause an error; by default the token inherits all of the installation’s permissions, but you can explicitly list required ones [2].

Citations:

• 1: https://github.com/actions/create-github-app-token/blob/93c1f04d6f14ea5b416e7a8dfd80446101c6adef/action.yml
• 2: https://github.com/actions/create-github-app-token

---

Restrict GitHub App token permissions to least privilege

The workflow currently generates the GitHub App installation token with only app-id and private-key, so the token can default to the GitHub App’s broad installation permissions. This job only needs permission to update PR reviews and delete issue comments.

Suggested fix

       - name: Generate GitHub App token
         if: steps.check-secrets.outputs.available == 'true'
         id: app-token
         uses: actions/create-github-app-token@v1
         with:
           app-id: ${{ secrets.CODERABBIT_CLEANUP_APP_ID }}
           private-key: ${{ secrets.CODERABBIT_CLEANUP_APP_PRIVATE_KEY }}
+          permission-pull-requests: write
+          permission-issues: write

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	with:
	app-id: ${{ secrets.CODERABBIT_CLEANUP_APP_ID }}
	private-key: ${{ secrets.CODERABBIT_CLEANUP_APP_PRIVATE_KEY }}
	with:
	app-id: ${{ secrets.CODERABBIT_CLEANUP_APP_ID }}
	private-key: ${{ secrets.CODERABBIT_CLEANUP_APP_PRIVATE_KEY }}
	permission-pull-requests: write
	permission-issues: write

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/delete-coderabbit-comments.yml around lines 39 - 41, The
workflow currently creates the GitHub App installation token using the with:
app-id and private-key inputs and leaves the token with the app's default
installation permissions; update the token-generation step to specify
least-privilege permissions by adding a permissions block that grants only what
this job needs (e.g., pull-requests: write and issues: write) alongside the
existing with: app-id and private-key so the generated installation token can
only update PR reviews and delete issue comments.