---
title: How Thally works
description: Understand the customer-facing workflow for publishing documentation and keeping it aligned with product changes.
url: https://pr-14-a9c4e9fe1b6c.thally.app/architecture
---

# How Thally works

Understand the customer-facing workflow for publishing documentation and keeping it aligned with product changes.

Thally keeps your documentation in Git, publishes reviewed changes, and helps
your team find pages that may need an update when the product changes.

You can use the open-source documentation site by itself or connect it to
Thally Cloud for managed publishing, Product Knowledge, and Track.

## Publish from one source

Your MDX pages, navigation, assets, and configuration stay in your Git
repository. That repository remains the source your team reviews and owns.

#### Create or connect a documentation repository

    Start with a new Thally project or connect an existing compatible project.

#### Review changes in GitHub

    Authors and automation use the same branch and pull-request workflow. A
    generated update never approves or merges itself.

#### Validate before publishing

    Thally checks the documentation before a managed publish becomes live. If a
    publish fails, the current live version stays available.

#### Serve people and agents from the same content

    The reviewed source powers the website, search, Markdown, structured
    endpoints, and agent discovery files.

Managed hosting also gives each documentation pull request a preview. Owners
and editors can restore a previously successful publish from deployment
history without rewriting Git history.

## Keep documentation aligned with the product

Track adds an optional review workflow for teams that connect product
repositories. Site owners can run it for trusted, same-repository, non-draft
pull request updates, merged changes, UTC schedules, or a combination of those
triggers.

```text
configured product change
      ↓
independent primary-docs and connected-surface runs
      ↓
ready-for-review pull request or no change per destination
      ↓
human review and merge
      ↓
each repository's publishing workflow
```

Track reads the exact source revision and starts a separate run for the primary
documentation repository and every enabled Knowledge surface. Each run uses
its saved branch, root, and path scopes, prepares the customer-facing update it
finds necessary, and checks the proposed result. If a destination needs no
change, its run finishes without opening a pull request.

When Track does propose an update, it opens a normal ready-for-review pull
request in that destination. Your team can correct, merge, or close it. Track
never merges the proposal itself. Only the primary documentation repository
receives Thally-managed previews and releases; connected destinations keep
their own preview and publishing workflows. See the
[Knowledge-surface contract](/guides/knowledge-surfaces).

## Know the ownership boundary

| You own                                   | Thally provides                                  |
| ----------------------------------------- | ------------------------------------------------ |
| Documentation content and Git history     | The open-source documentation site               |
| Product repositories and review decisions | Validation, previews, and managed publishing     |
| Hosting when you choose to self-host      | Optional Product Knowledge and Track workflows   |
| Whether a proposed update publishes       | Evidence and a reviewable documentation proposal |

Connecting Thally Cloud does not move ownership of your documentation out of
Git. You can continue to self-host the site, and disconnecting an optional
service does not remove your authored content or history.

## Customer-facing safeguards

- Product Knowledge does not run code from a connected product repository.
- Track proposes changes through pull requests and never merges its own work.
- Pull-request previews cannot publish to production.
- A failed managed publish leaves the current site online.
- Repository access is limited to the repositories you select through the
  GitHub App installation.

## Choose your next task

- [Publish your first site](/quickstart)
- [Manage sites with Thally Cloud](/guides/thally-cloud)
- [Review Product Knowledge](/guides/product-knowledge)
- [Set up Thally Track](/guides/thally-track)
- [Operate managed hosting](/guides/managed-hosting)