README

A Terminus plugin for upgrading a site to GCDN with bot protection, managing the DNS migration for your existing domains, and retrieving bot-bypass tokens for your own monitors and automation.

Installation

To install this plugin using Terminus 3 or later:

terminus self:plugin:install pantheon-systems/terminus-gcdn-plugin

Usage

If you have existing custom domains on your site, follow all of the steps below to upgrade and migrate your DNS.

1. Upgrade your site to GCDN

terminus gcdn:upgrade <site>

This migrates the site from Fastly to GCDN across all environments.

2. Get your DNS records and TXT verification challenges

terminus gcdn:dns <site>.live

This will show the TXT records needed for domain ownership and certificate validation.

3. Add TXT records to your DNS provider

Add the TXT records from step 2 to your DNS provider.

4. Verify your domains

Wait a few minutes for DNS propagation, then verify each domain. Verification typically takes a few minutes to complete:

terminus gcdn:verify <site>.live example.com
terminus gcdn:verify <site>.live www.example.com

By default, verification uses DNS challenges. To verify using HTTP challenges instead:

terminus gcdn:verify <site>.live example.com --method=http

5. Update your DNS records

Once verification passes, add the CNAME or A/AAAA records shown in the gcdn:dns output to point your domains to the new GCDN edge.

Orange-to-Orange (O2O) migrations

If your domain is already proxied through your own Cloudflare zone (orange-clouded), use the O2O flow instead of the plain TXT verification above:

terminus gcdn:o2o <site>.live

This prints the per-domain record set to add in your Cloudflare DNS: the hostname ownership TXT record, the DCV delegation CNAME (which must stay in place permanently and be set to DNS only / grey cloud), and the final traffic CNAME. Pass a domain as a second argument to limit output to one hostname. See the O2O documentation for the surrounding steps (Zone Hold, SSL/TLS encryption mode).

Certificate challenge method

View or change the certificate challenge method (DNS or HTTP) for a domain:

terminus gcdn:challenge <site>.live example.com
terminus gcdn:challenge <site>.live example.com --method=http
terminus gcdn:challenge <site>.live example.com --method=dns

To switch all unverified Cloudflare domains on an environment at once:

terminus gcdn:challenge <site>.live --all --method=http

Verified hostnames are never modified. Hostnames already on the requested method are skipped. The command prints a per-hostname status line and a summary:

  example.com — switched to HTTP
  www.example.com — skipped (already HTTP)
  blog.example.com — skipped (verified)

Summary
  Toggled:                 1
  Skipped (verified):      1
  Skipped (already http):  1

When set to DNS, the command shows DCV delegation CNAME and TXT records. When set to HTTP, it shows the cutover instructions and serve-file challenge token.

Note: A site converge resets the method to the default for the hostname type (custom → DNS, platform → HTTP).

Bot-bypass tokens

If your site is on GCDN with bot protection, your own uptime monitors, load tests and automation can be exempted from bot challenges by sending a per-site bot-bypass token in a request header. Retrieve the tokens with:

terminus gcdn:bot-bypass <site>

The command prints two tokens: the current token, and a next token that becomes valid three months later. Each row shows the window the token is accepted in and the header name to send it in. Switch to the next token on or after its Valid From date; both are accepted until the current token expires, so there is never a gap.

One token covers every environment on the site (dev, test, live and all multidevs). The argument is a site name, not <site>.<env>.

For CI pipelines and monitoring configuration, use the machine-readable form:

terminus gcdn:bot-bypass <site> --format=json

Treat these tokens as secrets. Do not commit them or paste them into shared logs. If the token service is unavailable, Terminus retries for up to about a minute before reporting the failure.

Updating the plugin

Check for and install the latest version:

terminus gcdn:update

This checks the latest release on GitHub and runs the update automatically.

Help

Run terminus help gcdn:upgrade, terminus help gcdn:dns, terminus help gcdn:verify, terminus help gcdn:challenge, terminus help gcdn:o2o, terminus help gcdn:bot-bypass, or terminus help gcdn:update for details on each command.

pantheon-systems / terminus-gcdn-plugin

Package info

Security

Statistics