How To Build A Workshop Package

In other words, how do I use what’s here

Sean Davis¹

First, this package doesn’t do much except add a template Github Action to build all the pieces necessary for a workshop.

Quickstart

• Create a repo from this template and rename it (do not fork the repository).
  • Ensure that “Read and Write Permissions” is checked under General > Workflow permissions.
• Edit DESCRIPTION file
  • Change package name
  • Change title and description
  • Change authors
  • Check dependencies
  • Change DockerImage tag
• Edit ’_pkgdown.yml’ (and .github/workflows yaml file as needed)
• Write a normal R package that can be installed
• Include one or more vignettes that will constitute the workshop materials
• After the first CI push: make your GHCR Docker image public (it is private by default!)

Details

To accomplish this follow each of the 7 steps below. Once your edit the yaml files, Github actions will run each time you commit to github and will create for you:

• the pkgdown website
• the docker image

1. Clone this repo

Clone this repo, fork and rename it,

OR

(PREFERRED) create a repo from this template

2. Edit DESCRIPTION file

• Change the package name to something identifiable and descriptive, ideally something that will be somewhat unique.
• Edit the title and description as per any normal R package.
• Update authors (unless you want me to get credit for your work).
• Workshop packages are normal R packages, so dependencies work as usual. Append libraries to the Depends/Suggests/Imports in this package DESCRIPTION File, which includes;

Depends: Biobase Suggests: knitr, rmarkdown, pkgdown If your packages depend on a github R repos, be sure to specify the correct repo username/reponame. Installation will deal with this.

• Edit the last 3 lines of the DESCRIPTION FILE, URL, BugReports and DockerImage (described in more detail below)

3. Set up a website (Github Pages)

In your repository, click on settings or url https://github.com/*GITHUB_USERNAME*/*REPO_NAME*/settings. Midway down the page, in the GitHub Pages section, select source ‘gh-pages branch’. If only ‘master branch’ is visible, select master for now, but once Github actions runs, ‘gh-pages branch’ will be available and is required to render the website.

In the DESCRIPTION file, update the URL: to the website url eg https://seandavi.github.io/BuildABiocWorkshop/ (but substitute your own repo, etc.)

4. Edit _pkgdown.yml

Edit the file _pkgdown.yml, updating the url:, title and href: which should be your website url, title of your workshop and github repos url respectively. You do not need to edit this file further. You do not need to add menus or links to vignettes. GitHub Actions and pkgdown will do this when it builds the website

5. Edit .github/workflows yaml as needed (likely no need)

You do not need to create a docker image manually. Github actions will read Dockerfile located in this template, and using the yaml files will create, build and push to the Github Container Registry an image with the name (default) ghcr.io/yourgithubuser/yourgithubreponame, all lowercase.

In the DESCRIPTION file, the DockerImage: should match your the docker image name (should be lowercase).

⚠️ CRITICAL: Make Your Docker Image Public After the First Push

Your Docker image will be PRIVATE by default on GHCR — and that will break your workshop.

GitHub Container Registry automatically sets all newly published packages to private visibility. Workshop attendees, organizers, and automated systems will receive an authentication error when trying to docker pull your image until you manually change the visibility to public. This step is easy to miss and will silently break your workshop for everyone.

This cannot be automated in the CI workflow here because changing package visibility requires owner-level permissions beyond what the GITHUB_TOKEN can do.

After GitHub Actions successfully pushes your image for the first time, do the following:

1. Go to your GitHub profile (or organization) page
2. Click the Packages tab
3. Click on the package with your repository name
4. Click “Package settings” (lower right of the page)
5. Scroll to the “Danger Zone” section
6. Click “Change visibility” → select Public → confirm

You can also navigate directly to the settings URL:

# For user accounts:
https://github.com/users/YOUR_USERNAME/packages/container/YOUR_REPO_NAME/settings

# For organization accounts:
https://github.com/orgs/YOUR_ORG/packages/container/YOUR_REPO_NAME/settings

Why does this matter? Bioconductor workshops must be open and reproducible. Attendees need to docker pull your image without a GitHub account or any credentials. A private image breaks this completely and without an obvious error message. Always verify your image is public before advertising or scheduling your workshop.

Relevant documentation:

• Configuring a package’s access control and visibility
• Working with the Container Registry
• Connecting a repository to a package

6. Edit README.md, add vignettes to vignettes folder

Edit the README.md. and add one or more Rmd vignettes that will constitute the workshop materials. It is normal R package that should pass rcmdcheck::rcmdcheck(), and be installed using regular R package install commands.

---

1. seandavi@gmail.com↩︎