Configuring Rover

Authenticating with GraphOS

1. Obtain an API key

All Rover commands that communicate with GraphOS require an API key to do so. GraphOS supports two types of API keys: personal API keys and graph API keys.

• On your local development machine, use a personal API key.
• In shared environments like CI, use a graph API key.

2. Provide the API key to Rover

You can provide your API key to Rover either via a Rover command (recommended for local development) or by setting an environment variable (recommended for automation and CI).

Via the auth command

You can provide your API key to Rover by running the following command:

1
rover config auth

This method is recommended for local development. If you have more than one API key you want to use with Rover, you can assign those keys to different configuration profiles.

With an environment variable

You can provide your API key to Rover by setting it as the value of the APOLLO_KEY environment variable. This method is recommended for automated environments such as CI.

Configuration profiles

You can create multiple configuration profiles in Rover. Each configuration profile has its own associated API key, so you can use different configuration profiles when interacting with different graphs.

To specify which configuration profile to use for a particular command, use the --profile flag:

1
rover graph check my-company@prod --profile work

If you don't specify a configuration profile for a command, Rover uses the default profile (named default).

To view all commands for working with configuration profiles, run the following command:

1
rover config --help

Logging

Rover supports the following levels of logging, in descending order of severity:

• error
• warn
• info
• debug
• trace

By default, Rover logs error, warn, and info messages. You can configure this behavior for a command by setting its minimum log level with the --log flag:

1
rover graph check my-graph@prod --schema ./schema.graphql --log debug

If Rover log messages are unhelpful or unclear, please leave us feedback in an issue on GitHub!

Configuring output

By default, Rover prints the main output of its commands to stdout in plaintext. It also prints a descriptor for that output to stderr if it thinks it's being operated by a human (it checks whether the terminal is TTY).

Every Rover command supports two options for configuring its output behavior:

• --format, for setting the output format (plain or json)
• --output, for writing a command's output to a file instead of stdout

JSON output

For more programmatic control over Rover's output, you can pass --format json to any command. Rover JSON output has the following minimal structure:

1
{
2
  "json_version": "1",
3
  "data": {
4
    "success": true
5
  },
6
  "error": null
7
}

1
{
2
  "json_version": "1",
3
  "data": {
4
    "success": false
5
  },
6
  "error": {
7
    "message": "An unknown error occurred.",
8
    "code": null
9
  }
10
}

As shown in error_example above, some Rover errors have a null error code. Despite this, your scripts should match on particular errors based on their code instead of their message (message strings are subject to change without bumping json_version).

If you frequently encounter un-coded errors, please submit an issue.

JSON output fields

Command-specific JSON output

Here's an example success output for rover subgraph publish:

1
{
2
  "json_version": "1",
3
  "data": {
4
    "api_schema_hash": "a1bc0d",
5
    "supergraph_was_updated": true,
6
    "subgraph_was_created": true,
7
    "subgraph_was_updated": true,
8
    "success": true
9
  },
10
  "error": null
11
}

And here's an example error output:

1
{
2
  "json_version": "1",
3
  "data": {
4
    "api_schema_hash": null,
5
    "subgraph_was_created": false,
6
    "subgraph_was_updated": true,
7
    "supergraph_was_updated": false,
8
    "success": true
9
  },
10
  "error": {
11
    "message": "Encountered 2 build errors while trying to build subgraph \"subgraph\" into supergraph \"name@current\".",
12
    "code": "E029",
13
    "details": {
14
      "build_errors": [
15
        {
16
          "message": "[Accounts] -> Things went really wrong",
17
          "code": "AN_ERROR_CODE",
18
          "type": "composition",
19
        },
20
        {
21
          "message": "[Films] -> Something else also went wrong",
22
          "code": null,
23
          "type": "composition"
24
        }
25
      ]
26
    }
27
  }
28
}

This particular error object includes details about what went wrong. Notice that even though errors occurred while executing this command, data.success is still true. That's because the errors are build errors associated with composing the supergraph schema. Although composition failed, the subgraph publish itself succeeded.

Example jq script

You can combine the --format json flag with the jq command line tool to create powerful custom workflows. For example, this gist demonstrates converting output from rover {sub}graph check my-graph --format json to Markdown.

Writing to a file

The --output option enables you to specify a file destination for writing a Rover command's output:

1
rover supergraph compose --output ./supergraph-schema.graphql --config ./supergraph.yaml

If the specified file already exists, Rover overwrites it.

Setting config storage location

Rover stores your configuration in a local file and uses it when making requests. By default, this file is stored in your operating system's default configuration directory, in a file named .sensitive.

You can override this file's location by setting the APOLLO_CONFIG_HOME environment variable. This can be useful for CI systems that don't give you access to default operating system directories.

1
# Stores config in ./myspecialconfig/rover.toml
2
APOLLO_CONFIG_HOME=./myspecialconfig/

Git context

Rover sends non-confidential information about your Git environment to GraphOS when you run a check or publish command. This information is displayed in relevant views of the Studio UI, making it easier to track down where schema changes were proposed or published:

This Git information includes:

• The remote URL of your Git repository (stripped of any usernames/passwords)
• The current commit's SHA
• The committer of the current SHA
• The current branch name

To see these values, run any check or publish command with the --log trace option.

Overriding

None of this information should be sensitive, but if you want to override these values, you can set the following environment variables:

• APOLLO_VCS_REMOTE_URL
• APOLLO_VCS_BRANCH
• APOLLO_VCS_COMMIT
• APOLLO_VCS_AUTHOR

Non-Git version control

If you use a version control system besides Git, you can use the environment variables described in Git context to set similar information relevant to your VCS tool,

Currently, only Git is fully supported by Apollo Studio.

Bypassing TLS/SSL validation

In some configurations (especially in internal networks), you might need Rover to communicate over encrypted channels (e.g., HTTPS) while avoiding strict digital certificate verifications that validate hostnames. You might even need to bypass digital certificate validation entirely.

This is not recommended and considered much less secure! However, for cases where it's necessary, you can use the following flags to configure how Rover validates HTTPS requests:

• The --insecure-accept-invalid-hostnames flag disables hostname validation. If hostname verification is not used, any valid certificate for any site is trusted for use from any other. This introduces a significant vulnerability to person-in-the-middle attacks.

• The --insecure-accept-invalid-certs flag disables certificate validation. If invalid certificates are trusted, any certificate for any site is trusted for use. This includes expired certificates. This introduces significant vulnerabilities, and should only be used as a last resort.

Increasing request timeouts

By default, Rover times out requests to the Apollo Studio API and your graph endpoints after 30 seconds. If you're executing a command that might take longer than 30 seconds to process, you can increase this timeout with the --client-timeout option:

1
rover subgraph check my-graph --validation-period 1m --client-timeout=60

Supported environment variables

You can configure Rover's behavior by setting the environment variables listed below.

If present, an environment variable's value takes precedence over all other methods of configuring the associated behavior.