This repository contains workflows to be used for Lessons using the Carpentries Workbench lesson infrastructure.

The three docker- workflows build lessons and maintain packages. The workflows run using the workbench-docker container. This container comprises prebuilt and installed dependencies of the core Workbench packages, i.e. sandpaper, pegboard and varnish.

Two update- workflows handle:

• checking for new renv packages and creating a Pull Request (PR) when a renv.lock file updates (update-cache.yaml)
• checking for updated versions of these workflow files (update-workflows.yaml)

The rest of the pr- workflows handle pull request management via base GitHub Actions.

For Carpentries Core Curriculum lessons across our lesson programmes, maintenance of these workflows should be minimal. For your own lesson repositories, it is important to understand the different workflows and what they do.

More information about workflow specific options is in the workflow documentation README

These workflows run on a mix of schedules, automatic triggers, and at the maintainer's request. Because they create pull requests that update workflows/require the downstream actions to run, they need a repository/organization secret token.

For "official" lessons which are those in the lesson program repositories, Incubator, or Lab, you don't need to manage any tokens as this is done for you.

If you are using lessons in your own repository, you need to create a token called SANDPAPER_WORKFLOW and it must have the public_repo and workflow scope. This can be an individual user token, OR it can be a trusted bot account.

If you want to use your personal account: you can go to https://github.com/settings/tokens/new?scopes=public_repo,workflow&description=Sandpaper%20Token to create a token. Once you have created your token, you should copy it to your clipboard and then go to your repository's Settings > Secrets > Actions and create or edit the SANDPAPER_WORKFLOW secret, pasting in the generated token.

This is the main workflow that you will encounter most often.

It will only act on the main branch of the lesson repository.

This workflow does the following:

1. checks out the lesson
2. provisions the following resources
   • the Workbench Docker container
   • lesson dependencies if needed (stored in a cache)
3. builds the lesson via sandpaper:::ci_deploy()

If your lesson contains rendered content using RMarkdown and/or any associated R package dependencies, you will need to generate and apply the renv cache. Please read the Caching section.

For lessons that have generated content, we use {renv} to ensure that the output is stable. This is controlled by a single lockfile which documents the packages needed for the lesson and the version numbers. This workflow is skipped in lessons that do not have generated content.

Packages are frequently updated, fixing bugs or introducing new features. It's a good idea to make sure these packages can be both: updated periodically, or; or left static to ensure consistent lesson builds.

The "02 Maintain: Check for Updated Packages" workflow will do this by:

• checking repositories for updates
• updating the renv lockfile
• summarising the updated packages and their versions in a branch called updates/packages
• creating a pull request with only the renv lockfile changed

From here, the markdown documents will be rebuilt and you can inspect what has changed based on how the packages have updated.

If all steps pass in this workflow, you can safely merge the PR that is raised. Once the PR is merged, the "03 Maintain: Apply Package Cache" workflow will run automatically to save the cache for future use.

This workflow takes the updated lockfile produced in "02 Maintain: Check for Updated Packages" and uses it to produce a cache file of the used packages. This cached file can then be reused repeatedly by the "01 Maintain: Build and Deploy Site" workflow, improving build times and allowing consistent package versioning.

This workflow is run automatically when the PR generated by "02 Maintain: Check for Updated Packages" is closed and merged.

You would only ever need to run this workflow manually:

• you have manually updated your lockfile and don't need to explicitly check for package updates using the workflow
• if your cache gets removed by GitHub due to age or non-use
• if your cache file contains packages that cannot be used by a Workbench Docker container's newer R version

The {sandpaper} repository was designed to do as much as possible to separate the tools from the content. For local builds, this is absolutely true as you can develop and build lessons without any GitHub workflows. When it comes to workflow files on GitHub itself for managed builds online, the workflows must live inside the lesson repository.

This workflow ensures that the workflow files are up-to-date. It downloads the update-workflows.sh script from GitHub and runs it. The current version of the workflows will be stored in the .github/workflows/workflows-version.txt file.

The script will do the following:

1. check the recorded version of the workbench-workflows against the current version on GitHub
2. update the files if there is a difference in versions

After the files are updated, and if there are any changes, they are pushed to a branch called update/workflows and a pull request is created. Maintainers are encouraged to review the changes and accept the pull request if the outputs are okay.

This update is run weekly or on demand.