Deploy to Github Pages like a pro with Github Actions

Great article, thank you. I had to do some changes to get it working through trial and error. For example if you have a custom domain you need to write a CNAME file to the dist/build directory before the git commands. Indenting was also broken for me on copy paste.

Hi!!!, Great post I have been using the gh-pages-deploy.js script for a while and it worked perfectly, but for some reason now I get an error when usingrequire`.

Error [ERR_REQUIRE_ESM]: Must use import to load ES Module...
...require() of ES modules is not supported...is an ES module file as it is a .js file whose nearest parent package.json contains "type": "module" which defines all .js files in that package scope as ES modules.

Is this happening to anyone?

Excellent post! Thank you! If I may make a recommendation, removing the first layer of indentation in the code block would help a lot I think. It took me a few minutes to figure out why my .yml was being rejected, but it was because everything except the name: line was indented too much.

Still, this got me up and running quickly, with a few minor tweaks to improve things for my workflow! Unfortunately, my user page has to deploy on master so I'm doing that. I might move my personal website to a different repo though, because being able to use gh-pages without polluting master would definitely be preferable.

Thank you for posting this great article. Just a few additional notes you might even want to put in the article.
1) I am fairly sure github pages has no way of implementing History mode, so it is important that if you are using the Vue router, it is set like so

export default new Router({
  mode: 'hash',

2) For the script to deploy to github pages from the local machine, I would advise checking if there are uncommitted changes first with something like

    try {
        await execa("git", ["update-index", "--refresh"]); 
        const { stdout } = await execa("git", ["diff-index", "HEAD"]);
        if (stdout) {
            console.log("Please stash or commit changes first!");
            process.exit(1);
        }
   }

3) It might be worth putting the final git commands in a finally block so you always end up back on master. Also note below the rm command is replaced by rimraf - rm is platform specific (and certainly will not work on Windows) and rimraf deals with this for us.

   const rmrf = promisify(rimraf);
    let exitCode = 0;
    try {
        await execa("git", ["checkout", "--orphan", "gh-pages"]);
        console.log("Building...");
        await execa("yarn", ["run", "build-modern"]);
        // Understand if it's dist or build folder
        const folderName = existsSync("dist") ? "dist" : "build";
        await execa("git", ["--work-tree", folderName, "add", "--all"]);
        await execa("git", ["--work-tree", folderName, "commit", "-m", "gh-pages"]);
        console.log("Pushing to gh-pages...");
        await execa("git", ["push", "origin", "HEAD:gh-pages", "--force"]);
        await rmrf(folderName, { glob: false })
        console.log("Successfully deployed");
    } catch (e) {
        console.log(e.message);
        exitCode = 1;
    } finally {
        await promises.writeFile(configFilePath, originPublicPath, fileOpts);
        await execa("git", ["checkout", "-f", "master"]);
        await execa("git", ["branch", "-D", "gh-pages"]);
    }
    process.exit(exitCode);

Small note for those who use yarn (like me) and not npm. You will get
npm ERR! cipm can only install packages when your package.json and package-lock.json or npm-shrinkwrap.json are in sync.
because obviously package-lock.json doesn't exist. You either need to create package-lock by npm install or change a bit last lines of gh-pages-deploy.yml to

      - name: Clean install dependencies
        run: yarn install --frozen-lockfile

      - name: Run deploy script
        run: |
          git config user.name "Your username" && git config user.email "your email"
          yarn run gh-pages-deploy

Hello, Thank you for the great tutorial.
one problem I have is rm -r dist doesn't work! it says that rm is not recognized and I tried replacing it with del so it asked me to delete everything inside dist and I said yes.
and nothing is working :(
Can you please help?

Thank you for the article. I've published many websites on gh-pages using this. I was getting an error while deploying using Github actions and it turns out that the setup-node version has been updated and using setup-node@v1.1.0 will throw an error. I used the updated version setup-node@v2 and it worked fine.

Excellent post! Thank you, Roland.

As Nathan Snyder pointed out, the .yml block doesn't work if you copy from the first character to the last as there is an indentation on the entire code block that is not immediately apparent. Though this is a minor detail, it might help other less experienced programmers (like myself) to take note of this.

I got mine working after tweaks here and there. Thank you sooo much!

Thanks for the post, Roland,

Especially arrows on the images are helpful as people don't have to scan the image to find out where.

Thanks for the post, Roland, nice done!
Is exactly what i was looking for, and save me a lot of time for sure :)
Only with the intention of improvement, and for others who may be had the same issue,
there is a little mistake in this line, its miss a "-" in the word worktree:
git --worktree dist add --all Docs (for react: replace dist with build)

should be >>
git --work-tree dist add --all Docs (for react: replace dist with build)
Got me crazy until I realised it

My congrats for the site aswell. Shum Faleminderit!

Hey Roland, thanks for the article!
My GitHub pages shows me the readme.md file instead of my website. I found that the reason is that the index.html file is not in the root directory, but in public directory. Locating index.html in public directory is vue's default. What can I do to see the whole website and not just the readme.md file?

Thanks for the awesome post, it helps me a lot.

What an awesome article. Thank you Roland Doda for you effort.

Very nice post mate thank you! Excellent work!!!