Overview of the Deployment Process

The Pages system has been architected to support building statically generated pages at scale. Most static site generators struggle to build sites with more than thousands of pages and most will require a full site rebuild even with a tiny data change.

The Pages deployment process is optimized for scale and allows you to build sites extremely quickly. Incremental data changes only update the necessary pages, resulting in changes going live in less than five seconds in most cases.

The deployment process is split into three independent phases:

1. The initial build
2. Page generation
3. Ongoing data updates

By decoupling these phases, the system can provide processing environments that are uniquely optimized for distinct responsibilities of each phase, yielding an overall faster deploy performance.

1. Initial Build

The initial build phase is responsible for generating all the static assets that make up the frontend of the website. This includes, but is not limited to, CSS stylesheets, JavaScript files, font files, and images.

This process is kicked off when a developer pushes code to GitHub.com. After the source code is pushed to GitHub, the Yext Pages systems will check out the code and initiate the build process.

Importantly, the initial build phase does not interact with the data source — it is not responsible for generating web pages based on data records. It is just responsible for generating the "supporting" assets (typically stylesheets and JavaScript files). This split is critical since it allows us to only update the HTML files when data changes rather than restarting the entire build process from scratch.

The exact build process is determined by a build command located within the config.yaml file at the root of the project. Generally, this step will run npm install and then npm build, but this can be configured. You can learn more in the Site Configuration reference doc.

After the initial build is completed, the initial page generation begins.

2. Initial Page Generation

The page generation phase is responsible for generating the HTML web pages that make up the site. These web pages are generated based on data records from the Yext Knowledge Graph. Under the hood, this uses a system called Streams that pushes entities from the Knowledge Graph into Pages.

For every single data record, Pages generates an HTML page using the build artifacts from the previous step. After the HTML is generated, the files are automatically pushed to the global CDN. Since each page can be generated independently, this process happens in parallel, which greatly improves generation speed.

After the initial page generation is complete, the deploy is live and will be served via the CDN. If data in the Knowledge Graph changes after this generation, those updates are processed incrementally in the next step.

3. Ongoing Data Updates

After the initial page generation, the deploy listens for any ongoing data changes via the same Streams system. If data changes in the Knowledge Graph, the Streams system notifies the site to incrementally build any new pages the data change impacts.

Unlike other static site generation systems, this does not kick off a new build from the beginning. Instead, it incrementally generates the HTML for only the pages that have changed, reusing the same build artifacts from step 1. Overall, the net result is incremental publishes in less than five seconds.

If a large number of updates happen all at once, the Pages system can parallelize these requests to minimize total processing time.

The deployment process is managed by the Pages system without additional developer intervention. If changes to the structure of the site are required, the developer just pushes their latest commit to GitHub. Otherwise, data changes in the Knowledge Graph automatically update the relevant statically-generated pages in real-time.

Deploying Your Changes

Once you've confirmed your code looks good locally, it's time to push your changes to your GitHub repository.

1. In your terminal, terminate your dev server if it is still running (press CTRL + C).
2. Save your files in your code editing tool.
3. Add your modified files to the git staging area:

git add -A

If you only want to commit certain files, use git add <file-name>.

4. Commit your changes with a commit message:

git commit -m "<commit-message>"

5. Push your changes to the remote repo:

git push origin <master/main>

6. Navigate back to your site in Yext. Pages will listen for any changes to your GitHub repo and build a new version of your site accordingly. You should see a new deploy in the UI with the same commit message you just wrote.
7. Once your deploy finishes, you'll have two deploy links you can share:
   • Deploy Preview: Click Preview on the right of your deploy.
   • Staging link: The most recent deploy is automatically staged. At the top of the screen, click the URL next to the orange "Staging" pill.

You also have the ability to deploy a backup version of your site as it existed at a previous point in time. Check out the Site Backups reference doc for more info.

Deployment Screens

Deployments are fully rendered versions of your site that can be published to staging or production in seconds.

• Staging — rough drafts or work in progress. These can be shared, but are not live sites that end users or customers can see.
• Production — the live version of your site. This is what users see when they navigate to your website if your Pages site has been integrated with your website.

Deploys Screen

To view deploys on your site, navigate to Pages, click on the relevant site, and click Deploys. This screen shows all the important links for your site at the top and a history of deploys for each branch.

Deploy Preview Links

Each deploy has a deploy-specific preview link. Clicking the Preview button next to a deploy will open a new tab with that version of your site. You can easily preview multiple deploys to compare your work or send different versions of the site to stakeholders for feedback.

Staging and Production Deploys

At the top of the Deploys screen, you will see a Production and Staging link. These are permalinks that will always display the version of the site pushed to either environment. The current staged deploy will be marked with an orange "Staging" indicator and the one pinned to production will have a green "Production" indicator.

Note: you can have a staging link for each branch (the branch name is prepended to the staging domain), but only one production link across the site, which must be from the production branch.

Stage or Publish a Previous Deploy

You can always stage or publish a previous deploy. Navigate to the relevant deploy, click the dropdown next to Preview, and click Publish to staging or Publish to production. Because each deploy is fully rendered, you can publish a deployment in seconds.

This capability lets you quickly push an update to staging for QA and then promote it to production once approved. It also allows you to roll back your staging and production environments nearly instantly — if you ever push a bug to production, you can roll back to a previous deploy in seconds.

Deploy Details

For each individual deploy, you will see information about the three phases of the deployment process:

• Initial Build
• Page Generation
• Data Updates

Click into any of these sections to see more details about that phase. Every deploy also has a View Deploy URLs button in the top-right corner. Clicking it shows the full list of live URLs in your deploy — filter by "HTML only" to see all generated pages.

Initial Build

The initial build phase generates all the static assets that make up the front end of the website.

Clicking on this section shows build details and a console log.

If a build fails, check the console log in the deploy details for error messages that may point you toward the issue.

Page Generation

The Page Generation phase generates all HTML web pages based on data records from the Knowledge Graph.

Clicking on the Page Generation section displays a log of all the pages that were built.

If data in the Knowledge Graph changes after this page is created, those updates are processed incrementally via the Data Updates phase.

Data Updates

The Data Updates tab captures pages in your deploy that were re-rendered as a result of data updates from your Knowledge Graph. See the Data Updates section below for full details.

Data Updates

Whenever Knowledge Graph data changes — whether from content edits in the UI or through API integrations — Yext automatically pushes data updates to Pages, updating the relevant web pages in your deploys. Data updates in Pages are extremely performant and highly scalable. An individual update can be processed in seconds and the system can handle hundreds of thousands of concurrent updates.

Viewing Entity Edits in Your Deploys

The Data Updates tab of the Deploy Details screen displays pages in your deploy that were re-rendered as a result of data updates from your Knowledge Graph. This tab will be empty if you haven't edited an entity since your last deploy was completed.

After making an update to an entity in your Knowledge Graph, return to the relevant site and click into the Data Updates section of your deploy. You should see a data update entry in the table representing your edit.

Clicking View Details on the far right shows a diff view that displays the data before and after your change.

Active Deployments

Yext's Streaming Static Generation architecture ensures that:

1. Your site is always up-to-date (has the freshest entity data)
2. Your site is always pre-rendered (loads quickly)
3. Only certain pages are regenerated when content is updated (no need for unnecessary full-site rebuilds)

An "active" deployment means pages in that deployment are actively regenerated in response to Knowledge Graph updates. An "inactive" deployment means pages are not updated — viewing pages from an inactive deployment may show outdated entity content.

In the Pages UI, you can identify active deployments based on the status in the "Data Updates" section.

Having multiple active deployments is useful in scenarios where you may want to roll back changes to your site — you can deploy, stage, or publish a previous commit with confidence that the data on the pages is not stale.

Default Active Deployments

By default, Yext guarantees that the following deployments on your production branch are always active:

1. Production deployment — the deployment currently published to your production environment
2. Staging deployment — the deployment currently published to the staging environment (note: staging deployments on non-production branches are inactive)
3. Head deployment — the most recent deployment
4. Previous Production deployment — the previous deployment that was published to your production environment

As you create new deployments, any applicable previous deployments will become inactive automatically.

Inactive Deployments

Note: It is possible to publish an inactive deployment to production; however, that deployment will remain inactive. This means some page content could be stale. To reliably ensure an old deployment is fully updated, we recommend redeploying that specific deployment and then publishing the new one to production instead.

Branch Settings

By default, only deployments from the production branch can be active; deployments from any other branch are always inactive.

If you ever need to switch your production branch, Yext automatically ensures that whatever deployment is currently published to production remains active until a deployment from the new production branch is published.

Staging Branch

You can also specify a "Staging Branch" in Site Settings > Repository Details. For a configured staging branch, Yext will automatically keep the following deployments active:

1. Staging deployment — the deployment currently published to the staging environment
2. Head deployment — the most recent deployment

Data Update Error Monitoring

You can monitor data update errors throughout the lifecycle of your deployments directly in the UI. Data update errors occur when entity data is updated in a way that causes a generation error in the Pages system (typically due to how your template and components interact with the data). This information is visible in the Data Updates portion of the deployment card.

To action on these errors, navigate to Deployment Details > Unresolved Errors. The platform shows each page in your website that is "stale" due to data update errors, along with relevant generation error messaging. Once you fix the underlying issue, the relevant page will be removed from this table.

Automated Alerts

You can set up automated alerts for data update errors by configuring webhooks. This feature allows you to send webhooks any time a Stream Update Failure event occurs in your system.