Skip to contents

This repository contains GitHub Actions continuous integration/continuous delivery (CI/CD) workflows, most of which are used by Admiral and its extensions extensions. Workflows defined here are responsible for assuring high package quality standards without compromising performance, security, or reproducibility.

Please refer to the .github/workflows directory to view the source code for the GitHub Actions workflows.

What these workflows do?

Most workflows have a BEGIN boilderplate steps and END boilderplate steps section within them which define some standard steps required for installing system dependencies, R version and R packages which serve as dependencies for the package.

The underlying mechanisms for installing R and Pandoc are defined in r-lib/actions, while the installation of system dependencies and R package dependencies is managed via the Staged Dependencies GitHub Action. The latter is used in conjunction with the staged_dependencies.yaml file in order to install dependencies that are in the same stage of development as the current package. You can read more about how it works here. Note that the latter is not necessary for this workflow to work and is completely optional.

Following the installation of system dependencies, R, and package dependencies, each workflow does something different.

check-templates.yml

Check Templates

This workflow checks for issues within template scripts. For example, in admiral package there are several template scripts with admiral-based functions showing how to build certain ADaM datasets. As we update the admiral functions, we want to make sure these template scripts execute appropriately. Functions in the template scripts that are deprecated or used inappropriately will cause this workflow to fail.

code-coverage.yml

Code Coverage

This workflow measures code coverage for unit tests and reports the code coverage as a percentage of the total number of lines covered by unit tests vs. the total number of lines in the codebase.

The covr R package is used to calculate the coverage.

Report summaries and badges for coverage are generated using a series of other GitHub Actions.

For this workflow to execute successfully, you will need to create an orphan branch called badges in your GitHub repository. You can do that using the following steps:

# Create orphan branch
git checkout --orphan badges
# Back up files
mv .git /tmp/.git-backup
# Remove everything else
rm -rf * .*
# Restore git files
mv /tmp/.git-backup .git
# Create a README file
echo "# Badges" > README.md
# Add, commit and push your new branch
git add . && git commit -m "Init badges" && git push origin badges

links.yml

Check URLs

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

lintr.yml

Lint

Static code analysis is performed by this workflow, which in turn uses the lintr R package.

Any .lintr configurations in the repository will be by this workflow.

man-pages.yml

Man Pages

This workflow checks if the manual pages in the man/ directory of the package are up-to-date with ROxygen comments in the code.

Workflow failures indicate that the manual pages are not up-to-date with ROxygen comments, and corrective actions are provided in the workflow log.

pkgdown.yml

Documentation

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 deployed to the gh-pages branch.

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

r-cmd-check.yml

R CMD Check

This workflow performs R CMD check for the package. Failed workflows are typically indicative of problems encountered during the check, and therefore an indication that the package does not meet quality standards.

r-pkg-validation.yml

R Package Validation report

When a new release of the package is made, this workflow executes to create a validation report via theValidatoR. The PDF report is then attached to the release within GitHub.

readme-render.yml

Render README

If your codebase uses a README.Rmd file (like this repository), then this workflow will automatically render a README.md and commit it to your branch.

spellcheck.yml

Spelling

Spellchecks are performed by this workflow, and the spelling R package is used to detect spelling mistakes. Failed workflows typically indicate misspelled words. In the inst/WORDLIST file, you can add words and or acronyms that you want the spell check to ignore, for example CDISC is not an English word but a common acronym used within Pharma. The workflow will flag this until a user adds it to the inst/WORDLIST.

style.yml

Style

Code style is enforced via the styler R package. Custom style configurations, if any, will be honored by this workflow.

Failed workflows are indicative of unstyled code.

How to use these workflows?

You could add just one file called .github/workflows/common.yml to directly import these workflows while receiving the latest updates and enhancements, given that the workflows defined in this repository are reusable via the workflow_call GitHub Actions event.

The contents of the .github/workflows/common.yml file are available in the common.yml.inactive file in this repository. Feature flags in the form of workflow_call inputs are available for customization purposes. Feature flags are documented in the same file - look for the env: and with: hashes in the file for feature flags.

Alternatively, if you want a high level of customization, you could simply copy the workflows as-is from this repository to your repository and modify them to your liking.