Test and Live Environments for Next.js
Specially named Git tags trigger deployments to Test and Live environments for Next.js sites on Pantheon.
This documentation describes support for Next.js that is under active development and is available only to customers who have been individually approved as part of our Private Alpha program.
To request access, please reach out to [email protected].
If you are migrating an existing Next.js site from our Front-End Sites offering please see our guide on migrating from Front-End Sites.
By default, all sites on Pantheon have at least three environments: Dev, Test, and Live. Additionally, Multidev workflows correspond to separate branches or pull requests.
These environments generate unique subdomains in the pattern of <environment>-<site-machine-name>.pantheonsite.io.
Sites on paid plans can connect custom domain names to any of these environments, though custom domains are most commonly connected to the Live environment.
Deploying to Test and Live environments through Git tags
The Test and Live environments are special in that they only receive code changes via Git tags. Deployments to these environments follow a simple pattern in which integers are incremented for each new deployment. For example deployments to Test can be triggered by tags like
pantheon_test_1
pantheon_test_2
pantheon_test_3Similarly, deployments to Live can be triggered by tags like
pantheon_live_1
pantheon_live_2
pantheon_live_3For sites running Drupal and WordPress, these tags are create automatically when triggering a deploment in the dashboard or via Terminus.
Presently, for Next.js sites, deployments to Test and Live must be triggered by Git tags in the connected GitHub repository.
These tags can be created in a few ways including:
On Drupal and WordPress sites, the extra Dev and Test environments separating a code in a Multidev from being deployed to Live are valuable for extra testing. For such sites, the cost of breaking the Live database is high because it may require database restores and content loss in addition to code fixes.
On Next.js sites which may only be displaying data sourced from a headless CMS or Content Publisher, the remediation for deploying broken code to Live is often as simple as pushing a fix to the repository and triggering a new deployment.
Depending on your team's workflow and preferences, you may choose to manually deploy the Test and then to Live, or you may choose to automate deployments to Dev, Test, and Live all at once via GitHub Actions or another CI/CD tool.
Manual Deployment to Test and Live
To manually deploy to Test or Live, create a Git tag in your local clone of the repository connected to your Pantheon site. For example, to deploy to Test, you might run
git tag pantheon_test_1 -a -m "Deploying to Test"
git push origin --tagsAfter this tag is pushed to GitHub, Pantheon will detect the new tag and begin building and deploying the code to the Test environment. The progress of the build and deployment can be monitored via Terminus:
terminus node:logs:build:list my-site-machine-name.testThis tactic requires knowing what the next integer tag should be. To find the latest tag, you can use
git tag --list 'pantheon_live_*' --sort=v:refname | tail -1Manual creation via GitHub's Releases interface
The manual creation of a tag can also be done via GitHub's Releases interface.
This screenshot shows a new tag named pantheon_test_1 being created from the main branch. For more details, see related GitHub documentation
Automating tagging via GitHub Actions
If you wish to automate deployments to Test and Live, you can use GitHub Actions or another CI/CD tool to create the necessary tags.
Here is an example repository that uses GitHub Actions to automate deployments to Live by running a workflow on pushes to the main branch that invokes a locally defined (but reusable) Action to create the necessary Git tag.
If you have input on what guidance we should provide for using GitHub Actions to automate deployments to Test and Live, please share your thoughts in this issue.
Connecting a custom domain name
In practice, what makes a Live environment different from Dev or Multidev environments is that only the Live environment is likely to have a custom domain name connected to it.
The custom domain name is what your end users will use to access your site.
Platform domains, those ending in pantheonsite.io, are typically only used by members of the web team for testing and development purposes.
To connect a custom domain name to your Live environment, follow the instructions in Connecting a Custom Domain Name.