ghqc Installation

The ghqc ecosystem is composed of 3 components:

ghqc - A lightweight R package to launch the Shiny apps
ghqc.app - A high dependency R package containing the Shiny apps
Configuration - A configuration directory/repository used to configure the behavior of the ecosystem

On this page, we will walk through the basics of how to install the ghqc ecosystem.

Installation Steps

Installation steps will be provided for both base R and rv, A2-Ai’s package manager.

1. Install `ghqc`

Add a repository containing ghqc and ghqc.app to the repos option

options("repos" = c(
    "ghqc-eco" = "https://prism.dev.a2-ai.cloud/rpkgs/ghqc-eco/v3",
    getOption("repos")
))

Install the package

We recommend installing all of the dependencies to install pak and gert, but it is not required.
- Suggested Dependencies
- No Suggested Dependencies
install.packages("ghqc", dependencies = TRUE)
install.packages("ghqc")

Add a repository containing ghqc and ghqc.app to the start of the repositories field in the rproject.toml

[project]
name = "ghqc example"
r_version = "4.5"
repositories = [
    { alias = "ghqc-eco", url = "https://prism.dev.a2-ai.cloud/rpkgs/ghqc-eco/v3" },
    { alias = "PRISM", url = "https://prism.a2-ai.cloud/rpkgs/nimbus/2025.09" },
]

Add ghqc to the dependencies field in the rproject.toml and sync.
- Suggested Dependencies
- No Suggested Dependencies
a. Add { name = "ghqc", install_suggestions = true } to the rproject.toml
rproject.toml
... repositories = [ { alias = "ghqc-eco", url = "https://prism.dev.a2-ai.cloud/rpkgs/ghqc-eco/v3" }, { alias = "PRISM", url = "https://prism.a2-ai.cloud/rpkgs/nimbus/2025.09" }, ] dependencies = [ { name = "ghqc", install_suggestions = true }, ]
b. Sync the dependencies
Terminal window
rv sync
If you wish to not install the suggested dependencies, simply run:
Terminal window
rv add ghqc

After installing ghqc, users should restart their R session to have the changes propagate into their R session.

2. Start Ecosystem Set-up

ghqc provides helper functions to help users finish the set-up. The following will help you interactively set-up the ecosystem.

library(ghqc)
ghqc_setup()

3. Configuration Repository Set-up

Set the GHQC_CONFIG_REPO environment variable
Terminal window
```
--- GHQC RENVIRON SETUP -----------------------------------------------------

GHQC_CONFIG_REPO is not set in your ~/.Renviron
Provide URL to custom configuration repository:
https://github.com/A2-ai/ghqc.example_config_repo
```
https://github.com/a2-ai/ghqc.example_config_repo is an example repository that can be used during exploration, but should be replaced by your organization’s custom configuration repository URL.
Set the clone destination directory
- Suggested Dependencies
- No Suggested Dependencies
Caution
gert is required to clone down the custom configuration repository. If you chose to not install the suggested dependencies you will be prompted with the following:
Terminal window
! Package `gert` is not found in your project package library The custom configuration repository cannot be downloaded unless this package is present Would you like to install `gert` to continue? (y/N) y
By default, ghqc will clone the configuration repository to $XDG_DATA_HOME/<repo name>. It is highly recommended to input y to clone to the default location.
Terminal window
```
--- CUSTOM CONFIGURATION REPOSITORY --------------------------------------

Download custom configuration repository to path:
~/.local/share/ghqc/ghqc.example_config_repo (y/N) y
```

Clone the Configuration Repository

Next, a prompt will appear to confirm you’d like to clone the Configuration Repository to the destination. Input y to download.

x Custom configuration repository ghqc.example_config_repo is not found locally
Would you like to download the repository (y/N)? y

After a successful download, the repository is verified for its structure and compatibility with the ghqc ecosystem

✔ logo.png successfully found

✔ options.yaml successfully found
    ✔ prepended_checklist_note:

    “Note: Please modify checklist items to insert relevant QC context.”
    — 

✔ Checklist directory successfully found
    ✔ advanced_checklist.yaml
    ✔ simple_checklist.yaml

4. `ghqc.app` Installation

ghqc.app has over 100 dependencies, with restrictive dependency constraints. To ensure the ghqc.app dependencies do not interfere with project work, ghqc.app and its dependencies are installed in an isolated directory outside the QCed project.

To get started with installation, the user will be prompted with the following:

--- GHQC.APP DEPENDENCY INSTALLATION ----------------------------------------
Would you like to INSTALL new packages form Posit Package Manager or LINK to a
previously installed package library?
1. INSTALL
2. LINK
3. Neither
Input:

Suggested Dependencies
No Suggested Dependencies

pak is highly recommended to improve package installation performance. While not required, it has no dependencies and should not influence project work. If you chose not to install the suggested dependencies you will be prompted with the following:

Package `pak` is not found in your project package library.
To improve performance, would you like to install pak? (y/N) y

By inputting 1, users choose to install ghqc.app and its dependencies into the isolated dependency directory.

Set the installation destination directory

By default, ghqc will install the dependencies to $XDG_DATA_HOME/ghqc/rpkgs/<OS>/<R VERSION>/<ARCH>. It is highly recommended to input y to install to the default location.
Terminal window
```
Install ghqc.app dependencies to path:
~/.local/share/ghqc/rpkgs/linux-ubuntu-jammy/R-4.4/x86_64-pc-linux-gnu (y/N) y
```
Install the packages

Users will be prompted with the following:
Terminal window
```
x No packages found in ~/.local/share/ghqc/rpkgs
Would you like to install the ghqc.app dependencies (y/N)? y
```
Input y to install ghqc.app and its dependencies.

ghqc does not install the dependencies of ghqc.app from the repositories set in the repos option, but rather from https://packagemanager.posit.co/cran/2025-03-01. This is the dependency version set the Shiny apps were developed against, therefore for best consistency is set by default.

On the other hand, ghqc.app IS installed from a repository in the repos option to allow for organizations to choose the source and version of the package. It can be manually installed via:

utils::install.packages("ghqc.app", lib = ghqc::ghqc_libpath(), repos = <REPO_URL>)

By inputting 2, users choose to symlink the dependencies of ghqc.app to the isolated dependency directory. This is the most efficient method, but should only be used if there exists a package library previously installed which contains all of the package versions required.

Provide the directory where the packages should be symlinked from:
Terminal window
```
Path to previously installed package library from which to link:
```
Set the dependency destination directory

By default, ghqc will install the dependencies to $XDG_DATA_HOME/ghqc/rpkgs/<OS>/<R VERSION>/<ARCH>. It is highly recommended to input y to install to the default location.
Terminal window
```
Path to link the ghqc.app dependencies:
~/.local/share/ghqc/rpkgs/linux-ubuntu-jammy/R-4.4/x86_64-pc-linux-gnu (y/N) y
```
In order to prevent errors, the current content in the destination is deleted and then the symlink occurs.

Install ghqc.app

After ghqc.app dependency linkage, ghqc.app will not be present and the user will see the following:

! NOTE: ghqc.app is not installed in ~/.local/share/ghqc/rpkgs/linux-ubuntu-jammy/R-4.4/x86_64-pc-linux-gnu.
Please install before running any ghqc apps

To install ghqc.app from the repository added in 1.1, run the following command:

utils::install.packages("ghqc.app", lib = ghqc::ghqc_libpath())

By inputting 3, users choose to not install ghqc.app or any of its dependencies.

A helper function ghqc_libpath() exists to create and output the string to the default dependency directory.