Each FRAGMENT Workspace is an isolated environment. Create a separate Workspace for each stage in your release process. For example, development, staging, and production.

API Client credentials are scoped to a single Workspace. Provide the credentials as secrets to fragment login in your CI pipeline:

fragment login \
  --client-id ${{ vars.FRAGMENT_CLIENT_ID }} \
  --client-secret ${{ secrets.FRAGMENT_CLIENT_SECRET }} \
  --api-url ${{ vars.FRAGMENT_API_URL }} \
  --oauth-url ${{ vars.FRAGMENT_OAUTH_URL }} \
  --oauth-scope ${{ vars.FRAGMENT_OAUTH_SCOPE }}

Run fragment workspace to verify the Workspace the CLI is authenticated to.

Check your Schema file into source control to keep your application code in sync with your Schema. A common pattern is to regenerate the SDK, then check that the output of git diff is empty.

1. Generate GraphQL queries from your Schema:

   fragment gen-graphql \
     --path=my-schema.jsonc \
     --output=queries.graphql

   Copy

2. Run your language's codegen tool to produce the SDK client:

   

   TypeScript

   ↓

   Copy

   fragment gen-graphql \
     --path=my-schema.jsonc \
     --output=queries.graphql &&\
   npm install --save @fragment-dev/node-client &&\
   npx fragment-node-client-codegen \
     --input=queries.graphql \
     --outputFilename=fragment-client.ts

   Copy

3. Fail the build if the generated SDK is out of date:

   fragment gen-graphql \
     --path=my-schema.jsonc \
     --output=queries.graphql &&\
   npx fragment-node-client-codegen \
     --input=queries.graphql \
     --outputFilename=fragment-client.ts &&\
   git diff --exit-code

   Copy

Treat your Schema file the same way you treat a database migration: it lives in source control, and CI applies it to the target Workspace on every deploy.

Validate the Schema on pull requests:

fragment verify-schema --path my-schema.jsonc

Store the Schema to your Workspace at deploy time:

fragment store-schema --path my-schema.jsonc

Storing a Schema is idempotent. The Schema's key is its idempotency key. FRAGMENT enforces changes to your Schema are backwards compatible so you don't break your application.

store-schema rejects a backwards-incompatible change, such as removing an account, once the Schema has Ledgers. To catch the change on the pull request, run verify-schema --against with a previous version of the Schema. To compare against the Schema in your Workspace, download it with get-schema:

fragment get-schema \
  --key my-schema \
  --output deployed-schema.jsonc &&\
fragment verify-schema \
  --path my-schema.jsonc \
  --against deployed-schema.jsonc

To compare against your base branch instead, write the branch's copy of the Schema with git show. This needs no API credentials. A shallow clone may not have the branch, so fetch it first:

git fetch --depth=1 origin main &&\
git show origin/main:my-schema.jsonc > base-schema.jsonc &&\
fragment verify-schema \
  --path my-schema.jsonc \
  --against base-schema.jsonc

--against enforces the rules even for a Schema with no Ledgers. A Schema you have not stored yet has no previous version, so skip the check until its first deploy.

Here's a GitHub Actions workflow that authenticates, verifies the Schema, checks that it is backwards compatible, generates the SDK, and stores the Schema on deploy:

- name: Use Node.js 20.x
  uses: actions/setup-node@8f152de45cc393bb48ce5d89d36b731f54556e65 # v4
  with:
    node-version: 20.x
- name: Install Fragment CLI
  run: |
    npm install -g @fragment-dev/cli
    echo "Fragment CLI installed"
- name: Authenticate with Fragment
  run: |
    fragment login \
      --client-id ${{ vars.FRAGMENT_CLIENT_ID }} \
      --client-secret ${{ secrets.FRAGMENT_CLIENT_SECRET }} \
      --api-url ${{ vars.FRAGMENT_API_URL }} \
      --oauth-url ${{ vars.FRAGMENT_OAUTH_URL }} \
      --oauth-scope ${{ vars.FRAGMENT_OAUTH_SCOPE }}
- name: Verify Schema
  run: |
    fragment verify-schema --path my-schema.jsonc
- name: Check Schema backwards compatibility
  run: |
    fragment get-schema \
      --key my-schema \
      --output deployed-schema.jsonc
    fragment verify-schema \
      --path my-schema.jsonc \
      --against deployed-schema.jsonc
- name: Generate SDK
  run: |
    fragment gen-graphql \
      --path=my-schema.jsonc \
      --output=queries.graphql
    npm install --save @fragment-dev/node-client
    npx fragment-node-client-codegen \
      --input=queries.graphql \
      --outputFilename=fragment-client.ts
    git diff --exit-code
- name: Store Schema
  run: |
    fragment store-schema --path my-schema.jsonc