Awesome
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 singletar
file
The tar
file must:
- be under 10GB in size (we recommend under 1 GB!)
- :warning: 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:
-
Locate the semantic version of the upcoming release (a draft is maintained by the
draft-release
workflow). -
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. :ballot_box_with_check: -
After publishing the release, the
release
workflow will automatically run to create/update the corresponding major version tag such asv0
.⚠️ Environment approval is required. Check the Release workflow run list.
License
The scripts and documentation in this project are released under the MIT License.
<!-- references -->