Configuring Rover

Authenticating with GraphOS

All Rover commands that communicate with GraphOS need a credential. Which one to use depends on where Rover runs.

Choosing a credential

Learn how to obtain an API key.

Which credential Rover uses

When more than one credential is available, Rover uses the first of these:

1. APOLLO_KEY, if it's set.

2. The access token from exchanging APOLLO_CLIENT_ID and APOLLO_CLIENT_SECRET, if both are set. Setting only one of them is an error.

3. The credential stored on the profile in use: an OAuth login or a personal API key. A profile holds one credential at a time, so rover auth login replaces a personal API key stored on that profile, and rover config auth replaces an OAuth login.

To see which credential a command uses, run rover auth whoami or rover config whoami. Their Origin row reads $APOLLO_KEY, $APOLLO_CLIENT_ID, --profile <name> (OAuth) for an OAuth login, or --profile <name> for a personal API key. rover config show reports only whether a credential is present and whether it came from the environment or the profile.

This order is separate from how Rover chooses a setting's value. Credentials never come from the project file.

Via the auth command

To store a personal API key on a profile, run:

1rover config auth

Rover first suggests rover auth login instead, then prompts for the key:

1warning: OAuth authentication is now available - consider running `rover auth login` instead of storing a Personal API Key.
2Go to https://go.apollo.dev/r/auth and create a new Personal API Key.
3Copy the key and paste it into the prompt below.
4>

If you have more than one API key you want to use with Rover, store each on a different configuration profile with --profile.

rover config auth is interactive to keep your API key out of your terminal command history. Because it's interactive, use an environment variable in automated environments such as CI.

With an environment variable

Provide a graph, subgraph, or personal API key by setting it as the value of the APOLLO_KEY environment variable. In CI, you can instead set APOLLO_CLIENT_ID and APOLLO_CLIENT_SECRET to a client-credential pair.

An environment variable credential takes precedence over one stored on a profile. See Which credential Rover uses and all supported environment variables.

export APOLLO_KEY="your_api_key_here"

set APOLLO_KEY=your_api_key_here

$env:APOLLO_KEY = "your_api_key_here"

Configuration profiles

You can create multiple configuration profiles in Rover. A profile can hold a credential (an OAuth login from rover auth login or a personal API key from rover config auth), settings, or both, so you can use different profiles when interacting with different graphs or GraphOS environments. A profile created by rover config set holds only settings until you add a credential to it.

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

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

--profile is accepted by every rover command, not only ones that talk to GraphOS.

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

Settings in a profile

A profile can also store non-secret settings, with or without a credential, so a profile pointed at a different GraphOS environment can carry its own registry URL, timeouts, and so on. Every setting marked in the Profile column of the environment variables table can be stored this way, with rover config set:

1rover config set APOLLO_REGISTRY_URL https://registry.staging.example.com --profile staging

A profile you name with --profile outranks the project file, which outranks the default profile. Flags and environment variables outrank all three. For the full order, see How Rover chooses a setting's value, and run rover config show to see which source supplied each setting.

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

1rover config --help

Learn more about rover config commands.

Project settings

Your project can carry its own settings, so everyone working in the same repository uses the same registry, timeouts, and plugin download host without configuring each machine. Add a settings: section to a rover.yaml file in a .rover/ directory at your project's root:

1settings:
2  APOLLO_REGISTRY_URL: https://registry.example.com
3  APOLLO_ROVER_DOWNLOAD_HOST: https://mirror.example.com
4  APOLLO_CHECKS_TIMEOUT_SECONDS: 600

Rover finds the file by looking for a .rover/ directory in the current directory and then in each parent directory, stopping at your home directory, so it applies to commands run anywhere in the project. rover plugin install --manifest-path <FILE> uses the settings in the file it names instead. A setting in the file applies to everyone who runs Rover there, unless a flag, an environment variable, or a profile they name with --profile overrides it. See How Rover chooses a setting's value.

• Names. A key is a setting's environment variable name, such as APOLLO_REGISTRY_URL, or that name in all lowercase, such as apollo_registry_url. The lowercase spelling is accepted in rover.yaml only. Using both spellings of the same setting in one file is an error (E061).

• Values. A value has the setting's type: a URL, a whole number of seconds, a graph ref, or true/false. A URL must use http or https. A stored boolean is a real true or false. For details, see Boolean values. An invalid URL or boolean, or an invalid APOLLO_CLIENT_TIMEOUT, fails every command run in the project, including rover config list, with an error naming the file and the key:

  Text

  copy

  1error[E054]: `rover.yaml` sets `APOLLO_REGISTRY_URL` to `ftp://registry.example.com`, which isn't a valid URL. Rover only accepts `http`/`https` URLs for this setting.

  An invalid APOLLO_CHECKS_TIMEOUT_SECONDS fails the commands that read it, such as rover config show and the check commands, with the same error code. An invalid graph ref fails every command run in the project, including rover config list, with the same error code, and so does an invalid APOLLO_GRAPH_REF in the environment or a profile. rover config set checks a graph ref before it stores one.

• Which settings. Only settings marked in the Project column of the environment variables table can be set here. Rover warns about any other key and ignores it, so a file written for a newer version of Rover doesn't break an older one.

• No credentials. The file is meant to be committed, so Rover refuses to read a credential from it. APOLLO_KEY, APOLLO_CLIENT_ID, or APOLLO_CLIENT_SECRET under settings: fails every command in the project (E060). Set your credential in the environment or in a profile instead; see Choosing a credential.

• Project only. A settings: section in your user-level rover.yaml (~/.rover/rover.yaml, or .rover/rover.yaml under APOLLO_HOME if you've set it) is ignored with a warning. To store settings for yourself rather than for a project, use a profile.

If Rover can't read or parse the project's rover.yaml, it prints a warning and applies none of its settings. The command still runs.

Configuration notices

When a setting's value sends Rover somewhere you might not expect, Rover prints a one-line note to stderr the first time it uses that setting. This happens when:

• a profile or the project file points a network destination, such as the registry URL or the plugin download host, at something other than its default:

  Text

  copy

  1Note: `rover.yaml` sets `APOLLO_ROVER_DOWNLOAD_HOST` to `https://mirror.example.com`.

• an environment variable overrides a value set by a profile you named with --profile, or by the project file. For a URL setting, the note names the URL the environment sends Rover to:

  Text

  copy

  1Note: `APOLLO_REGISTRY_URL` from the environment is set to `https://registry.example.com`, overriding the value set in profile `staging`.

  For any other setting, it doesn't repeat the value:

  Text

  copy

  1Note: `APOLLO_CHECKS_TIMEOUT_SECONDS` from the environment overrides the value set in profile `staging`.

Notices go to stderr only. They never appear in --format json output and never change a command's exit code. To turn them off, pass --no-config-notices or set APOLLO_ROVER_NO_CONFIG_NOTICES to true. You can't turn them off in a profile or project file.

Logging

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

• error

• warn

• info

• debug

• trace

By default, Rover doesn't log anything. To see log messages for a command, set your minimum log level with the --log flag (or the APOLLO_LOG_LEVEL environment variable):

1rover 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}

For a concrete example, here is rover auth whoami for a user API key supplied through an environment variable. In the default plaintext format:

┌──────────┬──────────────────┐
│ Key Type ┆ USER             │
├╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ User ID  ┆ user-123         │
├╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ Origin   ┆ $APOLLO_KEY      │
├╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ API Key  ┆ user********LOLO │
└──────────┴──────────────────┘

With --format json, the same output is the data object of the envelope (commands add "success": true to data):

1{
2  "json_version": "1",
3  "data": {
4    "key_type": "USER",
5    "graph_id": null,
6    "graph_title": null,
7    "user_id": "user-123",
8    "origin": "$APOLLO_KEY",
9    "grant_type": null,
10    "api_key": "user********LOLO",
11    "success": true
12  },
13  "error": null
14}

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:

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

If the specified file already exists, Rover overwrites it.

Where Rover stores configuration

Rover keeps credentials and settings in different places:

• Credentials. An OAuth login or personal API key is stored in your operating system's credential store under the service name rover: macOS Keychain, Windows Credential Manager, or the Linux kernel keyring. Where no credential store is available, Rover falls back to a credentials.json file in the configuration directory, readable and writable only by your user (mode 0600).

• Settings. Rover stores a profile's settings in profiles/<name>/settings.toml in the configuration directory.

The default configuration directory depends on your operating system:

To use a different directory, pass --config-home or set the APOLLO_CONFIG_HOME environment variable. This can be useful for CI systems that don't provide access to default operating system directories.

1APOLLO_CONFIG_HOME=./myspecialconfig/

If you stored an API key with an earlier version of Rover, Rover moves it from its old plaintext file into the credential store automatically the first time it reads it. For details, see Credentials are stored in the OS keychain.

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 GraphOS 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 GraphOS 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:

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

Supported environment variables

You can configure most of Rover's behavior with an environment variable, and most environment variables have a matching flag, shown in the following table. A flag's --help text also names its environment variable.

How Rover chooses a setting's value

For each setting, Rover uses the first of these sources that supplies a value:

1. A flag passed on the command line.

2. The setting's environment variable. A variable that's set to an empty value still counts as set, except APOLLO_HOME, where an empty APOLLO_HOME or --rover-home "" is treated as unset, and APOLLO_ROVER_ALLOW_AUTOMATIC_DOWNLOAD (for details, see Boolean values).

3. A profile named with --profile, including --profile default typed out.

4. The project file: the settings: section of rover.yaml in your project's .rover/ directory.

5. The default profile, when --profile isn't passed.

6. Rover's built-in default.

Only the settings marked in the Profile and Project columns below can come from a profile or the project file. For every other setting, the chain is just the flag, then the environment variable, then the built-in default. Run rover config show to see each setting's effective value and the source that supplied it.

Boolean values

A boolean environment variable is set by 1 or true (case-insensitive) and unset by 0, false, an empty value, or leaving it unset. There are two exceptions:

• APOLLO_TELEMETRY_DISABLED disables telemetry when it's set to any value, including false or an empty value. Only leaving it unset keeps telemetry enabled.

• NO_COLOR and APOLLO_NO_COLOR follow the cross-tool NO_COLOR convention: an empty value, 0, and false count as unset, and anything else turns color off.

APOLLO_ROVER_ALLOW_AUTOMATIC_DOWNLOAD has three states rather than two. 1 or true turns automatic downloads on, and 0 or false turns them off. Rover ignores any other value, such as no, yes, or an empty value, as if the variable were unset, so a profile, the project file, or the built-in default decides.

A boolean stored in a profile or the project file is always a real true or false, whatever its environment variable's rule. So APOLLO_TELEMETRY_DISABLED: false in a profile or project file keeps telemetry enabled, even though APOLLO_TELEMETRY_DISABLED=false in the environment disables it.

Variables