Publish Schemas to GraphOS using Rover
Use the Rover CLI to publish schemas as part of your CI/CD pipeline
This guide covers how to publish schemas using the Rover CLI. Consult the Platform API guide to learn how to use the API for publication.
Prerequisites
Authenticate Rover with GraphOS.
Publish subgraph schemas
When working with supergraphs, you individually publish each subgraph's schema to GraphOS. Every time you publish a subgraph schema, GraphOS attempts to compose all latest versions of your subgraph schemas into a single supergraph schema.
To publish a subgraph schema to GraphOS:
Identify the name of the subgraph you're publishing to. You can view the names of your existing subgraphs from your variant's Subgraphs page in GraphOS Studio.
If you're publishing a subgraph for the first time, also obtain the routing URL of that subgraph. This is the URL that your router will use to communicate with the subgraph.
If GraphOS already knows your subgraph's routing URL, you don't need to provide this value unless you're changing it.
Run the
rover subgraph publish
command and provide it your subgraph's schema either via a path to a local file or via an introspection.BashProvide a local .graphql pathrover subgraph publish my-graph@my-variant \ --name locations \ --routing-url https://flyby-locations-sub.herokuapp.com/ \ --schema ./schema.graphql
BashProvide an introspection result via stdinrover subgraph introspect http://localhost:4000 | \ rover subgraph publish my-graph@my-variant \ --name locations \ --routing-url https://flyby-locations-sub.herokuapp.com/ \ --schema -
Publish monograph schemas
For monographs, the publication process is simpler:
Decide how you'll provide your server's schema to Rover. You can either:
Use a
.gql
or.graphql
file saved on your local machine, orPerform an introspection query on your running server to fetch the schema
Run the
rover graph publish
command, providing your schema in one of the ways shown:BashProvide a local .graphql file pathrover graph publish my-graph@my-variant \ --schema ./schema.graphql
BashProvide an introspection result via stdinrover graph introspect http://localhost:4000 | \ rover graph publish my-graph@my-variant --schema -
As shown, the first positional argument you provide
rover graph publish
is a graph ref, a string that specifies a particular variant of a particular graph in GraphOS.
Publish with continuous delivery
To get the most out of GraphOS, you should publish each update to any production schema as soon as it occurs. Consequently, schema publishing should be part of your continuous delivery pipeline.
Here's a sample continuous delivery configuration for schema publishing in CircleCI:
1version: 2
2
3jobs:
4 build:
5 docker:
6 - image: circleci/node:8
7
8 steps:
9 - checkout
10
11 - run: npm install
12
13 - run:
14 name: Install Rover
15 command: |
16 # Download and install Rover
17 # This is pinned to a specific version for predictability in CI
18 curl -sSL https://rover.apollo.dev/nix/v0.8.1 | sh
19
20 # This allows the PATH changes to persist to the next `run` step
21 echo 'export PATH=$HOME/.rover/bin:$PATH' >> $BASH_ENV
22
23 # Start the GraphQL server. If a different command is used to
24 # start the server, use it in place of `npm start` here.
25 - run:
26 name: Starting server
27 command: npm start
28 background: true
29
30 # make sure the server has enough time to start up before running
31 # commands against it
32 - run: sleep 5
33
34 # When running on the 'main' branch, push the latest version
35 # of the schema to GraphOS.
36 - run: |
37 if [ "${CIRCLE_BRANCH}" == "main" ]; then
38 rover subgraph publish my-graph@my-variant \
39 --schema ./schema.graphql \
40 --name locations \
41 --routing-url https://products.example.com
42 fi
Additional resources
Rover
subgraph
commands (for supergraphs)Rover
graph
commands (for monographs)