Confusing README?

[BrutalCoding]

Context

First off, thanks, I've managed to make use of this action within my own custom GH Action workflow and it works perfect. Sorry for the long post, because the solution is very simple but I just wanted to give you my experience.

How I got to this repo.

1. ✅ My repo already had a workflow that checks for linter issues, runs tests and outputs a folder with test coverage HTML files.
2. ✅ I was convinced that I could deploy those HTML files somewhere, so my first thought was GitHub Pages.
3. ✅ Through my repo Settings -> GitHub Pages -> I read on that page that it is possible to deploy to GitHub Pages from a workflow without hosting my static HTML files as a seperate branch. Perfect! It does say BETA but nonetheless went for it. Here's the documentation that I read: https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#creating-a-custom-github-actions-workflow-to-publish-your-site
4. ✅ On that page, it mentions to use actions/upload-pages-artifact in step 4 to upload my artifacts (my folder output with HTML files). Done.
5. ❌ On step 5 (last step) it mentions to make use of actions/deploy-pages if the workflow was triggered by a push to the default branch. Thats not the case for me. I had a feature branch "feature/abc" that I opened a pull request for to merge into my "dev" branch. My workflow is triggered "on: pull_request". So I skipped this step.

Got started. Got confused.

"Usage" says: see action.yml

Time to get started, I edited my GH action workflow ("on pull request") to include step 4. I started by reading the README and under the header Usage there's a reference to action.yml. I was not familiar to other GitHub Action repos in general so I did not know that action.yml is the starting point of the action. I thought that this file was an example of how to make use of this action. I was wrong.

So here's me making use of actions/upload-artifact@main instead of actions/upload-pages-artifact@v1 because I found on that on the bottom of action.yml. My mistake..

Successfully uploaded artifacts. No github-pages environment.

Even though I made use of the wrong action, it did upload my artifacts. The logs mentioned that my artifacts got uploaded. But I couldnt find it in my environment nor did I see it on my GitHub Pages link.

Finally got it

After hours of trying and debugging I ended up with actions/deploy-pages's README. That README mentions that the action.yml can be read to learn about the various inputs that it supports and most importantly it mentions examples to be found here: https://github.com/actions/starter-workflows/tree/main/pages

So I checked out the examples, went for static.yml and noticed these 3 steps:

- name: Setup Pages
uses: actions/configure-pages@v1
- name: Upload artifact
uses: actions/upload-pages-artifact@v1
with:
# Upload entire repository
path: '.'
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@main

So thats it. I used the same actions in the same order and everything worked.

Can we update the README to make this more clear too? Thats all 😆

edited @ Sep 2024:
Heya future reader! It might be obvious to some, but my text and/or code is likely not up-to-date by the time you're reading this.

As of now, it's Sep 2024 and I stumbled upon a friendly commenter that mentioned that you should update the version number that I used before. Please check the latest documentation and versions numbers yourself, after that you likely will do something like this:

Change actions/upload-pages-artifact@v1 to actions/upload-pages-artifact@v4

The first thing that you should do, and this is applicable to any kind of code project, is simply follow along with the latest official instructions. This is better than following along with a dated video tutorial or article. Thus, in this case, make sure you read this README.md: https://github.com/actions/upload-artifact?tab=readme-ov-file.

Secondly, remember that README's are just text files - not code. Thus, they may have typo's in any of the included example codes found in the README. So, if you followed all the instruction and it didn't work as expected - try to browse the project to find real example code files. Thus again, since we're talking about actions/upload-pages-artifact, check out this file: https://github.com/actions/upload-pages-artifact/blob/main/action.yml. Even code files can have typo's too of course, but that'd called a bug and that is often way more noticable compared to having a typo in an informational text file (e.g. README.md).

[yoannchaudet]

Thank you for the feedback and taking time to write it here! We will be making some improvements on the README.

[moritzluedtke]

Thanks @BrutalCoding! That got my setup working.

A better documentation would be much appreciated 👍

[max-sixty]

Thanks @BrutalCoding — this issue is the readme that should have been!

[smheidrich]

Just FYI for anyone else who tried to use the sample code from the issue above but got hit with Error: No artifacts named "github-pages" were found for this workflow run. Ensure artifacts are uploaded with actions/upload-artifact@v4 or later. :

You need to update uses: actions/upload-pages-artifact@v1 to uses: actions/upload-pages-artifact@v3.

Maybe this could be changed in the issue text as well so people don't have to waste time piecing it together.

[BrutalCoding]

Just FYI for anyone else who tried to use the sample code from the issue above but got hit with `Error: No artifacts named "github-pages" were found for this workflow run. Ensure artifacts are uploaded with actions/upload-artifact@v4 or later.

`:

You need to update uses: actions/upload-pages-artifact@v1 to uses: actions/upload-pages-artifact@v3.

Maybe this could be changed in the issue text as well so people don't have to waste time piecing it together.

@smheidrich comments like this are helpful! Thanks, and I fully agree. I took your advice and have now edited my original issue text.

I added a new note that is hopefully generalized enough that it should last for many more years to come.

edit
Now this is funny, right after replying to you I decided to double check whether you're right about v3, and I noticed that v3 is being deprecated next month. Their own action.yml is using v4. Oh and dear future reader, it might be v999 by the time you see this comment of mine, just check out the latest README.md here: https://github.com/actions/upload-artifact?tab=readme-ov-file

This is a perfect example of why double checking the latest docs and/or official examples is the best thing to do.

PS. I wasn't aware of the shear amount of people that found my original insight useful. Cool to see!