---
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-7-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. It never
auto-merges its pull requests.

## 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. Future matching pull requests can create product snapshots
    and impact runs 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: Prepare and validate the documentation update
        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.

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

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