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": "john.doe@foo.bar",
"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.
More...
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": "john.doe@foo.bar",
"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.
More...