> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pwnbook.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflows

> Automate the security review your team does manually today — match a PR's CODEOWNERS to an AI skill and/or a custom scan before it can merge.

<Note>Workflows is an Enterprise feature. See [Billing](/admin/billing) for plan details.</Note>

## Overview

Many security teams already have a manual gate: when a pull request touches code owned by a specific team, someone has to review it before it merges — a threat model, a manual code review, a checklist. Workflows automates that gate.

You define a **rule**: when a PR touches files owned by a given [CODEOWNERS](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) team, run one or more required checks before the PR can merge. Checks can be an **AI skill** (a reusable, agentic reviewer with access to your repo, tagged knowledge base pages, and recent scan findings) and/or a **custom scan script** (your own shell script, run in Pwnbook's scanner container against the PR). Results post back to GitHub as a named Check.

## How it works

<Steps>
  <Step title="A PR is opened or updated">
    Pwnbook's GitHub App receives the webhook and fetches the PR's changed files.
  </Step>

  <Step title="CODEOWNERS is matched against the changed files">
    Pwnbook fetches and parses your repo's `CODEOWNERS` file (checking `.github/CODEOWNERS`, `CODEOWNERS`, and `docs/CODEOWNERS`, in that order) and resolves which owner team(s) the changed files belong to, using the same last-match-wins precedence GitHub itself uses.
  </Step>

  <Step title="Matching rules run their actions">
    Any active rule whose owner match is among the resolved owners runs its ordered list of actions.
  </Step>

  <Step title="Results post back to GitHub">
    Pwnbook creates a named Check for the rule (visible on the PR's Checks tab), updates it to `in_progress`, then to `completed` with a pass/fail conclusion once every action finishes.
  </Step>
</Steps>

To actually block merges on this, add the rule's Check as a required status check in your repo's branch protection settings — Pwnbook doesn't configure branch protection for you.

## Setting up a rule

1. Open **Workflows** from the sidebar.
2. On the **Rules** tab, click **New Rule**.
3. Enter the **CODEOWNERS owner to match** (e.g. `@org/security`) — this must match a token that appears in your repo's `CODEOWNERS` file exactly.
4. Optionally scope the rule to a single **repository**; leave it blank to apply across every repo your GitHub App install covers.
5. Choose whether **all actions must pass** to unblock the PR, or any one passing is enough.
6. Add one or more actions — an **AI Skill** (pick from your skill library) or a **Custom Scan** (paste a shell script).
7. Save. The rule takes effect on the next matching PR event (open, synchronize, or reopen).

## AI skills

A skill is a named, reusable reviewer — not a single prompt-and-response, but a real agent with tool access, scoped to only what you explicitly allow:

<CardGroup cols={2}>
  <Card title="Repo file access" icon="folder-open">
    Read files and list directories in the PR's head checkout, if `repo_files` is enabled for the skill.
  </Card>

  <Card title="Knowledge base search" icon="book-open">
    Pull tagged pages from connected [Notion](/integrations/notion), [Confluence](/integrations/confluence), or [Coda](/integrations/coda) — scoped to only the tags you list for this skill.
  </Card>

  <Card title="Recent scan findings" icon="magnifying-glass-code">
    Look up recent scan results for the repository, if `scan_findings` is enabled.
  </Card>

  <Card title="PR comments" icon="comment">
    Post a comment on the pull request with its findings.
  </Card>
</CardGroup>

A skill only ever gets the tools its own configuration grants — a skill without knowledge-base access can't search your docs, and one without repo access can't read your code. The skill runs using your organization's own AI provider (bring-your-own-key — see [AI Providers](/admin/ai-providers)); Pwnbook doesn't supply or meter the model calls.

To create a skill: **Workflows → Skills → New Skill**. Write instructions the way you'd brief a human reviewer — what to look for, what to flag, what "pass" means for this kind of change.

## Custom scans

A custom scan is your own shell script, run against a fresh clone of the PR's head branch inside the same scanner container every other CLI-based Pwnbook scan uses. The script must write its verdict to `/work/result.json`:

```json theme={null}
{ "passed": true, "summary": "No policy violations found.", "findings": [] }
```

`findings` is optional. The script also has access to `PR_NUMBER`, `PR_HEAD_SHA`, and `REPO_FULL_NAME` as environment variables.

## Reviewing runs

The **Runs** tab shows every time a rule has fired: which PR, which owner team matched, the overall pass/fail status, and — per action — the AI skill's summary and full tool-call log, or the custom scan's raw log output. This is the audit trail for exactly what a skill read, searched, and posted on any given run.

## Requirements

* A GitHub App connected to at least one repository with a `CODEOWNERS` file
* An AI provider configured (for AI skill actions) — see [AI Providers](/admin/ai-providers)
* A knowledge base connector (for skills that use tagged page context) — see [Notion](/integrations/notion), [Confluence](/integrations/confluence), or [Coda](/integrations/coda)