Create a GitHub Pages site - GitHub v3 REST API

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

To use this endpoint, you must be a repository administrator, maintainer, or have the 'manage GitHub Pages settings' permission. A token with the repo scope or Pages write permission is required. GitHub Apps must have the administration:write and pages:write permissions.

curl --location --request POST 'https://api.github.com/repos///pages' \ --header 'Content-Type: application/json' \ --data-raw '{ "source": { "branch": "main", "path": "/docs" } }'

{ "build_type": "legacy", "cname": "example.com", "custom_404": false, "html_url": "https://example.com", "https_certificate": { "description": "Certificate is approved", "domains": [ "example.com", "www.example.com" ], "expires_at": "2019-08-24", "state": "approved" }, "https_enforced": true, "pending_domain_unverified_at": "2019-08-24T14:15:22Z", "protected_domain_state": "pending", "public": true, "source": { "branch": "string", "path": "string" }, "status": "built", "url": "https://api.github.com/repos/github/hello-world/pages" }

Request

Path Params

owner

string

required

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

repo

string

required

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

Body Params application/json

optional

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

Any of

object | null

build_type

enum<string>

optional

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

Allowed values:

legacyworkflow

source

object

required

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

Examples

Responses

🟢201Response

application/json

Body

The configuration for GitHub Pages for a repository.

build_type

enum<string> | enum<null>

optional

The process in which the Page will be built.

Allowed values:

legacyworkflow

Example:

legacy

cname

string | null

required

The Pages site's custom domain

Example:

example.com

custom_404

boolean

required

Whether the Page has a custom 404 page.

Default:

false

Example:

false

html_url

string <uri>

optional

The web address the Page can be accessed from.

Example:

https://example.com

https_certificate

object (Pages Https Certificate)

optional

description

string

required

Example:

Certificate is approved

domains

array[string]

required

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

Example:

["example.com","www.example.com"]

expires_at

string <date>

optional

state

enum<string>

required

Allowed values:

newauthorization_createdauthorization_pendingauthorizedauthorization_revokedissueduploadedapprovederroredbad_authzdestroy_pendingdns_changed

Example:

approved

https_enforced

boolean

optional

Whether https is enabled on the domain

Example:

true

pending_domain_unverified_at

string <date-time> | null

optional

The timestamp when a pending domain becomes unverified.

protected_domain_state

enum<string> | enum<null>

optional

The state if the domain is verified

Allowed values:

pendingverifiedunverified

Example:

pending

public

boolean

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.

Example:

true

source

object (Pages Source Hash)

optional

branch

string

required

path

string

required

status

enum<string> | enum<null>

required

The status of the most recent build of the Page.

Allowed values:

builtbuildingerrored

Example:

built

url

string <uri>

required

The API address for accessing this Page resource.

Example:

https://api.github.com/repos/github/hello-world/pages

🟠409409

🟠422422