Cursor Action

Run Cursor agents in GitHub Actions using the official @cursor/sdk. An independent project, not affiliated with or endorsed by Cursor.

Quickstart

1. Add a repository secret named CURSOR_API_KEY.
2. Use the action in a workflow job.
3. Read steps.<id>.outputs.summary for the model response.

- name: Run Cursor Agent
  id: cursor
  uses: PunGrumpy/cursor-action@v1
  with:
    api-key: ${{ secrets.CURSOR_API_KEY }}
    prompt: "Review this PR for security issues and summarize your findings."

- name: Print summary
  env:
    SUMMARY: ${{ steps.cursor.outputs.summary }}
  run: echo "$SUMMARY"

The action runs on ubuntu-latest, windows-latest, and macos-latest.

Reference

Inputs

| Input | Required | Default | Description | | --- | --- | --- | --- | | cursor-version | ❌ | latest | (Deprecated) The SDK automatically manages the agent version. | | api-key | ✅ | — | Cursor API key for authentication | | prompt | ✅ | — | Prompt to pass to cursor-agent | | model | ❌ | default | Model id for the agent (e.g. default, composer-2). The Cursor SDK does not accept auto. | | working-directory | ❌ | . | Working directory for the agent to operate in | | permissions | ❌ | read-only | Validated but NOT enforced: 'read-only' does not stop the agent from editing files or running shell commands. Wired to the SDK in v2. | | timeout | ❌ | 300 | Timeout in seconds for the agent run |

Outputs

| Output | Description | | --- | --- | | summary | Text summary returned by the cursor-agent | | exit-code | Exit code from the cursor-agent process | | status | Run status returned by the cursor-agent (finished, error, or cancelled) | | duration-ms | Execution duration in milliseconds | | total-tokens | Total tokens consumed by the agent run | | input-tokens | Input tokens consumed by the agent run | | output-tokens | Output tokens generated by the agent run |

[!WARNING]

permissions does not restrict the agent today. The value is validated and then discarded — tool access follows whatever your API key and account allow, so read-only does not stop the agent from editing files or running shell commands. It is wired to the SDK's tool restrictions in v2.

[!IMPORTANT]

Treat summary as untrusted model output. Pass it through env: rather than interpolating ${{ steps.<id>.outputs.summary }} directly into a run: script or a github-script body — interpolation splices the text into the script before it executes.

Documentation

Worked examples, what the action does at runtime, and troubleshooting live in docs/, which is published as the documentation site. The tables above are generated from action.yml by the same script that generates the site's reference page, so neither can drift from the manifest.

Local development

Prerequisites

• Node.js 24 (matches CI and release workflows)
• Bun

Validate changes locally

bun install
bun run typecheck
bun run test
bun run build

dist/ is committed on purpose — GitHub Actions executes it straight from the tag. If you changed anything under src/, run bun run build and commit the result; CI fails when dist/ is out of date. The bundle only contains this repository's own code (a few KB); @actions/core and @cursor/sdk stay external and are installed by the action at runtime, so package-lock.json must stay in sync with package.json.

Work on the documentation site

bun run docs:reference   # regenerate the reference tables from action.yml
bun run docs:dev         # http://localhost:3000

docs/ is a separate Fumapress project with its own lockfile, so bun install at the repository root does not pull in its dependencies.

Run the action entrypoint locally

export GITHUB_STEP_SUMMARY="$(mktemp)"
export GITHUB_OUTPUT="$(mktemp)"

env "INPUT_API-KEY=$CURSOR_API_KEY" \
    "INPUT_PROMPT=Say 'smoke test passed' and nothing else." \
    "INPUT_MODEL=default" \
    "INPUT_PERMISSIONS=read-only" \
    "INPUT_TIMEOUT=60" \
    node dist/index.mjs

CI and release notes

• CI runs typecheck, lint, test, build, and a dist/ freshness check on every push and pull request. The Docs job regenerates the reference from action.yml, typechecks the site, and builds it.
• The Integration jobs install the action's runtime dependencies and run it with an invalid key on Ubuntu, Windows, and macOS. Being rejected at authentication is the pass condition: it proves the dependency tree resolves and the SDK reaches Cursor, without spending an agent run.
• Smoke Test runs the action for real and needs a CURSOR_API_KEY on a paid plan, so it only runs from the Actions tab (workflow_dispatch).
• Release runs Changesets on pushes to main to open a release PR or publish, then moves the v1 tag to the published version.
• uses: PunGrumpy/cursor-action@v1 tracks the latest v1.x.x. Pin a full tag or a commit SHA if you want a frozen version.

Versioning

This project uses Changesets. See .changeset/README.md for the contribution workflow.

License

MIT © PunGrumpy