How to Deploy to GitHub Pages With GitHub Actions

Upload the built site as a Pages artifact, then call actions/deploy-pages, which publishes to the github-pages environment.

Set the Pages source to "GitHub Actions", grant pages: write and id-token: write, upload the build with actions/upload-pages-artifact, then deploy with actions/deploy-pages.

Steps

• In repo settings, set Pages source to GitHub Actions.
• Build the site into a directory.
• Upload it with actions/upload-pages-artifact.
• Deploy with actions/deploy-pages in a job targeting the github-pages environment.

Workflow

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

Common pitfalls

• If Pages source is set to "Deploy from a branch", deploy-pages fails; switch it to "GitHub Actions".
• The artifact must be named the Pages default (github-pages); use upload-pages-artifact, not the generic upload action.
• Missing id-token: write causes the deploy step to fail because Pages verifies the run via OIDC.

Related guides