AI Issue Action

• Inputs
• Outputs
• Examples
• Tags
• Support
• Contributing

🤖 Automatically triage issues with AI trained on your existing documentation.

💯 100% free to use with OpenCode Zen or Gemini Free Tier models.

✅ Works with Claude, Gemini, OpenAI, and any OpenAI Compatible Provider.

- name: 'AI Issue'
  uses: cssnr/ai-issue-action@v1
  with:
    model: big-pickle
    instructions: 'You are a helpful assistant responding to a GitHub Issue'

💡 You can copy the issue.yaml to your workflows or see more Examples.

Features

• Works with Claude, Gemini, OpenAI, and OpenAI Compatible Provider
• Provide Instructions via Text, Path Globs or URL
• Add Custom Head or Tail Message to the Issue Reply
• Outputs Results, Reasoning, Usage, and Comment Details
• Built with the AI SDK

Tip

TO see more features, please submit a feature request.

Inputs

The only required input is the model name.
You must provide at least one of instructions, url or path.

Input	Default	Input Description
model	-	Model to Use
instructions	-	Text Instructions
url	-	Remote URL Instructions
path	-	Path(s) Glob Instructions
max_tokens	-	Max Output Tokens
head	-	Head Text for Reply
tail	-	Tail Text for Reply
base_url	https://opencode.ai/zen/v1	URL for OpenAI Compatible
number	Workflow Issue Number	Issue Number
token	${{ github.token }}	Optional GitHub Token

To authenticate provide your API key in the applicable environment variable:

• Claude: ANTHROPIC_API_KEY
• Gemini: GOOGLE_GENERATIVE_AI_API_KEY
• OpenAI: OPENAI_API_KEY
• OpenAI Compatible: PROVIDER_API_KEY

- name: 'AI Issue'
  uses: cssnr/ai-issue-action@v1
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
    GOOGLE_GENERATIVE_AI_API_KEY: ${{ secrets.GOOGLE_GENERATIVE_AI_API_KEY }}
    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
    PROVIDER_API_KEY: ${{ secrets.PROVIDER_API_KEY }} # optional for free models
  with:
    model: gemini-2.5-flash # or any Claude, Gemini, OpenAI, or OpenAI Compatible Provider

💡 Start for free with model big-pickle (no API key required).

Make sure your workflow has the required permissions.

permissions:
  contents: write
  issues: write

model

• Claude: https://platform.claude.com/docs/en/about-claude/models/overview
• Gemini: https://ai.google.dev/gemini-api/docs/models
• OpenAI: https://developers.openai.com/api/docs/models/compare
• OpenAI Compatible Provider: https://opencode.ai/zen

Provider routing is based on model name.

Pattern	Provider SDK
gemini*	@ai-sdk/google
gpt*	@ai-sdk/openai
claude*	@ai-sdk/anthropic
*	@ai-sdk/openai-compatible

Examples: claude-haiku-4-5, gemini-2.5-flash, gpt-5.4-nano, big-pickle

instructions

Text instruction.

Example: You are a helpful assistant responding to a GitHub Issue on training data:

url

URL to fetch remote instructions.

Example: https://smashedr.github.io/vitepress-chat/llms.txt

path

File glob(s) to read for instructions.

Example: .github/instructions/*.md

Examples

💡 To get started 100% free, copy the issue.yaml to your workflows.

Basic example using the free Zen Big Pickle model.

- name: 'AI Issue'
  uses: cssnr/ai-issue-action@v1
  with:
    model: big-pickle
    instructions: 'You are an assistant responding to a GitHub Issue'

Use remote llms.txt and Gemini Free Tier.

- name: 'AI Issue'
  uses: cssnr/ai-issue-action@v1
  env:
    GOOGLE_GENERATIVE_AI_API_KEY: ${{ secrets.GOOGLE_GENERATIVE_AI_API_KEY }}
  with:
    model: gemini-2.5-flash
    instructions: 'You are an assistant responding to a GitHub Issue with knowledge:'
    url: https://smashedr.github.io/vitepress-chat/llms.txt

Full example using an app token and file path globs.

name: 'Issue'

on:
  issues:
    types: [opened]

jobs:
  issue:
    name: 'Issue'
    runs-on: ubuntu-latest
    timeout-minutes: 15

    permissions:
      contents: write
      issues: write

    steps:
      - name: 'Checkout'
        uses: actions/checkout@v6
        with:
          sparse-checkout-cone-mode: false
          sparse-checkout: |
            docs/**

      - name: 'Create App Token'
        if: ${{ !github.event.release.prerelease }}
        id: app
        uses: actions/create-github-app-token@v3
        with:
          client-id: ${{ vars.APP_CLIENT_ID }}
          private-key: ${{ secrets.APP_PRIVATE_KEY }}

      - name: 'AI Issue'
        id: issue
        uses: cssnr/ai-issue-action@v1
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        with:
          token: ${{ steps.app.outputs.token }}
          model: gpt-5.4-nano
          instructions: 'You are an assistant responding to a GitHub Issue with Training Data:'
          path: |
            docs/**/*.md
          tail: |
            _Response generated by the [AI Issue Action](https://github.com/cssnr/ai-issue-action)._

Only run for issues with the label bug.

if: ${{ contains(github.event.issue.labels.*.name, 'bug') }}

Only run for issues without the label enhancement.

if: ${{ !contains(github.event.issue.labels.*.name, 'enhancement') }}

Only run for issues without a label or with label bug.

if: ${{ !github.event.issue.labels[0] || contains(github.event.issue.labels.*.name, 'bug') }}

Only run for issues without a type or the type bug (Organizations).

if: ${{ !github.event.issue.type || github.event.issue.type.name == 'Bug' }}

For more examples, you can check out other projects using this action:
https://github.com/cssnr/ai-issue-action/network/dependents

Outputs

Output	Description
text	Response Text
reasoningText	Reasoning Text
usage	Usage JSON
finishReason	Finish Reason
comment	Comment JSON
commentId	Comment ID
commentUrl	Comment URL

- name: 'AI Issue'
  id: issue
  uses: cssnr/ai-issue-action@v1
  env:
    GOOGLE_GENERATIVE_AI_API_KEY: ${{ secrets.GOOGLE_GENERATIVE_AI_API_KEY }}
  with:
    model: gemini-2.5-flash
    instructions: 'You are an assistant responding to a GitHub Issue with Training Data:'
    path: .github/instructions/*.md

- name: 'Echo Outputs'
  env:
    text: ${{ steps.issue.outputs.text }}
    reasoningText: ${{ steps.issue.outputs.reasoningText }}
    usage: ${{ steps.issue.outputs.usage }}
    comment: ${{ steps.issue.outputs.comment }}
  run: |
    echo "text: ${text}"
    echo "reasoningText: ${reasoningText}"
    echo "usage: ${usage}"
    echo "finishReason: ${{ steps.issue.outputs.finishReason }}"
    echo "comment: ${comment}"
    echo "commentId: ${{ steps.issue.outputs.commentId }}"
    echo "commentUrl: ${{ steps.issue.outputs.commentUrl }}"

Note: Multi-line outputs get evaluated using ${{ }} in a run block.

Tags

The following rolling tags are maintained.

Version Tag	Rolling	Bugs	Feat.	Name	Target	Example
	✅	✅	✅	Major	vN.x.x	vN
	✅	✅	❌	Minor	vN.N.x	vN.N
	❌	❌	❌	Micro	vN.N.N	vN.N.N

You can view the release notes for each version on the releases page.

The Major tag is recommended. It is the most up-to-date and always backwards compatible. Breaking changes would result in a Major version bump. At a minimum you should use a Minor tag.

Support

If you run into any issues or need help getting started, please do one of the following:

• Report an Issue
• Q&A Discussion
• Request a Feature
• Chat with us on Discord

Contributing

If you would like to submit a PR, please review the CONTRIBUTING.md.

Please consider making a donation to support the development of this project and additional open source projects.

Additionally, you can support other GitHub Actions I have published:

• Stack Deploy Action
• Portainer Stack Deploy Action
• Docker Context Action
• AI Issue Action
• Actions Up Action
• Webstore Publish Action
• Openai Translate Action
• Rhysd Actionlint Action
• Zensical Action
• VirusTotal Action
• Homebrew Action
• Mirror Repository Action
• Update Version Tags Action
• Docker Tags Action
• TOML Action
• Update JSON Value Action
• JSON Key Value Check Action
• Parse Issue Form Action
• Cloudflare Purge Cache Action
• Mozilla Addon Update Action
• Package Changelog Action
• NPM Outdated Check Action
• Label Creator Action
• Algolia Crawler Action
• Create Pull Action
• Upload Release Action
• Check Build Action
• Web Request Action
• Get Commit Action

❔ Unpublished Actions

These actions are not published on the Marketplace, but may be useful.

• cssnr/create-files-action - Create various files from templates.
• cssnr/draft-release-action - Keep a draft release ready to publish.
• cssnr/env-json-action - Convert env file to json or vice versa.
• cssnr/push-artifacts-action - Sync files to a remote host with rsync.
• smashedr/update-release-notes-action - Update release notes.
• smashedr/combine-release-notes-action - Combine release notes.

---

📝 Template Actions

These are basic action templates that I use for creating new actions.

• javascript-action - JavaScript
• typescript-action - TypeScript
• py-test-action - Dockerfile Python
• test-action-uv - Dockerfile Python UV
• docker-test-action - Docker Image Python

Note: The docker-test-action builds, runs and pushes images to GitHub Container Registry.

---

For a full list of current projects visit: https://cssnr.github.io/