# Publish Schemas to GraphOS using Rover

This guide covers how to publish schemas using the Rover CLI. Consult the [Platform API guide](https://www.apollographql.com/docs/graphos/platform/schema-management/delivery/publishing/platform-api) to learn how to use the API for publication.

## Prerequisites

1. [Install the Rover CLI](https://www.apollographql.com/docs/rover/getting-started/).
2. [Authenticate Rover](https://www.apollographql.com/docs/rover/configuring/#authenticating-with-graphos) 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:

1. 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](https://studio.apollographql.com/?referrer=docs-content).

2. 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.

3. 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.

   ```bash title=Provide a local .graphql path
    rover subgraph publish my-graph@my-variant \
      --name locations \
      --routing-url https://flyby-locations-sub.herokuapp.com/ \
      --schema ./schema.graphql
   ```

   ```bash title=Provide an introspection result via stdin
   rover 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:

1. 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, or
   * Perform an introspection query on your running server to fetch the schema

2. Run the `rover graph publish` command, providing your schema in one of the ways shown:

   ```bash title=Provide a local .graphql file path
    rover graph publish my-graph@my-variant \
      --schema ./schema.graphql
   ```

   ```bash title=Provide an introspection result via stdin
   rover 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.

Use a [subgraph API key](https://www.apollographql.com/docs/graphos/platform/access-management/api-keys/subgraph-api-keys) for authentication.

Here's a sample continuous delivery configuration for schema publishing in CircleCI:

```yaml
version: 2

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

    steps:
      - checkout

      - run: npm install

      - run:
          name: Install Rover
          # highlight-start
          command: |
            # Download and install Rover
            # This is pinned to a specific version for predictability in CI
            curl -sSL https://rover.apollo.dev/nix/v0.8.1 | sh

            # This allows the PATH changes to persist to the next `run` step
            echo 'export PATH=$HOME/.rover/bin:$PATH' >> $BASH_ENV
          # highlight-end

      # 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

      # highlight-start
      # When running on the 'main' branch, push the latest version
      # of the schema to GraphOS.
      - run: |
          if [ "${CIRCLE_BRANCH}" == "main" ]; then
            rover subgraph publish my-graph@my-variant \
              --schema ./schema.graphql \
              --name locations \
              --routing-url https://products.example.com
          fi
      # highlight-end
```

## Additional resources

* [Rover `subgraph` commands](https://www.apollographql.com/docs/rover/commands/subgraphs) (for supergraphs)
* [Rover `graph` commands](https://www.apollographql.com/docs/rover/commands/graphs) (for monographs)
* [Rover CI/CD guide](https://www.apollographql.com/docs/rover/ci-cd/)