this is how to integrate ai-sast

Author: tpilli

.github/workflows/ai-sast.yml

@@ -4,10 +4,10 @@
 # Important: For feedback collection to trigger, this file must be on your default branch (e.g. main).
 # GitHub runs issue_comment workflows from the default branch only.
 #
-# Required: copy this file as .github/workflows/ai-sast.yml, add secrets:
+# Required: fork this repo, copy this file as .github/workflows/ai-sast.yml into the repo you want to scan,
+#   set variable AI_SAST_REPO to your fork (e.g. your-username/ai-sast), add secrets:
 #   GOOGLE_CLOUD_PROJECT, GOOGLE_CREDENTIALS
-# Default: checks out rivian/ai-sast. Optional: set AI_SAST_REPO (e.g. for a fork);
-#   AI_SAST_BASE_BRANCH (default: main); AI_SAST_REF (default: main); runs-on for self-hosted.
+# Optional: AI_SAST_BASE_BRANCH (default: main); AI_SAST_REF (default: main); runs-on for self-hosted.
 #
 # PR scan runs only when the PR diff touches supported file extensions (see paths below).
 # workflow_dispatch and issue_comment have no path filter.
@@ -103,10 +103,17 @@ jobs:
       - name: Prepare feedback DB directory
         run: mkdir -p .ai-sast-db
 
+      - name: Require AI_SAST_REPO (use your fork)
+        run: |
+          if [ -z "${{ vars.AI_SAST_REPO }}" ]; then
+            echo "::error::Fork this repository (https://github.com/rivian/ai-sast), then set the repository variable AI_SAST_REPO to your fork (e.g. your-username/ai-sast). Settings → Secrets and variables → Actions → Variables."
+            exit 1
+          fi
+
       - name: Checkout AI-SAST
         uses: actions/checkout@v4
         with:
-          repository: ${{ vars.AI_SAST_REPO || 'rivian/ai-sast' }}
+          repository: ${{ vars.AI_SAST_REPO }}
           path: ai-sast
           ref: ${{ vars.AI_SAST_REF || 'main' }}
 
@@ -237,10 +244,17 @@ jobs:
       - name: Prepare feedback DB directory
         run: mkdir -p .ai-sast-db
 
+      - name: Require AI_SAST_REPO (use your fork)
+        run: |
+          if [ -z "${{ vars.AI_SAST_REPO }}" ]; then
+            echo "::error::Fork this repository (https://github.com/rivian/ai-sast), then set the repository variable AI_SAST_REPO to your fork (e.g. your-username/ai-sast). Settings → Secrets and variables → Actions → Variables."
+            exit 1
+          fi
+
       - name: Checkout AI-SAST
         uses: actions/checkout@v4
         with:
-          repository: ${{ vars.AI_SAST_REPO || 'rivian/ai-sast' }}
+          repository: ${{ vars.AI_SAST_REPO }}
           path: ai-sast
           ref: ${{ vars.AI_SAST_REF || 'main' }}
 

README.md

@@ -28,15 +28,20 @@ AI-SAST is an AI-driven static application security testing tool. Run it in **yo
 
 ## Integrate in your repository
 
-1. **Copy the workflow file** into your repo as `.github/workflows/ai-sast.yml`:  
+1. **Fork this repository** so the workflow uses your fork (and so the project’s fork count reflects adoption).
+
+2. **Copy the workflow file** into the repo you want to scan as `.github/workflows/ai-sast.yml`:  
    [`.github/workflows/ai-sast.yml`](.github/workflows/ai-sast.yml)
 
-2. **Add repository secrets** (Settings → Secrets and variables → Actions):  
+3. **Set the repository variable** (Settings → Secrets and variables → Actions → Variables):  
+   `AI_SAST_REPO` = your fork (e.g. `your-username/ai-sast`).
+
+4. **Add repository secrets** (Settings → Secrets and variables → Actions → Secrets):  
    `GOOGLE_CLOUD_PROJECT`, `GOOGLE_CREDENTIALS`
 
-The workflow checks out **`rivian/ai-sast`** at runtime. One file runs **PR scan** (on pull requests when base branch is `main`), **full scan** (manual "Run workflow"), and **feedback collection** (when someone edits a PR comment and checks a true/false positive box).
+The workflow checks out **your fork** at runtime. One file runs **PR scan** (on pull requests when base branch is `main`), **full scan** (manual "Run workflow"), and **feedback collection** (when someone edits a PR comment and checks a true/false positive box).
 
-**Optional:** Set variable `AI_SAST_REPO` (e.g. for a fork); `AI_SAST_BASE_BRANCH` (default `main`); `runs-on: self-hosted` in the workflow for your own runners.
+**Optional:** Set `AI_SAST_BASE_BRANCH` (default `main`); `AI_SAST_REF` (default `main`); `runs-on: self-hosted` in the workflow for your own runners.
 
 📚 **Full guide:** [docs/INTEGRATION.md](docs/INTEGRATION.md)
 
@@ -98,7 +103,7 @@ All configuration is driven by environment variables. The table below lists supp
 | Variable | Description | Default |
 |----------|-------------|---------|
 | **Workflow & scan behavior** | | |
-| `AI_SAST_REPO` | GitHub repo to checkout (e.g. `org/ai-sast` or a fork). | `rivian/ai-sast` (in workflow) |
+| `AI_SAST_REPO` | Your fork of this repo (e.g. `your-username/ai-sast`). **Required**—fork first, then set this variable. | — |
 | `AI_SAST_BASE_BRANCH` | Branch that triggers PR scan; PRs targeting this branch are scanned. | `main` |
 | `AI_SAST_SEVERITY` | Comma-separated severities to include in PR comments (e.g. `critical,high,medium`). The validator runs only on findings in these severities. | `critical,high` |
 | `AI_SAST_UPDATE_SAME_PR_COMMENT` | When `true`, each PR scan run updates the same PR comment with the latest results instead of posting a new comment (reduces noise on multi-commit PRs). When `false` or unset, a new comment is posted every time (default). | `false` |
@@ -158,7 +163,7 @@ All configuration is driven by environment variables. The table below lists supp
 - **Auth errors:** Service account needs "Vertex AI User" role; `GOOGLE_CREDENTIALS` must be the full JSON key.
 - **No PR comment:** Ensure the PR targets the branch set by `AI_SAST_BASE_BRANCH` (default `main`).
 - **Feedback not triggering:** The feedback job runs from your **default branch** (e.g. `main`). Make sure `ai-sast.yml` is merged to that branch—if it only exists on a feature branch, checking boxes in the PR comment won’t trigger the workflow.
-- **Using a fork:** Set repository variable `AI_SAST_REPO` to your `org/ai-sast`.
+- **Setup:** Fork this repo, then set repository variable `AI_SAST_REPO` to your fork (e.g. `your-username/ai-sast`).
 
 ## Support
 

docs/INTEGRATION.md

@@ -1,31 +1,44 @@
 # Integrating AI-SAST into Your Repository
 
-Run AI-SAST (PR scan + full scan) **in your repo on your runners**. The workflow checks out the ai-sast scanner at runtime—no submodule or manual copy. Your code never runs on ai-sast infrastructure.
+Run AI-SAST (PR scan + full scan) **in your repo on your runners**. The workflow checks out your fork of the ai-sast scanner at runtime—no submodule or manual copy. Your code never runs on ai-sast infrastructure.
 
-## Required (2 steps)
+## Required (4 steps)
 
-### 1. Copy the workflow file
+### 1. Fork this repository
+
+Fork [rivian/ai-sast](https://github.com/rivian/ai-sast) so the workflow uses your fork. This also helps the project’s visibility (fork count) and lets you customize the scanner.
+
+### 2. Copy the workflow file
 
 - **From this repo:** [`.github/workflows/ai-sast.yml`](../.github/workflows/ai-sast.yml)
-- **Save as:** `.github/workflows/ai-sast.yml` in **your** repository.
+- **Save as:** `.github/workflows/ai-sast.yml` in the **repository you want to scan** (not necessarily the fork).
 
 This single file runs PR scan, full scan, and feedback collection (when developers check boxes in PR comments). Feedback is stored in a database and included in the Vertex AI prompt on future scans to improve accuracy.
 
-### 2. Add Google secrets
+### 3. Set the AI_SAST_REPO variable
+
+In the repository you want to scan: **Settings → Secrets and variables → Actions → Variables**
+
+| Variable | Value |
+|----------|--------|
+| `AI_SAST_REPO` | Your fork (e.g. `your-username/ai-sast`) |
+
+The workflow will checkout this repo at runtime. If you skip this, the workflow will fail with instructions to fork and set the variable.
+
+### 4. Add Google secrets
 
-In your repository: **Settings → Secrets and variables → Actions → Secrets**
+In the same repository: **Settings → Secrets and variables → Actions → Secrets**
 
 | Secret | Description |
 |--------|-------------|
 | `GOOGLE_CLOUD_PROJECT` | Your GCP project ID |
 | `GOOGLE_CREDENTIALS` | Service account JSON (full contents of the key file) |
 
-The workflow checks out **`rivian/ai-sast`** by default. That’s it—PR scan runs on pull requests (when base branch matches), full scan (manual "Run workflow"), and feedback collection (when a PR comment with the AI-SAST scan is edited and checkboxes are used).
+That’s it—PR scan runs on pull requests (when base branch matches), full scan (manual "Run workflow"), and feedback collection (when a PR comment with the AI-SAST scan is edited and checkboxes are used).
 
 ## Optional
 
 - **LLM provider:** Default is **Vertex AI** (Gemini). To use **AWS Bedrock (Claude)** set variable **`AI_SAST_LLM`** = `bedrock`, and set **`AWS_REGION`** (e.g. `us-east-1`), **`BEDROCK_MODEL_ID`**. Add AWS credentials as secrets (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`) or use an IAM role on the runner. For local **Ollama**, set **`AI_SAST_LLM`** = `ollama`.
-- **Using a fork:** Set repository variable **`AI_SAST_REPO`** (e.g. `your-org/ai-sast`) to checkout your fork instead of `rivian/ai-sast`.
 - **Default branch for PR scan:** Add variable **`AI_SAST_BASE_BRANCH`** (e.g. `main`, `master`, `develop`). Default is `main` if unset.
 - **Scanner ref:** Add variable **`AI_SAST_REF`** (e.g. `main`, `v1.0`) to pin the ai-sast version. Default is `main`.
 - **Update same PR comment:** Set **`AI_SAST_UPDATE_SAME_PR_COMMENT`** = `true` to update the existing AI-SAST comment on each scan run instead of posting a new one (reduces noise when multiple commits trigger multiple scans). Default is `false`.
@@ -38,7 +51,7 @@ The workflow checks out **`rivian/ai-sast`** by default. That’s it—PR scan r
 
 ## Troubleshooting
 
-- **“repository not found” or checkout fails:** You may be using a fork; set `AI_SAST_REPO` to your `org/ai-sast`.
+- **“repository not found” or checkout fails:** Ensure `AI_SAST_REPO` is set to your fork (e.g. `your-username/ai-sast`). You must fork the repo first.
 - **No PR comment:** Check that the PR targets the branch set by `AI_SAST_BASE_BRANCH` (or `main`). Check the “Run AI-SAST PR Scan” step logs.
 - **Feedback not triggering when you check boxes:** The `issue_comment` event runs the workflow from your **default branch** (e.g. `main`). Ensure `ai-sast.yml` is committed and merged to that branch—if the file exists only on a feature branch, feedback collection will not run.
 - **Auth errors:** Ensure the service account has the “Vertex AI User” role and that `GOOGLE_CREDENTIALS` is the **full** JSON key (not a path).