> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pullfrog.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CI integration

> Run a Pullfrog agent as one step in any GitHub Actions workflow and pass its result to the next step.

The `pullfrog/pullfrog@v0` action behind every Pullfrog automation also works as a step in your own workflows. Run an agent inside a release, deploy or scheduled job, and hand its output to the steps that follow.

<Note>
  PR review, issue enrichment, addressing reviews and fixing CI are built-in features you turn on in the [console](https://pullfrog.com/console). Write a custom workflow only for behavior the console does not cover.
</Note>

A custom workflow fits when you want to:

* Run an agent as **one step** in an existing pipeline, such as a release, deploy, nightly job or scheduled audit.
* Feed the agent's result into **later steps**: a deploy, a Slack message, a `git tag` or a release body.
* Trigger on conditions the automations do not expose, such as specific labels, paths, schedules or manual dispatch inputs.
* Keep the orchestration in version control next to your other workflows.

## Inputs

Set exactly one of `prompt` or `prompt_file`. Every other input is optional.

| Input | Description |
| - | - |
| `prompt` | The task for the agent. |
| `prompt_file` | Path, relative to the workspace, of a file whose contents are the prompt. |
| `output_schema` | JSON Schema for the agent's result. See [Capturing agent output](#capturing-agent-output). |
| `model` | Model slug, such as `anthropic/claude-opus`, or a models.dev specifier. Overrides the repository setting. |
| `effort` | Reasoning effort: `low`, `medium`, `high`, `xhigh`, `max`, or a number from `0` to `1`. Overrides the repository setting. |
| `timeout` | Maximum run time, such as `10m` or `1h30m`. Defaults to `1h`. |
| `push` | `disabled`, `restricted` or `enabled`. Overrides the repository's [code pushes](/security#code-pushes) setting. |
| `shell` | `disabled`, `restricted` or `enabled`. Can only make the repository's [shell setting](/security#shell-environment-scrubbing) stricter. |
| `progress_comments` | `disabled` stops live task-list updates to the progress comment. |
| `debug` | `enabled` raises the run's log level. |
| `cwd` | Working directory for the agent. Defaults to the workspace root. |

## Capturing agent output

The action has one output, `result`, for later steps to read. The agent sets it by calling the `set_output` tool with whatever you asked for: a string, a JSON object or a file path.

| `output_schema` | Behavior |
| - | - |
| Omitted | `result` is optional. The agent may set any string or JSON value. |
| Set to a JSON Schema | `result` is required and validated against the schema. The step fails if the agent does not set it or the value does not conform. |

## Example: release changelog

This release workflow has an agent draft the changelog from the commits since the last tag. The schema makes `result` a typed object, so the release step reads its fields with `fromJSON()`. The version bump, build and publish stay in your workflow.

```yaml theme={null}
# .github/workflows/release.yml
name: Release

on:
  workflow_dispatch:
    inputs:
      version:
        description: Semver to release
        required: true

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write # for the release step
      id-token: write # for Pullfrog
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - name: Draft changelog
        id: changelog
        uses: pullfrog/pullfrog@v0
        with:
          prompt: |
            Read the commits between the latest tag and HEAD (use `git log`).
            Write a concise, user-facing changelog grouped by Added / Changed /
            Fixed. Skip internal refactors and chores. Output JSON only —
            no prose outside the schema.
          output_schema: |
            {
              "type": "object",
              "required": ["title", "markdown"],
              "properties": {
                "title": { "type": "string" },
                "markdown": { "type": "string" }
              }
            }

      - name: Build & publish
        run: pnpm release ${{ inputs.version }}

      # reads the agent's output as typed fields
      - name: Create GitHub release
        uses: softprops/action-gh-release@v2
        with:
          tag_name: v${{ inputs.version }}
          name: ${{ fromJSON(steps.changelog.outputs.result).title }}
          body: ${{ fromJSON(steps.changelog.outputs.result).markdown }}
```

## Required permissions

The action mints its own short-lived GitHub App installation tokens through OIDC for everything it does on GitHub: pushing branches, posting comments, creating reviews and updating issues. It does not use your workflow's `GITHUB_TOKEN` for any of it.

The action needs only two permissions from your workflow:

| Permission | Why |
| - | - |
| `id-token: write` | Lets the action mint installation tokens through OIDC |
| `contents: read` | Lets `actions/checkout` clone the repository |

Extra scopes, such as `contents: write` for a step that pushes tags, go to the workflow's `GITHUB_TOKEN` for the other steps in the job; the Pullfrog action does not use them. Set `permissions:` on the job rather than the workflow, so other jobs do not inherit them.

## Run tracking

Pullfrog records every run of these workflows from the same OIDC token, so on Pro its token usage, cost and model appear on the console's analytics page as **Uncategorized** runs. Failure emails and run diagnosis cover only the runs Pullfrog dispatches itself.

A workflow that runs the action more than once, such as a matrix or one review per model, is still one run. Each Pullfrog step's usage and model count separately, and the run shows the totals. The run's status follows the Pullfrog steps' own results, so a gate job that fails elsewhere in the workflow does not mark the run failed.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.