Cloud setup

1. Create a workspace

Sign up at app.usefragments.com and name your workspace. That single step creates the workspace and its first project, and starts a 14-day Pro trial — no credit card required. The onboarding wizard saves your progress as you go, so you can leave and resume at the same step, including after the GitHub redirect in the next section.

2. Connect GitHub

The wizard walks you through installing the Fragments GitHub App on your account or organization — or authorizing an installation that already exists. Grant the App access to the repository you want governed, then select that repository in the wizard. Fragments scans it to detect your components and token files; the scan feeds the next step, so nothing is typed in by hand.

3. Approve your contract

The contract is the list of canonical components (the ones people and agents should reuse instead of rebuilding) and the stylesheet files that define your tokens. The scan proposes both; you confirm which components are canonical and which files are your token sources. Everything the gates enforce later traces back to this approval — Fragments never invents vocabulary on your behalf.

The full authoring model — publishing vocabulary from a compiled component library, confirming detected components when you have no library, and what happens when the library changes — is covered in Set up your design contract.

4. Turn on governance in CI

Open your repository's Governance page and click Setup Governance (workspace owners and admins only). This requires the contract from the previous step — the gate refuses to install until there is an approved policy to enforce. One click then does three things in your repository:

First, it commits a GitHub Actions workflow at .github/workflows/fragments.yml on a new branch. The workflow runs the governance check on every push and pull request against your default branch. Second, it creates a repository secret named FRAGMENTS_API_KEY — a CI token scoped to this repository, which the workflow uses to report results back to Fragments Cloud. Third, it opens a pull request titled Enable Fragments Governance CI so the change lands through your normal review process.

Until that pull request merges, the Governance page shows the installation as pending and links to the open PR. If the App is missing a permission (Workflows or Secrets write access), the page names the exact permission to grant — approve the updated installation on GitHub and retry.

5. Merge the pull request

Review and merge the PR like any other change. The merge flips governance to active — no extra confirmation in the dashboard. From this point on, every push and pull request against your default branch runs the check and reports to Cloud.

What every pull request gets

The workflow runs the same command you can run locally:

npx @usefragments/cli check --ci

When the repository has no local configuration, the CLI fetches your cloud-managed policy automatically, so the rules CI enforces are exactly the ones you approved. On pull requests the check scans only what changed, keeping runs fast on large codebases.

Results land in three places. GitHub gets a Check Run with annotations on the exact lines that drifted, and inline review comments on the pull request itself. The Fragments dashboard gets the same findings with triage, bulk actions, and history, so trends survive individual PRs. To tune rule severity, scope rules off legacy paths, or add auditable suppressions, see the configuration reference.

If the installation breaks

Fragments watches its own footprint. A push that edits or deletes the workflow file flips governance from active to broken, and the Governance page names what changed and how to repair it — usually restoring the file or re-running the one-click installation, which supersedes the old one safely. Nothing silently stops enforcing.

For the wider model behind all of this — rules, error codes, and the surfaces that enforce them — start at Governance.