GitHub Pages Deploy Action :rocket:

Automatically deploy your project to GitHub Pages with GitHub Actions. This action can be configured to push your production-ready code into any branch you'd like, including gh-pages and docs. It can also handle cross repository deployments and works with GitHub Enterprise too.

Maintenance of this project is made possible by all the contributors and sponsors. If you'd like to sponsor this project and have your avatar or company logo appear below click here. 💖

Getting Started :airplane:

You can include the action in your workflow to trigger on any event that GitHub actions supports. If the remote branch that you wish to deploy to doesn't already exist the action will create it for you. Your workflow will also need to include the actions/checkout step before this workflow runs in order for the deployment to work. If you intend to make multiple deployments in quick succession you may need to leverage the concurrency parameter in your workflow to prevent overlaps.

You can view an example of this below.

name: Build and Deploy
on: [push]
permissions:
  contents: write
jobs:
  build-and-deploy:
    concurrency: ci-${{ github.ref }} # Recommended if you intend to make multiple deployments in quick succession.
    runs-on: ubuntu-latest
    steps:
      - name: Checkout 🛎️
        uses: actions/checkout@v6

      - name: Install and Build 🔧 # This example project is built using npm and outputs the result to the 'build' folder. Replace with the commands required to build your project, or remove this step entirely if your site is pre-built.
        run: |
          npm ci
          npm run build

      - name: Deploy 🚀
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          folder: build # The folder the action should deploy.

[!NOTE] You must configure your repository to deploy from the branch you push to. To do this, go to your repository settings, click on Pages, and choose Deploy from a Branch from the Source dropdown. From there select the branch you supplied to the action. In most cases this will be gh-pages as that's the default.

If you'd like to make it so the workflow only triggers on push events to specific branches then you can modify the on section.

on:
  push:
    branches:
      - main

[!WARNING] If you do not supply the action with an access token or an SSH key, you must access your repositories settings and provide Read and Write Permissions to the provided GITHUB_TOKEN, otherwise you'll potentially run into permission issues. Alternatively you can set the following in your workflow file to grant the action the permissions it needs.

permissions:
  contents: write

Configuration 📁

The with portion of the workflow must be configured before the action will work. You can add these in the with section found in the examples above. Any secrets must be referenced using the bracket syntax and stored in the GitHub repository's Settings/Secrets menu. You can learn more about setting environment variables with GitHub actions here.

Required Setup

The following options must be configured in order to make a deployment.

By default, the action does not need any token configuration and uses the provided repository scoped GitHub token to make the deployment. If you require more customization you can modify the deployment type using the following options.

Optional Choices