Constructing the check

I decided that my strategy would be to write the main body of my CICD check as an R script. As I am relatively confident in R, the main challenge for me would be to then figure out how to automatically execute that script in a CICD pipeline.

After some playing around, I settled with the following 30-line script:

# Get list of blog posts ----
posts <- list.files("posts", recursive = TRUE, pattern = "*.qmd")

# Get vector of allowed tags ----
source("R/allowed_tags.R")

# Function to extract tags from a post and check them against the allowed list ----
check_post_tags <- function(post, allowed_post_tags = allowed_tags) {
  post_tags <- rmarkdown::yaml_front_matter(file.path("posts", post))$categories
  cross_check <- post_tags %in% allowed_post_tags
  problematic_tags <- post_tags[!cross_check]

  if (!all(cross_check)) {
    cli::format_message("The tag(s) {.val {problematic_tags}} in the post {.val {post}} are not from the allowed list of tags.")
  }
}

# Apply check_post_tags to all blog posts and find problem posts ----
check_results <- lapply(posts, check_post_tags)
error_messages <- unlist(Filter(Negate(is.null), check_results))

# Construct error message if one or more posts have problematic tags ----
if (length(error_messages) > 0) {
  error_messages <- c(error_messages, "Please select from the following tags: {.val {allowed_tags}}, or contact one of the maintainers.")
  names(error_messages) <- rep("x", length(error_messages) - 1)

  concatenated_error_messages <- cli::cli_bullets(error_messages)

  cli::cli_abort(concatenated_error_messages)
}

The script works as follows:

1. Get a full list of blog posts. These are all the .qmd files within the posts folder of the pharmaverseblog repo.
2. Specify a vector of “allowed tags” in the allowed_tags.R script.
3. Specify a function that, given a post:
   1. Extracts categories from the yaml header of the .qmd file.
   2. Cross-checks the tags with the allowed ones.
   3. For problematic tags, uses the {cli} package to construct a nicely-formatted error message.
4. Loop check_post_tags() over all blog posts using a simple lapply() call and extract all error messages.
5. If there are any error messages, use {cli} again to construct a concatenated error message.

The final error message looks something like the below:

✖ The tag(s) "ADaMs" in the post
  "2024-06-17_new_admiral_ex.../new_admiral_extension_packages_admiralpeds_coming_soon.qmd"
  are not from the allowed list of tags.
Please select from the following tags: "Metadata", "SDTM", "ADaM", "TLG", "Shiny",
"Community", "Conferences", "Submissions", and "Technical", or contact one of the maintainers.

Creating a pipeline for the check

When it came to creating a pipeline for the check, if you had asked me to do this a few months ago, I wouldn’t have known my left from my right. Luckily I had recently attended a great CICD workshop at useR 2024 in Salzburg, led by Daphne Grasselly, Franciszek Walkowiak and Pawel Rucki. You can find the repository from their workshop here - it was invaluable to orient me in the right direction. With a (very naive) google search, I also found this video, which shows how to execute an R script automatically whenever a pull request is made to the main branch of a repo.

Through some trial and error, I was able to coalesce the above resources into quite a short yaml file that set up my CICD pipeline. Within the pharmaverseblog repository, the CICD pipelines live under .github/workflows. There, I added the following new workflow, in the form of a yaml file, called check_post_tags.yml:

name: Check post tags

on:
  pull_request:
    branches:
      - 'main'

jobs:
  Check-post-tags:
    runs-on: ubuntu-latest
    container:
      image: "rocker/tidyverse:4.2.1"
    steps:
      - uses: actions/checkout@v4
      - name: Run check_post_tags
        run: source("R/check_post_tags.R")
        shell: Rscript {0}

It’s deceptively simple to read:

1. We execute the workflow upon any pull request to main.
2. When there is a pull request to main, we can load the rocker/tidyverse:4.2.1 docker image which has all the {tidyverse} packages pre-installed.
3. Then we need to checkout the pharmaverseblog repo and run the check_post_tags.R script.

That’s it! If there are any problematic posts, the script will throw an error and the check will fail like so:

Clicking on the “Details” option will return the error message I constructed previously.

Otherwise, no error will be thrown, the check will pass, and the post is good to go (provided the other checks pass)!