# GitHub Actions Get Pages site failed in configure-pages

> A GitHub Actions Get Pages site failed error is a 404 from the Pages API, not a permissions problem. Read the enablement input before you swap tokens.

Source: https://latchkey.dev/learn/github-actions/gha-configure-pages-not-enabled  
Updated: 2026-09-20

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.

```Actions log, Setup Pages step, quoted from TechWorkshop-L300-GitHub-Copilot-and-platform#7 (configure-pages v4)
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
```

## 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.

```Terminal
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.

```.github/workflows/pages.yml (illustrative)
- 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.

```.github/workflows/pages.yml, corrected (illustrative)
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
```

## 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.

## 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.

```.github/workflows/pages.yml (illustrative)
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
```

## 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.

```actions/configure-pages, src/api-client.js
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}`)
```

| `enablement` | What the log says | What the job does |
| --- | --- | --- |
| `false` (the default) | Get Pages site failed, as an error annotation | Fails on the Setup Pages step |
| `true`, default token | Get Pages site failed as a warning, then Create Pages site failed | Fails one call later |
| `true`, token that can administer | Get Pages site failed as a warning only | Creates the site and continues |

## 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.

| Step | What it does | What it needs |
| --- | --- | --- |
| `actions/configure-pages` | Reads, or optionally creates, the Pages site | A token that can administer the repository, only when `enablement` is true |
| `actions/upload-pages-artifact` | Uploads the site as an artifact | Nothing beyond the default job token |
| `actions/deploy-pages` | Creates the Pages deployment | `pages: write` and `id-token: write` on the job |

> A run that gets past this step and then fails on the upload is a different error: see [actions/upload-artifact no files were found](/learn/github-actions/upload-artifact-no-files-were-found-v4).

## 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.

## FAQ

### Does enabling GitHub Pages fix Get Pages site failed?

Yes, when the second line says Not Found. The step is asking for a Pages site and there is not one, so creating it is the whole fix: set the source to GitHub Actions under Settings then Pages, or make the same change with one `gh api` call, and re-run. If the second line says 403, enabling changes nothing.

### What does enablement: true do in actions/configure-pages?

It turns the failed read into a warning and lets the action create the site itself, with the Actions build type. The catch is in the action metadata: the option "requires a token other than `GITHUB_TOKEN` to be provided", meaning a token with the `repo` scope or Pages write. Left with the default token it moves the failure to the next call.

### Do I need pages: write for actions/configure-pages?

No. That permission belongs to `actions/deploy-pages`, which creates the deployment and says so in its own error text. Adding it to fix a configure-pages 404 changes nothing, which is why this error is often reported as fixed by a permissions block that was needed for a different reason.

### Why does configure-pages fail when my site builds from a branch?

It usually does not. The action reads the Pages site object and ignores its build type, so a repository publishing from a branch returns 200 here and the step passes. If one is failing, look further down the run: the deployment is where the source setting is enforced.

## References

- [actions/configure-pages: the action metadata and the enablement input](https://github.com/actions/configure-pages)
- [An issue report quoting the Get Pages site failed log in full](https://github.com/cajetzer-zava-lab/TechWorkshop-L300-GitHub-Copilot-and-platform/issues/7)
- [A repository failing every Pages run with enablement left false](https://github.com/HolobiomicsLab/asb-skill-collections/issues/52)
- [GitHub Pages: configuring a publishing source for your site](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site)
- [REST API: get a GitHub Pages site, and the token permission that read needs](https://docs.github.com/en/rest/pages/pages#get-a-github-pages-site)

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt