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

InputDescription
promptThe task for the agent.
prompt_filePath, relative to the workspace, of a file whose contents are the prompt.
output_schemaJSON Schema for the agent's result. See Capturing agent output.
modelModel slug, such as anthropic/claude-opus, or a models.dev specifier. Overrides the repository setting.
effortReasoning effort: low, medium, high, xhigh, max, or a number from 0 to 1. Overrides the repository setting.
timeoutMaximum run time, such as 10m or 1h30m. Defaults to 1h.
pushdisabled, restricted or enabled. Overrides the repository's code pushes setting.
shelldisabled, restricted or enabled. Can only make the repository's shell setting stricter.
progress_commentsdisabled stops live task-list updates to the progress comment.
debugenabled raises the run's log level.
cwdWorking 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_schemaBehavior
Omittedresult is optional. The agent may set any string or JSON value.
Set to a JSON Schemaresult 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
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:

PermissionWhy
id-token: writeLets the action mint installation tokens through OIDC
contents: readLets 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.
© 2026 Pullfrog, Inc.

On this page