/ README.md
README.md
1 ## GitHub Actions for GitHub Pages 2 3 <img width="400" alt="GitHub Actions for deploying to GitHub Pages with Static Site Generators" src="./images/ogp.svg"> 4 5 [](https://github.com/peaceiris/actions-gh-pages/blob/main/LICENSE) 6 [](https://github.com/peaceiris/actions-gh-pages/releases/latest) 7 [](https://github.com/peaceiris/actions-gh-pages/releases) 8  9  10 [](https://www.codefactor.io/repository/github/peaceiris/actions-gh-pages) 11 12 This is a **GitHub Action** to deploy your static files to **GitHub Pages**. 13 This deploy action can be combined simply and freely with [Static Site Generators]. (Hugo, MkDocs, Gatsby, mdBook, Next, Nuxt, and so on.) 14 15 [Static Site Generators]: https://www.staticgen.com/ 16 17 The next example step will deploy `./public` directory to the remote `gh-pages` branch. 18 19 ```yaml 20 - name: Deploy 21 uses: peaceiris/actions-gh-pages@v3 22 with: 23 github_token: ${{ secrets.GITHUB_TOKEN }} 24 publish_dir: ./public 25 ``` 26 27 For newbies of GitHub Actions: 28 Note that the `GITHUB_TOKEN` is **NOT** a personal access token. 29 A GitHub Actions runner automatically creates a `GITHUB_TOKEN` secret to authenticate in your workflow. 30 So, you can start to deploy immediately without any configuration. 31 32 33 34 ## Supported Tokens 35 36 Three tokens are supported. 37 38 | Token | Private repo | Public repo | Protocol | Setup | 39 |---|:---:|:---:|---|---| 40 | `github_token` | ✅️ | ✅️ | HTTPS | Unnecessary | 41 | `deploy_key` | ✅️ | ✅️ | SSH | Necessary | 42 | `personal_token` | ✅️ | ✅️ | HTTPS | Necessary | 43 44 Notes: Actually, the `GITHUB_TOKEN` works for deploying to GitHub Pages but it has still some limitations. 45 For the first deployment, we need to select the `gh-pages` branch or another branch on the repository settings tab. 46 See [First Deployment with `GITHUB_TOKEN`](#%EF%B8%8F-first-deployment-with-github_token) 47 48 49 50 ## Supported Platforms 51 52 All Actions runners: Linux (Ubuntu), macOS, and Windows are supported. 53 54 | runs-on | `github_token` | `deploy_key` | `personal_token` | 55 |---|:---:|:---:|:---:| 56 | ubuntu-20.04 | ✅️ | ✅️ | ✅️ | 57 | ubuntu-18.04 | ✅️ | ✅️ | ✅️ | 58 | macos-latest | ✅️ | ✅️ | ✅️ | 59 | windows-latest | ✅️ | (2) | ✅️ | 60 61 2. WIP, See [Issue #87](https://github.com/peaceiris/actions-gh-pages/issues/87) 62 63 64 65 ## GitHub Enterprise Server Support 66 67 ✅️ GitHub Enterprise Server is supported above `2.22.6`. 68 69 Note that the `GITHUB_TOKEN` that is created by the runner might not inherently have push/publish privileges on GHES. You might need to create/request a technical user with write permissions to your target repository. 70 71 72 73 ## Table of Contents 74 75 <!-- START doctoc generated TOC please keep comment here to allow auto update --> 76 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --> 77 78 - [Getting started](#getting-started) 79 - [Options](#options) 80 - [⭐️ Set Runner's Access Token `github_token`](#%EF%B8%8F-set-runners-access-token-github_token) 81 - [⭐️ Set SSH Private Key `deploy_key`](#%EF%B8%8F-set-ssh-private-key-deploy_key) 82 - [⭐️ Set Personal Access Token `personal_token`](#%EF%B8%8F-set-personal-access-token-personal_token) 83 - [⭐️ Set Another GitHub Pages Branch `publish_branch`](#%EF%B8%8F-set-another-github-pages-branch-publish_branch) 84 - [⭐️ Source Directory `publish_dir`](#%EF%B8%8F-source-directory-publish_dir) 85 - [⭐️ Deploy to Subdirectory `destination_dir`](#%EF%B8%8F-deploy-to-subdirectory-destination_dir) 86 - [⭐️ Filter publishing assets `exclude_assets`](#%EF%B8%8F-filter-publishing-assets-exclude_assets) 87 - [⭐️ Add CNAME file `cname`](#%EF%B8%8F-add-cname-file-cname) 88 - [⭐️ Enable Built-in Jekyll `enable_jekyll`](#%EF%B8%8F-enable-built-in-jekyll-enable_jekyll) 89 - [⭐️ Allow empty commits `allow_empty_commit`](#%EF%B8%8F-allow-empty-commits-allow_empty_commit) 90 - [⭐️ Keeping existing files `keep_files`](#%EF%B8%8F-keeping-existing-files-keep_files) 91 - [⭐️ Deploy to external repository `external_repository`](#%EF%B8%8F-deploy-to-external-repository-external_repository) 92 - [⭐️ Force orphan `force_orphan`](#%EF%B8%8F-force-orphan-force_orphan) 93 - [⭐️ Set Git username and email](#%EF%B8%8F-set-git-username-and-email) 94 - [⭐️ Set custom commit message](#%EF%B8%8F-set-custom-commit-message) 95 - [⭐️ Create Git tag](#%EF%B8%8F-create-git-tag) 96 - [Tips and FAQ](#tips-and-faq) 97 - [⭐️ Create SSH Deploy Key](#%EF%B8%8F-create-ssh-deploy-key) 98 - [⭐️ First Deployment with `GITHUB_TOKEN`](#%EF%B8%8F-first-deployment-with-github_token) 99 - [⭐️ Use the latest and specific release](#%EF%B8%8F-use-the-latest-and-specific-release) 100 - [⭐️ Schedule and Manual Deployment](#%EF%B8%8F-schedule-and-manual-deployment) 101 - [Examples](#examples) 102 - [⭐️ Static Site Generators with Node.js](#%EF%B8%8F-static-site-generators-with-nodejs) 103 - [⭐️ Gatsby](#%EF%B8%8F-gatsby) 104 - [⭐️ React and Next](#%EF%B8%8F-react-and-next) 105 - [⭐️ Vue and Nuxt](#%EF%B8%8F-vue-and-nuxt) 106 - [⭐️ Docusaurus](#%EF%B8%8F-docusaurus) 107 - [⭐️ Static Site Generators with Python](#%EF%B8%8F-static-site-generators-with-python) 108 - [⭐️ mdBook (Rust)](#%EF%B8%8F-mdbook-rust) 109 - [⭐️ Flutter Web](#%EF%B8%8F-flutter-web) 110 - [⭐️ Elm](#%EF%B8%8F-elm) 111 - [⭐️ github/personal-website](#%EF%B8%8F-githubpersonal-website) 112 - [⭐️ Swift Publish](#%EF%B8%8F-swift-publish) 113 - [License](#license) 114 - [Maintainer](#maintainer) 115 116 <!-- END doctoc generated TOC please keep comment here to allow auto update --> 117 118 119 120 ## Getting started 121 122 Add your workflow file `.github/workflows/gh-pages.yml` and push it to your remote default branch. 123 124 Here is an example workflow for Hugo. 125 126 - [peaceiris/actions-hugo: GitHub Actions for Hugo](https://github.com/peaceiris/actions-hugo) 127 128 [](https://github.com/peaceiris/actions-hugo) 129 130 ```yaml 131 name: github pages 132 133 on: 134 push: 135 branches: 136 - main # Set a branch name to trigger deployment 137 138 jobs: 139 deploy: 140 runs-on: ubuntu-18.04 141 steps: 142 - uses: actions/checkout@v2 143 with: 144 submodules: true # Fetch Hugo themes (true OR recursive) 145 fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod 146 147 - name: Setup Hugo 148 uses: peaceiris/actions-hugo@v2 149 with: 150 hugo-version: '0.79.1' 151 152 - name: Build 153 run: hugo --minify 154 155 - name: Deploy 156 uses: peaceiris/actions-gh-pages@v3 157 with: 158 github_token: ${{ secrets.GITHUB_TOKEN }} 159 publish_dir: ./public 160 ``` 161 162 | Actions log overview | GitHub Pages log | 163 |---|---| 164 |  |  | 165 166 <div align="right"> 167 <a href="#table-of-contents">Back to TOC ☝️</a> 168 </div> 169 170 171 172 ## Options 173 174 ### ⭐️ Set Runner's Access Token `github_token` 175 176 **This option is for `GITHUB_TOKEN`, not a personal access token.** 177 178 A GitHub Actions runner automatically creates a `GITHUB_TOKEN` secret to use in your workflow. You can use the `GITHUB_TOKEN` to authenticate in a workflow run. 179 180 ```yaml 181 - name: Deploy 182 uses: peaceiris/actions-gh-pages@v3 183 with: 184 github_token: ${{ secrets.GITHUB_TOKEN }} 185 publish_dir: ./public 186 ``` 187 188 For more details about `GITHUB_TOKEN`: [Authenticating with the GITHUB_TOKEN - GitHub Help](https://help.github.com/en/actions/configuring-and-managing-workflows/authenticating-with-the-github_token) 189 190 ### ⭐️ Set SSH Private Key `deploy_key` 191 192 Read [Create SSH Deploy Key](#%EF%B8%8F-create-ssh-deploy-key), create your SSH deploy key, and set the `deploy_key` option like the following. 193 194 ```yaml 195 - name: Deploy 196 uses: peaceiris/actions-gh-pages@v3 197 with: 198 deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }} 199 publish_dir: ./public 200 ``` 201 202 ### ⭐️ Set Personal Access Token `personal_token` 203 204 [Generate a personal access token (`repo`)](https://github.com/settings/tokens) and add it to Secrets as `PERSONAL_TOKEN`, it works as well as `ACTIONS_DEPLOY_KEY`. 205 206 ```yaml 207 - name: Deploy 208 uses: peaceiris/actions-gh-pages@v3 209 with: 210 personal_token: ${{ secrets.PERSONAL_TOKEN }} 211 publish_dir: ./public 212 ``` 213 214 ### ⭐️ Set Another GitHub Pages Branch `publish_branch` 215 216 Set a branch name to use as GitHub Pages branch. 217 The default is `gh-pages`. 218 219 ```yaml 220 - name: Deploy 221 uses: peaceiris/actions-gh-pages@v3 222 with: 223 github_token: ${{ secrets.GITHUB_TOKEN }} 224 publish_branch: your-branch # default: gh-pages 225 ``` 226 227 ### ⭐️ Source Directory `publish_dir` 228 229 A source directory to deploy to GitHub Pages. The default is `public`. 230 231 ```yaml 232 - name: Deploy 233 uses: peaceiris/actions-gh-pages@v3 234 with: 235 github_token: ${{ secrets.GITHUB_TOKEN }} 236 publish_dir: ./out # default: public 237 ``` 238 239 ### ⭐️ Deploy to Subdirectory `destination_dir` 240 241 *This feature is on beta.* 242 *Any feedback is welcome at [Issue #324](https://github.com/peaceiris/actions-gh-pages/issues/324)* 243 244 A destination subdirectory on a publishing branch. The default is empty. 245 246 ```yaml 247 - name: Deploy 248 uses: peaceiris/actions-gh-pages@v3 249 with: 250 github_token: ${{ secrets.GITHUB_TOKEN }} 251 destination_dir: subdir 252 ``` 253 254 ### ⭐️ Filter publishing assets `exclude_assets` 255 256 *This feature is on beta.* 257 *Any feedback is welcome at [Issue #163](https://github.com/peaceiris/actions-gh-pages/issues/163)* 258 259 Set files or directories to exclude from publishing assets. 260 The default is `.github`. 261 Values should be split with a comma. 262 263 ```yaml 264 - name: Deploy 265 uses: peaceiris/actions-gh-pages@v3 266 with: 267 github_token: ${{ secrets.GITHUB_TOKEN }} 268 exclude_assets: '.github,exclude-file1,exclude-file2' 269 ``` 270 271 Set `exclude_assets` to empty for including the `.github` directory to deployment assets. 272 273 ```yaml 274 - name: Deploy 275 uses: peaceiris/actions-gh-pages@v3 276 with: 277 deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }} # Recommended for this usage 278 # personal_token: ${{ secrets.PERSONAL_TOKEN }} # An alternative 279 # github_token: ${{ secrets.GITHUB_TOKEN }} # This does not work for this usage 280 exclude_assets: '' 281 ``` 282 283 The `exclude_assets` option supports glob patterns. 284 285 ```yaml 286 - name: Deploy 287 uses: peaceiris/actions-gh-pages@v3 288 with: 289 github_token: ${{ secrets.GITHUB_TOKEN }} 290 exclude_assets: '.github,exclude-file.txt,exclude-dir/**.txt' 291 ``` 292 293 ### ⭐️ Add CNAME file `cname` 294 295 To add the `CNAME` file, we can set the `cname` option. 296 Alternatively, put your `CNAME` file into your `publish_dir`. (e.g. `public/CNAME`) 297 298 For more details about the `CNAME` file, read the official documentation: [Managing a custom domain for your GitHub Pages site - GitHub Help](https://help.github.com/en/github/working-with-github-pages/managing-a-custom-domain-for-your-github-pages-site) 299 300 ```yaml 301 - name: Deploy 302 uses: peaceiris/actions-gh-pages@v3 303 with: 304 github_token: ${{ secrets.GITHUB_TOKEN }} 305 publish_dir: ./public 306 cname: github.com 307 ``` 308 309 ### ⭐️ Enable Built-in Jekyll `enable_jekyll` 310 311 If you want GitHub Pages to process your site with the static site generator Jekyll, set `enable_jekyll` to true. 312 313 [github/personal-website](https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-githubpersonal-website) is one of the examples using GitHub Pages built-in Jekyll. 314 315 By default, this action signals to GitHub Pages that the site shall not be processed with Jekyll. This is done by adding an empty `.nojekyll` file when publishing to the master or gh-pages branch. When a `.nojekyll` file already exists, this action does nothing. 316 317 Bypassing Jekyll makes the deployment faster and is necessary if you are deploying files or directories that start with underscores, since Jekyll considers these to be special resources and does not copy them to the final site. You only need to set `enable_jekyll` to true when you want to deploy a Jekyll-powered website and let GitHub Pages do the Jekyll processing. 318 319 320 ```yaml 321 - name: Deploy 322 uses: peaceiris/actions-gh-pages@v3 323 with: 324 github_token: ${{ secrets.GITHUB_TOKEN }} 325 publish_dir: ./public 326 enable_jekyll: true 327 ``` 328 329 For more details about `.nojekyll`: [Bypassing Jekyll on GitHub Pages - The GitHub Blog](https://github.blog/2009-12-29-bypassing-jekyll-on-github-pages/) 330 331 ### ⭐️ Allow empty commits `allow_empty_commit` 332 333 By default, a commit will not be generated when no file changes. If you want to allow an empty commit, set the optional parameter `allow_empty_commit` to `true`. 334 335 For example: 336 337 ```yaml 338 - name: Deploy 339 uses: peaceiris/actions-gh-pages@v3 340 with: 341 github_token: ${{ secrets.GITHUB_TOKEN }} 342 publish_dir: ./public 343 allow_empty_commit: true 344 ``` 345 346 ### ⭐️ Keeping existing files `keep_files` 347 348 By default, existing files in the publish branch (or only in `destination_dir` if given) will be removed. If you want the action to add new files but leave existing ones untouched, set the optional parameter `keep_files` to `true`. 349 350 Note that users who are using a Static Site Generator do not need this option in most cases. Please reconsider your project structure and building scripts, or use a built-in feature of a Static Site Generator before you enable this flag. 351 352 - [Static Files | Hugo](https://gohugo.io/content-management/static-files/) 353 - [Using the Static Folder | Gatsby](https://www.gatsbyjs.com/docs/static-folder/) 354 355 For example: 356 357 ```yaml 358 - name: Deploy 359 uses: peaceiris/actions-gh-pages@v3 360 with: 361 github_token: ${{ secrets.GITHUB_TOKEN }} 362 publish_dir: ./public 363 keep_files: true 364 ``` 365 366 With the v3, this option does not support working with the force_orphan option. The next major release (version 4) will support this. 367 See [the issue #455](https://github.com/peaceiris/actions-gh-pages/issues/455) 368 369 ### ⭐️ Deploy to external repository `external_repository` 370 371 By default, your files are published to the repository which is running this action. 372 If you want to publish to another repository on GitHub, set the environment variable `external_repository` to `<username>/<external-repository>`. 373 374 For example: 375 376 ```yaml 377 - name: Deploy 378 uses: peaceiris/actions-gh-pages@v3 379 with: 380 deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }} 381 external_repository: username/external-repository 382 publish_branch: your-branch # default: gh-pages 383 publish_dir: ./public 384 ``` 385 386 You can use `deploy_key` or `personal_token`. 387 When you use `deploy_key`, set your private key to the repository which includes this action and set your public key to your external repository. 388 389 **Note that `GITHUB_TOKEN` has no permission to access to external repositories. Please create a personal access token and set it to `personal_token` like `personal_token: ${{ secrets.PERSONAL_TOKEN }}`.** 390 391 Use case: 392 393 A GitHub Free Plan account cannot use the GitHub Pages in a private repository. To make your source contents private and deploy it with the GitHub Pages, you can deploy your site from a private repository to a public repository using this option. 394 395 - `peaceiris/homepage`: A private repository running this action with `external_repository: peaceiris/peaceiris.github.io` 396 - `peaceiris/peaceiris.github.io`: A public repository using GitHub Pages 397 398 ### ⭐️ Force orphan `force_orphan` 399 400 We can set the `force_orphan: true` option. 401 This allows you to make your publish branch with only the latest commit. 402 403 ```yaml 404 - name: Deploy 405 uses: peaceiris/actions-gh-pages@v3 406 with: 407 github_token: ${{ secrets.GITHUB_TOKEN }} 408 publish_dir: ./public 409 force_orphan: true 410 ``` 411 412 ### ⭐️ Set Git username and email 413 414 Set custom `git config user.name` and `git config user.email`. 415 A commit is always created with the same user. 416 417 ```yaml 418 - name: Deploy 419 uses: peaceiris/actions-gh-pages@v3 420 with: 421 github_token: ${{ secrets.GITHUB_TOKEN }} 422 publish_dir: ./public 423 user_name: 'github-actions[bot]' 424 user_email: 'github-actions[bot]@users.noreply.github.com' 425 ``` 426 427 <img width="400px" alt="Add GitHub Actions bot as a committer" src="./images/committer_github_actions_bot.jpg"> 428 429 ### ⭐️ Set custom commit message 430 431 Set a custom commit message. 432 When we create a commit with a message `docs: Update some post`, a deployment commit will be generated with a message `docs: Update some post ${GITHUB_SHA}`. 433 434 ```yaml 435 - name: Deploy 436 uses: peaceiris/actions-gh-pages@v3 437 with: 438 github_token: ${{ secrets.GITHUB_TOKEN }} 439 publish_dir: ./public 440 commit_message: ${{ github.event.head_commit.message }} 441 ``` 442 443 <img width="400px" alt="Set a custom commit message - GitHub Actions for GitHub Pages" src="./images/commit_message.jpg"> 444 445 To set a full custom commit message without a triggered commit hash, 446 use the `full_commit_message` option instead of the `commit_message` option. 447 448 ```yaml 449 - name: Deploy 450 uses: peaceiris/actions-gh-pages@v3 451 with: 452 github_token: ${{ secrets.GITHUB_TOKEN }} 453 publish_dir: ./public 454 full_commit_message: ${{ github.event.head_commit.message }} 455 ``` 456 457 ### ⭐️ Create Git tag 458 459 Here is an example workflow. 460 461 ```yaml 462 name: github pages 463 464 on: 465 push: 466 branches: 467 - main 468 tags: 469 - 'v*.*.*' 470 471 jobs: 472 deploy: 473 runs-on: ubuntu-18.04 474 steps: 475 - uses: actions/checkout@v2 476 477 - name: Some build 478 479 - name: Prepare tag 480 id: prepare_tag 481 if: startsWith(github.ref, 'refs/tags/') 482 run: | 483 TAG_NAME="${GITHUB_REF##refs/tags/}" 484 echo "::set-output name=tag_name::${TAG_NAME}" 485 echo "::set-output name=deploy_tag_name::deploy-${TAG_NAME}" 486 487 - name: Deploy 488 uses: peaceiris/actions-gh-pages@v3 489 with: 490 github_token: ${{ secrets.GITHUB_TOKEN }} 491 publish_dir: ./public 492 tag_name: ${{ steps.prepare_tag.outputs.deploy_tag_name }} 493 tag_message: 'Deployment ${{ steps.prepare_tag.outputs.tag_name }}' 494 ``` 495 496 Commands on a local machine. 497 498 ```console 499 $ # On a main branch 500 $ git tag -a "v1.2.3" -m "Release v1.2.3" 501 $ git push origin "v1.2.3" 502 503 $ # After deployment 504 $ git fetch origin 505 $ git tag 506 deploy-v1.2.3 # Tag on the gh-pages branch 507 v1.2.3 # Tag on the main branch 508 ``` 509 510 <div align="right"> 511 <a href="#table-of-contents">Back to TOC ☝️</a> 512 </div> 513 514 515 516 ## Tips and FAQ 517 518 ### ⭐️ Create SSH Deploy Key 519 520 Generate your deploy key with the following command. 521 522 ```sh 523 ssh-keygen -t rsa -b 4096 -C "$(git config user.email)" -f gh-pages -N "" 524 # You will get 2 files: 525 # gh-pages.pub (public key) 526 # gh-pages (private key) 527 ``` 528 529 Next, Go to **Repository Settings** 530 531 - Go to **Deploy Keys** and add your public key with the **Allow write access** 532 - Go to **Secrets** and add your private key as `ACTIONS_DEPLOY_KEY` 533 534 | Add your public key | Success | 535 |---|---| 536 |  |  | 537 538 | Add your private key | Success | 539 |---|---| 540 |  |  | 541 542 ### ⭐️ First Deployment with `GITHUB_TOKEN` 543 544 The `GITHUB_TOKEN` has limitations for the first deployment so we have to select the GitHub Pages branch on the repository settings tab. After that, do the second deployment like the following pictures. 545 546 | First deployment failed | Go to the settings tab | 547 |---|---| 548 |  |  | 549 550 | Select branch | Deploying again and succeed | 551 |---|---| 552 |  |  | 553 554 ### ⭐️ Use the latest and specific release 555 556 We recommend you to use the latest and specific release of this action for stable CI/CD. 557 It is useful to watch this repository (release only) to check the [latest release] of this action. 558 559 [latest release]: https://github.com/peaceiris/actions-gh-pages/releases 560 561 For continuous updating, we can use the GitHub native Dependabot. 562 Here is an example configuration of the bot. The config file is located in `.github/dependabot.yml`. 563 564 ```yaml 565 version: 2 566 updates: 567 - package-ecosystem: "github-actions" 568 directory: "/" 569 schedule: 570 interval: "daily" 571 labels: 572 - "CI/CD" 573 commit-message: 574 prefix: ci 575 ``` 576 577 See the official documentation for more details about the Dependabot: [Keeping your dependencies updated automatically - GitHub Docs](https://docs.github.com/en/github/administering-a-repository/keeping-your-dependencies-updated-automatically) 578 579 ### ⭐️ Schedule and Manual Deployment 580 581 For deploying regularly, we can set the `on.schedule` workflow trigger. 582 See [Scheduled events | Events that trigger workflows - GitHub Docs](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#scheduled-events) 583 584 For deploying manually, we can set the `on.workflow_dispatch` workflow trigger. 585 See [Manual events `workflow_dispatch` | Events that trigger workflows - GitHub Docs](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#manual-events) 586 587 ```yaml 588 name: github pages 589 590 on: 591 push: 592 branches: 593 - main 594 schedule: 595 - cron: "22 22 * * *" 596 workflow_dispatch: 597 598 jobs: 599 deploy: 600 runs-on: ubuntu-18.04 601 steps: 602 ... 603 ``` 604 605 <div align="right"> 606 <a href="#table-of-contents">Back to TOC ☝️</a> 607 </div> 608 609 610 611 ## Examples 612 613 ### ⭐️ Static Site Generators with Node.js 614 615 [hexo], [vuepress], [react-static], [gridsome], [create-react-app] and so on. 616 Please check where your output directory is before pushing your workflow. 617 e.g. `create-react-app` requires `publish_dir` to be set to `./build` 618 619 [hexo]: https://github.com/hexojs/hexo 620 [vuepress]: https://github.com/vuejs/vuepress 621 [react-static]: https://github.com/react-static/react-static 622 [gridsome]: https://github.com/gridsome/gridsome 623 [create-react-app]: https://github.com/facebook/create-react-app 624 625 Premise: Dependencies are managed by `package.json` and `package-lock.json` 626 627 ```yaml 628 name: github pages 629 630 on: 631 push: 632 branches: 633 - main 634 635 jobs: 636 deploy: 637 runs-on: ubuntu-18.04 638 steps: 639 - uses: actions/checkout@v2 640 641 - name: Setup Node 642 uses: actions/setup-node@v2.1.2 643 with: 644 node-version: '12.x' 645 646 - name: Cache dependencies 647 uses: actions/cache@v2 648 with: 649 path: ~/.npm 650 key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }} 651 restore-keys: | 652 ${{ runner.os }}-node- 653 654 - run: npm ci 655 - run: npm run build 656 657 - name: Deploy 658 uses: peaceiris/actions-gh-pages@v3 659 with: 660 github_token: ${{ secrets.GITHUB_TOKEN }} 661 publish_dir: ./public 662 ``` 663 664 ### ⭐️ Gatsby 665 666 An example for [Gatsby] (Gatsby.js) project with [gatsby-starter-blog] 667 668 [Gatsby]: https://github.com/gatsbyjs/gatsby 669 [gatsby-starter-blog]: https://github.com/gatsbyjs/gatsby-starter-blog 670 671 ```yaml 672 name: github pages 673 674 on: 675 push: 676 branches: 677 - main 678 679 jobs: 680 deploy: 681 runs-on: ubuntu-18.04 682 steps: 683 - uses: actions/checkout@v2 684 685 - name: Setup Node 686 uses: actions/setup-node@v2.1.2 687 with: 688 node-version: '12.x' 689 690 - name: Cache dependencies 691 uses: actions/cache@v2 692 with: 693 path: ~/.npm 694 key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }} 695 restore-keys: | 696 ${{ runner.os }}-node- 697 698 - run: npm ci 699 - run: npm run format 700 - run: npm run test 701 - run: npm run build 702 703 - name: Deploy 704 uses: peaceiris/actions-gh-pages@v3 705 with: 706 github_token: ${{ secrets.GITHUB_TOKEN }} 707 publish_dir: ./public 708 ``` 709 710 ### ⭐️ React and Next 711 712 An example for [Next.js] (React.js) project with [create-next-app] 713 714 - cf. [Deploying a Next.js app into GitHub Pages · zeit/next.js Wiki](https://github.com/zeit/next.js/wiki/Deploying-a-Next.js-app-into-GitHub-Pages) 715 716 [Next.js]: https://github.com/zeit/next.js 717 [create-next-app]: https://nextjs.org/docs 718 719 ```yaml 720 name: github pages 721 722 on: 723 push: 724 branches: 725 - main 726 727 jobs: 728 deploy: 729 runs-on: ubuntu-18.04 730 steps: 731 - uses: actions/checkout@v2 732 733 - name: Setup Node 734 uses: actions/setup-node@v2.1.2 735 with: 736 node-version: '12.x' 737 738 - name: Get yarn cache 739 id: yarn-cache 740 run: echo "::set-output name=dir::$(yarn cache dir)" 741 742 - name: Cache dependencies 743 uses: actions/cache@v2 744 with: 745 path: ${{ steps.yarn-cache.outputs.dir }} 746 key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }} 747 restore-keys: | 748 ${{ runner.os }}-yarn- 749 750 - run: yarn install --frozen-lockfile 751 - run: yarn build 752 - run: yarn export 753 754 - name: Deploy 755 uses: peaceiris/actions-gh-pages@v3 756 with: 757 github_token: ${{ secrets.GITHUB_TOKEN }} 758 publish_dir: ./out 759 ``` 760 761 ### ⭐️ Vue and Nuxt 762 763 An example for [Nuxt.js] (Vue.js) project with [create-nuxt-app] 764 765 - cf. [GitHub Pages Deployment - Nuxt.js](https://nuxtjs.org/faq/github-pages) 766 767 [Nuxt.js]: https://github.com/nuxt/nuxt.js 768 [create-nuxt-app]: https://github.com/nuxt/create-nuxt-app 769 770 ```yaml 771 name: github pages 772 773 on: 774 push: 775 branches: 776 - main 777 778 jobs: 779 deploy: 780 runs-on: ubuntu-18.04 781 steps: 782 - uses: actions/checkout@v2 783 784 - name: Setup Node 785 uses: actions/setup-node@v2.1.2 786 with: 787 node-version: '12.x' 788 789 - name: Cache dependencies 790 uses: actions/cache@v2 791 with: 792 path: ~/.npm 793 key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }} 794 restore-keys: | 795 ${{ runner.os }}-node- 796 797 - run: npm ci 798 - run: npm test 799 - run: npm run generate 800 801 - name: deploy 802 uses: peaceiris/actions-gh-pages@v3 803 with: 804 github_token: ${{ secrets.GITHUB_TOKEN }} 805 publish_dir: ./dist 806 ``` 807 808 ### ⭐️ Docusaurus 809 810 An example workflow for [Docusaurus](https://docusaurus.io/). 811 812 `npx @docusaurus/init@next init website classic` is useful to create a new Docusaurus project. 813 814 ```yaml 815 # .github/workflows/deploy.yml 816 817 name: github pages 818 819 on: 820 push: 821 branches: 822 - main 823 paths: 824 - '.github/workflows/deploy.yml' 825 - 'website/**' 826 827 jobs: 828 deploy: 829 runs-on: ubuntu-18.04 830 defaults: 831 run: 832 working-directory: website 833 steps: 834 - uses: actions/checkout@v2 835 836 - name: Setup Node 837 uses: actions/setup-node@v2.1.2 838 with: 839 node-version: '12.x' 840 841 - name: Get yarn cache 842 id: yarn-cache 843 run: echo "::set-output name=dir::$(yarn cache dir)" 844 845 - name: Cache dependencies 846 uses: actions/cache@v2 847 with: 848 path: ${{ steps.yarn-cache.outputs.dir }} 849 key: ${{ runner.os }}-website-${{ hashFiles('**/yarn.lock') }} 850 restore-keys: | 851 ${{ runner.os }}-website- 852 853 - run: yarn install --frozen-lockfile 854 - run: yarn build 855 856 - name: Deploy 857 uses: peaceiris/actions-gh-pages@v3 858 with: 859 github_token: ${{ secrets.GITHUB_TOKEN }} 860 publish_dir: ./website/build 861 ``` 862 863 ### ⭐️ Static Site Generators with Python 864 865 [pelican], [MkDocs], [sphinx], and so on. 866 867 [pelican]: https://github.com/getpelican/pelican 868 [MkDocs]: https://github.com/mkdocs/mkdocs 869 [sphinx]: https://github.com/sphinx-doc/sphinx 870 871 Premise: Dependencies are managed by `requirements.txt` 872 873 ```yaml 874 name: github pages 875 876 on: 877 push: 878 branches: 879 - main 880 881 jobs: 882 deploy: 883 runs-on: ubuntu-18.04 884 steps: 885 - uses: actions/checkout@v2 886 887 - name: Setup Python 888 uses: actions/setup-python@v2 889 with: 890 python-version: '3.8' 891 892 - name: Upgrade pip 893 run: | 894 # install pip=>20.1 to use "pip cache dir" 895 python3 -m pip install --upgrade pip 896 897 - name: Get pip cache dir 898 id: pip-cache 899 run: echo "::set-output name=dir::$(pip cache dir)" 900 901 - name: Cache dependencies 902 uses: actions/cache@v2 903 with: 904 path: ${{ steps.pip-cache.outputs.dir }} 905 key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }} 906 restore-keys: | 907 ${{ runner.os }}-pip- 908 909 - name: Install dependencies 910 run: python3 -m pip install -r ./requirements.txt 911 912 - run: mkdocs build 913 914 - name: Deploy 915 uses: peaceiris/actions-gh-pages@v3 916 with: 917 github_token: ${{ secrets.GITHUB_TOKEN }} 918 publish_dir: ./site 919 ``` 920 921 ### ⭐️ mdBook (Rust) 922 923 An example GitHub Actions workflow to deploy [rust-lang/mdBook] site to GitHub Pages. 924 925 [rust-lang/mdBook]: https://github.com/rust-lang/mdBook 926 927 - [peaceiris/actions-mdbook: GitHub Actions for mdBook (rust-lang/mdBook)](https://github.com/peaceiris/actions-mdbook) 928 929 ```yaml 930 name: github pages 931 932 on: 933 push: 934 branches: 935 - main 936 937 jobs: 938 deploy: 939 runs-on: ubuntu-18.04 940 steps: 941 - uses: actions/checkout@v2 942 943 - name: Setup mdBook 944 uses: peaceiris/actions-mdbook@v1 945 with: 946 mdbook-version: '0.4.5' 947 # mdbook-version: 'latest' 948 949 - run: mdbook build 950 951 - name: Deploy 952 uses: peaceiris/actions-gh-pages@v3 953 with: 954 github_token: ${{ secrets.GITHUB_TOKEN }} 955 publish_dir: ./book 956 ``` 957 958 ### ⭐️ Flutter Web 959 960 An exapmle workflow for [Flutter web project]. 961 962 [Flutter web project]: https://flutter.dev/docs/get-started/web 963 964 ```yaml 965 name: github pages 966 967 on: 968 push: 969 branches: 970 - main 971 972 jobs: 973 deploy: 974 runs-on: ubuntu-18.04 975 steps: 976 - uses: actions/checkout@v2 977 978 - name: Setup Flutter 979 run: | 980 git clone https://github.com/flutter/flutter.git --depth 1 -b beta _flutter 981 echo "${GITHUB_WORKSPACE}/_flutter/bin" >> ${GITHUB_PATH} 982 983 - name: Install 984 run: | 985 flutter config --enable-web 986 flutter pub get 987 988 - name: Build 989 run: flutter build web 990 991 - name: Deploy 992 uses: peaceiris/actions-gh-pages@v3 993 with: 994 github_token: ${{ secrets.GITHUB_TOKEN }} 995 publish_dir: ./build/web 996 ``` 997 998 ### ⭐️ Elm 999 1000 An example workflow for [Elm]. 1001 1002 [Elm]: https://elm-lang.org 1003 1004 ```yaml 1005 name: github pages 1006 1007 on: 1008 push: 1009 branches: 1010 - main 1011 1012 jobs: 1013 deploy: 1014 runs-on: ubuntu-18.04 1015 steps: 1016 - uses: actions/checkout@v2 1017 1018 - name: Setup Node 1019 uses: actions/setup-node@v2.1.2 1020 with: 1021 node-version: '12.x' 1022 1023 - name: Setup Elm 1024 run: npm install elm --global 1025 1026 - name: Make 1027 run: elm make --optimize src/Main.elm 1028 1029 - name: Move files 1030 run: | 1031 mkdir ./public 1032 mv ./index.html ./public/ 1033 # If you have non-minimal setup with some assets and separate html/js files, 1034 # provide --output=<output-file> option for `elm make` and remove this step 1035 1036 - name: Deploy 1037 uses: peaceiris/actions-gh-pages@v3 1038 with: 1039 github_token: ${{ secrets.GITHUB_TOKEN }} 1040 publish_dir: ./public 1041 ``` 1042 1043 ### ⭐️ github/personal-website 1044 1045 - [github/personal-website](https://github.com/github/personal-website) - Code that'll help you kickstart a personal website that showcases your work as a software developer. 1046 1047 ```yaml 1048 # .github/workflows/github-pages.yml 1049 1050 name: GitHub Pages 1051 1052 on: 1053 push: 1054 branches: 1055 - master 1056 schedule: 1057 - cron: '24 */24 * * *' # Once a day 1058 1059 jobs: 1060 deploy: 1061 runs-on: ubuntu-18.04 1062 steps: 1063 - uses: actions/checkout@v2 1064 - name: Deploy to GitHub Pages 1065 uses: peaceiris/actions-gh-pages@v3 1066 with: 1067 github_token: ${{ secrets.GITHUB_TOKEN }} 1068 publish_dir: ./ 1069 allow_empty_commit: true 1070 enable_jekyll: true 1071 cname: github.peaceiris.com 1072 ``` 1073 1074 ### ⭐️ Swift Publish 1075 1076 An example workflow for [JohnSundell/Publish]. 1077 1078 [JohnSundell/Publish]: https://github.com/JohnSundell/Publish 1079 1080 ```yaml 1081 name: GitHub Pages 1082 1083 on: 1084 push: 1085 branches: 1086 - main 1087 1088 jobs: 1089 deploy: 1090 runs-on: macos-latest 1091 steps: 1092 - uses: actions/checkout@v2 1093 1094 - uses: actions/cache@v2 1095 with: 1096 path: | 1097 ~/Publish_build 1098 .build 1099 key: ${{ runner.os }}-spm-${{ hashFiles('**/Package.resolved') }} 1100 restore-keys: | 1101 ${{ runner.os }}-spm- 1102 1103 - name: Setup JohnSundell/Publish 1104 run: | 1105 cd ${HOME} 1106 export PUBLISH_VERSION="0.7.0" 1107 git clone https://github.com/JohnSundell/Publish.git 1108 cd ./Publish && git checkout ${PUBLISH_VERSION} 1109 mv ~/Publish_build .build || true 1110 swift build -c release 1111 cp -r .build ~/Publish_build || true 1112 echo "${HOME}/Publish/.build/release" >> ${GITHUB_PATH} 1113 1114 - run: publish-cli generate 1115 1116 - name: Deploy to GitHub Pages 1117 uses: peaceiris/actions-gh-pages@v3 1118 with: 1119 github_token: ${{ secrets.GITHUB_TOKEN }} 1120 publish_dir: ./Output 1121 ``` 1122 1123 <div align="right"> 1124 <a href="#table-of-contents">Back to TOC ☝️</a> 1125 </div> 1126 1127 1128 1129 ## License 1130 1131 - [MIT License - peaceiris/actions-gh-pages] 1132 1133 [MIT License - peaceiris/actions-gh-pages]: https://github.com/peaceiris/actions-gh-pages/blob/main/LICENSE 1134 1135 1136 1137 ## Maintainer 1138 1139 - [peaceiris homepage](https://peaceiris.com/) 1140 - [GitHub Action Hero: Shohei Ueda - The GitHub Blog](https://github.blog/2020-03-22-github-action-hero-shohei-ueda/) 1141 1142 1143 1144 <div align="right"> 1145 <a href="#table-of-contents">Back to TOC ☝️</a> 1146 </div>