Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ng add angular-cli-ghpages
✓ ng add angular-cli-ghpages
✗ npm install angular-cli-ghpages
This command integrates the `angular-cli-ghpages` deployment builder into your Angular project, configuring `angular.json` and installing necessary packages. It is the primary way to 'add' this functionality to your project.
ng deploy
✓ ng deploy
✗ npm deploy
After installation via `ng add`, this command executes the full build and deployment process to GitHub Pages or a specified remote. It accepts various options (e.g., `--branch`, `--message`).
angular.json builder configuration
✓ { "builder": "angular-cli-ghpages:deploy", "options": { ... } }
While not a direct code import, this is the configuration 'symbol' that defines how `ng deploy` uses the `angular-cli-ghpages` builder within your `angular.json` project's `architect` section. It is typically managed automatically by `ng add` but can be manually adjusted for advanced settings.
Demonstrates how to install the Angular CLI, create a new project, link it to a GitHub repository, and deploy it to GitHub Pages using the `ng deploy` command.
npm install --location=global @angular/cli
ng new your-angular-project --no-standalone
cd your-angular-project
git remote add origin https://github.com/<username>/<repositoryname>.git
# Replace <username> and <repositoryname> with your GitHub details
# Create an empty GitHub repository first for this to work.
ng deploy
# When prompted, select 'GitHub Pages' from the options.
# This command will build your app and deploy it to the 'gh-pages' branch.
ng --version
Debug
Known issues
breakingMajor versions of `angular-cli-ghpages` are tightly coupled to specific Angular CLI versions. Version 3.x requires Angular CLI 18+, Version 2.x supports Angular CLI 17-18, and Version 1.x supports Angular CLI 13-16.fixAlways ensure your `angular-cli-ghpages` version matches your Angular CLI version, as documented in the package's release notes. Upgrade your Angular project or use a compatible older version of this package.
affects: all major versions
gotchaVersions prior to 3.0.0 used an outdated `gh-pages` dependency (older than 6.3.0) which had known security vulnerabilities.fixUpgrade to `angular-cli-ghpages` v3.0.0 or newer to benefit from the patched `gh-pages` dependency.
affects: <3.0.0
gotchaVersions `v1.0.1` and `v1.0.2` were released with critical bugs and are known to be broken, leading to deployment failures.fixAvoid using versions `1.0.1` and `1.0.2`. Upgrade to `v1.0.3` or a newer compatible version.
affects: 1.0.1, 1.0.2
breakingStarting from v2.0.0, the default deployment behavior is to remove existing files in the target branch (`gh-pages`) before adding new ones. This can lead to loss of custom files not part of your build output.fixIf you need to preserve existing files on your `gh-pages` branch, use the `--add` option with your `ng deploy` command: `ng deploy --add`.
affects: >=2.0.0
gotchaThe `remote` option in versions prior to `v2.0.3` could cause deployment issues if not explicitly provided, failing to identify the Git remote to push to.fixIf experiencing deployment issues with older versions, explicitly provide the `--remote` option (e.g., `ng deploy --remote origin`), or upgrade to `v2.0.3` or newer which provides a default value.
affects: <2.0.3
Errors
Common errors & fixes
Cannot find 'deploy' target for the specified project.
The `angular-cli-ghpages` deployment builder has not been correctly added to the Angular project's `angular.json` configuration.
fixRun `ng add angular-cli-ghpages` in your project's root directory to integrate the deployment builder. This command will update your `angular.json` automatically.
Error: Could not find a 'dist' folder to deploy.
The Angular application has not been built, or the `outputPath` configured in `angular.json` does not point to the correct build output directory.
fixEnsure your Angular project builds successfully by running `ng build`. If you have multiple build configurations, specify the correct target using `--build-target` (e.g., `ng deploy --build-target production`).
Audit
Dependencies
@angular/clirequiredThis package is an Angular CLI extension and requires @angular/cli to function as a deployment builder.