---
title: Turn product changes into docs pull requests
description: Choose when Thally Track checks connected product repositories, follow each run, and review the documentation pull requests it prepares.
url: https://pr-14-a9c4e9fe1b6c.thally.app/guides/thally-track
---

# Turn product changes into docs pull requests

Choose when Thally Track checks connected product repositories, follow each run, and review the documentation pull requests it prepares.

Connect the repositories that describe your product, then choose when Thally
Track should check them. Track reads the exact product change, reviews it
against your current documentation, and opens a ready-for-review documentation
pull request when an update is needed.

Track never merges its own pull requests. Your documentation changes only
after your team reviews the proposal and merges it through your normal GitHub
workflow.

## Connect Product sources

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

#### Open Track

    In Thally Cloud, open the site and select **Track**. Owners and editors can
    manage the connected repositories from this 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 watch.

#### Choose your triggers

    Decide whether Track should run for pull request updates, merged changes,
    scheduled checks, or a combination of them. New sites keep the familiar
    merge-only behavior until you change this setting.

Each Product source keeps its own repository, branch, optional path filters,
and enabled state. A site can connect multiple sources, such as an API, SDK,
and web application, to the same documentation repository.

## Connect Knowledge surfaces

If customer-facing content also lives in a website, help center, or another
repository, connect it from **Site settings → Knowledge surfaces**. A Knowledge
surface is a Track destination, not a Product source or Product Knowledge
input.

Every qualifying source event creates an independent run for the primary
documentation repository and each enabled surface. Confirm the destination
repository, branch, optional root, and exact allowed paths. Track can open one
ready-for-review pull request per affected repository; a destination that is
already accurate finishes without one.

Read the [Knowledge-surface contract](/guides/knowledge-surfaces) for trigger
eligibility, path confinement, validation, preview limits, and publication
ownership.

## Choose when Track runs

Trigger settings apply to every enabled Product source for the site.

| Trigger                  | When Track checks                                                                                            | Use it when                                                              |
| ------------------------ | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
| **Pull request updates** | A trusted, same-repository, non-draft pull request opens, becomes ready for review, or receives a new commit | You want documentation ready to review before the product change merges  |
| **Merged changes**       | A pull request merges into the tracked branch                                                                | You want documentation work to begin only after the product change lands |
| **Scheduled checks**     | Daily, weekly, or at a custom interval between hourly and weekly                                             | You want Track to catch changes on a predictable UTC schedule            |

Pull request updates do not run from forks or untrusted contributor branches.
Track can evaluate those changes after they merge into the tracked branch.

You can enable pull request and merge triggers together. Track treats them as
separate review points, while duplicate deliveries for the same source revision
do not create duplicate work.

The first scheduled check establishes the current branch revision. Later
checks compare from that point. If the branch has not changed—or its complete
change falls outside your watched paths—Track finishes without opening a pull
request.

## Follow a run

The Track page keeps each destination run visible while you work elsewhere or
close the browser. A typical run moves through these steps:

1. **Change received**
2. **Preparing**
3. **Writing documentation**
4. **Checking the update**
5. **Opening pull request**

If Track needs another attempt, the activity shows **Retrying safely**. It also
shows elapsed time and a typical 15-minute target instead of an artificial
percentage. You can open the run details to see the source change, current
attempt, and final result.

## Understand the result

Every run ends with one of three customer-facing outcomes:

| Result               | What it means                                                                                               |
| -------------------- | ----------------------------------------------------------------------------------------------------------- |
| **Ready for review** | Track opened a normal GitHub pull request. Review, edit, merge, or close it through your usual workflow.    |
| **No docs change**   | Track checked the source revision and found no documentation update to propose. No pull request was opened. |
| **Needs attention**  | Track stopped before opening a pull request. Open the run details for the available next step.              |

Track may update existing pages, add a page when the product introduces a new
documented concept, or adjust navigation needed for the proposed content. The
pull request explains the update and reports whether the documentation checks
passed; it does not include raw build logs.

## Review and publish

For the site's primary documentation repository, a merged Track pull request
publishes through the same path as any other reviewed documentation change. The
update becomes live only after the resulting release passes validation.

Knowledge-surface pull requests use the destination repository's own checks,
previews, reviewers, and publishing workflow. Thally does not build or publish
those repositories. Managed Thally preview URLs apply only to the primary
documentation repository.

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

## What to expect

- Track runs only for Product sources and branches you connect. Optional watched
  paths decide which changes proceed to documentation writing; a run wholly
  outside those paths finishes as **No docs change**. During an admitted run,
  Track reviews the connected source and current documentation repository.
- A source change with no documentation impact creates no pull request.
- Each enabled Knowledge surface receives its own run and independent
  no-change or pull-request result.
- A failed or stopped run cannot change the live documentation site.
- Track opens ready-for-review pull requests and never merges them.
- Your Git repository remains the source of truth for every published change.

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