actions/deploy-pages

Deploy a previously uploaded Pages artifact to GitHub Pages.

Official actionCategory: Release AutomationLatest v5View on GitHub

What it does

actions/deploy-pages takes the artifact produced by actions/upload-pages-artifact and deploys it as the GitHub Pages site for the repository.

It is the deploy half of the Actions-based Pages flow, replacing branch-based (gh-pages) publishing.

Usage

workflow (.yml)

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm run build
      - uses: actions/upload-pages-artifact@v5
        with:
          path: dist/
  deploy:
    needs: build
    runs-on: ubuntu-latest
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v5

Inputs

Input	Description	Default	Required
`token`	GitHub token.	`${{ github.token }}`	Yes
`timeout`	Time in milliseconds after which to timeout and cancel the deployment.	`600000`	No
`error_count`	Maximum number of status report errors before cancelling a deployment.	`10`	No
`artifact_name`	Name of the artifact to deploy.	`github-pages`	No
`preview`	Deploy a pull request as a Pages preview site (alpha, not publicly available).	`false`	No

Outputs

Output	Description
`page_url`	URL of the deployed GitHub Pages site.

Notes

Set the repository Pages source to "GitHub Actions" (Settings → Pages), otherwise deployments are rejected.

The job needs permissions: pages: write and id-token: write, and conventionally targets the github-pages environment.

Common errors

Failed to create deployment (status: 404) means GitHub Pages is not enabled for the repository, or the Pages source is not set to GitHub Actions.
A missing id-token: write permission fails the deployment before it starts, the action validates the OIDC token to prove artifact provenance.
An artifact-not-found error means the build job did not upload with actions/upload-pages-artifact, or artifact_name does not match.

Security and pinning

Keep permissions on the deploy job only (pages: write, id-token: write) rather than workflow-wide, and use the github-pages environment so protection rules apply.

Alternatives and related

actions/upload-pages-artifactPackage a directory of static assets into the artifact GitHub Pages expects. actions/checkoutCheck out your repository so a workflow can access its code.

Frequently asked questions

Do I still need a gh-pages branch?

No. With the Actions-based flow the site deploys straight from the uploaded artifact; no publishing branch exists. Set the Pages source to "GitHub Actions".

References

GitHub Actions documentation