How to Deploy Your Angular Website on GitHub Pages

Source: Dev.to

Angular and GitHub Pages

Fortunately, there is a more‑or‑less “official” method for deploying an Angular web application on GitHub Pages. Although it is a third‑party script, angular-cli-ghpages (GitHub repo) is formally accepted as the best and recommended way to proceed. It worked for me 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 I plan to take a further step and switch to Flutter later, and the script already does everything I need (including custom‑domain support).

I had to change my publishing strategy—from a GitHub‑Actions‑only flow to one that uses the gh-pages branch—while still keeping GitHub Actions in the mix. Ideally I would have kept everything on the same branch to avoid confusion, but for now the gh-pages branch works fine.

What, What Not, and What the F*ck

I chose Angular for three reasons:

1. I also use it at work.
2. I found interesting projects that combine it with Rust via WebAssembly.
3. It integrates easily with Antigravity.

It isn’t because Angular is the “best” framework; I still believe a framework should be chosen based on specific needs.

If I had to pick a framework based on current demand, I’d go with React + Next.js, and I’m sure I’ll find a way to use that too. For a personal portfolio, any modern framework will do.

I built sites without a framework for years. The longest‑lasting structure I had for my personal website was 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 bit of a comeback.

Deploying Angular to GitHub Pages

There are two ways to add the deployment step:

• Manually install the angular-cli-ghpages package.
• Via the Angular CLI, which also adds a deploy entry to angular.json.

I chose the latter. Run:

ng add angular-cli-ghpages

Assumption: you have the Angular CLI installed globally.

Next, update your publishing settings (replace the GitHub‑Pages source with the gh-pages branch). Add the following deploy configuration to angular.json:

{
  "deploy": {
    "builder": "angular-cli-ghpages:deploy",
    "options": {
      "name": "John Doe",
      "email": "john.doe@foo.bar",
      "cname": "foo.bar"
    }
  }
}

Replace name, email, and cname with your own GitHub credentials and custom domain (the cname key is only needed if you use a custom domain).

Running ng deploy will now push the built site to the gh-pages branch (creating it if it doesn’t exist). Let’s automate that with GitHub Actions.

Automatic Deployment with GitHub Actions

If you don’t have any special requirements, the only extra step is to create a classic personal access token (PAT) from Developer Settings with both repo and user scopes. Save this token in your repository’s secrets as GH_TOKEN.

Create a workflow file (e.g., .github/workflows/deploy.yml) with the following content:

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 dependencies
        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 with GitHub Actions, this should be straightforward.
• The last three commands (npm install, npm run build, npm run deploy) could be combined into a single line because angular-cli-ghpages automatically detects the Angular configuration—just ensure you’re using a recent version of the framework to avoid issues.

What to Pay Attention To

• Generating the token – Create a new PAT from your personal settings page and store it as a secret (GH_TOKEN) in the repository. You can name the secret whatever you like; just adjust the secrets.GH_TOKEN reference accordingly.
• Workflow file location – The file must be placed in a .github/workflows folder at the repository root and have a .yml (or .yaml) extension. My file is called deploy.yml, but the name is not important.
• gh-pages branch – I’m not a fan of maintaining a separate gh-pages branch; it feels like a legacy approach. However, the current third‑party package requires it, so for now I’ll keep it. I hope to find a cleaner solution soon.

That’s it! Your Angular site should now automatically build and deploy to GitHub Pages on every push to main.

It just works, and that’s all I wanted.

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