upload-pages-artifact

A composite Action for packaging and uploading artifact that can be deployed to GitHub Pages.

Usage

See action.yml for the various inputs this action supports (or below).

If you breakdown your workflow in two jobs (build and deploy), we recommend this action to be used in your build job:

jobs:
  # Build job
  build:
    # Specify runner +  build & upload the static files as an artifact
    runs-on: ubuntu-latest
    steps:
      - name: Build static files
        id: build
        run: |
          # <Not provided for brevity>
          # At a minimum this step should build the static files of your site
          # <Not provided for brevity>

      - name: Upload static files as artifact
        id: deployment
        uses: actions/upload-pages-artifact@v3 # or specific "vX.X.X" version tag for this action
        with:
          path: build_outputs_folder/

  # Deployment job
  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

Inputs 📥

Input	Required?	Default	Description
name	false	github-pages	Artifact name
path	true	_site/	Path of the directory containing the static assets
retention-days	false	1	Duration after which artifact will expire in days

Outputs 📤

Output	Description
artifact_id	The ID of the artifact that was uploaded

Artifact validation

While choosing to use this action as part of your approach to deploying to GitHub Pages is technically optional, we highly recommend it since it takes care of producing (mostly) valid artifacts.

However, if you do not choose to use this action but still want to deploy to Pages using an Actions workflow, then you must upload an Actions artifact that meets the following criteria:

• Be named github-pages
• Be a single gzip archive containing a single tar file

The tar file must:

• be under 10GB in size (we recommend under 1 GB!)
  • ⚠️ The GitHub Pages officially supported maximum size limit is 1GB, so the subsequent deployment of larger tarballs are not guaranteed to succeed — often because they are more prone to exceeding the maximum deployment timeout of 10 minutes.
  • ⛔ However, there is also an unofficial absolute maximum size limit of 10GB, which Pages will not even attempt to deploy.
• not contain any symbolic or hard links
• contain only files and directories

Release instructions

In order to release a new version of this Action:

1. Locate the semantic version of the upcoming release (a draft is maintained by the draft-release workflow).

2. Publish the draft release from the main branch with semantic version as the tag name, with the checkbox to publish to the GitHub Marketplace checked. ☑️

3. After publishing the release, the release workflow will automatically run to create/update the corresponding major version tag such as v0.

   ⚠️ Environment approval is required. Check the Release workflow run list.

License

The scripts and documentation in this project are released under the MIT License.