angular-cli-ghpages: ng deploy for GitHub Pages and Cloudflare Pages

One command that builds and pushes

angular-cli-ghpages deploys an Angular app to GitHub Pages, Cloudflare Pages or any other Git repo directly from the Angular CLI, and it is published on npm under that name. The licence is MIT, the primary language is TypeScript, and the repository is the angular-schule organisation.

The mechanism is short enough to state in one sentence. The package compiles your app, then pushes the build output to a dedicated branch, defaulting to gh-pages, and that branch serves as the source for your web host. The README says it works out of the box with GitHub Pages and Cloudflare Pages.

The command is ng deploy, which reads as an Angular CLI verb rather than a separate deployment tool, and the plugin adds a deploy capability to the CLI in the same way any schematics package does. When you run it for the first time the CLI prompts you to choose a deployment target, and the list it shows is:

Would you like to add a package with "deploy" capabilities now?
  No
  Amazon S3
  Firebase
  Netlify
❯ GitHub Pages

So the package is one option in a list the Angular CLI already knows how to present, and the same ng deploy invocation covers S3, Firebase and Netlify through other packages. The value is that the deployment step lives in the same tool, with the same configuration file, as the build.

The release history is active, with v3.1.2 and v3.1.1 both published on 2026-10-09, v3.1.0 on 2026-06-08, and the last push to the main branch on 2026-10-14.

The base href, and the subfolder problem it solves

One option deserves its own attention because it is the thing that breaks most first deployments.

After the install, the same ng deploy command builds and deploys, and the example the README gives is:

ng deploy --base-href=/<repositoryname>/

The README warns about this option specifically: it is necessary when your project will be deployed to a non-root folder, and there is a section in the options list for it.

The reason is how static hosting resolves paths. A project published at https://<username>.github.io/<repositoryname> is not at the domain root, so an application that assumes it is will request its scripts and styles from the wrong place and render a blank page. The base href is the value the build injects so that the generated asset URLs are relative to the subfolder.

The quick start ends with the project being available at https://<username>.github.io/<repositoryname>, which is the shape of the URL when the app sits in a project subfolder rather than a user or organisation site. So the base href is not an optional extra in the common case, it is the difference between a working site and a 404 for every asset.

The other options in the list follow the same logic of telling the deploy step about the shape of your hosting. There is --build-target, --prerender-target, --no-build for when you have already built, --repo, --message, --branch, --name and --email for the commit identity, --no-dotfiles, --no-notfound, --no-nojekyll, --cname for a custom domain, --add, --dir and --dry-run.

CI needs a token, and there is a GitHub Actions subtlety

The Continuous Delivery section is where the README shifts from the happy path to the real one, and the message is blunt. If you run this command from a CI/CD environment, the deployment will most likely not work out of the box, and the reasons are given: those environments usually have read-only privileges, or you have not set up Git correctly.

The fix is tokens. The README points at two: personal access tokens, GH_TOKEN, which works everywhere, and the installation access token GITHUB_TOKEN, which is exclusively provided by GitHub Actions. The reasoning is stated in a sentence worth keeping: a token replaces username and password and is a safer choice because a token can be revoked at any time.

So the instruction is to set an environment variable called GH_TOKEN, or PERSONAL_TOKEN, in the CI environment. For GitHub Actions you can also use GITHUB_TOKEN, which provides more security and requires no additional setup.

Two limits follow. All the tokens only work if the remote repository uses the HTTPS scheme, and tokens are generally not supported for Git over SSH. That is a hard constraint on how your repository is configured, and it is worth checking before you wire the deploy into a pipeline rather than discovering it on the first run.

There is then a note specific to GitHub Actions that is easy to miss and confusing when it bites. The GITHUB_TOKEN installation access token will only trigger a release of a new website if the action runs in a private repository. In a public repo, a commit is generated, but the site does not change.

That is worth understanding rather than working around. A public repository that needs automated deployment wants a personal access token instead.

The option list, and what each one changes

The README carries a long options list under Deployment Options, and it is worth skimming because the names alone tell you how much of the hosting setup the tool is willing to handle for you.

There is --base-href, which you have already seen, and --build-target and --prerender-target, which select which build output and which prerender variant is deployed. There is --no-build for when you have already produced the build yourself and only want the push, which is what you want in a pipeline where the build happens in an earlier step.

Then the git side. --repo sets the target repository, --message sets the commit message, --branch sets the branch the output goes to, and --name and --email set the author of the commit the tool creates. Those last three are what make the tool usable outside a repository that already has a remote, because the README notes that if you specify all three of --repo, --name and --email then angular-cli-ghpages will also work in directories that are not under version control at all.

The hosting side has --no-dotfiles, which skips copying dotfiles into the published branch, --no-notfound, which skips generating a fallback page, and --no-nojekyll, which skips the .nojekyll marker. That last one matters on GitHub Pages, where Jekyll will otherwise process the branch and ignore directories prefixed with an underscore, which is a common way for an Angular build to appear to deploy and then serve nothing.

--cname sets a custom domain, --add adds the remote if it is missing, --dir selects the output directory, and --dry-run shows what would happen without doing it.

Installing, and the standalone path for older projects

The installation is one command, and it does two things:

ng add angular-cli-ghpages

The README says this installs the npm package and adds the necessary deploy configuration to your angular.json file, so the schematic writes the configuration rather than asking you to.

If you have multiple projects in one workspace you need to name the project:

ng add angular-cli-ghpages --project MYPROJECTNAME

That is a detail that surfaces as a confusing failure in a monorepo, since the schematic cannot guess which project you meant.

The prerequisites are the other thing to read before you start. Git 1.9 or higher, checked with git --version, and an Angular project created via Angular CLI v18 or greater. The version support is spelled out in the changelog section: angular-cli-ghpages v3 supports Angular 18 to 22, and for previous versions of Angular you use v1 or v2.

There is also a standalone program. The README says older Angular projects can still use a v1.x version or use the standalone program, with the documentation at a separate README_standalone document in the docs directory. The repository has a docs/ directory and a src/ directory for the schematics, plus a .claude/ directory, a CLAUDE.md, an .editorconfig and a .vscode/ directory.

The topics attached to the repository tell you what the project is integrated with, beyond the two hosts: circle-ci, cloudflare-pages, github-actions, github-pages, ng-deploy and travis-ci, so the CI guidance is aimed at more than one pipeline.

Editorial conclusion

Adopt angular-cli-ghpages if you want your Angular deployment to be an Angular CLI command rather than a separate script or CI job, because it compiles the project and pushes the build output to the gh-pages branch in one step, and it configures itself through the CLI's own schematics. Do not adopt it for an SSH based remote, because the README states the tokens only work if the remote uses the HTTPS scheme. Before you set it up, check the Angular version, since v3 supports Angular 18 to 22 and older projects need v1 or v2 or the standalone program, and set a base href when the app will be served from a subfolder rather than the domain root.

Frequently asked questions

Official sources

1. angular-schule/angular-cli-ghpages on GitHub
2. License: MIT
3. Project website
4. README
5. Releases