JuliaRegistrator や TagBot でtag 打ちをしても stable Document が生成されない対処法

本日は

General に登録した（≒いわゆる公式パッケージと呼ばれているもの）パッケージを日々メンテしていくとドキュメントもメンテしたくなります．stable 版のリンクが生成されない問題を解決しましたので情報共有したいと思います.

現象

リリースタグをつけてるのに対応するバージョンのリンクが作成されない.

dev しか出ないが・・・？？？

期待する結果

Julia の Documentation のように各バージョンごとのドキュメントのリンクが作成されて欲しい

分かったこと

DOCUMENTER＿KEY の設定を行う必要があった.

文脈の補足

なぜこういう話が出てくるようになったかの文脈を補足します．公式パッケージをリリースしたあとメンテする際にハマる気がしたので書いておこうと思ったからです．

公式パッケージとして登録した後のメンテ方法

昔書いた Qiita 記事も参考にしてください:

• https://qiita.com/SatoshiTerasaki/items/7dbb809c962e794a9df6

バージョンの更新

例えば，読者は，PkgTemplates.jl を利用しパッケージの雛形を作ったとします．そして何かしらの機能を提供する Julia パッケージを GitHub などで公開したとします. それを Julia の，「いわゆる公式パッケージ」にしたとします．ここで「いわゆる公式パッケージ」というのは Julia のパッケージ情報を格納する General レジストリ に登録されたものを指しています.

初期のバージョン 0.1.0 から機能追加，バグ修正を main ブランチにマージしそろそろ安定板をリリースしたいと仮定します. 例えばバージョン番号を 0.2.0 としてリリースしたいとします.

どういうふうにバージョン番号を上げていくかは https://semver.org/#summary を見ると良いです．

まずはメンテナンスしているパッケージの Project.toml を編集し 0.1.0 を 0.2.0 に変更しましょう．

Before:

Project.toml

name = "YourPkg"
uuid = "xxxxxxx"
authors = ["Goma-chan kawaii and contributors"]
version = "0.1.0"

After:

Project.toml

name = "YourPkg"
uuid = "xxxxxxx"
authors = ["Goma-chan kawaii and contributors"]
version = "0.2.0"

この変更を行う, ブランチを作り, コミット, そしてプルリクエストをだして GitHubAction の CI が通ったことを確認しマージします．

作業を　JuliaRegistrator　bot に依頼

GitHub のリポジトリ直下でマージした後のコミットのハッシュをクリックします（下図参照，この場合 fc16524 をクリック）．

コメント欄で下記のメッセージをコメントとして書きます.

@JuliaRegistrator register

このリンク を参考にしてください:

あとは全て JuliaRegistrator bot General に自動プルリクエストを作成します.
General 側でのCIが通り特に問題がなければ自動的にマージされます．

そのあとは？

インターネット上にある PkgTemplates.jl でパッケージの雛形を作る方法に従うと　.github/workflows/TagBot.yml が生成されているはずです:

name: TagBot
on:
  issue_comment:
    types:
      - created
  workflow_dispatch:
jobs:
  TagBot:
    if: github.event_name == 'workflow_dispatch' || github.actor == 'JuliaTagBot'
    runs-on: ubuntu-latest
    steps:
      - uses: JuliaRegistries/TagBot@v1
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          ssh: ${{ secrets.DOCUMENTER_KEY }}

General レジストリで自動PRがマージされるとこの結果をトリガーにし TagBot.yml で定義された Action が動作します. これでリリースタグ v0.2.0 が Release ページに生成されます．

ここからが本番

さて，本来ならリリースタグを作成することで v0.2.0 用のソフトウェアドキュメントが Documenter.jl によって作られるはずです．でも出ないんです．

TagBot のドキュメントを読む

https://github.com/JuliaRegistries/TagBot の README を読みましょう.

You may, however, want to customize the behaviour via the available configuration options.

For example, if you use GitHub Actions to build the documentation for your package, you will find that with the default TagBot configuration, your documentation build is not triggered when a new tag is created. In this case, you will need to use SSH Deploy Keys.

Read on for a full description of all of the available configuration options.

はーん．．．

your documentation build is not triggered when a new tag is created.

なるほど．つまり色々設定が必要だったようです．リリースタグをリポジトリの管理者が手動で作成する場合は特に困ることはないですけれど，botを経由して自動でリリースタグを作った場合は SSH Deploy Keys を作る必要があるようです．

作り方

作業の方針は Qiita に書いていたもの をベースにすればOKです．Qiita の記事は古くなったので Zenn の上で更新します．

DocumenterTools.jl の導入

下記のように DocumenterTools.jl を導入します.

julia> using Pkg
julia> Pkg.add("DocumenterTools")

REPL で下記を実行します:

julia> using DocumenterTools
julia> DocumenterTools.genkeys(user="YourGitHubUserName", repo="YourPkg.jl")

ここで GitHub で管理しているリポジトリのURLが https://github.com/YourGitHubUserName/YourPkg.jl の場合を仮定しています.

YourGitHubUserName は会社だったり組織だったりするかもしれません. 適宜読み替えてください. 出力は下記のようになります:

output

[ Info: add the public key below to https://github.com/YourGitHubUserName/YourPkg.jl/settings/keys with read/write access:

ssh-rsa <みじかーい文字列>= Documenter

[ Info: add a secure environment variable named 'DOCUMENTER_KEY' to https://travis-ci.com/YourGitHubUserName/YourPkg.jl/settings (if you deploy using Travis CI) or https://github.com/YourGitHubUserName/YourPkg.jl/settings/secrets (if you deploy using GitHub Actions) with value:

<ながーーーい文字列>

上記のログを冷静に眺めれば

https://github.com/YourGitHubUserName/YourPkg.jl/settings/keys

にアクセスし ssh-rsa <みじかーい文字列>= Documenter の値を登録すればOKです．その際にread/write access にチェックを入れる必要があります.

さらに

https://github.com/YourGitHubUserName/YourPkg.jl/settings/secrets

にアクセスし DOCUMENTER_KEY という名前で保存します．この DOCUMENTER_KEY は TagBot.yml にあるものと対応していると理解すればOKです．

TagBot.yml

'JuliaTagBot'
    runs-on: ubuntu-latest
    steps:
      - uses: JuliaRegistries/TagBot@v1
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          ssh: ${{ secrets.DOCUMENTER_KEY }} # <---- こいつのこと

あとは次回のリリース作業をすれば TagBot さんが ssh キーを検知しよしなに stable 用のページを作ってくれます．