Pages

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 /repos/{owner}/{repo}/pages

curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/repos/octocat/hello-world/pages

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

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
}

Status: 404 Not Found

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

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

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

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"