Using custom workflows with Pages

You can take advantage of using Actions and Pages by creating a workflow file or choosing from the predefined workflows.

Who can use this feature?

Pages is available in public repositories with Free and Free for organizations, and in public and private repositories with Pro, Team, Enterprise Cloud, and Enterprise Server. For more information, see ’s plans.

Pages now uses Actions to execute the Jekyll build. When using a branch as the source of your build, Actions must be enabled in your repository if you want to use the built-in Jekyll workflow. Alternatively, if Actions is unavailable or disabled, adding a .nojekyll file to the root of your source branch will bypass the Jekyll build process and deploy the content directly. For more information on enabling Actions, see Managing Actions settings for a repository.

In this article

About custom workflows

Custom workflows allow Pages sites to be built via the use of Actions. You can still select the branch you would like to use via the workflow file, but you are able to do much more with the use of custom workflows. To start using custom workflows you must first enable them for your current repository. For more information, see Configuring a publishing source for your Pages site.

Configuring the configure-pages action

Actions enables the use of Pages through the configure-pages action, which also lets you gather different metadata about a website. For more information, see the configure-pages action.

To use the action place this snippet under your jobs in the desired workflow.

- name: Configure  Pages
  uses: actions/configure-pages@v5

This action helps support deployment from any static site generator to Pages. To make this process less repetitive you can use workflow templates for some of the most widely used static site generators. For more information, see Using workflow templates.

Configuring the upload-pages-artifact action

The upload-pages-artifact actions enables you to package and upload artifacts. The Pages artifact should be a compressed gzip archive containing a single tar file. The tar file must be under 10GB in size and should not contain any symbolic or hard links. For more information, see the upload-pages-artifact action.

To use the action in your current workflow place this snippet under jobs.

- name: Upload  Pages artifact
  uses: actions/upload-pages-artifact@v3

Deploying Pages artifacts

The deploy-pages action handles the necessary setup for deploying artifacts. To ensure proper functionality, the following requirements should be met:

  • The job must have a minimum of pages: write and id-token: write permissions.
  • The needs parameter must be set to the id of the build step. Not setting this parameter may result in an independent deployment that continuously searches for an artifact that hasn't been created.
  • An environment must be established to enforce branch/deployment protection rules. The default environment is -pages.
  • To specify the URL of the page as an output, utilize the url: field.

For more information, see the deploy-pages action.

# ...

jobs:
  deploy:
    permissions:
      contents: read
      pages: write
      id-token: write
    runs-on: ubuntu-latest
    needs: jekyll-build
    environment:
      name: -pages
      url: ${{steps.deployment.outputs.page_url}}
    steps:
      - name: Deploy artifact
        id: deployment
        uses: actions/deploy-pages@v4
# ...

Linking separate build and deploy jobs

You can link your build and deploy jobs in a single workflow file, eliminating the need to create two separate files to get the same result. To get started on your workflow file, under jobs you can define a build and deploy job to execute your jobs.

# ...

jobs:
  # Build job
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v5
      - name: Build with Jekyll
        uses: actions/jekyll-build-pages@v1
        with:
          source: ./
          destination: ./_site
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3

  # Deployment job
  deploy:
    environment:
      name: -pages
      url: ${{steps.deployment.outputs.page_url}}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to  Pages
        id: deployment
        uses: actions/deploy-pages@v4
# ...

In certain cases, you might choose to combine everything into a single job, especially if there is no need for a build process. Consequently, you would solely focus on the deployment step.

# ...

jobs:
  # Single deploy job no building
  deploy:
    environment:
      name: -pages
      url: ${{steps.deployment.outputs.page_url}}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Setup Pages
        uses: actions/configure-pages@v5
      - name: Upload Artifact
        uses: actions/upload-pages-artifact@v3
        with:
          # upload entire directory
          path: '.'
      - name: Deploy to  Pages
        id: deployment
        uses: actions/deploy-pages@v4

# ...

You can define your jobs to be run on different runners, sequentially, or in parallel. For more information, see Choosing what your workflow does.