# Custom workflows

> 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.

```yaml
- uses: pullfrog/pullfrog@v0
  with:
    prompt: Summarize the commits since the last tag as a changelog.
```

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](https://pullfrog.com/docs/automations) do not expose, such as specific labels, paths, schedules or manual dispatch inputs.

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

## 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](https://pullfrog.com/docs/custom-workflows#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](https://pullfrog.com/docs/security#code-pushes) setting. |
| `shell` | `disabled`, `restricted` or `enabled`. Can only make the repository's [shell setting](https://pullfrog.com/docs/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()`.

`.github/workflows/release.yml`:

```yaml
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. Set `permissions:` on the job, so other jobs do not inherit them.

## Run tracking

Pullfrog records every run of these workflows from the same OIDC token. On a personal account or the Organization plan, 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.
