How to deploy Angular app to GitHub Pages
Łukasz Holeczek
Follow Łukasz Holeczek on GitHub
Connect with Łukasz Holeczek on LinkedIn
Follow Łukasz Holeczek on X (Twitter)
GitHub Pages provides free static website hosting directly from GitHub repositories, ideal for Angular applications, documentation sites, and portfolios. As the creator of CoreUI, a widely used open-source UI library, I’ve deployed Angular applications to GitHub Pages throughout my 11 years of Angular development. The most straightforward approach is using the angular-cli-ghpages package to build and deploy Angular apps with a single command. This method automates the deployment process, handling base href configuration and branch management automatically.
Install angular-cli-ghpages and deploy with npx angular-cli-ghpages command.
# Build your Angular app for production
ng build --configuration production --base-href "/your-repo-name/"
# Install angular-cli-ghpages globally (one-time)
npm install -g angular-cli-ghpages
# Deploy to GitHub Pages
npx angular-cli-ghpages --dir=dist/your-app-name
Or add to package.json scripts:
{
"scripts": {
"build:prod": "ng build --configuration production --base-href \"/your-repo-name/\"",
"deploy": "npx angular-cli-ghpages --dir=dist/your-app-name"
}
}
Then deploy with:
npm run build:prod
npm run deploy
Here ng build creates the production build with –base-href set to your repository name, ensuring asset paths work correctly on GitHub Pages. The angular-cli-ghpages package pushes the dist folder contents to the gh-pages branch. GitHub Pages automatically serves content from this branch at username.github.io/repo-name. The –dir flag specifies the build output directory location.
Best Practice Note:
This is the deployment method we use for CoreUI Angular demo sites and documentation hosted on GitHub Pages. Configure custom domains in repository settings for professional URLs, enable HTTPS in GitHub Pages settings for secure connections, and use GitHub Actions for automatic deployment on every push to main branch.
