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

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.

<Note>
  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](https://pullfrog.com/console). Use this page when you need behavior the dashboard doesn't cover.
</Note>

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

```yaml theme={null}
# .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:

1. 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`.
2. 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.