Pages - GitHub Docs

The GitHub Pages API retrieves information about your GitHub Pages configuration, and the statuses of your builds. Information about the site and the builds can only be accessed by authenticated owners, even if the websites are public. For more information, see "About GitHub Pages."

In GitHub Pages API endpoints with a status key in their response, the value can be one of:

null: The site has yet to be built.
queued: The build has been requested but not yet begun.
building:The build is in progress.
built: The site has been built.
errored: Indicates an error occurred during the build.

In GitHub Pages API endpoints that return GitHub Pages site information, the JSON responses include these fields:

html_url: The absolute URL (including scheme) of the rendered Pages site. For example, https://username.github.io.
source: An object that contains the source branch and directory for the rendered Pages site. This includes:
- branch: The repository branch used to publish your site's source files. For example, main or gh-pages.
- path: The repository directory from which the site publishes. Will be either / or /docs.

Get a GitHub Pages site

get /repos/{owner}/{repo}/pages

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`owner`	string	path
`repo`	string	path

Code samples

Shell

 curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/pages

JavaScript (@octokit/core.js)

 await octokit.request('GET /repos/{owner}/{repo}/pages', {
  owner: 'octocat',
  repo: 'hello-world'
})

Response

 Status: 200 OK

 {
  "url": "https://api.github.com/repos/github/developer.github.com/pages",
  "status": "built",
  "cname": "developer.github.com",
  "custom_404": false,
  "html_url": "https://developer.github.com",
  "source": {
    "branch": "master",
    "path": "/"
  },
  "public": true,
  "https_certificate": {
    "state": "approved",
    "description": "Certificate is approved",
    "domains": [
      "developer.github.com"
    ],
    "expires_at": "2021-05-22"
  },
  "https_enforced": true
}

Resource not found

 Status: 404 Not Found

Notes

Works with GitHub Apps

Create a GitHub Pages site

Configures a GitHub Pages site. For more information, see "About GitHub Pages."

post /repos/{owner}/{repo}/pages

Parameters

Name Type In Description

accept

string

header

Setting toapplication/vnd.github.v3+json is recommended.

owner string path

repo string path

source

object

body

Required. The source branch and directory used to publish your Pages site.

Properties of thesourceobject

Name (Type)	Description
`branch` (string)	Required. The repository branch used to publish your site's source files.
`path` (string)	The repository directory that includes the source files for the Pages site. Allowed paths are `/` or `/docs`. Default: `/`

Code samples

Shell

 curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/pages \
  -d '{"source":{"branch":"branch","path":"path"}}'

JavaScript (@octokit/core.js)

 await octokit.request('POST /repos/{owner}/{repo}/pages', {
  owner: 'octocat',
  repo: 'hello-world',
  source: {
    branch: 'branch',
    path: 'path'
  }
})

Response

 Status: 201 Created

 {
  "url": "https://api.github.com/repos/github/developer.github.com/pages",
  "status": "built",
  "cname": "developer.github.com",
  "custom_404": false,
  "html_url": "https://developer.github.com",
  "source": {
    "branch": "master",
    "path": "/"
  },
  "public": true,
  "https_certificate": {
    "state": "approved",
    "description": "Certificate is approved",
    "domains": [
      "developer.github.com"
    ],
    "expires_at": "2021-05-22"
  },
  "https_enforced": true
}

Conflict

 Status: 409 Conflict

Validation failed

 Status: 422 Unprocessable Entity

Notes

Works with GitHub Apps

Update information about a GitHub Pages site

Updates information for a GitHub Pages site. For more information, see "About GitHub Pages.

put /repos/{owner}/{repo}/pages

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`owner`	string	path
`repo`	string	path
`cname`	string or null	body	Specify a custom domain for the repository. Sending a `null` value will remove the custom domain. For more about custom domains, see "Using a custom domain with GitHub Pages."
`https_enforced`	boolean	body	Specify whether HTTPS should be enforced for the repository.
`public`	boolean	body	Configures access controls for the GitHub Pages site. If public is set to `true`, the site is accessible to anyone on the internet. If set to `false`, the site will only be accessible to users who have at least `read` access to the repository that published the site. This includes anyone in your Enterprise if the repository is set to `internal` visibility. This feature is only available to repositories in an organization on an Enterprise plan.
`source`		body

Code samples

Shell

 curl \
  -X PUT \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/pages \
  -d '{"cname":"cname"}'

JavaScript (@octokit/core.js)

 await octokit.request('PUT /repos/{owner}/{repo}/pages', {
  owner: 'octocat',
  repo: 'hello-world',
  cname: 'cname'
})

Response

 Status: 204 No Content

Bad Request

 Status: 400 Bad Request

Validation failed

 Status: 422 Unprocessable Entity

Notes

Works with GitHub Apps

Delete a GitHub Pages site

delete /repos/{owner}/{repo}/pages

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`owner`	string	path
`repo`	string	path

Code samples

Shell

 curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/pages

JavaScript (@octokit/core.js)

 await octokit.request('DELETE /repos/{owner}/{repo}/pages', {
  owner: 'octocat',
  repo: 'hello-world'
})

Response

 Status: 204 No Content

Resource not found

 Status: 404 Not Found

Validation failed

 Status: 422 Unprocessable Entity

Notes

Works with GitHub Apps

List GitHub Pages builds

get /repos/{owner}/{repo}/pages/builds

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`owner`	string	path
`repo`	string	path
`per_page`	integer	query	Results per page (max 100) Default: `30`
`page`	integer	query	Page number of the results to fetch. Default: `1`

Code samples

Shell

 curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/pages/builds

JavaScript (@octokit/core.js)

 await octokit.request('GET /repos/{owner}/{repo}/pages/builds', {
  owner: 'octocat',
  repo: 'hello-world'
})

Response

 Status: 200 OK

 [
  {
    "url": "https://api.github.com/repos/github/developer.github.com/pages/builds/5472601",
    "status": "built",
    "error": {
      "message": null
    },
    "pusher": {
      "login": "octocat",
      "id": 1,
      "node_id": "MDQ6VXNlcjE=",
      "avatar_url": "https://github.com/images/error/octocat_happy.gif",
      "gravatar_id": "",
      "url": "https://api.github.com/users/octocat",
      "html_url": "https://github.com/octocat",
      "followers_url": "https://api.github.com/users/octocat/followers",
      "following_url": "https://api.github.com/users/octocat/following{/other_user}",
      "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
      "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
      "organizations_url": "https://api.github.com/users/octocat/orgs",
      "repos_url": "https://api.github.com/users/octocat/repos",
      "events_url": "https://api.github.com/users/octocat/events{/privacy}",
      "received_events_url": "https://api.github.com/users/octocat/received_events",
      "type": "User",
      "site_admin": false
    },
    "commit": "351391cdcb88ffae71ec3028c91f375a8036a26b",
    "duration": 2104,
    "created_at": "2014-02-10T19:00:49Z",
    "updated_at": "2014-02-10T19:00:51Z"
  }
]

Notes

Works with GitHub Apps

Request a GitHub Pages build

You can request that your site be built from the latest revision on the default branch. This has the same effect as pushing a commit to your default branch, but does not require an additional commit. Manually triggering page builds can be helpful when diagnosing build warnings and failures.

Build requests are limited to one concurrent build per repository and one concurrent build per requester. If you request a build while another is still in progress, the second request will be queued until the first completes.

post /repos/{owner}/{repo}/pages/builds

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`owner`	string	path
`repo`	string	path

Code samples

Shell

 curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/pages/builds

JavaScript (@octokit/core.js)

 await octokit.request('POST /repos/{owner}/{repo}/pages/builds', {
  owner: 'octocat',
  repo: 'hello-world'
})

Response

 Status: 201 Created

 {
  "url": "https://api.github.com/repos/github/developer.github.com/pages/builds/latest",
  "status": "queued"
}

Notes

Works with GitHub Apps

Get latest Pages build

get /repos/{owner}/{repo}/pages/builds/latest

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`owner`	string	path
`repo`	string	path

Code samples

Shell

 curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/pages/builds/latest

JavaScript (@octokit/core.js)

 await octokit.request('GET /repos/{owner}/{repo}/pages/builds/latest', {
  owner: 'octocat',
  repo: 'hello-world'
})

Response

 Status: 200 OK

 {
  "url": "https://api.github.com/repos/github/developer.github.com/pages/builds/5472601",
  "status": "built",
  "error": {
    "message": null
  },
  "pusher": {
    "login": "octocat",
    "id": 1,
    "node_id": "MDQ6VXNlcjE=",
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "gravatar_id": "",
    "url": "https://api.github.com/users/octocat",
    "html_url": "https://github.com/octocat",
    "followers_url": "https://api.github.com/users/octocat/followers",
    "following_url": "https://api.github.com/users/octocat/following{/other_user}",
    "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
    "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
    "organizations_url": "https://api.github.com/users/octocat/orgs",
    "repos_url": "https://api.github.com/users/octocat/repos",
    "events_url": "https://api.github.com/users/octocat/events{/privacy}",
    "received_events_url": "https://api.github.com/users/octocat/received_events",
    "type": "User",
    "site_admin": false
  },
  "commit": "351391cdcb88ffae71ec3028c91f375a8036a26b",
  "duration": 2104,
  "created_at": "2014-02-10T19:00:49Z",
  "updated_at": "2014-02-10T19:00:51Z"
}

Notes

Works with GitHub Apps

Get GitHub Pages build

get /repos/{owner}/{repo}/pages/builds/{build_id}

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`owner`	string	path
`repo`	string	path
`build_id`	integer	path

Code samples

Shell

 curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/pages/builds/42

JavaScript (@octokit/core.js)

 await octokit.request('GET /repos/{owner}/{repo}/pages/builds/{build_id}', {
  owner: 'octocat',
  repo: 'hello-world',
  build_id: 42
})

Response

 Status: 200 OK

 {
  "url": "https://api.github.com/repos/github/developer.github.com/pages/builds/5472601",
  "status": "built",
  "error": {
    "message": null
  },
  "pusher": {
    "login": "octocat",
    "id": 1,
    "node_id": "MDQ6VXNlcjE=",
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "gravatar_id": "",
    "url": "https://api.github.com/users/octocat",
    "html_url": "https://github.com/octocat",
    "followers_url": "https://api.github.com/users/octocat/followers",
    "following_url": "https://api.github.com/users/octocat/following{/other_user}",
    "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
    "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
    "organizations_url": "https://api.github.com/users/octocat/orgs",
    "repos_url": "https://api.github.com/users/octocat/repos",
    "events_url": "https://api.github.com/users/octocat/events{/privacy}",
    "received_events_url": "https://api.github.com/users/octocat/received_events",
    "type": "User",
    "site_admin": false
  },
  "commit": "351391cdcb88ffae71ec3028c91f375a8036a26b",
  "duration": 2104,
  "created_at": "2014-02-10T19:00:49Z",
  "updated_at": "2014-02-10T19:00:51Z"
}

Notes

Works with GitHub Apps

Get a DNS health check for GitHub Pages

Gets a health check of the DNS settings for the CNAME record configured for a repository's GitHub Pages.

The first request to this endpoint returns a 202 Accepted status and starts an asynchronous background task to get the results for the domain. After the background task completes, subsequent requests to this endpoint return a 200 OK status with the health check results in the response.

Users must have admin or owner permissions. GitHub Apps must have the pages:write and administration:write permission to use this endpoint.

get /repos/{owner}/{repo}/pages/health

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`owner`	string	path
`repo`	string	path

Code samples

Shell

 curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/pages/health

JavaScript (@octokit/core.js)

 await octokit.request('GET /repos/{owner}/{repo}/pages/health', {
  owner: 'octocat',
  repo: 'hello-world'
})

Response

 Status: 200 OK

 {
  "domain": {
    "host": "example.com",
    "uri": "http://example.com/",
    "nameservers": "default",
    "dns_resolves": true,
    "is_proxied": false,
    "is_cloudflare_ip": false,
    "is_fastly_ip": false,
    "is_old_ip_address": false,
    "is_a_record": true,
    "has_cname_record": false,
    "has_mx_records_present": false,
    "is_valid_domain": true,
    "is_apex_domain": true,
    "should_be_a_record": true,
    "is_cname_to_github_user_domain": false,
    "is_cname_to_pages_dot_github_dot_com": false,
    "is_cname_to_fastly": false,
    "is_pointed_to_github_pages_ip": true,
    "is_non_github_pages_ip_present": false,
    "is_pages_domain": false,
    "is_served_by_pages": true,
    "is_valid": true,
    "reason": null,
    "responds_to_https": true,
    "enforces_https": true,
    "https_error": null,
    "is_https_eligible": true,
    "caa_error": null
  },
  "alt_domain": {
    "host": "www.example.com",
    "uri": "http://www.example.com/",
    "nameservers": "default",
    "dns_resolves": true,
    "is_proxied": false,
    "is_cloudflare_ip": false,
    "is_fastly_ip": false,
    "is_old_ip_address": false,
    "is_a_record": true,
    "has_cname_record": false,
    "has_mx_records_present": false,
    "is_valid_domain": true,
    "is_apex_domain": true,
    "should_be_a_record": true,
    "is_cname_to_github_user_domain": false,
    "is_cname_to_pages_dot_github_dot_com": false,
    "is_cname_to_fastly": false,
    "is_pointed_to_github_pages_ip": true,
    "is_non_github_pages_ip_present": false,
    "is_pages_domain": false,
    "is_served_by_pages": true,
    "is_valid": true,
    "reason": null,
    "responds_to_https": true,
    "enforces_https": true,
    "https_error": null,
    "is_https_eligible": true,
    "caa_error": null
  }
}

Empty response

 Status: 202 Accepted

Custom domains are not available for GitHub Pages

 Status: 400 Bad Request

Resource not found

 Status: 404 Not Found

There isn't a CNAME for this page

 Status: 422 Unprocessable Entity

Notes

Works with GitHub Apps

Feb	MAR	Apr
	13
2021	2022	2023