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 (claude, codex, gemini)'
        required: false
        type: string
        default: 'codex'
  pull_request_target:
    types: [opened, synchronize, 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: netlify-${{ github.repository }}-${{ github.event.pull_request.number || github.event.issue.number || 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, or gemini 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.

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 }}"

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