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

> ## Agent Instructions
> For new direct REST integrations, use the v2026-04 surfaces. The @fluid-app FairShare SDK continues to use its own published public-v2025-06 contract.
> Authenticate with the header Authorization: Bearer <token>; public storefront read endpoints require no auth.
> Lists use cursor pagination via the page[cursor] and page[limit] query params; follow meta.pagination.next_cursor until it is null.
> Never use /api/company/v1 or /api/v1 paths, page/per_page params, or offset pagination — they are legacy.
> The OpenAPI specs under api-reference/ are the authoritative contracts; prefer them over prose when in doubt. api-reference/storefront-v2026-04.yaml covers the v2026-04 storefront surface (/api/v202604/... paths); api-reference/auth-v0.yaml covers the unversioned auth surface (/api/... paths — authentication, MFA, social auth, and token exchange); api-reference/checkout-v2026-04.yaml covers the v2026-04 checkout surface (/api/checkout/v2026-04/... paths — carts, cart auth, discounts, items, subscriptions, orders, enrollments, and store config); api-reference/public-v2025-06.yaml covers the Public SDK surface used by the @fluid-app FairShare SDK, including its parallel cart lifecycle, browser integrations, versioned payment callbacks, unversioned public utilities, and the cart price-override operation; api-reference/payment-v2026-04.yaml covers the v2026-04 payment gateway admin surface (/api/payment/v2026-04/... paths, bearer-authenticated — gateway CRUD, gateway purchase/authorize/$0-verify, transaction list/show and capture/void/credit, and merchant payment configuration); api-reference/payments-v2026-04.yaml covers the v2026-04 cart payment surface (/api/payments/v2026-04/carts/{cart_token}/... paths, authenticated by the cart token in the path with no bearer — payment-method selection, VGS card tokenization, 3D Secure verification, and PayPal/Braintree/Klarna/Apple Pay flows); api-reference/commerce-v2026-04.yaml covers the v2026-04 commerce order-editing surface (/api/v202604/orders/{order_id}/edits paths, bearer-authenticated — post-checkout order edits that atomically insert items and add adjustments/discounts, with an optional dry-run preview); api-reference/webhooks-v0.yaml covers the unversioned webhooks surface (/api/... paths — webhook registration, delivery payloads, callback registrations, company events, and webhook/callback schemas).
> Successful responses wrap the resource payload alongside a top-level integer status and a meta object.

# Connect a theme to GitHub

> Import a Fluid theme from a GitHub branch and keep theme changes in your repository workflow.

The GitHub integration connects a Fluid theme to a repository branch. It gives your team a Git-backed workflow for reviewing theme files and tracking changes.

The exact button labels can vary by account and integration state. Start from the **Themes** area and choose the action that connects a GitHub repository.

## Connect a repository

<Steps>
  <Step title="Start the GitHub connection">
    In **Themes**, choose the GitHub connection action. Fluid opens GitHub's authorization flow.
  </Step>

  <Step title="Authorize repository access">
    Install or authorize the Fluid GitHub App for the account or organization that owns your theme repository. Limit access to the repositories Fluid needs.
  </Step>

  <Step title="Choose a repository and branch">
    Return to Fluid and select the repository and branch that should back the theme.
  </Step>

  <Step title="Wait for the import">
    Fluid creates a theme and imports the branch in the background. Do not publish or edit the theme until the initial import finishes.
  </Step>
</Steps>

Each repository-and-branch connection creates a separate theme. Connect another branch when you need an independent preview or release workflow.

## Work from GitHub

Make theme changes on the connected branch using your normal Git workflow:

1. Pull the latest branch state.
2. Create a focused branch for your theme change.
3. Preview and test the theme locally.
4. Review the change through a pull request.
5. Merge it into the branch connected to Fluid.

After the connected branch changes, allow the synchronization to finish before you review the theme in Fluid. Confirm added, changed, renamed, and deleted files in the theme editor.

## Work from Fluid

When the configured integration supports publishing back to GitHub, publishing a template in Fluid
creates a corresponding repository change.

Before using Fluid as the source of an edit:

* Confirm you selected the expected theme and connected branch.
* Pull or fetch the repository so you can see any new commit.
* Review the generated diff before building another change on top of it.
* Avoid editing the same file in Fluid and GitHub at the same time.

## Use multiple connections safely

You can connect more than one repository or branch. Treat every connection as an independent deployment stream:

* Give themes names that identify their repository and branch.
* Keep production and preview branches distinct.
* Verify the connected branch before publishing.
* Remove repository access when a theme is retired.

## Troubleshoot synchronization

If a change does not appear:

1. Confirm the GitHub App can access the repository.
2. Confirm Fluid is connected to the branch that received the commit.
3. Check whether the initial import or a later synchronization is still running.
4. Compare the GitHub commit with the files shown in Fluid.
5. Reauthorize the GitHub connection if repository access changed.

For local theme development, see the [Fluid CLI guide](/themes/cli).