Technical notes are migrating to GitHub Actions

Tags: #<Tag:0x00007fb38283d848>

Starting today, technical notes that you create with @sqrbot-jr create project will integrate with GitHub Actions for their continuous integration and delivery to LSST the Docs.

Advantages of GitHub Actions

Overall, you shouldn’t notice a significant difference while you author technotes. Your technote’s editions will still update soon after you push to GitHub, and your pull requests will still include feedback about whether your document builds successfully or not. On a closer look, GitHub Actions brings us significant advantages:

  • Builds are blazing fast. Expect your LaTeX technote builds, which have traditionally been quite slow because of their Docker environment, to be quite snappy.
  • More reliable. With our previous CI solution, we’ve started to see more and more failures for a push to trigger a build and for that build status to be reflected back in the PR. This was a major motivation for us to use GitHub Actions and we couldn’t be happier with the greater reliability.
  • No more pull requests for encrypted credentials. Upload credentials for LSST the Docs are now stored as secrets with the associated GitHub organization. This means that you don’t need to remember to merge sqrbot’s pull request with encrypted upload credentials before your document appears on the web. For admins, this feature means it’s easier to rotate credentials.

In conjunction with this update, sqrbot-jr will now create new technotes with the GitHub repo’s description and homepage fields filled out.

Updating existing technical notes

The work that we’ve shipped today only affects new technical notes through updated templates, updates to the sqrbot-jr Slack bot, and Lander (the PDF landing page generator).

We intend to migrate all technical notes to GitHub Actions in the near future with automated PRs. If you feel inclined to skip the wait and migrate your technote yourself, you can do so. The steps are:

  1. Create a new file with the path .github/workflows/ci.yaml:
  2. Delete the .travis.yml file.
  3. Modify your README to reference GitHub Actions and use its badge. See this diff on GitHub for guidance.

If you have any questions, feel free to ask in this forum topic on #dm-docs in Slack.