Clarification on `gzip` + upload size in the readme

[Tom Forbes]

Hello,
The documentation says:

• Be a single [gzip archive][gzip] containing a single [tar file][tar]

However the current action does not gzip compress the contents, and the artifact appears to be a zip?

The docs also say:

the tar file must... be under 10GB in size

However I get the following warning:

Uploaded artifact size of 3481333760 bytes exceeds the allowed size of 1 GB. Deployment might fail.

Is it possible to clarify the readme? Is it saying the input must be a .tar.gz file, or a .tar file in a zip file? And is the 10gb upload limit correct for the compressed artifact size or the uncompressed size?

[James M. Greene]

As a service, GitHub Pages has official usage limits that would come into play here. Specifically:

• Published GitHub Pages sites may be no larger than 1 GB.
• GitHub Pages deployments will timeout if they take longer than 10 minutes.

If your deployment cannot meet those requirements, GitHub Pages does not guarantee your deploy will succeed. While we admittedly have some tolerances built in on the backend, they are not part of the official terms of service, and therefore cannot be relied upon.

The 10GB size limit mentioned is a bit of a leak of internal intel, in that, yes, if your tarball is more than 10GB in uncompressed size, GitHub Pages will not even attempt to deploy your site. Again, that larger size is not officially supported and is subject to change at our discretion, ergo it should not be relied upon nor expected to succeed.

As your tarball is larger than the officially supported size of 1 GB, using this action issues a warning that your deployment might fail. This is just intended as a helpful context clue in case the deployment does indeed fail when you trigger it when using the subsequent actions/deploy-pages action.

Finally, with regard to this action not creating a ZIP: based on reading the documentation for the Actions artifact library, which is used internally by the actions/upload-artifact action that gets directly used by this composite action, I believe it is creating a ZIP -- at least within the GitHub Actions artifact context -- though it is a bit nuanced, thus leaving some room for interpretation, especially since it sounds like the artifact download will automatically wrap with a ZIP file if the artifact isn't a ZIP already. 🤔

What I can tell you for certain is that, internally, when deploying, GitHub Pages will download the artifact from Actions and 100% expects that downloaded file to be a ZIP file containing a tarball at that point. 🤷🏻 😅

[James M. Greene]

You are also correct that our README needs an improvement around usage.

For the short term, I recommend taking a peek at usage examples in workflow contexts, such as the Pages starter workflow templates that get consumed by GitHub.

For instance, here's an example of the upload-pages-artifact action being used in the Hugo starter workflow template: https://github.com/actions/starter-workflows/blob/f3c5d7931d054ffbbdcbfdc463cc3bd0def74929/pages/hugo.yml#L60-L63

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v2
        with:
          path: ./public

TL;DR: Use with.path to provide a directory path containing all of your static assets (e.g. ./public for Hugo), and this action will generate an appropriate artifact to be used in a subsequent Pages deployment.

[Matthew Woehlke]

Zip != gzip. I was struggling with why deploy-pages was rejecting my artifact, and it turns out it is because I was following the README and gzip-compressing my tarball. Removing that step resolved the issue.

As noted, upload-artifact creates a zip (zip != gzip!), and deploy-pages expects a zip containing an uncompressed tar.

Please update the misleading README. It should not mention "gzip", and it should note that upload-artifact, used internally, creates a zip for you.