actions/upload-pages-artifact

Package a directory of static assets into the artifact GitHub Pages expects.

Official actionCategory: ArtifactsLatest v5View on GitHub

What it does

actions/upload-pages-artifact archives a directory of static assets (as a single tar) and uploads it as an artifact named github-pages by default, the format actions/deploy-pages requires.

It is a composite action wrapping actions/upload-artifact with Pages-specific packaging.

Usage

workflow (.yml)

steps:
  - uses: actions/checkout@v4
  - run: npm ci && npm run build
  - uses: actions/upload-pages-artifact@v5
    with:
      path: dist/
# a separate job with pages: write + id-token: write then runs
# actions/deploy-pages to publish this artifact

Inputs

Input	Description	Default	Required
`name`	Artifact name.	`github-pages`	No
`path`	Path of the directory containing the static assets.	`_site/`	Yes
`retention-days`	Duration after which the artifact will expire, in days.	`1`	No
`include-hidden-files`	Include hidden files and directories (dotfiles) in the artifact. Excludes .git and .github regardless.	`false`	No

Outputs

Output	Description
`artifact_id`	The ID of the artifact that was uploaded.

Notes

Dotfiles are excluded by default. If your site needs files like .nojekyll inside the output, set include-hidden-files: true.

Keep the default artifact name github-pages unless you also set artifact_name on deploy-pages to match.

Common errors

No files were found with the provided path means path points at a directory that does not exist, usually the build step wrote output somewhere else.
A deploy that serves the wrong content usually means path pointed at the repo root instead of the built output directory.

Security and pinning

Upload only the built output directory, never the repo root, the artifact is exactly what gets served publicly.

Alternatives and related

actions/deploy-pagesDeploy a previously uploaded Pages artifact to GitHub Pages. actions/upload-artifactUpload files from a job so other jobs or a person can download them after the run. actions/download-artifactDownload artifacts uploaded earlier in the workflow, or from another run.

Frequently asked questions

Can I use actions/upload-artifact instead?

No, deploy-pages expects the specific single-tar artifact layout this action produces. Use upload-pages-artifact for the Pages flow.

References

GitHub Actions documentation