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.

Here's a GitHub Actions workflow that authenticates, verifies the Schema, 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: 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