workflows.md

What these workflows do?

audit.yaml

This workflow scans dependencies of your package for vulnerabilities using oysteR. Dependencies can be retrieved either from DESCRIPTION file or from renv.lock file.

bioccheck.yaml

This workflow implements Bioconductor-specific R package checks with BiocCheck.

branch-cleanup.yaml

This workflow checks if any (non-default) branches had the last commit added to them more than a configurable number of days ago. If yes, such branches are deleted.

build-check-install.yaml

This workflow includes the following activities:

1. Build an R package.
2. Run R CMD check.
3. Publish unit test summary.
4. Catch any notes, warnings etc. in the R CMD check output.
5. Install the package.

gitleaks.yaml

This workflow runs gitleaks on the repo to discover any secrets that might have been hardcoded.

Additionally, it runs presidio-cli to find any personally identifiable information (PII) within the git repo.

grammar.yaml

This workflow uses write-good to check changed files with names matching a pattern for English sentences that could be corrected. Then, it adds annotations to the pull request so that problematic grammar can be reviewed.

licenses.yaml

This workflow generates a license report of R package's dependencies for continuous compliance.

links.yaml

This workflow checks whether URLs embedded in code and documentation are valid. This workflow uses lychee to detect broken links. Occasionally, this check will detect false positives of strings that look like URLs. To remedy, please add this false positive to the .lycheeignore file.

linter.yaml

This workflow lints the codebase using super-linter.

pkgdown.yaml

Documentation for the R package is generated via this workflow. This workflow uses the pkgdown framework to generate documentation in HTML, and the HTML pages are then deployed to the gh-pages branch.

Moreover, an additional Versions dropdown is generated via the GitHub Action, so that the end user can view multiple versions of the documentation for the package.

release.yaml

This workflow creates a GitHub release from a git tag and generates changelog based on NEWS.md file.

roxygen.yaml

This workflow uses roxygen to generate .Rd files in man/ directory. It also checks if manuals are up-to-date with roxygen comments in the code.

spelling.yaml

Spellchecks are performed by this workflow, and the spelling R package is used to detect spelling mistakes. In the inst/WORDLIST file, you can add words and/or acronyms that you want the spell check to ignore.

style.yaml

Code style is enforced via the styler R package. The workflow can be configured to commit files that had styling problems automatically, after remediating the problems.

test-coverage.yaml

This workflow examines the test coverage of given R package with covr. Following that, coverage report is added to the PR. Additional feature is the ability to compare code coverage between branches, so the PR can be declined if the coverage would decrease following the merge.

The second part of the workflow runs utilizes covtracer to:

• prepare traceability matrix
• identify untested behavior
• verify directly tested functions

validation.yaml

This workflow generates and publishes validation report.

version-bump.yaml

This workflow increases R package version in NEWS.md and DESCRIPTION files and commits this change to the repository.

version.yaml

This workflow checks if NEWS.md and DESCRPTION files have the same R package version.

Adding unit test and coverage reports to pkgdown documentation

In order to add unit test reports and coverage reports to the documentation generated by pkgdown, the following steps are needed.

1. If you'd like to have a custom branding in unit test report, add unit-test-report-brand parameter to the build-check-install.yaml workflow. See examples below.

2. Don't use the skip-r-cmd-install parameter so that unit test report gets generated.

3. build-check-install.yaml and test-coverage.yaml should depend on pkgdown.yaml workflow. This is to ensure that race condition where pkgdown.yaml workflow overwrites gh-pages branch is avoided. This can be done for example by:

   • setting the needs: [docs] for build-check-install.yaml and test-coverage.yaml workflows,
   • or if the build-check-install.yaml and test-coverage.yaml are invoked from another workflow than pkgdown.yaml, additional dependency can be added which will trigger test-coverage.yaml and build-check-install.yaml after pkgdown.yaml has finished running. See example below.

4. _pkgdown.yaml should be updated with the following contents to ensure that links to coverage report and unit test report appear in the navbar.

   navbar:
     structure:
       left: [intro, reference, articles, tutorials, news, reports]
       right: [search, github]
     components:
       reports:
         text: Reports
         menu:
         - text: Coverage report
           href: coverage-report/
         - text: Unit test report
           href: unit-test-report/
       github:
         icon: fa-github
         href: <url-to-the-repository>

Example configuration for main branch:

name: Check 🛠
on:
  push:
    branches:
      - main
  workflow_run:
    workflows: ["Docs 📚"]
    types:
      - completed
jobs:
  r-cmd:
    name: R CMD Check 🧬
    uses: insightsengineering/coursera.cicd.lab/.github/workflows/build-check-install.yaml@main
    with:
      unit-test-report-brand: >-
        https://github.com/insightsengineering/hex-stickers/raw/main/thumbs/tern.png
  coverage:
    name: Coverage 📔
    uses: insightsengineering/coursera.cicd.lab/.github/workflows/test-coverage.yaml@main

Example configuration for tags:

name: Release 🎈
on:
  push:
    tags:
      - "v*"
jobs:
  build:
    name: Build package 🎁
    needs: [release, docs]
    uses: insightsengineering/coursera.cicd.lab/.github/workflows/build-check-install.yaml@main
    with:
      unit-test-report-brand: >-
        https://github.com/insightsengineering/hex-stickers/raw/main/thumbs/tern.png
  coverage:
    name: Coverage 📔
    needs: [release, docs]
    uses: insightsengineering/coursera.cicd.lab/.github/workflows/test-coverage.yaml@main
  docs:
    name: Pkgdown Docs 📚
    needs: release
    uses: insightsengineering/coursera.cicd.lab/.github/workflows/pkgdown.yaml@main