2021-06-23
3 min read
A couple of months ago, we announced the general availability of Cloudflare Pages: the easiest way to host and collaboratively develop websites on Cloudflare’s global network. It’s been amazing to see over 20,000 incredible sites built by users and hear your feedback. Since then, we’ve released user-requested features like URL redirects, web analytics, and Access integration.
We’ve been listening to your feedback and today we announce two new features: rollbacks and the Pages API. Deployment rollbacks allow you to host production-level code on Pages without needing to stress about broken builds resulting in website downtime. The API empowers you to create custom functionality and better integrate Pages with your development workflows. Now, it’s even easier to use Pages for production hosting.
Rollbacks
You can now rollback your production website to a previous working deployment with just a click of a button. This is especially useful when you want to quickly undo a new deployment for troubleshooting. Before, developers would have to push another deployment and then wait for the build to finish updating production. Now, you can restore a working version within a few moments by rolling back to a previous working build.
To rollback to a previous build, just click the “Rollback to this deployment” button on either the deployments list menu or on a specific deployment page.
API Access
The Pages API exposes endpoints for you to easily create automations and to integrate Pages within your development workflow. Refer to the API documentation for a full breakdown of the object types and endpoints. To get started, navigate to the Cloudflare API Tokens page and copy your "Global API Key". Now, you can authenticate and make requests to the API using your email and auth key in the request headers.
For example, here is an API request to get all projects on an account.
Request (example)
curl -X GET "https://api.cloudflare.com/client/v4/accounts/{account_id}/pages/projects" \
-H "X-Auth-Email: {email}" \
-H "X-Auth-Key: {auth_key}"Response (example)
{
"success": true,
"errors": [],
"messages": [],
"result": {
"name": "NextJS Blog",
"id": "7b162ea7-7367-4d67-bcde-1160995d5",
"created_on": "2017-01-01T00:00:00Z",
"subdomain": "helloworld.pages.dev",
"domains": [
"customdomain.com",
"customdomain.org"
],
"source": {
"type": "github",
"config": {
"owner": "cloudflare",
"repo_name": "ninjakittens",
"production_branch": "main",
"pr_comments_enabled": true,
"deployments_enabled": true
}
},
"build_config": {
"build_command": "npm run build",
"destination_dir": "build",
"root_dir": "/",
"web_analytics_tag": "cee1c73f6e4743d0b5e6bb1a0bcaabcc",
"web_analytics_token": "021e1057c18547eca7b79f2516f06o7x"
},
"deployment_configs": {
"preview": {
"env_vars": {
"BUILD_VERSION": {
"value": "3.3"
}
}
},
"production": {
"env_vars": {
"BUILD_VERSION": {
"value": "3.3"
}
}
}
},
"latest_deployment": {
"id": "f64788e9-fccd-4d4a-a28a-cb84f88f6",
"short_id": "f64788e9",
"project_id": "7b162ea7-7367-4d67-bcde-1160995d5",
"project_name": "ninjakittens",
"environment": "preview",
"url": "https://f64788e9.ninjakittens.pages.dev",
"created_on": "2021-03-09T00:55:03.923456Z",
"modified_on": "2021-03-09T00:58:59.045655",
"aliases": [
"https://branchname.projectname.pages.dev"
],
"latest_stage": {
"name": "deploy",
"started_on": "2021-03-09T00:55:03.923456Z",
"ended_on": "2021-03-09T00:58:59.045655",
"status": "success"
},
"env_vars": {
"BUILD_VERSION": {
"value": "3.3"
},
"ENV": {
"value": "STAGING"
}
},
"deployment_trigger": {
"type": "ad_hoc",
"metadata": {
"branch": "main",
"commit_hash": "ad9ccd918a81025731e10e40267e11273a263421",
"commit_message": "Update index.html"
}
},
"stages": [
{
"name": "queued",
"started_on": "2021-06-03T15:38:15.608194Z",
"ended_on": "2021-06-03T15:39:03.134378Z",
"status": "active"
},
{
"name": "initialize",
"started_on": null,
"ended_on": null,
"status": "idle"
},
{
"name": "clone_repo",
"started_on": null,
"ended_on": null,
"status": "idle"
},
{
"name": "build",
"started_on": null,
"ended_on": null,
"status": "idle"
},
{
"name": "deploy",
"started_on": null,
"ended_on": null,
"status": "idle"
}
],
"build_config": {
"build_command": "npm run build",
"destination_dir": "build",
"root_dir": "/",
"web_analytics_tag": "cee1c73f6e4743d0b5e6bb1a0bcaabcc",
"web_analytics_token": "021e1057c18547eca7b79f2516f06o7x"
},
"source": {
"type": "github",
"config": {
"owner": "cloudflare",
"repo_name": "ninjakittens",
"production_branch": "main",
"pr_comments_enabled": true,
"deployments_enabled": true
}
}
},
"canonical_deployment": {
"id": "f64788e9-fccd-4d4a-a28a-cb84f88f6",
"short_id": "f64788e9",
"project_id": "7b162ea7-7367-4d67-bcde-1160995d5",
"project_name": "ninjakittens",
"environment": "preview",
"url": "https://f64788e9.ninjakittens.pages.dev",
"created_on": "2021-03-09T00:55:03.923456Z",
"modified_on": "2021-03-09T00:58:59.045655",
"aliases": [
"https://branchname.projectname.pages.dev"
],
"latest_stage": {
"name": "deploy",
"started_on": "2021-03-09T00:55:03.923456Z",
"ended_on": "2021-03-09T00:58:59.045655",
"status": "success"
},
"env_vars": {
"BUILD_VERSION": {
"value": "3.3"
},
"ENV": {
"value": "STAGING"
}
},
"deployment_trigger": {
"type": "ad_hoc",
"metadata": {
"branch": "main",
"commit_hash": "ad9ccd918a81025731e10e40267e11273a263421",
"commit_message": "Update index.html"
}
},
"stages": [
{
"name": "queued",
"started_on": "2021-06-03T15:38:15.608194Z",
"ended_on": "2021-06-03T15:39:03.134378Z",
"status": "active"
},
{
"name": "initialize",
"started_on": null,
"ended_on": null,
"status": "idle"
},
{
"name": "clone_repo",
"started_on": null,
"ended_on": null,
"status": "idle"
},
{
"name": "build",
"started_on": null,
"ended_on": null,
"status": "idle"
},
{
"name": "deploy",
"started_on": null,
"ended_on": null,
"status": "idle"
}
],
"build_config": {
"build_command": "npm run build",
"destination_dir": "build",
"root_dir": "/",
"web_analytics_tag": "cee1c73f6e4743d0b5e6bb1a0bcaabcc",
"web_analytics_token": "021e1057c18547eca7b79f2516f06o7x"
},
"source": {
"type": "github",
"config": {
"owner": "cloudflare",
"repo_name": "ninjakittens",
"production_branch": "main",
"pr_comments_enabled": true,
"deployments_enabled": true
}
}
}
},
"result_info": {
"page": 1,
"per_page": 100,
"count": 1,
"total_count": 1
}
}Here’s another quick example using the API to rollback to a previous deployment:
Request (example)
curl -X POST "https://api.cloudflare.com/client/v4/accounts/{account_id}/pages/projects/{project_name}/deployments/{deployment_id}/rollback" \
-H "X-Auth-Email: {email}" \
-H "X-Auth-Key: {auth_key"Response (example)
{
"success": true,
"errors": [],
"messages": [],
"result": {
"id": "f64788e9-fccd-4d4a-a28a-cb84f88f6",
"short_id": "f64788e9",
"project_id": "7b162ea7-7367-4d67-bcde-1160995d5",
"project_name": "ninjakittens",
"environment": "preview",
"url": "https://f64788e9.ninjakittens.pages.dev",
"created_on": "2021-03-09T00:55:03.923456Z",
"modified_on": "2021-03-09T00:58:59.045655",
"aliases": [
"https://branchname.projectname.pages.dev"
],
"latest_stage": {
"name": "deploy",
"started_on": "2021-03-09T00:55:03.923456Z",
"ended_on": "2021-03-09T00:58:59.045655",
"status": "success"
},
"env_vars": {
"BUILD_VERSION": {
"value": "3.3"
},
"ENV": {
"value": "STAGING"
}
},
"deployment_trigger": {
"type": "ad_hoc",
"metadata": {
"branch": "main",
"commit_hash": "ad9ccd918a81025731e10e40267e11273a263421",
"commit_message": "Update index.html"
}
},
"stages": [
{
"name": "queued",
"started_on": "2021-06-03T15:38:15.608194Z",
"ended_on": "2021-06-03T15:39:03.134378Z",
"status": "active"
},
{
"name": "initialize",
"started_on": null,
"ended_on": null,
"status": "idle"
},
{
"name": "clone_repo",
"started_on": null,
"ended_on": null,
"status": "idle"
},
{
"name": "build",
"started_on": null,
"ended_on": null,
"status": "idle"
},
{
"name": "deploy",
"started_on": null,
"ended_on": null,
"status": "idle"
}
],
"build_config": {
"build_command": "npm run build",
"destination_dir": "build",
"root_dir": "/",
"web_analytics_tag": "cee1c73f6e4743d0b5e6bb1a0bcaabcc",
"web_analytics_token": "021e1057c18547eca7b79f2516f06o7x"
},
"source": {
"type": "github",
"config": {
"owner": "cloudflare",
"repo_name": "ninjakittens",
"production_branch": "main",
"pr_comments_enabled": true,
"deployments_enabled": true
}
}
}
}Try out an API request with one of your projects by replacing {account_id}, {deployment_id},{email}, and {auth_key}. You can find your account_id in the URL address bar by navigating to the Cloudflare Dashboard. (Ex: 41643ed677c7c7gba4x463c4zdb9563c).
Refer to the API documentation for a full breakdown of the object types and endpoints.
Using the Pages API on Workers
The Pages API is even more powerful and simple to use with Cloudflare Workers: the easiest way to deploy serverless functions globally. Below are three ways you can use the Pages API on Workers.
1. Triggering a new build every hour: Suppose you have a CMS that pulls data from live sources to compile a static output. You can keep the static content as fresh as possible by triggering new builds periodically using the API. This is easy to do on Workers using Cron Triggers, so let’s walk through an example.
First, let’s create a new Worker by navigating to workers.new. If you haven’t used Workers before, feel free to go through the getting started guide to learn more. However, you’ll need to have set up a Pages project to follow along. Next, you can copy and paste this template for the new worker. Then, customize the values such as {account_id}, {project_name}, {auth_key}, and {your_email}.
const endpoint = "https://api.cloudflare.com/client/v4/accounts/{account_id}/pages/projects/{project_name}/deployments";
const email = "{your_email}";
addEventListener("scheduled", (event) => {
event.waitUntil(handleScheduled(event.scheduledTime));
});
async function handleScheduled(request) {
const init = {
method: "POST",
headers: {
"content-type": "application/json;charset=UTF-8",
"X-Auth-Email": email,
"X-Auth-Key": API_KEY,
//We recommend you store API keys as secrets using the Workers dashboard or using Wrangler as documented here https://developers.cloudflare.com/workers/cli-wrangler/commands#secret
},
};
const response = await fetch(endpoint, init);
return new Response(200);
}To finish configuring the script, click the back arrow near the top left of the window and click on the settings tab. Then, set an environment variable “API_KEY” with the value of your Cloudflare Global key and click “Encrypt” and then “Save”.
The script just makes a POST request to the deployments' endpoint to trigger a new build. Click “Quick edit” to go back to the code editor to finish testing the script. You can test out your configuration and make a request by clicking on the “Trigger scheduled event” button in the “Schedule” tab near the tabs saying “HTTP” and “Preview”. You should see a new queued build on your Project through the Pages dashboard. Now, you can click “Save and Deploy” to publish your work. Finally, back to the worker settings page by clicking the back arrow near the top left of the window.
All that’s left to do is set a cron trigger to periodically run this Worker on the “Triggers tab”. Click on “Add Cron Trigger”.
Next, we can input “0 * * * *” to trigger the build every hour.
Finally, click save and your automation using the Pages API will trigger a new build every hour.
2. Deleting old deployments after a week: Pages hosts and serves all project deployments on preview links. Suppose you want to keep your project relatively private and prevent access to old deployments. You can use the API to delete deployments after a month so that they are no longer public online. This is easy to do on Workers using Cron Triggers.
3. Sharing project information: Imagine you are working on a development team using Pages to build our websites. You probably want an easy way to share deployment preview links and build status without having to share Cloudflare accounts. Using the API, you can easily share project information, including deployment status and preview links, and serve this content as HTML from a Cloudflare Worker.
Find the code snippets for all three examples here.
Conclusion
We will continue making the API more powerful with features such as supporting prebuilt deployments in the future. We are excited to see what you build with the API and hope you enjoy using rollbacks. At Cloudflare, we are committed to building the best developer experience on Pages, and we always appreciate hearing your feedback. Come chat with us and share more feedback on the Workers Discord (We have a dedicated #pages-help channel!).