AsciidocのドキュメントをGitHub Actionsを用いてGitHub Pagesで公開する。

これを流し読みしてやってみた。

サンプルコード

完成ドキュメント

GitHub Pagesのポイント

GitHub Pagesの公開手法には以下の３パターンある。

• gh-pagesブランチで公開
• masterブランチで公開
• masterブランチの/docフォルダで公開
  https://help.github.com/ja/enterprise/2.14/user/articles/configuring-a-publishing-source-for-github-pages
  単なる静的コンテンツの場合は、masterブランチでの公開でいい気がするのだが、asciidocなど他を利用する場合は、gh-pagesブランチでの公開で良いと思う。理由は後述する。

だいたいymlはこんな感じ。

ドキュメントを読めばいいといえばそれまでだが。
https://github.com/peaceiris/actions-gh-pages

asciidocの場合はこうかな。

main.yml

name: Asciidoc Build&Deploy

on:
  push:
    branches: [ master ]
  pull_request:
    branches: [ master ]

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2
    - name: Set up JDK 1.11
      uses: actions/setup-java@v1
      with:
        java-version: 1.11
    - name: Change wrapper permissions
      run: chmod +x ./gradlew
    - name: Build with Gradle
      run: ./gradlew docs
    - name: Deploy
      # PR時にはDeployさせたくないので、merge時のみに実施する。
      if: github.ref == 'refs/heads/master'
      uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: ./docs

※ コメント頂いた箇所を訂正

GitHub Actions作成の基本は以下からそれっぽいものを探すのがまず第一である。
https://github.com/actions/starter-workflows/tree/master/ci

凝ったことをやろうとするなら、気合を入れてリファレンス読むのもいいのだが、結構色々できそうで、逆に訳わからない。
https://help.github.com/ja/actions/reference/workflow-syntax-for-github-actions#

各Stepの中でifが使えるので、どうしてもというときに使うのがポイントである。でも、if文駆使しすぎると普通に他の人が読めなくなる。

GitHub Actionsの結果

Actionsタブから見れば良い。

TOKEN利用時について補足

GITHUB_TOKENを利用する場合は、リポジトリのSettingsから下記手順を実施のこと。
https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-first-deployment-with-github_token

デフォルトの設定はgh-pages branchなので、上記のfirst deploymentの手順を実施しておけばそのようになる。

…と思ったが、どうやらgh-pagesブランチに入って、environmentをクリックし、一度以下の画面から参照する必要がありそうだ。

注意事項

なお、GitHub Actionsを利用してのドキュメントの公開をしたい場合、masterブランチでのGitHubPagesの公開はやめた方がいい。actions-gh-pagesをGitHub Actionsで動作させてみればわかるが、deploy時にmasterブランチ直下にpublish用のドキュメントが再構築され、元々あったはずのドキュメントが消える。そんなことは恐らく望む人はいないと思われる。

そんなことやってもいいという人は、下のようにすれば良い。

main.yml

    - name: Deploy
      uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_branch: master
        publish_dir: ./docs

追記(20200423)

コメント頂きましたが、これは想定動作ではなく修正中とのことでした。
https://github.com/peaceiris/actions-gh-pages/issues/245

完成！

これでmasterブランチでmergeが完了すれば、自動的にドキュメントが公開される。