13  Troubleshoot package builds

13.1 How often is data updated?

  • The system checks package Git repositories and the registry for changes every hour.
  • If changes are detected:
    • The workflow starts building the affected packages.
    • Upon completion, the packages are uploaded to R-universe.

13.2 Can the package build process be customized with custom options/tools/variables?

No, customization is overall not possible, except for addressing third-party system requirements (covered in the next two sections).
Think of R-universe as your own mini-CRAN. The build environment is very similar to CRAN’s, so if a package builds successfully on CRAN, it is likely to work on R-universe.

This restriction ensures that packages deployed on R-universe are reproducible, work seamlessly on user machines, and do not rely on custom settings or tools.

13.3 Configure some options with config.json

You can create a config.json file alongside your packages.json file to set some global options.

Currently the only option is cran_version which has to be a yyyy-mm-dd string and will use dependencies from a certain p3m snapshot date.

{
  "cran_version": "2025-01-15"
}

This will set options(repos = c(CRAN = "https://p3m.dev/cran/2025-01-15"))

13.4 What if the Git repository is not a ready-to-build source package?

For repositories requiring additional preparation before building, you can add a script at the root of the package:

  • An R script named bootstrap.R, or
  • A shell script named .prepare.

These scripts will be executed before R CMD build.

Examples of actions performed by the script:

  • Initializing a Git submodule.
  • Running roxygen2 (if .Rd files are not committed to Git).
  • Performing other necessary preparations.

13.5 How to request additional third-party system requirements?

If packages need a Linux library that is not available on the server:

  1. Send a pull request (PR) to the base image for reasonably small or common dependencies.
  2. Alternatively, send a PR to rstudio/r-system-requirements to resolve the library based on the SystemRequirements field in the package DESCRIPTION file.

13.6 How to publish vignettes/articles requiring custom software/tokens to render?

Precompute these vignettes locally before publishing.
Follow the guide: How to precompute package vignettes or pkgdown articles.

13.7 Are packages on R-universe required to pass CMD check or meet other criteria?

No, R-universe is an open publishing system. It builds and deploys R packages from Git into personal CRAN-like repositories.

The universe owner is responsible for setting policies and ensuring quality control.

13.8 How to use a universe on regular continuous integration?

If you want to test a package against versions of other packages that are in a universe, on GitHub Actions you can use the extra-repositories field of the r-lib/actions setup-r action.

13.9 How to test the R-universe build workflow from your own GitHub repository

To troubleshoot why your package cannot be built by R-universe, you can use the same GitHub Actions workflow. This is only possible on GitHub.

The instructions on r-universe-org/workflows explain how it works. You need to get a file /.github/workflows/r-universe-test.yml in your R package Git repository with the following config:

name: Test R-universe

on:
  push:
  pull_request:

jobs:
  build:
    name: R-universe testing
    uses: r-universe-org/workflows/.github/workflows/build.yml@v3
    with:
      universe: ${{ github.repository_owner }}

You can either create the file manually or by calling the universe::use_universe_action() function in the universe R package.

The workflow will use the fully automated R-universe setup to build and check the package on a range of R versions on Linux, Windows, and MacOS configurations very similar to CRAN.

It is possible to use this workflow in your R package for pushes and/or pull requests alongside those from r-lib/actions. Both will check your R package, but note that the purpose is very different: workflows from r-lib/actions are highly configurable and can test R packages using countless options and environments. The R-universe workflow on the other hand is, just like CRAN, not customizable at all: it uses the exact setup and process as it happens on R-universe, nothing else.

13.10 How to know whether tests are run on R-universe?

During the build, the MY_UNIVERSE environment variable is set to the URL of the universe.

13.11 How to handle the transfer of a repository to another GitHub owner?

If a package is on GitHub and possibly CRAN, and on R-Universe through an organization with a packages.json, here is how to best move the package to another GitHub organization:

  1. Move the GitHub repository to another organization on GitHub. This will create redirects from the old URL to the new.
  2. Remove the package from the original organization’s packages.json. This will remove it from the original organization’s universe.
  3. Change the URL in the package DESCRIPTION to the new GitHub organization.
  4. If the package is on CRAN, update the package on CRAN with the new URL in DESCRIPTION

Updating the package on CRAN will speed up the process of having R-universe point to the right repository from the CRAN universe. Otherwise it could take up to a month for the cran.r-universe.dev/ to get rebuilt and detect the redirected git origin.