GitHub: Create a Git Hub Pages site

← Repos operations · Get started

Operation github.repos_create_pages_site

Provider route: POST /repos/{owner}/{repo}/pages. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/github with npm, or alter-sdk-github with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { GitHubIntegration } from "@alter-ai/github";

async function execute(input: Parameters<GitHubIntegration["repos"]["reposCreatePagesSite"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new GitHubIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.repos.reposCreatePagesSite(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_github import GitHubIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = GitHubIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.repos.repos_create_pages_site(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
path	object	Required within parent	Additional keys: not allowed
path.owner	string	Required within parent
path.repo	string	Required within parent
body	JSON	Required within parent
body (anyOf 1)	object	Alternative	The source branch and directory used to publish your Pages site.
body (anyOf 1).build_type	string	Optional	The process in which the Page will be built. Possible values are `“legacy”` and `“workflow”`. One of: legacy, workflow
body (anyOf 1).source	object	Optional	The source branch and directory used to publish your Pages site.
body (anyOf 1).source.branch	string	Required within parent	The repository branch used to publish your site’s source files.
body (anyOf 1).source.path	string	Optional	The repository directory that includes the source files for the Pages site. Allowed paths are `/` or `/docs`. Default: `/` Default: / One of: /, /docs
body (anyOf 1) (anyOf 1)	JSON	Alternative
body (anyOf 1) (anyOf 2)	JSON	Alternative
body (anyOf 2)	null	Alternative

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	Model	Root	Expand Get a Git Hub Pages site — response body

Referenced models: Get a Git Hub Pages site — response body

Schemas

Get a Git Hub Pages site — response body

Field	Type	Presence	Description and constraints
$	object	Root	The configuration for GitHub Pages for a repository.
build_type	JSON	Optional
build_type (anyOf 1)	string	Alternative	The process in which the Page will be built. Known values: legacy, workflow
build_type (anyOf 2)	null	Alternative
cname	JSON	Required within parent
cname (anyOf 1)	string	Alternative	The Pages site's custom domain
cname (anyOf 2)	null	Alternative
custom_404	boolean	Required within parent	Whether the Page has a custom 404 page. Default: false
html_url	string	Optional	The web address the Page can be accessed from. Format: uri
https_certificate	Model	Optional	Expand Get a Git Hub Pages site — response body — https certificate
https_enforced	boolean	Optional	Whether https is enabled on the domain
pending_domain_unverified_at	JSON	Optional
pending_domain_unverified_at (anyOf 1)	string	Alternative	The timestamp when a pending domain becomes unverified. Format: date-time
pending_domain_unverified_at (anyOf 2)	null	Alternative
protected_domain_state	JSON	Optional
protected_domain_state (anyOf 1)	string	Alternative	The state if the domain is verified Known values: pending, verified, unverified
protected_domain_state (anyOf 2)	null	Alternative
public	boolean	Required within parent	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.
source	Model	Optional	Expand Get a Git Hub Pages site — response body — source
status	JSON	Required within parent
status (anyOf 1)	string	Alternative	The status of the most recent build of the Page. Known values: built, building, errored
status (anyOf 2)	null	Alternative
url	string	Required within parent	The API address for accessing this Page resource. Format: uri

Referenced models: Get a Git Hub Pages site — response body — https certificate, Get a Git Hub Pages site — response body — source

Get a Git Hub Pages site — response body — https certificate

Field	Type	Presence	Description and constraints
$	object	Root
description	string	Required within parent
domains	array	Required within parent	Array of the domain set and its alternate name (if it is configured)
domains[]	string	Each item
expires_at	string	Optional	Format: date
state	string	Required within parent	Known values: new, authorization_created, authorization_pending, authorized, authorization_revoked, issued, uploaded, approved, errored, bad_authz, destroy_pending, dns_changed

Get a Git Hub Pages site — response body — source

Field	Type	Presence	Description and constraints
$	object	Root
branch	string	Required within parent
path	string	Required within parent

Policy, approvals and errors

SDK function policy ID: github.repos_create_pages_site. Catalog operation: repos/create-pages-site. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Pinned headers: {"X-GitHub-Api-Version": "2026-03-10", "User-Agent": "Alter", "Accept": "application/vnd.github+json"}

Official provider source