GitHub Actions Get Pages site failed in configure-pages

By Kaveh Alemi·Latchkey

A GitHub Actions Get Pages site failed error comes from one REST call: the actions/configure-pages step asked for the repository Pages site and the API answered 404. What happens next is decided by the enablement input, which defaults to false, and by which token you handed the action.

What this error means

The deploy workflow dies in its first real step, before anything is built. The annotation names the Setup Pages step and carries two lines. The first is a sentence the action writes itself, telling you to verify that Pages is enabled and configured to build using GitHub Actions. The second is the HTTP error that sentence is wrapping, and it is the line with the diagnosis in it. Not Found means the repository has no Pages site at all, the ordinary state of a repository that has never deployed one. A 403 in the same position means the call was understood and refused, which is a token problem rather than a configuration one. From version 5 the action appends that HTTP message to its own sentence rather than logging it underneath.

Get Pages site failed. Please verify that the repository has Pages enabled and configured to build using GitHub Actions, or consider exploring the `enablement` parameter for this action.
HttpError: Not Found

A minimal workflow that produces it

This file is written for this page and has never been run. The steps are the ones from GitHub's own Pages starter workflow, with the permissions block that workflow ships cut back to contents: read, pointed at a public repository whose Pages site has never been created. The third step asks the API for a site that does not exist, and because enablement is left at its default the action turns that answer into a failed job. Public matters here: the read is documented as needing pages read, waived for public resources, so the same file on a private repository can answer 403 rather than 404.

name: pages
on:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/configure-pages@v6
      - uses: actions/upload-pages-artifact@v5
        with:
          path: ./_site
      - uses: actions/deploy-pages@v5

Common causes

The repository has never had a Pages site

This is nearly all of them. A Pages site has to exist before a workflow can deploy to it, and pushing a workflow file does not create one, so the API answers 404. It is why this error shows up on the first run of a new repository, on a fork and on a repository made from a template, and never again once a deployment has landed.

enablement is true but the token cannot create a site

Setting enablement: true moves the failure one call later rather than fixing it, unless you change the token too. The action says so in its own action.yml: the option "requires a token other than GITHUB_TOKEN to be provided", or a GitHub App with administration:write and pages:write. With the default token you get the warning, then Create Pages site failed.

The token cannot read the repository settings

A 403 rather than a 404 means the call was refused, not that the resource is missing. A fine-grained token without repository administration read, a GitHub App whose installation misses the repository, or an organization policy restricting Pages all land here, and the action reports every one of them with the same sentence.

Pages is not available for this repository at all

On a private repository under GitHub Free there is no Pages site to enable, so there is nothing to find and nothing enablement: true can create. The same is true where an organization administrator has turned Pages off. In our experience this is the rarest of the four and the likeliest to be mistaken for a token problem.

How to fix it

Read the second line before you change anything

1. Open the failed run and expand the Setup Pages step.
2. Find the HTTP status after the sentence: on version 5 and later it is on the same line, after Error:.
3. Not Found means no site exists, and the fix is to create one.
4. A 403 means the site may well exist and the token is the problem, so changing enablement will not help.

Create the site once, from your own terminal

The cheapest fix, and the one that leaves the workflow alone. One authenticated call creates the site with the Actions build type, which is what enablement: true would have done, except that your own credentials are allowed to and the job token is not. Re-run the workflow afterwards.

gh api -X POST repos/OWNER/REPO/pages \
  -f "build_type=workflow"

gh api repos/OWNER/REPO/pages --jq .build_type

Or let the first run create it, with a token that can

If the workflow has to be self-sufficient, for example because it is a template others will copy, set enablement: true and give the step a token allowed to administer the repository. The token input defaults to the job token, so it has to be set explicitly.

      - uses: actions/configure-pages@v6
        with:
          enablement: true
          token: ${{ secrets.PAGES_ADMIN_TOKEN }}

Give the deploy job the permissions the deploy actually needs

Once the site exists, the next failure in line is the deployment, which needs permissions the illustrative workflow does not declare. The corrected file below is that workflow with the permissions block from GitHub's own Pages starter workflow, the environment the deployment reports into, and a concurrency group. It runs as written. If you took the previous route instead, the two lines from it go on the same configure-pages step.

name: pages
on:
  push:
    branches: [main]

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/checkout@v7
      - uses: actions/configure-pages@v6
      - uses: actions/upload-pages-artifact@v5
        with:
          path: ./_site
      - id: deployment
        uses: actions/deploy-pages@v5

One call, and enablement decides what a 404 costs

The action does very little. Its findOrCreatePagesSite function calls repos.getPages, and the whole of the error handling hangs off whether that call threw. The two branches below are the action source, and they explain why the same repository state produces a red job for one person and a warning for another.

With enablement false, the default the action declares in its own action.yml, the failure is logged with core.error and rethrown, and the entry file calls core.setFailed. With enablement true the same failure is only a warning: the action falls through to repos.createPagesSite with build_type: workflow, and a 409 there is treated as success.

core.error(
  `Get Pages site failed. Please verify that the repository has Pages enabled and configured to build using GitHub Actions, or consider exploring the \`enablement\` parameter for this action. Error: ${error.message}`
)

core.warning(`Get Pages site failed. Error: ${error.message}`)

The build source is not what returns the 404

The old advice on this error was to check that the Pages source says GitHub Actions rather than a branch. That is good advice for a site deploying the wrong content and the wrong diagnosis here: getPagesSite reads the site object and never looks at its build_type, so a repository publishing from a branch returns 200 and walks straight past this step. Only a repository with no Pages site at all returns 404.

The permissions advice has the same problem. configure-pages reads; it is actions/deploy-pages that writes, and that action says so itself. On a 403 it appends Ensure GITHUB_TOKEN has permission and then "pages: write"., and on a 404 a link to the repository Pages settings page.

Two other things put a 404 there. A repository whose plan does not include Pages has no site to find: the docs limit Pages to public repositories on GitHub Free, and to public and private repositories on GitHub Pro, Team, Enterprise Cloud and Enterprise Server. And a scoped token or an organization policy can hide the read, which gives a 403 rather than a 404.

Why there is no recorded run on this page

Other failure pages here carry a log from a job we ran. This one cannot: the failure is a property of a repository, not of a runner, and it needs a repository with no Pages site, so creating one to film it would destroy the condition being filmed. Nothing in it is transient either: the API answers 404 every time, so no retry changes the outcome and there is nothing for a runner to repair.

How to prevent it

• Create the Pages site as part of repository setup, not as part of the first deploy.
• Keep enablement at its default unless the workflow ships with a token that can administer.
• Declare pages: write and id-token: write on the deploy job, and nothing else.
• Pin the three Pages actions to majors that were released together and move them together.

Frequently asked questions

Related guides

References

• actions/configure-pages: the action metadata and the enablement input
• An issue report quoting the Get Pages site failed log in full
• A repository failing every Pages run with enablement left false
• GitHub Pages: configuring a publishing source for your site
• REST API: get a GitHub Pages site, and the token permission that read needs
• GitHub Actions documentation