Building Git Packages for R#
R packages can come in multiple formats:
- Source: A collection of directories and files containing source code.
- Bundle: A specially created tar file containing bundled source code. The result of
R CMD build.
- Binary: A binary file specific to an operating system and architecture, containing compiled source code. Not an executable. The result of
R CMD INSTALL.
In some configurations, Package Manager will need to run R in order to transform a package from one state to another.
You can optionally specify the installation of R in the Package Manager configuration file:
/opt/R/4.0.5 with the path to your R installation. Use the path to the R installation directory, not the path to the binary (do not include
/bin/R). While multiple versions of R may be installed on the server, only one version of R may be specified for use by Package Manager.
R must be configured in order for Git builders to work correctly.
RVersion field is included, then it must be valid, and it must only appear once in the configuration file. Check the server log after starting and stopping the Package Manager process for messages relevant to the R configuration.
Posit recommends that in most cases you install R from pre-compiled binaries.
To install from pre-compiled binaries, follow the instructions at Install R.
Alternatively, you can install R from source, to do this follow the instructions at Install R from source.
Package Manager defines a
git-builder as an entity that watches a Git endpoint, whether it be remote (e.g.,
email@example.com:user/example.git) or local (e.g.
file:///path/to/local/git/repo), for changes and builds R package bundles.
An administrator follows these steps:
- Create a git source.
- Create a
git-builderfor the source, specifying whether to watch for commits to a Git branch or tags in a Git repository. The endpoint can be: HTTP, SSH (see below), or a local file path (see below). See the
rspm create git-buildercommand for full details, e.g., how to track a specific branch.
- Based on the selection specified with the
rspm create git-buildercommand, Package Manager clones the Git endpoint and runs an R job to transform the Git clone into a package bundle. The package bundle is made available to any repositories subscribing to the source.
- Package Manager polls the Git endpoint to watch for either new commits or new tags (based on the selection specified with the
rspm create git-buildercommand). If an update is available, Package Manager automatically pulls the new changes and launches an R job. The R job creates a package bundle from the updated Git clone and updates the package available in the git source. Previous versions are archived.
- Users install the package from the repository via
See the Getting Started section for a specific example.
Server log messages related to this component can be shown by enabling the
git region. More information about activating log regions is in the configuration appendix.
Access Restricted Git Endpoints Using Git Credentials#
If Git builders require authentication to read a repository, Package Manager can use SSH keys or HTTPS credentials to authenticate against the endpoint.
Importing an SSH key#
Begin by creating an SSH key and granting the SSH key access to the Git endpoint. Although Package Manager allows the use of SSH keys with no passphrase, it is still recommended to use a strong SSH key with a passphrase. The specific steps for granting access will depend on your Git provider.
Once you have the path to the SSH key, use the
rspm import ssh-key command to name and securely store the SSH key for later use by Package Manager. If desired, you can now remove the SSH key file from your filesystem, as it is loaded into Package Manager's database as encrypted text. Multiple keys can be imported, but they must have unique names to refer to. This is the
--name argument you pass to the
rspm import ssh-key command, not the filename of the key.
Because the use of a password for the key requires writing the password to a file on disk, there is some risk of leaking the password while it is on disk. To mitigate this risk, you can encrypt the password using the
rspm encrypt command prior to writing it in a file. Package Manager will understand passwords in the file as either plaintext or encrypted text, and will decrypt the password as necessary to unlock your SSH key.
To use the newly imported SSH key with a new Git builder, specify the key name with the
--credential flag in the
rspm create git-builder command.
Importing an HTTPS credential#
HTTPS credentials consist of a username and password. In applications where two-factor authentication is used, you will often need a PAT that serves as the password. To import an HTTPS credential, use the
rspm import https-credential command.
Note that using this command requires you to input the password/PAT on the command line, which may be stored in your command history. To avoid this possible credential leak, you may first encrypt your password using the
rspm encrypt command, and pass this encrypted string to the
rspm import https-credential command instead.
To use the newly imported credential with a new Git builder, specify the credential name with the
--credential flag in the
rspm create git-builder command.
Git Credential Security#
Package Manager encrypts and stores imported credentials in the metadata database. Any person (by default, members of the
rstudio-pm unix group) with access to the admin CLI can:
- Associate an imported credential with a Git builder using the
rspm create git-buildercommand
- List the names of available Git credentials using the
rspm list git-credentialscommand
Users cannot access the contents of the credential, nor is the credential available for arbitrary actions. We recommend granting SSH keys and HTTPS credentials imported to Package Manager limited read-only access to only the endpoints you wish to expose as R packages.
Changing credentials for a git-builder#
Credentials may be rotated by either creating a new credential and editing an existing git-builder:
If you would like to change the URL type of a git builder from https to git or vice-versa, ensure that you pass a credential that matches the new URL type.
Package Manager does not change credentials aside from manually specified commands. Therefore, when changing a URL without changing the credential, Package Manager will continue using any prior credential. To remove the association of the credential with the git-builder, use the
rspm edit git-builder --remove-credential command:
Access Git Endpoints on a Local File System#
If a Git repository is available locally, it is possible to point a Git builder to watch this location and update when changes are made on a branch or tag (based on the selection specified with the
rspm create git-builder command).
To do this, the
Git.AllowFileURLs configuration option must first be set to
true. Once the option is set, the following command can be used to create a Git builder pointed to a local Git repository:
Git must be installed on the server if you need support for
Commits vs Tags#
A package based on a Git endpoint can can be configured to watch one of two types of changes: "commits" or "tags". In short, "commits" watches for changes to a specified Git branch, where "tags" watches for new tags in the whole Git repository. In more detail:
Commits - Package Manager will update the package any time new commits are discovered in a branch. In this mode, Package Manager automatically modifies the package's version, assigning a unique version number to each build. The version number is created based on the commit time-stamp and is designed to avoid conflicts with the version scheme used by the package author. For example, if the Description file for a package indicates a version of
1.1-3, the automatic version number would be:
1.1-18.104.22.168.1537204599. If the author updates the package with a new commit, but keeps the version in the Description file the same, the new automatic version number would reflect the new commit time-stamp, e.g.
1.1-22.214.171.124.1537218677. This process ensures that users of the package always get the correct behavior from
install.packages, with newer commits being associated with a semantically higher version number.
The above version behavior for "commits" triggers may be overridden by using the
Git.ForceDescriptionVersionconfiguration option. This will force all packages built by commits in a branch to use the exact version in the DESCRIPTION file.
Tags - Package Manager will update the package any time a new Git tag is discovered. In this mode, Package Manager retains the version specified in the package's Description file. This mode is designed to work when a Git tag is used to indicate a package release. Note: The name of the tag must match the version in the Description file. For example, if your package's Description file has
Version: 5.4.2your tag must be either
v5.4.2. If two tags reference the same version, preference is given to the newer tag. If a newer tag references an older version than a prior tag, the new tag is built as an archived package. If a tag is removed from a Git endpoint, any packages already built for that tag remain.
If you wish to build packages where the Description file version does not match the tag, use the
Git.AllowTagVersionMismatchconfiguration option. When
true, the version from the Description file will be used.
Commit mode is recommended for bleeding edge repositories, whereas tag mode is suitable for exposing stable releases of packages.
A git source can support different packages with different modes. However, a given package can only have one mode in a source. If you would like to surface the same package in both commit and tag mode, you must create two git sources.
If your Git repository includes Git submodules that are required for building the R package, use the
--recurse-submodules=[depth] flag when creating or editing the Git builder. Set the flag value to the required submodule recursion depth. The default recursion depth is
0, which means that no submodules will be included when cloning. If the Git builder includes credentials, the same credentials will be used for checking out the Git submodules.
Git Builder Naming and Multiple Builders for the same Git Repo#
When you create a Git builder without providing a name, the Git builder is named after the R package name. If you need to add multiple Git builders for the same Git repo to the same Git source, use the
--name flag to provide a custom name for each additional Git builder. For example, you could create Git builders to follow two branches:
rspm create source --name=git --type=git rspm create repo --name=git rspm subscribe --repo=git --source=git # Build "main" branch rspm create git-builder --source=git --url https://github.com/rstudio/plumber --branch=main --wait # Build "v044" branch rspm create git-builder --source=git --url https://github.com/rstudio/plumber --branch=v044 --name=plumber-044 --wait
When multiple git-builders are enabled for the same repository using the same source, the latest version will always be marked as "latest", and all others will be considered "archived," regardless of when the git-builder was created or when the build was run.
By default, packages will be built from the git root directory. If the R package exists in a different location, it can be specified using the
--sub-dir flag when adding a git package.
Managing Packages from Git#
git-builder (described above) watches the Git endpoint for changes, automatically handling package updates and archives. There might be cases where you wish to remove packages, or to stop package building altogether.
Packages can be removed at any time using the
rspm remove command.
To stop automatic package building, but keep the existing packages, use the
rspm delete git-builder command. To resume package building, simply create a new
git-builder with the same metadata.
To view information about the current Git endpoints that are being tracked, use:
Git builders have a few fields which may be edited: credentials, URLs, sub directories, and branches (for "commits" triggers). The git-builders cannot be changed from SSH to HTTP URLs or vice versa.
$ rspm edit git-builder --name=[git-builder name] --source=[git source name] --new-url=[HTTP/SSH URL] $ rspm edit git-builder --name=[git-builder name] --source=[git source name] --new-credential=[credential name] $ rspm edit git-builder --name=[git-builder name] --source=[git source name] --new-branch=[branch name] $ rspm edit git-builder --name=[git-builder name] --source=[git source name] --new-sub-dir=[sub directory path] $ rspm edit git-builder --name=[git-builder name] --source=[git source name] --remove-credential $ rspm edit git-builder --name=[git-builder name] --source=[git source name] --remove-sub-dir
Combining Packages from Git with Other Package Sources#
Local packages cannot be added manually to a git source, but a repository can surface packages from a git source alongside local packages and CRAN packages by subscribing to multiple sources. Take care when managing a repository's subscriptions as order is important, see the Multiple Sources section.
You can control how frequently Package Manager checks for updates using the
Git.PollInterval configuration field. If multiple commits occur between checks, Package Manager will create a single version representing all of the changes. If multiple tags are created or removed between checks, Package Manager will build each tag individually, automatically archiving tags representing older versions of the package.
Repository Versioning is identical in all source types, including git sources.
Tracking Changes and Errors#
If a repository subscribes to a git source, you can view the git source's history in the Activity Log. The Activity Log will identify each change to a package including the new version, and a message will indicate the associated Git tag or commit as appropriate. If an error is encountered attempting to clone, poll, or bundle a package, the Activity Log will record the attempt and include a message with the CLI command to be run to view a full error log.
You can also use the following Package Manager CLI commands to quickly check your active Git builders and view the logs:
$ rspm list git-builds --source=[source name] --name=[git package name] << Git Builds: << - [git package name] << Transaction ID: [transaction ID] << SHA: [SHA] << Tag: [tag] << Status: [job status] << Time: [time of run] << Only showing latest build, for more builds use the --count and --page flags << For more information run: rspm logs --transaction-id=[transaction ID]
Package Manager automatically tries to build updates from a Git source three times. If the build fails more than three times, the update causing the failure is ignored. New updates are still discovered and built.
To retry a failed update, or to force a Git builder to rebuild the latest package version, use the
rspm rerun command:
You can also rerun commit-based Git builders to rebuild the package based on a specific Git SHA:
To aid in debugging, it can help to view output from the git commands that are run as well as output from the SSH connection when applicable. To enable debugging, refer to the
Debug.Log configuration property in the configuration appendix. To enable the debug log temporarily without restarting the server use the
rspm config command:
See Process Management for information on how Package Manager securely runs R processes when building R packages for git sources.