CI integration - Pullfrog

Pullfrog’s main entry point is the orchestration layer — webhooks, automations, and the dashboard. But the same pullfrog/pullfrog@v0 action that powers all of that is also a primitive you can drop into any GitHub Actions workflow when you want an agent step inside a larger pipeline. This page is for that second mode of use: agents as a building block in your existing CI, not as a replacement for it.

If you want auto PR review, issue enrichment, address-reviews, or autofix, don’t copy a workflow from here — those are first-class Pullfrog features configured in the console. Use this page when you need behavior the dashboard doesn’t cover.

When to reach for this

Drop the action into a custom workflow when you want to:

Run an agent as one step in an existing pipeline (release, deploy, nightly job, scheduled audit).
Capture the agent’s result and feed it into subsequent workflow steps (the next deploy step, a Slack notification, a git tag, a release body).
Trigger on conditions Pullfrog’s automations don’t expose directly (specific labels, paths, schedules, manual dispatch with custom inputs).
Keep the orchestration in version control alongside your other workflows.

Capturing agent output

The action exposes a result output that downstream steps can consume. Inside the agent run, the agent calls set_output exactly once with whatever you asked it to produce — a string, a structured JSON object, a generated artifact path, etc. You can leave the shape free-form, or pin it to a JSON Schema for stricter pipelines:

Action input	Behavior
(omit)	Output is optional. The agent may call `set_output` with any string or JSON-serializable value.
`output_schema: <JSON Schema>`	Output is required and validated against the schema. The action fails if the agent doesn’t call `set_output` or the value doesn’t conform.

This is the bridge between an agent’s “soft” reasoning and your workflow’s “hard” steps. The schema turns result into a contract you can rely on in subsequent jobs.

Example: agent-authored changelog in a release flow

A common pattern: you already have a release workflow that bumps the version, builds artifacts, tags, and publishes. You want an agent to draft the human-readable changelog from the commits since the last tag, then plug that into your existing release-notes step.

# .github/workflows/release.yml
name: Release

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

permissions:
  contents: write
  id-token: write

jobs:
  release:
    runs-on: ubuntu-latest
    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" }
              }
            }

      # downstream steps consume the agent's output as a contract
      - name: Build & publish
        run: pnpm release ${{ inputs.version }}

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

Two things to notice:

The output_schema makes result a typed contract. The release step downstream parses it with fromJSON() and uses fields directly — no string-mangling, no flaky grep.
The agent isn’t doing the release. It’s drafting one piece of it. Everything else — version bump, build, publish, tag — stays in your existing workflow.

Required permissions

The Pullfrog action mints its own short-lived GitHub App installation tokens via OIDC for every API call it makes — pushing branches, posting PR comments, creating reviews, updating issues. None of that uses your workflow’s GITHUB_TOKEN. The only two permissions the action ever needs from your workflow are:

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

If you grant additional scopes (e.g., contents: write to let other steps push tags, or pull-requests: write for downstream comment steps), they go to the workflow GITHUB_TOKEN. The Pullfrog action itself doesn’t read or use those — they only matter for other steps in the same job. Prefer scoping permissions: at the job level rather than the workflow level so other jobs don’t inherit them.

Tips

Keep prompts specific. The more concretely you describe the expected output, the more reliably downstream steps can rely on it. Pair specific prompts with output_schema for hard contracts.
One agent, one job step. Don’t chain agents — chain workflow steps. Each step gets a clear input and a clear output.
Reach for the dashboard first. If your workflow is “review every PR” or “enrich every issue,” configure it in the console instead. The action-as-primitive shines for bespoke pipeline steps the dashboard can’t express.

Documentation Index

​When to reach for this

​Capturing agent output

​Example: agent-authored changelog in a release flow

​Required permissions

​Tips

When to reach for this

Capturing agent output

Example: agent-authored changelog in a release flow

Required permissions

Tips