1 | # angular-cli-ghpages
|
2 |
|
3 | [![NPM version][npm-image]][npm-url]
|
4 | [![GitHub Actions](https://github.com/angular-schule/angular-cli-ghpages/actions/workflows/main.yml/badge.svg)](https://github.com/angular-schule/angular-cli-ghpages/actions/workflows/main.yml)
|
5 | [![The MIT License](https://img.shields.io/badge/license-MIT-orange.svg?color=blue&style=flat-square)](http://opensource.org/licenses/MIT)
|
6 |
|
7 | **Deploy your Angular app to GitHub Pages, Cloudflare Pages or any other Git repo directly from the Angular CLI! đ**
|
8 |
|
9 | ![Screenshot](docs/img/angular-cli-ghpages-deploy.gif)
|
10 |
|
11 | **Table of contents:**
|
12 |
|
13 | 1. [đ Changelog](#changelog)
|
14 | 2. [â ī¸ Prerequisites](#prerequisites)
|
15 | 3. [đ Quick Start (local development)](#quickstart-local)
|
16 | 4. [âī¸ Installation](#installation)
|
17 | 5. [đ Continuous Delivery](#continuous-delivery)
|
18 | 6. [đĻ Deployment Options](#options)
|
19 | - [--base-href](#base-href)
|
20 | - [--build-target](#build-target)
|
21 | - [--no-build](#no-build)
|
22 | - [--repo](#repo)
|
23 | - [--message](#message)
|
24 | - [--branch](#branch)
|
25 | - [--name & --email](#name)
|
26 | - [--no-dotfiles](#no-dotfiles)
|
27 | - [--no-notfound](#no-notfound)
|
28 | - [--no-nojekyll](#no-nojekyll)
|
29 | - [--cname](#cname)
|
30 | - [--dry-run](#dry-run)
|
31 | 7. [đ Configuration File](#configuration-file)
|
32 | 8. [đ Environments](#environments)
|
33 | 9. [âī¸ FAQ](#faq)
|
34 |
|
35 | <hr>
|
36 |
|
37 | ## đ Changelog <a name="changelog"></a>
|
38 |
|
39 | A detailed changelog is available in the [releases](https://github.com/angular-schule/angular-cli-ghpages/releases) section.
|
40 |
|
41 | **â ī¸ BREAKING CHANGE (v2)**
|
42 |
|
43 | The internal build of Angular has changed with Angular 17.
|
44 | Unfortunately, there are now a lot of different _build targets_ and builders.
|
45 | We will try to guess the correct build target, based on the usual conventions to name them.
|
46 | The conventions are shown below, try to specify the build target more and more explicitly until the project compiles.
|
47 |
|
48 | In the following example, your app is called `test` and you want to deploy the `production` build.
|
49 |
|
50 | ```bash
|
51 | ng deploy
|
52 | ```
|
53 |
|
54 | If this doesn't work, try this:
|
55 |
|
56 | ```bash
|
57 | ng deploy --build-target=test
|
58 | ```
|
59 |
|
60 | If this doesn't work, try this:
|
61 |
|
62 | ```bash
|
63 | ng deploy --build-target=test:build:production
|
64 | ```
|
65 |
|
66 | You can also and modify your `angular.json` to archive the same:
|
67 |
|
68 | ```json
|
69 | {
|
70 | "deploy": {
|
71 | "builder": "angular-cli-ghpages:deploy",
|
72 | "options": {
|
73 | "buildTarget": "test:build:production"
|
74 | }
|
75 | }
|
76 | }
|
77 | ```
|
78 |
|
79 | For your convenience, you can also use `prerenderTarget` (which adds the suffix `:prerender:production`).
|
80 | There is no support for `universalBuildTarget` or `serverTarget` because Github Pages only supports static assets and no Server-Side Rendering!
|
81 |
|
82 | We will then try to deploy the `dist/test/browser` folder to Github Pages.
|
83 | If this is not the folder that you want to serve, you should explicitly specify the directory with the `--dir` option:
|
84 |
|
85 | ```bash
|
86 | ng deploy --dir=dist/test/browser
|
87 | ```
|
88 |
|
89 | This new build logic is a breaking change, therefore `angular-cli-ghpages` v2 only supports Angular 17 and higher.
|
90 | For previous versions of Angular, use `angular-cli-ghpages` v1.x.
|
91 |
|
92 | ## â ī¸ Prerequisites <a name="prerequisites"></a>
|
93 |
|
94 | This command has the following prerequisites:
|
95 |
|
96 | - Git 1.9 or higher (execute `git --version` to check your version)
|
97 | - Angular project created via [Angular CLI](https://github.com/angular/angular-cli) v17 or greater
|
98 | - older Angular projects can still use a v1.x version or use the standalone program. See the documentation at [README_standalone](https://github.com/angular-schule/angular-cli-ghpages/blob/master/docs/README_standalone.md).
|
99 |
|
100 | ## đ Quick Start (local development) <a name="quickstart-local"></a>
|
101 |
|
102 | This quick start assumes that you are starting from scratch.
|
103 | If you already have an existing Angular project on GitHub, skip step 1 and 2.
|
104 |
|
105 | 1. Install the latest version of the Angular CLI globally
|
106 | and create a new Angular project.
|
107 |
|
108 | ```sh
|
109 | npm install -g @angular/cli
|
110 | ng new your-angular-project --defaults
|
111 | cd your-angular-project
|
112 | ```
|
113 |
|
114 | 2. By default the Angular CLI initializes a Git repository for you.
|
115 | To add a new remote for GitHub, use the `git remote add` command:
|
116 |
|
117 | ```sh
|
118 | git remote add origin https://github.com/<username>/<repositoryname>.git
|
119 | ```
|
120 |
|
121 | Hints:
|
122 |
|
123 | - Create a new empty GitHub repository first.
|
124 | - Replace `<username>` and `<repositoryname>` with your username from GitHub and the name of your new repository.
|
125 | - Please enter the URL `https://github.com/<username>/<repositoryname>.git` into your browser â you should see your existing repository on GitHub.
|
126 | - Please double-check that you have the necessary rights to make changes to the given project!
|
127 |
|
128 | 3. Add `angular-cli-ghpages` to your project. For details, see the [installation section](#installation).
|
129 |
|
130 | ```sh
|
131 | ng add angular-cli-ghpages
|
132 | ```
|
133 |
|
134 | 4. Deploy your project to GitHub pages with all default settings.
|
135 | Your project will be automatically built in production mode.
|
136 |
|
137 | ```sh
|
138 | ng deploy --base-href=/<repositoryname>/
|
139 | ```
|
140 |
|
141 | Which is the same as:
|
142 |
|
143 | ```sh
|
144 | ng deploy your-angular-project --base-href=/<repositoryname>/
|
145 | ```
|
146 |
|
147 | Please be aware of the `--base-href` option. It is necessary when your project will be deployed to a non-root folder. See more details below.
|
148 |
|
149 | 5. Your project should be available at `https://<username>.github.io/<repositoryname>`.
|
150 | Learn more about GitHub pages on the [official website](https://pages.github.com/).
|
151 |
|
152 | ## âī¸ Installation <a name="installation"></a>
|
153 |
|
154 | `angular-cli-ghpages` can be installed via `ng add`.
|
155 | This will install the NPM package and add the necessary `deploy` configuration to your `angular.json` file.
|
156 |
|
157 | ```sh
|
158 | ng add angular-cli-ghpages
|
159 | ```
|
160 |
|
161 | If you have multiple projects in one workspace, you should manually define the project name:
|
162 |
|
163 | ```sh
|
164 | ng add angular-cli-ghpages --project MYPROJECTNAME
|
165 | ```
|
166 |
|
167 | ## đ Continuous Delivery <a name="continuous-delivery"></a>
|
168 |
|
169 | If you run this command from a CI/CD environment, the deployment will most likely not work out of the box.
|
170 | For security reasons, those environments usually have read-only privileges or you haven't set up Git correctly.
|
171 | Therefore you should take a look at ["personal access tokens" `GH_TOKEN`](https://help.github.com/articles/creating-an-access-token-for-command-line-use/) (which works everywhere) and the ["installation access token" `GITHUB_TOKEN`](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/authenticating-with-the-github_token) (which is exclusively provided by GitHub actions).
|
172 | In short: a token replaces username and password and is a safer choice because a token can be revoked at any time.
|
173 |
|
174 | All you need to do is to set an environment variable called `GH_TOKEN` (or `PERSONAL_TOKEN`) in your CI/CD environment.
|
175 | For GitHub Actions, you can also use the `GITHUB_TOKEN` which provides more security and requires no additional setup.
|
176 | All the tokens only work if the remote repository uses the HTTPS scheme.
|
177 | Tokens are generally not supported for Git over SSH.
|
178 |
|
179 | If the current working directory is already a git repository, you don't need to specify the repository again. The current remote repository with the name `origin` will be used in this case.
|
180 | You can also override the repository setting using the `--repo` option.
|
181 |
|
182 | If you specify all the three options (`--repo`, `--name` and `--email`), then angular-cli-ghpages will also work in directories that are not under version control at all.
|
183 |
|
184 | ```sh
|
185 | ng deploy --repo=https://github.com/<username>/<repositoryname>.git --name="Your Git Username" --email=your.mail@example.org
|
186 | ```
|
187 |
|
188 | (replace `<username>` and `<repositoryname>` with your username from GitHub and the name of your repository)
|
189 |
|
190 | > **âšī¸ Note for GitHub Actions**
|
191 | >
|
192 | > 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. See this [GitHub Community post](https://github.community/t5/GitHub-Actions/Github-action-not-triggering-gh-pages-upon-push/m-p/26869) for more info. If your repo is public, you must still use the `GH_TOKEN` (personal access token).
|
193 |
|
194 | ## đĻ Deployment Options <a name="options"></a>
|
195 |
|
196 | #### --base-href <a name="base-href"></a>
|
197 |
|
198 | - **optional**
|
199 | - Default: `undefined` (string)
|
200 | - Example:
|
201 | - `ng deploy` â The tag `<base href="/">` remains unchanged in your `index.html`
|
202 | - `ng deploy --base-href=/the-repositoryname/` â The tag `<base href="/the-repositoryname/">` is added to your `index.html`
|
203 |
|
204 | Specifies the base URL for the application being built.
|
205 | Same as `ng build --base-href=/XXX/`
|
206 |
|
207 | **âšī¸ Please read the next lines carefully, or you will get 404 errors in case of a wrong configuration!**
|
208 |
|
209 | ##### A) You don't want to use a custom domain
|
210 |
|
211 | If you don't want to use an own domain, then your later URL of your hosted Angular project should look like this:
|
212 | `https://your-username.github.io/the-repositoryname`.
|
213 | In this case you have to adjust the `--base-href` accordingly:
|
214 |
|
215 | ```sh
|
216 | ng deploy --base-href=/the-repositoryname/
|
217 | ```
|
218 |
|
219 | ##### B) You want to use a custom domain
|
220 |
|
221 | If you want to use your own domain, then you don't have to adjust `--base-href`.
|
222 | However, it is now necessary to set the `--cname` parameter!
|
223 |
|
224 | ```sh
|
225 | ng deploy --cname=example.org
|
226 | ```
|
227 |
|
228 | See the option [--cname](#cname) for more information!
|
229 |
|
230 | #### --build-target <a name="build-target"></a>
|
231 |
|
232 | - **optional**
|
233 | - Default: `undefined` (string)
|
234 | - Example:
|
235 | - `ng deploy` â Angular project is built in `production` mode
|
236 | - `ng deploy --build-target=test` â Angular project is using the build configuration `test` (this configuration must exist in the `angular.json` file)
|
237 |
|
238 | If no `buildTarget` is set, the `production` build of the default project will be chosen.
|
239 | The `buildTarget` simply points to an existing build configuration for your project, as specified in the `configurations` section of `angular.json`.
|
240 | Most projects have a default configuration and a production configuration (commonly activated by using the `--prod` flag) but it is possible to specify as many build configurations as needed.
|
241 |
|
242 | This is equivalent to calling the command `ng build --configuration=XXX`.
|
243 | This command has no effect if the option `--no-build` is active.
|
244 |
|
245 | **â ī¸ BREAKING CHANGE (v1)**
|
246 |
|
247 | This option was called `--configuration` in previous versions.
|
248 |
|
249 | BEFORE (_does not work_):
|
250 |
|
251 | ```
|
252 | ng deploy --configuration=test
|
253 | ```
|
254 |
|
255 | NOW:
|
256 |
|
257 | ```
|
258 | ng deploy --build-target=test
|
259 | ```
|
260 |
|
261 | #### --no-build <a name="no-build"></a>
|
262 |
|
263 | - **optional**
|
264 | - Default: `false` (string)
|
265 | - Example:
|
266 | - `ng deploy` â Angular project is build in production mode before the deployment
|
267 | - `ng deploy --no-build` â Angular project is NOT build
|
268 |
|
269 | Skip build process during deployment.
|
270 | This can be used when you are sure that you haven't changed anything and want to deploy with the latest artifact.
|
271 | This command causes the `--build-target` setting to have no effect.
|
272 |
|
273 | #### --repo <a name="repo"></a>
|
274 |
|
275 | - **optional**
|
276 | - Default: URL of the origin remote of the current dir (assumes a Git repository)
|
277 | - Example: `ng deploy --repo=https://github.com/<username>/<repositoryname>.git`
|
278 |
|
279 | This specifies the target repository. If none is given as an option, the repository is discovered from the current working directory.
|
280 |
|
281 | By default, this command assumes that the current working directory is a Git repository,
|
282 | and that you want to push changes to the `origin` remote.
|
283 | If instead your files are not in a git repository, or if you want to push to another repository,
|
284 | you can provide the repository URL in the `repo` option.
|
285 |
|
286 | > **âšī¸ Hint**
|
287 | >
|
288 | > Set an environment variable with the name `GH_TOKEN` / `PERSONAL_TOKEN` or `GITHUB_TOKEN` and it will be automatically added to the URL, if it uses the HTTPS shema (it must start with `https://github.com`).
|
289 | > Tokens are generally not supported for Git over SSH (starts with `git@github.com`).
|
290 |
|
291 | Learn more about ["personal access tokens" here](https://help.github.com/articles/creating-an-access-token-for-command-line-use/) (`GH_TOKEN`) and about the ["installation access token" here](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/authenticating-with-the-github_token) (`GITHUB_TOKEN`). `PERSONAL_TOKEN` is an alias for `GH_TOKEN`.
|
292 |
|
293 | #### --message <a name="message"></a>
|
294 |
|
295 | - **optional**
|
296 | - Default: `Auto-generated commit` (string)
|
297 | - Example: `ng deploy --message="What could possibly go wrong?"`
|
298 |
|
299 | The commit message **must be wrapped in quotes** if there are any spaces in the text.
|
300 | Some additional text is always added to the message, if the command runs on Travis CI, Circle CI or GitHub Actions.
|
301 |
|
302 | #### --branch <a name="branch"></a>
|
303 |
|
304 | - **optional**
|
305 | - Default: `gh-pages` (string)
|
306 | - Example: `ng deploy --branch=master`
|
307 |
|
308 | The name of the branch you'll be pushing to.
|
309 | The default uses GitHub's `gh-pages` branch,
|
310 | but this can be configured to push to any branch on any remote.
|
311 | You have to change this to `master` if you are pushing to a GitHub organization page (instead of a GitHub user page).
|
312 |
|
313 | #### --name & --email <a name="name"></a>
|
314 |
|
315 | - **optional**
|
316 | - Default: value of `git config user.name` and `git config user.email`
|
317 | - Example: `ng deploy --name="Displayed Username" --email=mail@example.org`
|
318 |
|
319 | If you run the command in a repository without `user.name` or `user.email` Git config properties
|
320 | (or on a machine without these global config properties),
|
321 | you must provide user info before Git allows you to commit.
|
322 | In this case, provide **both** `name` and `email` string values to identify the committer.
|
323 |
|
324 | #### --no-dotfiles <a name="no-dotfiles"></a>
|
325 |
|
326 | - **optional**
|
327 | - Default: Dotfiles are created (boolean `true`)
|
328 | - Example:
|
329 | - `ng deploy` â Dotfiles are included by default.
|
330 | - `ng deploy --no-dotfiles` â Dotfiles are ignored.
|
331 |
|
332 | The command includes dotfiles by default (e.g. `.htaccess` will be committed).
|
333 | With `--no-dotfiles` files starting with `.` are ignored.
|
334 |
|
335 | #### --no-notfound <a name="no-notfound"></a>
|
336 |
|
337 | - **optional**
|
338 | - Default: `404.html` file is created (boolean `true`)
|
339 | - Example:
|
340 | - `ng deploy` â A `404.html` file is created by default.
|
341 | - `ng deploy --no-notfound` â No `404.html` file is created.
|
342 |
|
343 | By default a `404.html` file is created, because this is the only known workaround to avoid 404 error messages on GitHub Pages.
|
344 | For Cloudflare Pages we highly recommend to disable the `404.html` file by setting this switch to true! see [#178](https://github.com/angular-schule/angular-cli-ghpages/issues/178)
|
345 |
|
346 | #### --no-nojekyll <a name="no-nojekyll"></a>
|
347 |
|
348 | - **optional**
|
349 | - Default: `.nojekyll` file is created (boolean `true`)
|
350 | - Example:
|
351 | - `ng deploy` â A `.nojekyll` file is created by default.
|
352 | - `ng deploy --no-nojekyll` â No `.nojekyll` file is created.
|
353 |
|
354 | By default a `.nojekyll` file is created, because we assume you don't want to compile the build again with Jekyll.
|
355 |
|
356 | **Explanation:**
|
357 | By creating such a file in the root of your pages repo, you will bypass the Jekyll static site generator on GitHub Pages.
|
358 | Static content is still delivered â even without Jekyll.
|
359 | But now the deployment will be a bit faster.
|
360 | This is also necessary if your site uses files or directories that start with **\_underscores** since Jekyll considers these to be special resources and does not copy them to the final site.
|
361 | The same applies to `.txt` files in your assets folder: They will just disappear if Jekyll processes the build. see [#160](https://github.com/angular-schule/angular-cli-ghpages/issues/160)
|
362 |
|
363 | #### --cname <a name="cname"></a>
|
364 |
|
365 | - **optional**
|
366 | - Default: `undefined` (string) â No CNAME file is generated
|
367 | - Example:
|
368 | - `ng deploy --cname=example.com`
|
369 |
|
370 | A CNAME file will be created enabling you to use a custom domain.
|
371 | [More information on GitHub Pages using a custom domain](https://help.github.com/articles/using-a-custom-domain-with-github-pages/).
|
372 |
|
373 | #### --dir <a name="dir"></a>
|
374 |
|
375 | - **optional**
|
376 | - Default: `undefined` (string) â Conventions will be used to guess the correct directory in your `dist` folder.
|
377 | - Example:
|
378 | - `ng deploy --dir=dist/completely-different-folder/en`
|
379 |
|
380 | Overrides the directory for all published sources, relative to the current working directory.
|
381 |
|
382 | #### --dry-run <a name="dry-run"></a>
|
383 |
|
384 | - **optional**
|
385 | - Default: `false` (boolean)
|
386 | - Example:
|
387 | - `ng deploy` â Normal behavior: Changes are applied.
|
388 | - `ng deploy --dry-run` â No changes are applied at all.
|
389 |
|
390 | Run through without making any changes.
|
391 | This can be very useful because it outputs what would happen without doing anything.
|
392 |
|
393 | ## đ Configuration File <a name="configuration-file"></a>
|
394 |
|
395 | To avoid all these command-line cmd options, you can write down your configuration in the `angular.json` file in the `options` attribute of your deploy project's architect. Just change the kebab-case to lower camel case. This is the notation of all options in lower camel case:
|
396 |
|
397 | - baseHref
|
398 | - buildTarget
|
399 | - noBuild
|
400 | - repo
|
401 | - message
|
402 | - branch
|
403 | - name
|
404 | - email
|
405 | - noDotfiles
|
406 | - noNotfound
|
407 | - noNojekyll
|
408 | - cname
|
409 | - dir
|
410 | - dryRun
|
411 |
|
412 | A list of all available options is also available [here](https://github.com/angular-schule/angular-cli-ghpages/blob/master/src/deploy/schema.json).
|
413 |
|
414 | Example:
|
415 |
|
416 | ```sh
|
417 | ng deploy --base-href=https://angular-schule.github.io/angular-cli-ghpages/ --name="Angular Schule Team" --email=team@angular.schule
|
418 | ```
|
419 |
|
420 | becomes
|
421 |
|
422 | ```json
|
423 | "deploy": {
|
424 | "builder": "angular-cli-ghpages:deploy",
|
425 | "options": {
|
426 | "baseHref": "https://angular-schule.github.io/angular-cli-ghpages/",
|
427 | "name": "Angular Schule Team",
|
428 | "email": "team@angular.schule"
|
429 | }
|
430 | }
|
431 | ```
|
432 |
|
433 | Now you can just run `ng deploy` without all the options in the command line! đ
|
434 |
|
435 | > **âšī¸ Hint**
|
436 | >
|
437 | > You can always use the [--dry-run](#dry-run) option to verify if your configuration is right.
|
438 | > The project will build but not deploy.
|
439 |
|
440 | ## đ Environments <a name="environments"></a>
|
441 |
|
442 | We have seen `angular-cli-ghpages` running on various environments, like Travis CI, CircleCi or Github Actions.
|
443 | Please share your knowledge by writing an article about how to set up the deployment.
|
444 |
|
445 | 1. [GitHub Actions](https://angular.schule/blog/2020-01-everything-github)
|
446 | 2. Travis CI
|
447 | 3. CircleCI
|
448 |
|
449 | ## âī¸ FAQ <a name="faq"></a>
|
450 |
|
451 | Before posting any issue, [please read the FAQ first](https://github.com/angular-schule/angular-cli-ghpages/wiki/FAQ).
|
452 | See the contributors documentation at [README_contributors](https://github.com/angular-schule/angular-cli-ghpages/blob/master/docs/README_contributors.md) if you want to debug and test this project.
|
453 |
|
454 | ## License <a name="license"></a>
|
455 |
|
456 | Code released under the [MIT license](LICENSE).
|
457 |
|
458 | <hr>
|
459 |
|
460 | <img src="https://assets.angular.schule/logo-angular-schule.png" height="60">
|
461 |
|
462 | ### © 2017-2024 https://angular.schule
|
463 |
|
464 | This project is made on top of [tschaub/gh-pages](https://github.com/tschaub/gh-pages).
|
465 | Thank you very much for this great foundation!
|
466 |
|
467 | [npm-url]: https://www.npmjs.com/package/angular-cli-ghpages
|
468 | [npm-image]: https://badge.fury.io/js/angular-cli-ghpages.svg
|