[CI/CD] Pull Requestごとの環境を GitHub Pages へとデプロイする GitHub Actions の追加

[stefafafan]

Tip

実装にあたって https://github.com/jdkfx/phpdoc を参考にさせていただきました 🎉 ありがとうございます 🙏🏻

解決したい課題

• PHP 8.4 マニュアル翻訳状況 #150 の翻訳作業のハードルを下げたい
  • ちょっとした編集をコミットした後に意図通り反映されているかの確認を楽にしたい

実施したこと

• Pull Requestが開かれた際に、環境をビルドしGitHubのArtifactsにアップロードし、その結果をGitHub Pagesにデプロイするようにした
  • ArtifactsのRetention Periodは7日にしているので、ずっと溜まり続けることはないと思います

    doc-ja/.github/workflows/branch-preview.yaml

    Line 61 in d0fbafc

    retention-days: 7 # 1週間くらい残しておく

• その上で、デプロイされたURLをPull Requestにコメントするようにした

以下のコメントが実際に私のfork上で投稿されたコメント(stefafafan#1 (comment)) です:

php/doc-ja に組み込むために必要な設定

デフォルトのGitHubのリポジトリ設定では動かないので、以下の2点の設定が必要です。

/settings/pages から Source を GitHub Actions に変更する

デフォルトではDeploy from a branchになっているので、GitHub Actionsに変更する必要があります。

/settings/environments/ の github-pages の Deployment branches and tags の制限を緩める

デフォルトの状態だと main (master) branch 以外からGitHub Pagesへのデプロイはできないので緩める必要があります

追記: Workflow Approval 設定も見直したほうが便利かもしれません

このPull Requestを出して気づきましたが、初ContributeなこともあってCIは自動で走ってくれないようでした。
以下の設定の見直しも場合によってはすると良いかもしれません。

https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/approving-workflow-runs-from-public-forks

[stefafafan]

出したものの、こういう👇設定も変えないと100%便利ではないかもしれないか 🤔
https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/approving-workflow-runs-from-public-forks

pull_request_target でもいけるならそっちがいいかな (というのをもうちょっと調べてみる)

[jdkfx]

@stefafafan

私が作成したPHP 日本語マニュアル 翻訳用リポジトリ（以下、翻訳リポジトリ）では、以下の問題を抱えておりました。

• 変更を行なったファイルのURLを開きたい
• ビルドする対象を指定してビルドしたい

以前、KentarouTakeda さんにPRをいただいて、変更したファイルを見ることができるコマンドは追加されています。
しかし、私の翻訳リポジトリでのビルドにかかる時間が長いという問題がまだ残っており、その解決のために調査をする必要がありました。

ちょっとした編集をコミットした後に意図通り反映されているかの確認を楽にしたい

こちらのPRによって上記の内容が可能になれば、私の翻訳リポジトリの問題点を一気に解決できると考えています。

[stefafafan]

@jdkfx

共有ありがとうございます！ 🙌🏻

現状こちらのPRは全てをビルドしているので時間がかかってしまう点は変わりませんが、
確かに「変更を行なったファイルのみ再ビルド」という風にできるととても便利になりそうですね..！！

私もまだビルドの仕組みをちゃんとみてないですが暇ができたら詳しく見てみようと思います 👓

[takaram]

PRが来てこのワークフローが動いた場合、前のPRでデプロイされたページは消えてしまいますか？
そんなに立て続けにPRが来ることも多くはなさそうなので、PR作成直後に見られれば十分と考えれば消えたとしても大きな問題ではないのかもですが

[stefafafan]

@takaram

PRが来てこのワークフローが動いた場合、前のPRでデプロイされたページは消えてしまいますか？

全然気づいてなかったのですが現実装だとそうなってしまいそうです 😿

GitHub Pages only lets you configure one publishing source for a particular repository.
https://github.com/orgs/community/discussions/21582

ただ、あらゆるブランチの内容を共通のURLへマージしてパスをわける、みたいな工夫をやればできなくはなさそうかもです (それかデプロイ先としてGitHub Pagesの利用を諦めるか 🤔 )

I found a workaround for my needs. I used different files in the gh-pages branch to show different pages/test reports.
https://stackoverflow.com/a/75892056

[youkidearitai]

@stefafafan
ありがとうございます！そこまでするかどうかはお任せしますが https://github.com/php/doc-en で取り込まれると各言語で使えるようになるかもしれませんね（各言語のメンテナー次第かもしれません）

[stefafafan]

@youkidearitai 提案ありがとうございます 🙌🏻

そのうち doc-en にも英語でPR出して反応みてみようと思います 👍🏻

[KentarouTakeda]

@stefafafan
大変素晴らしいプルリクエストありがとうございます。お返事が遅くなり大変申し訳ございません。

是非とも欲しい機能なのですが、今の形で取り込むのは難しい気がしてます。とは言えアイディアは活かしたいので、代替案を考えてみました。

難しい理由

• 悪意のあるプルリクエストへの対応:
  Contributorの履歴があるアカウントから、不適切な内容のプルリクエストが送信された場合、それも php/* のリソースから配信されてしまう点
• 他リポジトリでの対応:
  php/web-php で最近、同等の機能をメンテナが承認したプルリクエストのみに絞る対応を行っている点

代替案

• 参考: php/doc-en では、ビルド済のxmlファイルをartifactとして保存する実装が存在する
• 提案: これに対し html の生成結果も保存すれば（ユーザービリティに難は残るが）似たことを行える
  • 実施する場合、コントリビューターのためにドキュメントでの公知などを検討します。

一旦、この形にとどめておいてみるのはどうでしょうか？検討頂けると幸いです！

@mumumu
もし何かご意見やアドバイスあれば頂けると幸いです！

[stefafafan]

@KentarouTakeda
わざわざご検討ありがとうございます！

生成結果をArtifactsに残すことに留めるという代替案で個人的には問題ないと思います！

他にあるとしたらGitHub Actionsでがんばるのではなく、たとえば Cloudflare Pages の Preview deployments とか、Vercelとか、サードパーティのものとリポジトリを連携してプレビューを作ることも可能そうですが、GitHub以外のサービスを利用する・しないの判断が大変そうなので、
まずは武田さんの案がちょうどよいかなと思いました！

[mumumu]

是非とも欲しい機能なのですが、今の形で取り込むのは難しい気がしてます。

私もすぐには難しいと思います。

php/* 以下の各リポジトリの設定を変更できるのは一部のメンバに限られている（私も権限は持っていません）ので、まずは少なくとも doc-en の連中に本件の仕組みを納得させる必要があります。

ちょっとした編集をコミットした後に意図通り反映されているかの確認を楽にしたい

個人的には、本件の仕組みはプレビューを実現するには大掛かり過ぎると思います。
そのため、以下の代替案を示しておきます。

---

PHP Manual は、巨大な docbook を phd コマンドで XHTML に変換したものです。

https://github.com/php/phd

なので、プレビューを高速にやりたいのなら、これを改造するのが近道だと思います。phd がどのようにマニュアルを生成しているのかはソースを読んでもらえればと思いますが、概ね以下のような動きをします

• マニュアルの種となる xml を読み取り、xmlツリーの情報を sqlite に保存する
  • この sqlite の生成処理は -I オプションでスキップできます
• 上記を読み取り、指定したフォーマットでレンダリングする
  • ここでファイルをひとつひとつ処理しているので、お目当てのファイル以外はスキップすると、特定のファイルのみ高速な生成が可能かもしれません