GitHub Integration Sample

Automate GitHub issue analysis with AI. Mention @caret in any issue comment to trigger an autonomous investigation that reads files, analyzes code, and provides actionable insights - all running automatically in GitHub Actions.

ℹ️Note

New to Caret CLI? This sample assumes you understand Caret CLI basics and have completed the Installation Guide. If you're new to Caret CLI, we recommend starting with the GitHub RCA sample first, as it's simpler and will help you understand the fundamentals before setting up GitHub Actions.

The Workflow

Trigger Caret by mentioning @caret in any issue comment:

Caret's automated analysis appears as a new comment, with insights drawn from your actual codebase:

The entire investigation runs autonomously in GitHub Actions - from file exploration to posting results.

Let's configure your repository.

Prerequisites

Before you begin, you'll need:

• Caret CLI knowledge - Completed the Installation Guide and understand basic usage
• GitHub repository - With admin access to configure Actions and secrets
• GitHub Actions familiarity - Basic understanding of workflows and CI/CD
• API provider account - OpenRouter, Anthropic, or similar with API key

Setup

1. Copy the Workflow File

Copy the workflow file from this sample to your repository. The workflow file must be placed in the .github/workflows/ directory in your repository root for GitHub Actions to detect and run it. In this case, we'll name it caret-responder.yml.

# In your repository root
mkdir -p .github/workflows
curl -o .github/workflows/caret-responder.yml https://raw.githubusercontent.com/caret/caret/main/src/samples/cli/github-integration/caret-responder.yml

Alternatively, you can copy the full workflow file directly into .github/workflows/caret-responder.yml:

Click to view the complete caret-responder.yml workflow

name: Caret Issue Assistant

on:
  issue_comment:
    types: [created, edited]

permissions:
  issues: write

jobs:
  respond:
    runs-on: ubuntu-latest
    environment: caret-actions
    steps:
      - name: Check for @caret mention
        id: detect
        uses: actions/github-script@v7
        with:
          script: |
            const body = context.payload.comment?.body || "";
            const isPR = !!context.payload.issue?.pull_request;
            const hit = body.toLowerCase().includes("@caret");
            core.setOutput("hit", (!isPR && hit) ? "true" : "false");
            core.setOutput("issue_number", String(context.payload.issue?.number || ""));
            core.setOutput("issue_url", context.payload.issue?.html_url || "");
            core.setOutput("comment_body", body);

      - name: Checkout repository
        if: steps.detect.outputs.hit == 'true'
        uses: actions/checkout@v4

      # Node v20 is needed for Caret CLI on GitHub Actions Linux
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Setup Caret CLI
        if: steps.detect.outputs.hit == 'true'
        run: |
          # Install the Caret CLI
          sudo npm install -g caret

      - name: Create Caret Instance
        if: steps.detect.outputs.hit == 'true'
        env:
          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
          CLINE_DIR: ${{ runner.temp }}/caret
        run: |
          # Create instance and capture output
          INSTANCE_OUTPUT=$(caret instance new 2>&1)
          
          # Parse address from output (format: "  Address: 127.0.0.1:36733")
          CLINE_ADDRESS=$(echo "$INSTANCE_OUTPUT" | grep "Address:" | grep -oE '([0-9]{1,3}\.){3}[0-9]{1,3}:[0-9]+')
          echo "CLINE_ADDRESS=$CLINE_ADDRESS" >> $GITHUB_ENV
          
          # Configure API key
          caret config set open-router-api-key=$OPENROUTER_API_KEY --address $CLINE_ADDRESS -v

      - name: Download analyze script
        if: steps.detect.outputs.hit == 'true'
        run: |
          export GITORG="YOUR-GITHUB-ORG"
          export GITREPO="YOUR-GITHUB-REPO"

          curl -L https://raw.githubusercontent.com/${GITORG}/${GITREPO}/refs/heads/main/git-scripts/analyze-issue.sh -o analyze-issue.sh
          chmod +x analyze-issue.sh

      - name: Run analysis
        if: steps.detect.outputs.hit == 'true'
        id: analyze
        env:
          ISSUE_URL: ${{ steps.detect.outputs.issue_url }}
          COMMENT: ${{ steps.detect.outputs.comment_body }}
          CLINE_ADDRESS: ${{ env.CLINE_ADDRESS }}
        run: |
          set -euo pipefail
          
          RESULT=$(./analyze-issue.sh "${ISSUE_URL}" "Analyze this issue. The user asked: ${COMMENT}" "$CLINE_ADDRESS")
          
          {
            echo 'result<<EOF'
            printf "%s\n" "$RESULT"
            echo 'EOF'
          } >> "$GITHUB_OUTPUT"

      - name: Post response
        if: steps.detect.outputs.hit == 'true'
        uses: actions/github-script@v7
        env:
          ISSUE_NUMBER: ${{ steps.detect.outputs.issue_number }}
          RESULT: ${{ steps.analyze.outputs.result }}
        with:
          script: |
            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: Number(process.env.ISSUE_NUMBER),
              body: process.env.RESULT || "(no output)"
            });

⚠️Warning

You MUST edit the workflow file before committing!

Open .github/workflows/caret-responder.yml and update the "Download analyze script" step within the workflow to specify your GitHub organization and repository where the analysis script is stored:

export GITORG="YOUR-GITHUB-ORG"      # Change this!
export GITREPO="YOUR-GITHUB-REPO"    # Change this!

Example: If your repository is github.com/acme/myproject, set:

export GITORG="acme"
export GITREPO="myproject"

This tells the workflow where to download the analysis script from your repository after you commit it in step 3.

The workflow will look for new or updated issues, check for @caret mentions, and then start up an instance of the Caret CLI to dig into the issue, providing feedback as a reply to the issue.

2. Configure API Keys

Add your AI provider API keys as repository secrets:

1. Go to your GitHub repository

2. Navigate to Settings → Environment and Add a new environment.

   

   Make sure to name it "caret-actions" so that it matches the environment value at the top of the caret-responder.yml file.

3. Click New repository secret

4. Add a secret for the OPENROUTER_API_KEY with a value of an API key from openrouter.com.

   

5. Verify your secret is configured:

   

Now you're ready to supply Caret with the credentials it needs in a GitHub Action.

3. Add Analysis Script

Add the analysis script from the github-issue-rca sample to your repository. First, you'll need to create a git-scripts directory in your repository root where the script will be located. Choose one of these options:

Option A: Download directly (Recommended)

# In your repository root, create the directory and download the script
mkdir -p git-scripts
curl -o git-scripts/analyze-issue.sh https://raw.githubusercontent.com/caret/caret/main/src/samples/cli/github-issue-rca/analyze-issue.sh
chmod +x git-scripts/analyze-issue.sh

Option B: Manual copy-paste

Create the directory and file manually, then paste the script content:

# In your repository root
mkdir -p git-scripts
# Create and edit the file with your preferred editor
nano git-scripts/analyze-issue.sh  # or use vim, code, etc.

Click to view the complete analyze-issue.sh script

#!/bin/bash
# Analyze a GitHub issue using Caret CLI

if [ -z "$1" ]; then
    echo "Usage: $0 <github-issue-url> [prompt] [address]"
    echo "Example: $0 https://github.com/owner/repo/issues/123"
    echo "Example: $0 https://github.com/owner/repo/issues/123 'What is the root cause of this issue?'"
    echo "Example: $0 https://github.com/owner/repo/issues/123 'What is the root cause of this issue?' 127.0.0.1:46529"
    exit 1
fi

# Gather the args
ISSUE_URL="$1"
PROMPT="${2:-What is the root cause of this issue?}"
if [ -n "$3" ]; then
    ADDRESS="--address $3"
fi

# Ask Caret for its analysis, showing only the summary
caret -y "$PROMPT: $ISSUE_URL" --mode act $ADDRESS -F json | \
    sed -n '/^{/,$p' | \
    jq -r 'select(.say == "completion_result") | .text' | \
    sed 's/\\n/\n/g'

After pasting the script content, make it executable:

chmod +x git-scripts/analyze-issue.sh

This analysis script calls Caret to execute a prompt on a GitHub issue, summarizing the output to populate the reply to the issue.

4. Commit and Push

git add .github/workflows/caret-responder.yml
git add git-scripts/analyze-issue.sh
git commit -m "Add Caret issue assistant workflow"
git push

Usage

Once set up, simply mention @caret in any issue comment:

@caret what's causing this error?

@caret analyze the root cause

@caret what are the security implications?

GitHub Actions will:

1. Detect the @caret mention
2. Start a Caret CLI instance
3. Download the analysis script
4. Analyze the issue using act mode with yolo (fully autonomous)
5. Post Caret's analysis as a new comment

Note: The workflow only triggers on issue comments, not pull request comments.

How It Works

The workflow (caret-responder.yml):

1. Triggers on issue comments (created or edited)
2. Detects @caret mentions (case-insensitive)
3. Installs Caret CLI globally using npm
4. Creates a Caret instance using caret instance new
5. Configures authentication using caret config set open-router-api-key=... --address ...
6. Downloads the reusable analyze-issue.sh script from the github-issue-rca sample
7. Runs analysis with the instance address
8. Posts the analysis result as a comment

Related Samples

• github-issue-rca: The reusable script that powers this integration