Pages failed to deploy (HttpError: Validation Failed)

[skramm]

Select Topic Area

Question

Body

Hi,
I have some static pages, built with Pelican, but I notice that there is a deployment failure on Github pages.
The "build" step runs fine.
It used to work perfectly before (a couple of years), I don't think I've done anything significant in between.
After rerun the failed deployment with debug options, I have a HttpError: Validation Failed error:

line 60:

Creating Pages deployment with payload:
{
	"artifact_id": 4541425568,
	"pages_build_version": "1d602df7ee803f8c5b9a1800b7e1ff3e26b0ff23",
	"oidc_token": "***"
}
Error: Creating Pages deployment failed
Error: HttpError: Validation Failed
    at /home/runner/work/_actions/actions/deploy-pages/v4/node_modules/@octokit/request/dist-node/index.js:124:1
    at processTicksAndRejections (node:internal/process/task_queues:95:5)
    at createPagesDeployment (/home/runner/work/_actions/actions/deploy-pages/v4/src/internal/api-client.js:125:1)
    at Deployment.create (/home/runner/work/_actions/actions/deploy-pages/v4/src/internal/deployment.js:74:1)
    at main (/home/runner/work/_actions/actions/deploy-pages/v4/src/index.js:30:1)
Error: Error: Failed to create deployment (status: 422) with build version 1d602df7ee803f8c5b9a1800b7e1ff3e26b0ff23. Request ID 8401:23C97B:4A7F2C3:14F59FD2:69145E8C
##[debug]Node Action run completed with exit code 1
##[debug]Finishing: Deploy to GitHub Pages

And the URL on github.io returns a 404?

The status pages (https://www.githubstatus.com/) says there are no problems with Pages.
I don't understand what the problem is.
Anybody has an idea of further steps I can try?

[Musafir02]

GitHub Pages can’t read your deployment data correctly — likely a small config or build issue. Double-check your output folder, workflow config, and branch.

update your workflow to use:

- uses: actions/deploy-pages@v4

Quick fix steps:

Re-run your workflow with “Rebuild and redeploy”.
Check that the folder you deploy (output/, _site/, etc.) actually has files.
Make sure permissions: contents: write and id-token: write are in your workflow’s permissions.

[skramm]

Thanks for your answer, actually I use the Pelican provided worflow:
https://docs.getpelican.com/en/latest/tips.html#publishing-to-github-pages-using-a-custom-github-actions-workflow

jobs:
  deploy:
    uses: getpelican/pelican/.github/workflows/github_pages.yml@main
    permissions:
      contents: "read"
      pages: "write"
      id-token: "write"
    with:
      settings: "publishconf.py"
      requirements: "pelican[markdown]" 

Maybe something changed, either on the Pelican side, or on the GH side. I'll check your advices and come back here.
Thanks again!

[skramm]

Additional checks:

• I do have read + write permissions in Settings->Actions->Workflow permissions
• The build seems to be good: artifacts are produced. I downloaded manually the file, and the content is what expected: Pelican generated HTML pages.
  
• The - uses: actions/deploy-pages@v4 step is done by the Pelican provided yaml file that I use:
  https://github.com/getpelican/pelican/blob/main/.github/workflows/github_pages.yml

So it looks to me more a permission problem, but I have not clue...

For the record, my yaml file is pretty standard, used to work just out of the box! :

name: Deploy to GitHub Pages
on:
  push:
    branches: ["main"]
  workflow_dispatch:
jobs:
  deploy:
    uses: getpelican/pelican/.github/workflows/github_pages.yml@main
    permissions:
      contents: "read"
      pages: "write"
      id-token: "write"
    with:
      settings: "publishconf.py"
      requirements: "pelican[markdown]"

[skramm]

Thanks for your answer. I tried changing "contents" from "read" to "write", changed nothing, still the HttpError: Validation Failed error. The artifact indeed has the index.html page.
I'll try to contact GH support.

[skramm]

Hi @queenofcorgis , I read your page about 404 errors on GH pages
(https://github.com/orgs/community/discussions/61073 )
but it seems my case does not fit in that category (the error happens on the GH actions deploy step).
I was wondering if you have an idea of what is going on here, or if you could point me on some other direction, because I'm kind of stuck...
Thanks in advance!

[Krizzz18]

The HttpError: Validation Failed (status 422) error you're seeing is a known issue with GitHub Pages deployments, particularly affecting Pelican and other static site generators. Here's what's likely happening and how to fix it:

Root Cause

The error occurs because GitHub Pages recently made changes to how deployment artifacts are validated. The error "Failed to create deployment (status: 422)" specifically indicates that the deployment API is rejecting the artifact payload.

Common Causes:

1. Pages Deployment API Changes

GitHub Pages changed some internal validation rules. The actions/deploy-pages@v4 action might be sending deployment data in a format that doesn't pass new validation checks.

2. Pages Not Enabled Correctly

Go to your repository Settings → Pages and verify:

• Source is set to "GitHub Actions" (not "Deploy from a branch")
• If it's still set to branch deployment, switch to GitHub Actions

3. Artifact Size or Structure Issues

The artifact might exceed size limits or have an unexpected structure.

Solutions to Try:

Solution 1: Update Your Workflow to Use Latest Stable Versions

Instead of relying on Pelican's workflow, try creating your own workflow with explicit versions:

name: Deploy Pelican to GitHub Pages

on:
  push:
    branches: ["main"]
  workflow_dispatch:

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

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

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      
      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      
      - name: Install Pelican
        run: pip install 'pelican[markdown]'
      
      - name: Build site
        run: pelican content -s publishconf.py
      
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: 'output/'
  
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Solution 2: Verify Pages Settings

1. Go to Settings → Pages
2. Under "Build and deployment":
   • Source: Select "GitHub Actions"
3. Save and re-run your workflow

Solution 3: Check Repository Environment Settings

The deployment might be failing due to environment protection rules:

1. Go to Settings → Environments
2. If you have a github-pages environment:
   • Click on it
   • Check "Deployment branches" - make sure your main branch is allowed
   • Remove any deployment protection rules that might be blocking

Solution 4: Re-enable Pages

Sometimes the Pages service gets into a weird state:

1. Go to Settings → Pages
2. If Pages is enabled, disable it (select "None" as source)
3. Wait 30 seconds
4. Re-enable Pages (select "GitHub Actions" as source)
5. Re-run your workflow

Solution 5: Use actions/upload-pages-artifact@v3 Specifically

The Pelican workflow might be using a different version. The v3 of upload-pages-artifact fixed several validation issues:

- name: Upload artifact
  uses: actions/upload-pages-artifact@v3
  with:
    path: 'output/'

Debugging Steps:

1. Check artifact contents: You mentioned the artifact has index.html - good! But also verify:

   • No files over 100MB
   • Total uncompressed size under 1GB
   • No symbolic links that point outside the artifact

2. Enable debug logging: Add to your workflow:

env:
  ACTIONS_STEP_DEBUG: true

3. Inspect the artifact structure: Download the artifact and check:
   • Files are in the root level (not nested in extra folders)
   • No .git directories included

Quick Fix to Try Right Now:

Since your Pelican workflow is using a reusable workflow from getpelican/pelican, there might be an issue with that workflow. Try forking that workflow and using the explicit versions I showed above.

Alternatively, check if there's an updated version of the Pelican workflow:

• The workflow you're using: getpelican/pelican/.github/workflows/github_pages.yml@main
• They might have updated it recently

If Nothing Works:

Contact GitHub Support (https://support.github.com) with:

• Your Request ID: 8401:23C97B:4A7F2C3:14F59FD2:69145E8C
• Repository name
• Workflow run URL
• Mention "Pages deployment validation failure status 422"

This error has affected many users recently, so GitHub support should be familiar with it.

Let me know which solution works for you!

[skramm]

Thanks for your answer, I'll step through these steps and let you know. Just a question about "GitHub Pages recently made changes": you have a source on that? I'm curious, what exactly did they change (without notice, just saying |-( ). Because it just worked before, and suddenly, boom!

[skramm]

Hi @justinmayer, I notice you made a commit two weeks ago on the Pelican" Deploying to GH pages" yaml file:
getpelican/pelican@86f1f72
This GH action is documented here:
https://docs.getpelican.com/en/latest/tips.html#publishing-to-github-pages-using-a-custom-github-actions-workflow
I used that and it worked perfectly previously.
And suddenly it just fails...
Do you think my issue could be related to the change you made on the yaml file (switching from actions/upload-artifact@v3, then actions/upload-artifact@v4, then actions/upload-artifact@v5)?
(see above discussion for details)
Thanks!

[justinmayer]

It seems that recent changes in the upload-artifact action have caused a lot of problems for a lot of people. I have no problem reverting back to a previous version in the Pelican repository’s workflow if that resolves the aforementioned problems.

That said, I don’t use GitHub Pages myself, I am not the best person to ask about this. What do you think, @seanh?

[skramm]

Thanks for you answer! No, please don't revert until someone can positively assert that the problem is related to this. I haven't had time these past days to work on this, but ASAP, I'll try some other thing (maybe build locally and check if I'm able to deploy).

[seanh]

@justinmayer (Sorry for the repetitive answer across separate issues: I'm processing them one by one) We didn't uprade Pelican's workflow to upload-pages-artifact@v4 (that PR was closed without mergin: getpelican/pelican#3495). Instead, we removed upload-pages-artifact: getpelican/pelican#3502

[seanh]

I just did a quick test of the latest version of Pelican's workflow and it's working for me.

I just noticed that you're talking about recent changes to upload-artifact (which Pelican's workflow does still use) rather than to upload-pages-artifact (which it doesn't). I'm not familiar with the issues people are seeing with upload-artifact@v5 but sure, if you want to try downgrading to upload-artifact@v4 I say go for it 👍 (I would not downgrade to @v3 because it's scheduled for deprecation). We could then consider upgrading to @v5 again at some point in the future when it's had some point releases, but my guess is we will be able to stay on @v4 for quite a while.

upload-artifact's changelog for v4->v5 is quite poor but I'm not seeing any obvious reason not to downgrade back to v4.

[skramm]

Thanks for reply. Not sure I understand everything, but I assume you'll know whats the best thing to do.
Sorry, have been quite short on time lately, but I'm still willing to make my pages deploy.

[skramm]

Ok, thanks to all that have answered, I think I found the problem:
the source repo must be public!
Yes, this is indeed clearly stated here (at least today...):
https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site

If the account that owns the repository uses GitHub Free or GitHub Free for organizations, the repository must be public.

So I tried making it public and re-run the jobs, and everything was fine, pages back online.

The things is: that seems to be a recent change (or is it, @queenofcorgis ?), because my website has been build from a private repo since the beginning, and I don't think I had any notice from GH that they changed their policy on that topic!
So I'm quite frustrated to have you guys loose your time, but I'd blame GH on:
1- not telling me the free plan didn't allow using a private repo as source anymore
2- not having a clear error message on the deploy step!

To be clear: I perfectly understand the fact that GH can change their policy anytime and decide to charge user for a given service.
But its better to gives the users that information, would have saved a lot of time...