Chapter 2 Example workflow to set up continuous integration for packages
This is an example workflow to create a package and use GitHub actions to apply continuous integration (CI).
CI automatically checks and tests packages upon a git push.
Wrappers to implement some GitHub actions are included in the development version of usethis, which can be installed from GitHub using:
2.1 Set up package
2.1.1 New project, GitHub first
The CI GitHub actions require a package that is set up with Git and GitHub. There are some useful instructions for setting up a new project in the happygitwithr book. After setting up the repo in this way, you’ll need to add the infrastructure to turn the project into a package. You can do so, for example, with the following command:
2.1.2 Existing package with GitHub
Make sure that you have GitHub set up with your package. Refer to https://happygitwithr.com/ for setting up with an existing project.
2.1.3 Add GitHub links to DESCRIPTION
You’ll need to point your package to where your GitHub instance is located. The following function populates the URL and BugReports fields of a GitHub-using R package DESCRIPTION file with links to GitHub. If your project is hosted by an enterprise GitHub server, this is where you can specify that in the input arguments.
If a new GitHub Personal Access Token (PAT) needs to be generated, usethis will print some instructions to the console for you to follow.
2.2 Actions for continuous integration checks
Both of the following functions create a yaml file in .github/workflows/ that will trigger a CI check using GitHub actions.
They also print the code to copy into your readme to add a badge for CI.
2.2.1 CI release check
This option is the more simplified check. It only specifies checking on Mac-OSX and on the most recent version of R. If you are happy with these settings, no alterations to the automatically generated yaml are needed.
2.2.2 CI full check
This option sets up a more comprehensive CI check. It tests the package on Linux, Windows, as well as Mac-OSX operating systems. It also queries dependencies, caches previous installations of them, and evaluates test coverage using codecov. To make the file work as is, a token for codecov must be added to your secrets page. We explain how to do this below! If you are not interested in syncing your package to codecov, this part is not necessary.
2.3 Triggering actions
Now git add, commit the changes and push them to your repo and the action will run!
On your repository you can see the what actions are running under the “Actions” tab.
2.4 Did it succeed?
You can get information about the status of your GitHub action by looking under the actions tab, and once completed, there will be either a green tick or red cross next to the action. By clicking on the action itself while it’s running or after it’s finished you can view the run logs, which can be useful to understand if your action failed.
Further information can be found by clicking on a particular action, and there is the option to make this information displayed as a badge on your README by using the create badge button and copying the markdown code into your README.md file.
2.5 What next?
Read on to Chapter 4 to get an introduction to the contents of the yaml files.