---
title: Turn product changes into docs pull requests
description: Connect Product sources and Knowledge surfaces, then let Thally prepare evidence-backed documentation pull requests for human review.
url: https://pr-8-a9c4e9fe1b6c.thally.app/guides/thally-track
---

# Turn product changes into docs pull requests

Connect Product sources and Knowledge surfaces, then let Thally prepare evidence-backed documentation pull requests for human review.

Connect the repositories that describe your product. When a matching product
pull request merges, Thally Track finds affected documentation and prepares a
pull request for your team to review.

Track is a Thally Cloud service. It connects verified GitHub changes to the
Product Knowledge Graph, uses evidence-backed impact analysis to select the
documentation that may need work, and prepares a draft for your team. Track is
automatic by default: you do not need to configure an automation mode, a
per-run credit budget, or whether it may create pages. It never auto-merges its
pull requests.

> **Note:**
  Track drafts consequential updates automatically, may update existing pages or
  create new ones, uses the workspace's available AI credits for the run, and
  always stops at a GitHub pull request for human review. Unused reserved
  credits are returned when the run settles.

## Product sources and Knowledge surfaces

These connections have different jobs:

| Connection                  | What it contributes                                     | What Thally may do                                                                                       |
| --------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| **Product source**          | Product code and specifications that Track observes     | Read an exact revision, extract evidence, and calculate documentation impact                             |
| **Primary docs repository** | The documentation site connected to the Thally site     | Open a review-gated docs pull request; publish the exact merged revision when managed hosting is enabled |
| **Knowledge surface**       | Another explicitly connected Markdown or MDX repository | Open a scoped draft pull request; never deploy the repository                                            |

The primary docs repository cannot also be one of its own Product sources. That
hard boundary prevents a documentation update from looking like a new product
change and creating a loop.

## Connect Product sources

You can connect Product sources while creating a site or later from the site's
settings.

#### Open Product sources

    In Thally Cloud, open the site and select **Track**. Owners and editors can
    manage the connected repositories from that page.

#### Authorize the repository

    Install or update the Thally GitHub App for the account that owns the
    product repository.

#### Choose what Track watches

    Select the repository and base branch. Add path filters when only part of a
    monorepo represents the product surface Track should observe. You can also
    choose the destination tab and group where new primary-documentation pages
    from this source should appear.

#### Save the Product source

    Track is ready. No policy setup is required. Future matching pull requests
    can create product snapshots, impact runs, and reviewable documentation pull
    requests for this site.

Each Product source keeps its own repository, branch, optional path filters,
destination tab and group placement, and enabled state. A site can connect
multiple sources so an API, SDK, and web application can contribute to the
same product model without sharing mutable repository state.

## Connect Knowledge surfaces

Use Knowledge surfaces when a product change may also require an update in a
separate Markdown or MDX repository—for example SDK guides, tutorials, or
release notes.

When Knowledge surfaces are available for the workspace, open **Site settings
→ Knowledge surfaces**, choose a repository that the Thally GitHub App can
access, and confirm:

- the base branch;
- the repository root Track may inspect;
- the exact Markdown or MDX paths Track may change;
- the validation policy; and
- any administrator instructions for that destination.

Pausing or removing a surface affects future product changes. Existing pull
requests remain available for your team to review or close.

> **Note:**
  Thally may open a scoped draft pull request in the connected repository, but
  it never runs that repository's dependencies, scripts, generators, or
  workflows and never deploys it. The repository's own team reviews and ships
  the change through its normal process.

## What triggers Track

Track supports two explicit modes:

### Merged product changes

When a pull request merges into a connected Product source's configured base
branch, Track evaluates the exact merged revision.

### Preview product changes

An explicitly labelled preview pull request can ask Track to prepare docs
before the product change merges. Preview runs remain separate from merged
production runs, so an unmerged revision cannot silently become production
product knowledge. Preview runs do not fan out to connected Knowledge
surfaces; those destinations are updated only from merged product changes.

## How a Track run works

{`
sequenceDiagram
    participant Product as Product repository
    participant Knowledge as Product Knowledge
    participant Track as Track
    participant Docs as Documentation repository
    participant Person as Reviewer

    Product->>Knowledge: A connected product change merges
    Knowledge->>Knowledge: Find affected documentation with evidence
    alt No tracked impact
        Knowledge-->>Product: Finish without a pull request
    else Documentation may need work
        Knowledge->>Track: Provide the affected pages and evidence
        Track->>Track: Plan existing-page and new-page work
        Track->>Track: Draft and validate in an isolated sandbox
        Track->>Docs: Open a review-gated pull request
        Person->>Docs: Review, edit, merge, or reject
    end

`}

Track compares the product revision with the earlier version and gathers the
evidence behind each suggested documentation page. A text or meaning-based
match can suggest a page, but inspectable product evidence is what makes the
suggestion useful to a reviewer.

The run advances through seven durable stages: merge received, evidence
captured, changes analyzed, docs planned, draft created, draft validated, and
ready for review. The Track page keeps that state even when a worker retries or
the browser closes.

## Existing pages, new pages, and larger changes

Track first looks for existing documentation that should change. When the
evidence describes a new concept with no suitable page, Track may create an MDX
page inside the configured documentation root. It also updates navigation so
the page appears in the Product source's selected tab and group. The new page
and navigation change arrive in the same reviewable pull request.

A product pull request may introduce an entire feature rather than one small
fact. Track can plan changes across guides, API or SDK documentation, examples,
release notes, and other connected Markdown or MDX surfaces when those
destinations are explicitly connected. Source diffs are analyzed as bounded
evidence instead of being rejected merely for being large. Output is still
bounded by the current writer: a primary-docs plan can change up to 64 files
and 1 MB, and a connected surface may have a smaller limit. When work exceeds a
destination's current capability, Track records an explicit oversized outcome
rather than publishing a partial or silently truncated update.

## Review and publication

Track's output is a normal GitHub pull request. Reviewers can change, accept,
or reject it. The activity record keeps the source revision and evidence that
led to the proposal.

For the primary docs repository, merging the pull request publishes through
the same path as any other reviewed documentation change. The update becomes
live only after the resulting release passes validation.

Connected Knowledge surfaces stop at the merged draft pull request. Thally
does not publish or otherwise operate the connected repository.

## Retries and failures

A failed Track run cannot publish or change live documentation. Its stage and
diagnostic remain attached to the run. Choosing **Retry** creates a new run from
the original evidence and current destination revision; it does not erase or
rewrite the earlier attempt. This preserves an audit trail and prevents a
delayed worker from turning an old attempt into a second pull request.

## What to expect

- A product change with no documented impact completes without creating a pull
  request.
- Every suggestion links back to product evidence you can inspect.
- Track edits only the documentation destination and paths you allowed.
- Connected product repositories are read without running their dependencies
  or scripts.
- Drafting happens in an isolated, disposable sandbox with no permission to
  publish the result.
- A failed run cannot change the live documentation site.
- You always review and merge the resulting pull request yourself.

## Self-hosted authoring tools

The public `thally` CLI, docs agent, and MCP server can also help a developer
prepare documentation locally. Those self-managed authoring tools are separate
from the Cloud Track workflow described here.

## Next steps

- [See how Thally works](/architecture) for the customer-facing publishing and
  update workflow.
- [Understand the product-change pipeline](/product-change-pipeline).
- [Use the docs agent locally](/guides/docs-agent).
- [Connect an MCP client](/guides/mcp-server).
- [Review provenance and freshness](/guides/provenance).