How to Deploy Your Angular Website on GitHub Pages

If you recall, I am switching to Google services for all my personal needs: not for the company I work for. This means that my website has also switched to Angular. It was a painless transition, but I had to modify some existing configurations in addition to the new ones. Let’s see how I handled the changes.

Angular and GitHub Pages

Fortunately, there is a more or less “official” method for deploying a web application created with Angular on GitHub Pages. Although it is a third-party script, angular-cli-ghpages is formally accepted as the best and recommended method to proceed. I must admit that it worked immediately, so I implemented it.

I generally prefer built-in solutions to avoid being dependent on external libraries, but in this case I made an exception. This is also because in the future I would like to take a further step and switch to Flutter, but in general the script does everything I need it to do. I didn’t have any problems with the custom domain, for example.

In any case, I had to change my publishing strategy, based on GitHub Actions, to one based on the gh-pages branch. All this while continuing to use GitHub Actions: not exactly ideal. I would have preferred to keep everything on the same branch to avoid confusion, but in the end, I’m keeping the code to myself.

What, What Not, and What the F*ck

I chose Angular for two reasons, or rather three: I also use it for work, I found some interesting projects that combine it with Rust via WebAssembly, and it’s easy to integrate with Antigravity. It’s not because of the framework itself. I still believe that a framework should be chosen based on specific needs.

If I had to choose based on current demand, I would opt for React with Next.js, but I’m sure I’ll find a way to use that too. More than a specific framework, I needed to leverage GitHub Pages and GitHub Actions. Leaving aside my experiments, when it comes to creating a portfolio, one framework is as good as another.

I did without one for years. The longest-lasting structure I had for my personal website was based on WordPress. It still exists, but does anyone still use it for this purpose? Honestly, I hope not. Not because it’s a bad product, but because it has had its day. Even though PHP is making a big comeback.

Deploying Angular to GitHub Pages

There are two ways of doing the same thing: you can either add the angular-cli-ghpages package manually or by using the Angular CLI. I chose the latter, since it also adds a deploy entry in angular.json — otherwise, you must do it on your own. Let’s start executing the command below.

ng add angular-cli-ghpages

I’m assuming that you already installed the Angular CLI globally. Then, you must change your publishing settings, replacing GitHub Actions with the branch gh-pages as the source: it doesn’t matter if we’re going to use GitHub Actions as well. That’s why you must update the angular.json entry as follow.

"deploy": {
  "builder": "angular-cli-ghpages:deploy",
  "options": {
    "name": "John Doe",
    "email": "[e-mail]",
    "cname": "foo.bar"
  }
}

Remember to replace name and email with your own GitHub credentials. This will push any updates to the gh-pages branch (it will create a new one in your repository, if it didn’t exist yet) every time you execute ng deploy from your terminal emulator. Let’s automate all the things by configuring GitHub Actions.

Automatic Deployment With GitHub Actions

You’re almost done. If you don’t have specific needs – I forgot to mention that the cname key is only needed if you configured a custom domain – such as a different base, all you have to do is creating a classic token from the Developer Settings: give it both the repo and the user scopes, then save it in a secret called GH_PAGES.

name: Deploy to GitHub Pages

on:
  push:
    branches: ['main']

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v6
      - name: Setup Node.js
        uses: actions/setup-node@v6
        with:
          node-version: '24.x'
      - name: Install
        run: npm install
      - name: Build
        run: npm run build
      - name: Deploy
        run: npm run deploy
        env:
          CI: true
          GH_TOKEN: ${{ secrets.GH_TOKEN }}

If you’re already familiar to GitHub Actions, you shouldn’t need more details. Without further parameters, you could put the last three commands together in a single line: angular-cli-ghpages will detect your Angular configuration automatically. Just make sure to use a recent version of the framework to avoid issues.

What to Pay Attention To

Maybe the most difficult things here is generating the token. You will need to create a new one from your personal settings’ page, then paste it as a GH_TOKEN secret in the repository’s. Of course, you can give this latter the name you want, simply replacing the variable secrets.GH_TOKEN you can see above accordingly.

I also assumed that you know where to put a GitHub Actions’ configuration file. It must be placed in a .github/workspaces folder on your repository’s root. Since it’s a YAML file, it should have a .yml extension: mine is called deploy.yml. It doesn’t really matter which name you choose for it.

I don’t really like the idea of having a gh-pages branch. Is a legacy of the past: newer CD/CI solutions excluded it, but I think I can’t get rid of it as long as I use this third-party package. I hope I will find a better way soon. Right know, it just works, and that’s all I wanted.

^{If you’d like, follow me on Bluesky and/or GitHub for more contents. I enjoy networking.}

Comments

[Federico Moretti]

Yes, I already have a repository named after my own personal account (cf. github.com/fedtti/fedtti.github.io). I use it with a CNAME file to host my personal webpage that points to federicomoretti.it — a domain I registered on GoDaddy some years ago. I use to configure advanced settings as well, just because I forced the HTTPS protocol, etc.; for sure publishing a dist/ folder to the root would have been enough.

The main branch of that repository only hosts my project’s sources. I don’t want to have a dist/ folder there: before switching to Angular, I used GitHub Actions to publish its compiled sources from the same branch. I don’t know where GitHub placed them actually. This solution hosts the binaries in a separate gh-pages branch I don’t like much, but it basically does the same thing with a “visible” destination.

Of course, being a personal account, instead an organization one, every time I put some web pages in another repository I automatically have their folders published under the same public base address (since I don’t use private repositories as a free GitHub user). That’s why I tend to avoid having “binaries” in my repositories… 😅

[Federico Moretti]

I should definitely consider to register one or more organizations for bigger projects!

I also think that, in the medium term, I will get rid of the angular-cli-ghpages at all and rely on GitHub Actions only — as I used to: it’s just a matter of setting the right path there.

[Danny Engelman]

But don't tell anyone; its a good secret. Microsoft applies "fair use", so if too many people use this hack they will shut it down.

I am deleting my answers here because of that