Deployments in the portal

Deployments lists a service’s deployments in the portal: what is live, everything that came before it, and why a deployment that did not go live did not. Open a service in the portal and choose Deployments. What a deployment is, and what happens to traffic and the cache while one runs, is on deployments.

Permission deployment:view

Who sees what

Permission	Without it
`deployment:view`	The list, every deployment’s page and its two files say “You do not have permission to see this service’s deployments.” The Schema and Config pages need it too.
`deployment:edit`	New deployment, Redeploy and Stop this build are not shown.
`service:edit`	New deployment and Redeploy offer no Upload a file, because uploading writes the service’s files; every other source stays. A deployment’s gpilot.toml tab says The configuration file is not shown to you instead of the file, with a link to the service’s Config values, which show every setting with secrets redacted; there is no download and no comparison of the file. A configuration can hold a provider’s shared secret, so the file itself needs this permission.

These follow the portal’s hidden or disabled rule: a control you lack the permission for is not shown. See permissions.

Running deployments in the header

While a deployment of any of the organization’s services is building, and for a while after it ends, the header shows it on every page: Deployment running, Deployment live, Deployment failed or Deployment canceled, with a count when there are several. Open it for the list, headed Deployments. Each entry links to its deployment’s page and disappears once opened; a failed one stays until you open it or select Dismiss. A deployment GraphPilot started on its own reads Automatic. A deployment that a newer deployment of the same service replaced before it went live ends canceled, so it shows as Deployment canceled (see the header for what its page says).

The list

The page opens on the live deployment and, below it, the history, newest first. It loads the 50 most recent deployments and refreshes on its own while one is building.

The Live card

The card at the top names the deployment that is serving traffic: Live since when, the Schema and Config versions it was built from, the Proxy version and who deployed it (Deployed by). View schema and View config open its two files. A deployment without a schema shows No schema: plain HTTP as its Schema and has no View schema link, and one without a configuration file shows Default configuration as its Config. A service with nothing live yet says Nothing is live yet.

Deployed by names the person who signed in (point at the name for their email), or, for a deployment made with an API key (from CI, for example), the key’s name followed by its redacted value, such as ci-deploy (sk_...9W8H). The value shows when a key was replaced under the same name. A person whose account was deleted reads Deleted user, usually followed by a short code that stays the same for all of that person’s deployments without identifying them. The first deployment GraphPilot makes when a service is created with Deploy right away reads GraphPilot (point at it for Started automatically when the service was created); see set up a new service. The history rows and a deployment’s header use the same wording.

Search and filters

The chips above the list narrow it:

Filter	Keeps
All	Every deployment loaded.
Failed	Deployments that failed. Canceled deployments are not included.
With findings	Deployments whose build recorded at least one error or warning; notices alone do not count, so a deployment without a schema is not listed for its notice.
Schema changed	Deployments whose schema differs from the deployment before them, including a schema added or removed.
Config changed	Deployments whose configuration differs from the deployment before them.

Search deployments (“Search reason, author, version”) matches the deploy message, who deployed it, and the schema and config versions; no schema finds the deployments without one, and default configuration the ones without a configuration file. The count beside it says how many of the loaded deployments are shown.

One row

Each row shows, left to right:

The state: Building, Live, Superseded (it was live, and a later one took over), Failed, or Canceled (the build was stopped).
The message given with the deployment, or Schema <version>, config <version> without one (No schema, config <version> for a deployment without a schema, default configuration in place of config <version> for one without a configuration file), with who deployed it and when. Where the schema changed against the one that was live before, the line adds Schema: <summary>, such as Schema: +3 types, -1 field, and Introspection failed when the schema was to be read by introspection and could not be.
Findings: the number of errors and of warnings the build recorded. A deployment that never got as far as checking the schema shows ? for both, which is not the same as zero.
The proxy version it was built on, with an arrow when it moved against the deployment before: up for an upgrade, down (highlighted) for a rollback.
Change markers: SCH and CFG, highlighted when the schema or the configuration changed against the deployment before, dashed when unchanged, and marked as having nothing to compare with on the oldest deployment loaded. When a schema was removed, SCH is highlighted as a warning and reads Schema removed: GraphQL features off; when one was added to a service that had none, Schema added: GraphQL features on.

Select a row to open the deployment’s page.

A service that has never been deployed shows No deployment yet with the command to run, gpilot deploy, next to your schema.graphql and gpilot.toml, and says that New deployment can also deploy without either file.

A deployment’s page

The header

The header gives the state, the message, who deployed it, when, and how long the build took. Rebuild forced appears when the deployment was started with a forced rebuild. A deployment that failed shows This deployment did not go live with the reason: what was refused and why (see a deployment can be refused), or, for a failure on GraphPilot’s side, a support reference. A canceled deployment shows This deployment was canceled instead: it was stopped before it went live, nothing it built serves traffic, and whatever was serving before it is unaffected. When GraphPilot stopped it, the alert gives the reason first, for example Replaced by a newer deployment of this service before it went live. A deployment stopped on request has none.

Below that, Schema, Config and Proxy version name what it was built from. The schema and config versions link to the files, and the download button beside each saves the file as it was deployed, named after its version (for example <version>-schema.graphql). A deployment without a schema shows No schema: plain HTTP instead, and one without a configuration file Default configuration, with no link and no download. Proxy version reads Resolved during the build while a deployment is building and has not recorded its version yet.

When another deployment is picked under Compare against, each of the three is marked changed, upgraded or rolled back where it differs. Schema is marked removed or added when one of the two deployments has no schema, and Config the same way when one of them has no configuration file.

Above them, two lines say where the schema came from when that is news:

Schema changes: <summary>, such as +3 types, -1 field, against the schema that was live when the deployment was requested. Open it for each added and removed type and field (+ type Review, - Product.legacyId). It is not shown when either side has no schema.
For a service whose schema source is Introspect at deploy: Schema read by introspection on <path> when it worked. When it did not, Schema from <date>, introspection failed with the reason: the deployment went live with the newest schema stored before it, uploaded on that date. With no schema stored before, it reads No schema, introspection failed and the deployment has none.

Tabs

Tab	Shows
Findings	What the build recorded about your schema and configuration.
Build	Every step of the build pipeline, with a line above it naming the current step (for example Step 3 of 5: Provision) or where the deployment ended (Every step finished., Failed at Build., Canceled during Provision.). See the build steps.
schema.graphql	The schema this deployment was built from. For a deployment without one: No schema: this deployment is plain HTTP.
gpilot.toml	The configuration this deployment was built from. For a deployment without one: No configuration file: this deployment runs on the defaults.

The build steps

A deployment runs these steps in order. Open a step for what it does, when it started and when it finished.

Step	What it does
Prepare	Loads the service and checks that it can be deployed.
Build	Builds the service from the schema and configuration.
Provision	Sets up the new version at the edge, with its hostnames, certificates, origin and logging, without serving traffic yet.
Activate	Switches traffic to the new version.
Finalize	Records the deployment as live.

Each step shows one of these states:

State	Means
Waiting	The deployment is still building and has not reached this step yet.
Running	The step is running now.
Done	The step finished.
Reused	Only for Build: an identical build of the same schema, configuration and proxy version already existed, so it was reused.
Skipped	The pipeline passed over the step.
Failed	The step failed. It opens on its own and says This step stopped here with the reason.
Canceled	The step was running when the build was stopped.
Not run	The deployment failed or was canceled before it reached this step.

Findings

The findings are grouped by the check that reported them. Filter findings… searches the messages, the severity buttons (All, Errors, Warnings, each with its count, and Notices when there is one) and the source buttons narrow the list. A notice asks for nothing: a deployment without a schema carries one saying GraphQL features are off. One finding comes from your plan rather than from the build: a configuration that sets origin.shield on a plan without shielding gets a warning on origin.shield. The shield is deployed anyway, stays inactive, and turns on by itself after an upgrade, with no redeployment. A finding’s line links into schema.graphql, and the type it sits in opens in the Explorer of the live schema. What each finding means is in deployment diagnostics.

Against the compared deployment, a box headed Since the deployment being compared with counts the findings that appeared and those that were resolved, and lists them. It says so instead when there is nothing to compare with, or when one of the two deployments recorded no findings.

Compare against

Compare against, at the top right of the page, picks the deployment everything on the page is measured against. It starts on the deployment just before this one. On the schema.graphql and gpilot.toml tabs, choose This version to read the file, or Side by side or Unified for a diff against the compared deployment. When the two files are identical, the diff buttons are disabled and the page says Identical to the deployment being compared with. When only one of the two has a schema, there is no diff, and the schema.graphql tab says which one had none.

Start a deployment from the portal

Permission deployment:edit

Upload a file also needs service:edit, which uploading a schema or configuration needs everywhere (gpilot deploy too); without it the option is not offered.

Most teams deploy with gpilot deploy or from CI. To start one here, select New deployment on the list, or Redeploy on a deployment’s page, which starts with that deployment’s files selected. Deploy from the portal and Deploy it elsewhere in the portal open the same dialog.

For Schema and for Configuration, pick where the file comes from: Latest upload (the last one uploaded, for example by gpilot deploy), From a deployment (the file an earlier deployment used), Upload a file from your machine (with service:edit), or none of it: No schema or Default configuration.
- No schema deploys the service as plain HTTP: every path is forwarded to your origin and GraphQL features are off.
- Default configuration deploys without a gpilot.toml: every setting is at its default, and the Config page lists each value after the deployment.
- Both together deploy a pass-through: requests reach your origin unchanged, and only responses your origin marks with Cache-Control are cached.
- A schema with Default configuration reads GraphQL on /graphql only, and the dialog says so: if your API answers on another path, use a gpilot.toml that sets request.graphql_paths, or every operation there is refused with NOT_A_GRAPHQL_PATH.
Latest upload is disabled, with Latest upload: nothing uploaded yet., while nothing was ever uploaded for that file. Each half starts on Latest upload when there is one, and on No schema or Default configuration when there is not. Taking a half From a deployment that had none deploys without it again; this is also what Redeploy does for a deployment without a schema or without a configuration file.

For a service whose schema source is Introspect at deploy, Schema also offers Introspect at deploy, and starts on it: the build reads the schema from your origin through the service’s hostname. Introspection carries no directives such as @cacheControl, @surrogateKey or @vary; upload your schema.graphql to use them. With No schema as the schema source, Latest upload still deploys the newest uploaded schema.
Under Proxy version, keep the default unless you have a reason to build this deployment on a specific version. The default is the service’s runtime pin, else the stable version, and is labelled with what it resolves to now: Service pin (<version>) or Stable (<version>). Below it, every version that can still be deployed is listed, newest first, with the stable one marked (stable) and deprecated ones (deprecated). Withdrawn versions are not listed. On Redeploy, the version the deployment ran on is marked same as this deployment; if it was withdrawn, or is not in the runtime catalog, it is not offered and the dialog says why. A version picked here applies to this deployment only and does not change the service’s pin.

If the service is pinned to a version that was withdrawn or is no longer in the runtime catalog, the default would be refused with RUNTIME_VERSION_WITHDRAWN, so the dialog says so and Start deployment stays disabled until you pick a version. If the list of versions cannot be loaded, only the default is offered.
Tick Force a rebuild only if a build itself went wrong. Without it, GraphPilot reuses an existing build for the same two files. If the two files you picked and the proxy version are exactly what is live, the dialog says so: the deployment would succeed and change nothing. If only the proxy version differs from the one the live deployment was built with, the dialog says Only the runtime changes: <live version> → <chosen version> instead. While the default’s version cannot be resolved (the list of versions is loading or failed to load), or the live deployment recorded no version, the dialog says neither.
Select Start deployment. The portal opens the new deployment’s page. If the service’s schema or configuration changed while the deployment was being prepared, nothing is started and the dialog that says so offers Try again, which sends the same deployment again.

Rolling back with Redeploy is walked through in staging and rollback.

Stop a build