AsciidocのドキュメントをGitHub Actionsを用いてGitHub Pagesで公開する。
これを流し読みしてやってみた。
サンプルコード
完成ドキュメント
GitHub Pagesのポイント
GitHub Pagesの公開手法には以下の3パターンある。
- 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の場合はこうかな。
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の結果
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用のドキュメントが再構築され、元々あったはずのドキュメントが消える。そんなことは恐らく望む人はいないと思われる。
そんなことやってもいいという人は、下のようにすれば良い。
- 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が完了すれば、自動的にドキュメントが公開される。
Author And Source
この問題について(AsciidocのドキュメントをGitHub Actionsを用いてGitHub Pagesで公開する。), 我々は、より多くの情報をここで見つけました https://qiita.com/fake-deli-ca/items/1a946362e3d1993163e2著者帰属:元の著者の情報は、元のURLに含まれています。著作権は原作者に属する。
Content is automatically searched and collected through network algorithms . If there is a violation . Please contact us . We will adjust (correct author information ,or delete content ) as soon as possible .