Netlify Agent Runners

Setup

netlify init

name: Netlify Agent Runners

on:
  workflow_dispatch:
    inputs:
      trigger_text:
        description: 'Prompt for the agent run'
        required: true
        type: string
        default: '@netlify'
      actor:
        description: 'Actor triggering the agent'
        required: true
        type: string
      agent:
        description: 'Agent to use'
        required: false
        type: choice
        options:
          - codex
          - claude
          - gemini
        default: 'codex'
  pull_request_target:
    types: [opened, reopened]
  pull_request_review_comment:
    types: [created]
  pull_request_review:
    types: [submitted, edited]
  issues:
    types: [opened, assigned, edited]
  issue_comment:
    types: [created, edited]

concurrency:
  group: ${{ (github.event_name == 'issue_comment' || github.event_name == 'pull_request_review_comment') && github.event.comment.body == '@netlify stop' && format('netlify-stop-{0}', github.run_id) || format('netlify-{0}-{1}', github.repository, github.event.pull_request.number || github.event.issue.number || inputs.recover_thread || github.run_id) }}
  cancel-in-progress: false

jobs:
  netlify-agent:
    # Skip bot senders early to avoid burning Actions minutes
    if: >-
      github.event_name == 'workflow_dispatch' ||
      (
        github.event.sender.login != 'github-actions[bot]' &&
        github.event.sender.login != 'netlify-coding[bot]' &&
        github.event.sender.login != 'netlify[bot]'
      )
    runs-on: ubuntu-latest
    timeout-minutes: 25
    permissions:
      contents: write
      pull-requests: write
      issues: write
    steps:
      - uses: netlify-labs/agent-runner-action@v1
        with:
          netlify-auth-token: ${{ secrets.NETLIFY_AUTH_TOKEN }}
          netlify-site-id: ${{ secrets.NETLIFY_SITE_ID }}
          # preflight-only: 'false' # Validate setup and skip agent execution

Usage

From an issue

Create an issue with @netlify in the body:

@netlify Build a landing page for a coffee shop with a menu and contact form

Choose an agent

Specify claude, codex, gemini, or opencode after @netlify:

@netlify claude Add a dark mode toggle
@netlify codex Make the hero section responsive
@netlify gemini Add a testimonials carousel

Default agent is codex. You can change the default with the default-agent input.

Choose a model and effort

After @netlify, name an agent, a model, and an effort level, in that order. Each is optional, and a model picks its own agent:

@netlify fable high Refactor the checkout flow
@netlify claude fable high Refactor the checkout flow
@netlify-fable high Refactor the checkout flow
@netlify codex sol medium Add retry logic
@netlify claude high Fix the header

Claude models: fable, opus, opus-4.8, sonnet, haiku. Codex: codex sol, codex terra, codex luna, codex mini. Gemini: gemini pro, gemini flash, gemini flash-lite. OpenCode: kimi, kimi-code, glm, deepseek, deepseek-flash, grok, minimax. Exact model IDs and model:<id> also work.

Effort is low, medium, or high (some OpenCode models also take max; Kimi K2.7 Code and MiniMax M3 take none), placed after an agent or model and followed by a space, :, ,, or the end of the line. effort:<level> anywhere on the @netlify line takes precedence, and effort:auto forces Auto. Anything left out is chosen by the backend (Auto) unless you set default-model-id or default-effort.

Follow-up prompts

After the first run creates a PR, add follow-up @netlify comments on the PR to iterate. The agent continues from where it left off.

Execution modes

dry-run and preflight-only are different controls:

• dry-run: 'true' still starts an agent run, but skips commit and PR creation.
• preflight-only: 'true' validates setup and exits before any agent run is created or resumed.
• If both are true, preflight-only behavior wins and no agent run starts.

- uses: netlify-labs/agent-runner-action@v1
  with:
    netlify-auth-token: ${{ secrets.NETLIFY_AUTH_TOKEN }}
    netlify-site-id: ${{ secrets.NETLIFY_SITE_ID }}
    preflight-only: 'true' # setup validation only

- uses: netlify-labs/agent-runner-action@v1
  with:
    netlify-auth-token: ${{ secrets.NETLIFY_AUTH_TOKEN }}
    netlify-site-id: ${{ secrets.NETLIFY_SITE_ID }}
    dry-run: 'true' # run agent preview, skip commits/PR

Typo-tolerant

Common typos are recognized: @nelify, @netlfy, @netify, @netlif, @netfly. Aliases like @netlify-agent and @netlify-ai also work.

Inputs

Outputs

Use these in subsequent workflow steps for custom automation:

Example: run tests after agent

steps:
  - uses: netlify-labs/agent-runner-action@v1
    id: agent
    with:
      netlify-auth-token: ${{ secrets.NETLIFY_AUTH_TOKEN }}
      netlify-site-id: ${{ secrets.NETLIFY_SITE_ID }}

  - name: Run tests on agent PR
    if: steps.agent.outputs.outcome == 'success'
    run: echo "PR created at ${{ steps.agent.outputs.agent-pr-url }}"

Asking questions

Ask mode answers a question about the code in a comment, without changing files or opening a PR. Use @netlify-ask, @netlify ask: (the colon is required), or mode:ask right after the mention: for example @netlify-ask fable high how are webhooks retried?. A plain "ask" isn't enough, because @netlify ask the user to confirm… is a build request. The answer appears as a result comment marked 💬 Answered. On a PR, the agent reads the PR branch, and a later @netlify request continues with the same context.

Scope guard

After a successful run, the action checks which files that run changed and adds a ⚠️ Review these changes table to the result comment (and to the PR, for runs started from an issue) when it touched workflows, netlify.toml, root *.toml files, lockfiles, AGENTS.md/CLAUDE.md, .env files, new root files, or new top-level folders. Files the request names are listed as requested instead. It never blocks a run.

Configure it with protected-paths (globs; a pattern without / matches only at the root; default, none, and !pattern are supported) and escalate with protected-paths-action: comment,label,draft. By default, scope-instructions also tells agents to report unrelated build or deploy failures instead of working around them.

Run checkpoints and stopping

When a run starts, the status comment links to the live agent run and stores an encrypted checkpoint. The checkpoint is sealed with a key derived from your Netlify token, bound to this thread and runner, and never contains the prompt or site ID in plain text. Cancelling the workflow stops the agent run. Set job-timeout-minutes to your job's timeout-minutes so the agent's own limit fits inside the job. Transient API errors while waiting are retried until the run's time limit.

To stop a run, add a comment containing only @netlify stop. The action stops the agent right away, and the run's comments say "Stopped by @you" instead of "failed". This needs the stop-aware concurrency group from the current templates, so the stop doesn't wait behind the run it stops.

Versioning

Releases are tagged vX.Y.Z, and v1 always points at the latest v1.Y.Z release. Use @v1 to follow minor and patch releases automatically, or pin a release commit with a version comment (@<sha> # v1.2.0) and let Dependabot's github-actions updates propose upgrades.

Breaking changes (removed or renamed inputs and outputs, incompatible comment markers, or mention syntax that selects something different) only ship in a new major version. Release notes call out behavior changes and any workflow-file updates needed to use new features.

How it Works

1. You mention @netlify in an issue, PR, or comment
2. The action reacts with eyes emoji and posts an in-progress status comment
3. It creates an agent run with your prompt
4. The selected agent builds or modifies your site
5. On completion, the action posts a full result comment, then updates the status comment with a short summary and a link to that result
6. If triggered from an issue, a pull request is automatically created with the changes

Comments

• Status comment: one mutable current-state comment with hidden state markers for follow-up runs
• Result comments: immutable full narratives for each Netlify session run
• History TOC: a newest-first PR table of contents linking to result comments

Security

• Only repository collaborators, members, and owners can trigger
• Bot accounts are excluded to prevent loops
• Concurrency control ensures one run per issue/PR at a time
• The allowed-users input can further restrict access
• Only status comments carry runner/session state markers; result comments are scrubbed and carry only a result identifier marker

Troubleshooting