Skip to content
forgit api docs

Create a GitHub Pages site

POST
/repos/{owner}/{repo}/pages

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

The authenticated user must be a repository administrator, maintainer, or have the ‘manage GitHub Pages settings’ permission.

OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint.

API method documentation

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “ Path Parameters ”
owner
required
string

The account owner of the repository. The name is not case sensitive.

repo
required
string

The name of the repository without the .git extension. The name is not case sensitive.

Request Body required

Section titled “ Request Body required ”
Media type application/json
Any of:

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

object
build_type

The process in which the Page will be built. Possible values are "legacy" and "workflow".

string
Allowed values: legacy workflow
source
required

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

object
branch
required

The repository branch used to publish your site’s source files.

string
path

The repository directory that includes the source files for the Pages site. Allowed paths are / or /docs. Default: /

string
default: /
Allowed values: / /docs
Examples
Example default 
{
  "source": {
    "branch": "main",
    "path": "/docs"
  }
}

Responses

Section titled “ Responses ”

201

Section titled “ 201 ”

Response

Media type application/json
GitHub Pages

The configuration for GitHub Pages for a repository.

object
url
required

The API address for accessing this Page resource.

string format: uri
status
required

The status of the most recent build of the Page.

string
nullable
Allowed values: built building errored
cname
required

The Pages site’s custom domain

string
nullable
protected_domain_state

The state if the domain is verified

string
nullable
Allowed values: pending verified unverified
pending_domain_unverified_at

The timestamp when a pending domain becomes unverified.

string format: date-time
nullable
custom_404
required

Whether the Page has a custom 404 page.

boolean
html_url

The web address the Page can be accessed from.

string format: uri
build_type

The process in which the Page will be built.

string
nullable
Allowed values: legacy workflow
source
Pages Source Hash
object
branch
required
string
path
required
string
public
required

Whether the GitHub Pages site is publicly visible. If 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.

boolean
https_certificate
Pages Https Certificate
object
state
required
string
Allowed values: new authorization_created authorization_pending authorized authorization_revoked issued uploaded approved errored bad_authz destroy_pending dns_changed
description
required
string
domains
required

Array of the domain set and its alternate name (if it is configured)

Array<string>
expires_at
string format: date
https_enforced

Whether https is enabled on the domain

boolean
Examples
Example default 
{
  "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,
  "pending_domain_unverified_at": "2024-04-30T19:33:31Z",
  "protected_domain_state": "verified",
  "https_certificate": {
    "state": "approved",
    "description": "Certificate is approved",
    "domains": [
      "developer.github.com"
    ],
    "expires_at": "2021-05-22"
  },
  "https_enforced": true
}

409

Section titled “ 409 ”

Conflict

Media type application/json
Basic Error

Basic Error

object
message
string
documentation_url
string
url
string
status
string
Example generated 
{
  "message": "example",
  "documentation_url": "example",
  "url": "example",
  "status": "example"
}

422

Section titled “ 422 ”

Validation failed, or the endpoint has been spammed.

Media type application/json
Validation Error

Validation Error

object
message
required
string
documentation_url
required
string
errors
Array<object>
object
resource
string
field
string
message
string
code
required
string
index
integer
value
One of:
string
nullable
Example generated 
{
  "message": "example",
  "documentation_url": "example",
  "errors": [
    {
      "resource": "example",
      "field": "example",
      "message": "example",
      "code": "example",
      "index": 1,
      "value": [
        "example"
      ]
    }
  ]
}