Stable (tagged) versions are not being deployed?

tpoisot · April 30, 2023, 4:34pm

I am using this workflow file to build the documentation for a package:

PoisotLab/SpeciesDistributionToolkit.jl/blob/main/.github/workflows/Documentation.yml

name: Documentation
on:
  push:
    branches: [main]
    tags: '*'
  pull_request:

jobs:
  Documenter:
    permissions:
      contents: write
    name: Documentation
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: julia-actions/setup-julia@v1
        with:
          version: '1.8'
      - name: Setup the component packages (globally)
        run: julia --project bootstrap.jl

This file has been truncated. show original

The dev version works, but the tags (which are generated by TagBot) are not resulting in a stable version being built.

Is there something obviously wrong in my workflow?

Following question: is there a way to retro-actively build the website for the different tags?

gdalle · April 30, 2023, 5:11pm

I had the same problem this week, not sure why it happens but the Documenter.jl documentation has a fix:

It can happen that, for one reason or another, the documentation for a tagged version of your package fails to deploy and a fix would require changes to the source code (e.g. a misconfigured make.jl). However, as registered tags should not be changed, you can not simply update the original tag (e.g. v1.2.3) with the fix.
In this situation, you can manually create and push a tag for the commit with the fix that has the same version number, but also some build metadata (e.g. v1.2.3+doc1). For Git, this is a completely different tag, so it won’t interfere with anything. But when Documenter runs on this tag, it will ignore the build metadata and deploy the docs as if they were for version v1.2.3.
Note that, as with normal tag builds, you need to make sure that your CI that runs Documenter is configured to run on such tags (e.g. that the regex constraining the branches the CI runs on is broad enough etc).

jishnub · May 1, 2023, 3:11am

You might also need an SSH key, as I think GitHub actions (tagbot in this case) can’t trigger another GitHub action (documenter build) using the GitHub token. Typically packages define a variable named ‘DOCUMENTER_KEY’