How to fix stable documentation not being generated when tagging with JuliaRegistrator or TagBot

Introduction

As you maintain packages registered in the General registry (≒ what are commonly called "official packages") on a daily basis, you'll naturally want to keep the documentation updated as well. I've resolved an issue where links to the stable version were not being generated, so I'd like to share the details.

The Phenomenon

Even though release tags are applied, links for the corresponding versions are not being created.

Only dev appears... why???

Expected Result

I want documentation links to be generated for each version, similar to how it works for Julia's own documentation.

What I Found Out

I needed to set up the DOCUMENTER_KEY.

Contextual Background

I'll provide some context on why this topic came up. I wanted to write this down because I felt it's easy to get stuck when maintaining an official package after its initial release.

Maintenance After Official Registration

Please also refer to my previous Qiita article (in Japanese):

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

Updating the Version

For example, let's assume you used PkgTemplates.jl to create a package template and then published a Julia package on GitHub. Suppose you then made it a "so-called official package." By "so-called official package," I mean a package registered in the General registry, which stores Julia package information.

Suppose you have merged feature additions or bug fixes into the main branch since the initial version 0.1.0 and now want to release a stable version—say, version 0.2.0.

You should refer to https://semver.org/#summary regarding how to increment version numbers.

First, edit the Project.toml of the package you are maintaining and change 0.1.0 to 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"

Create a branch for this change, commit it, and submit a pull request. Once you confirm the GitHub Actions CI has passed, merge it.

Requesting the Task from the JuliaRegistrator Bot

Click the commit hash after merging in the root of the GitHub repository (see the figure below; in this case, click fc16524).

Post the following message as a comment in the comment section:

@JuliaRegistrator register

Please refer to this link for reference:

The JuliaRegistrator bot will then handle everything and automatically create a pull request to the General registry. If the CI on the General registry side passes and there are no issues, it will be merged automatically.

What's Next?

If you followed the methods for creating a package template with PkgTemplates.jl found on the internet, a .github/workflows/TagBot.yml file should have been generated:

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 }}

When the automatic PR is merged in the General registry, it triggers the action defined in TagBot.yml. This creates the release tag v0.2.0 on the Release page.

The Real Challenge Starts Here

Now, normally, creating a release tag should trigger Documenter.jl to build the software documentation for v0.2.0. But it doesn't appear.

Reading the TagBot Documentation

Let's read the README at https://github.com/JuliaRegistries/TagBot.

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.

I see...

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

I see. It seems various settings were required. If the repository administrator creates the release tag manually, there usually isn't an issue. However, if the release tag is created automatically via a bot, it seems necessary to create SSH Deploy Keys.

How to Set It Up

You can base your work on the approach previously described on Qiita. Since that Qiita article is now outdated, I will update the information here on Zenn.

Introducing DocumenterTools.jl

Install DocumenterTools.jl as follows:

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

Run the following in the REPL:

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

This assumes that the URL of the repository you are managing on GitHub is https://github.com/YourGitHubUserName/YourPkg.jl.

YourGitHubUserName might be an individual, a company, or an organization; please substitute it accordingly. The output will look like this:

output

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

ssh-rsa <short string>= 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:

<long string>

If you look at the logs above calmly, you can see that you just need to access:

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

and register the value ssh-rsa <short string>= Documenter. At that time, you need to check the "read/write access" box.

Furthermore, access:

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

and save it under the name DOCUMENTER_KEY. You just need to understand that this DOCUMENTER_KEY corresponds to the one in TagBot.yml.

TagBot.yml

'JuliaTagBot'
    runs-on: ubuntu-latest
    steps:
      - uses: JuliaRegistries/TagBot@v1
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          ssh: ${{ secrets.DOCUMENTER_KEY }} # <---- This is it

After that, when you perform the next release, TagBot will detect the SSH key and properly generate the stable version pages for you.