Custom workflows
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.
- 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 tagor a release body. - Trigger on conditions the 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 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. |
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 setting. |
shell | disabled, restricted or enabled. Can only make the repository's shell setting 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().
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.

