/
Launch Apollo Studio

Schema registration via the Apollo CLI


If you're using an earlier version of Apollo Server or another GraphQL server that doesn't support schema reporting, you can register your schema via the Apollo CLI.

Do not use both schema reporting and the Apollo CLI to register schemas for the same graph. Doing so can cause you to register "no-op" schema changes that are semantically identical but cosmetically different. For example, automatic registration preserves a schema's comments and directives, whereas manual registration does not.

Registering a non-federated schema

  1. Install the Apollo CLI if you haven't yet.
  2. Decide how you'll provide your server's schema to the Apollo CLI. The CLI can either:

    • Use a .gql or .graphql file saved on your local machine, or
    • Perform an introspection query on your running server to fetch the schema
  3. Run the apollo service:push command, providing the following options (documented below):

    apollo service:push \
      --localSchemaFile=./schema.gql \ # (or --endpoint)
      --key=service:docs-example-graph:NYKgCqwfCyYPIm84WVXCdw
      --graph=docs-example-graph \
      --variant=local-development \
NameDescription
--endpoint

The URL of the running service to perform an introspection query on.

Provide this only if the CLI should obtain your schema via introspection.

--localSchemaFile

The path of the schema file to register.

Provide this only if the CLI should obtain your schema via a local file.

--key

The graph API key that the CLI should use to authenticate with the schema registry.

By default, the CLI uses the value of the APOLLO_KEY environment variable.

--graphThe name of your graph in Apollo Studio (e.g., docs-example-graph)
--variant

The variant of your graph to register the schema with.

The default value is current.

Registering federated schemas

See Setting up managed federation.

Registering with continuous delivery

To get the most out of Studio, you should register each update to your production schema as soon as it occurs. Consequently, schema registration should be part of your continuous delivery pipeline.

Here's a sample continuous delivery configuration for CLI-based schema registration using CircleCI:

version: 2

jobs:
  build:
    docker:
      - image: circleci/node:8

    steps:
      - checkout

      - run: npm install
      # CircleCI needs global installs to be sudo
      - run: sudo npm install --global apollo
      # Start the GraphQL server.  If a different command is used to
      # start the server, use it in place of `npm start` here.
      - run:
          name: Starting server
          command: npm start
          background: true

      # make sure the server has enough time to start up before running
      # commands against it
      - run: sleep 5

      # When running on the 'master' branch, push the latest version
      # of the schema to Apollo Studio.
      - run: |
          if [ "${CIRCLE_BRANCH}" == "master" ]; then            apollo service:push --variant=master          fi
Edit on GitHub