Git-Backed Content
Content may be deployed to Posit Connect directly from a remote Git repository. Content will automatically fetch from the associated remote Git repository and re-deploy. This allows for integration with Git-centric workflows and continuous deployment automation.
Support for Git-backed content is dependent on an acceptable version of Git being present in the Posit Connect deployment environment, as described in the Admin Guide.
Git-backed content may be distinguished from other content by the presence of the text “from Git” in the content description as well as a Git metadata section in the content Settings -> Info panel.
Publishing for the First Time
In order to deploy Git-backed content to Posit Connect you’ll follow a two step process:
- Create and commit a manifest file
- Link Posit Connect to the Git repository
The first step is completed in the development environment, and the second step is accomplished from within Posit Connect.
Creating a Manifest File From R
The first step is to create a manifest.json
file associated with the content you want Posit Connect to track and deploy. The manifest file tells Posit Connect how to deploy and host your content. This manifest includes information like the content’s environment dependencies. The manifest can be created by calling the R function rsconnect::writeManifest()
from within your project directory.
Please use rsconnect version 0.8.15 or higher when generating a manifest file.
For example, if your project has a single app.R
file, the sequence would look like:
# In a directory with app.R
list.files()
# [1] "app.R"
# Create the manifest
::writeManifest()
rsconnect
# Confirm manifest.json output
list.files()
# [1] "app.R" "manifest.json"
Calling rsconnect::writeManifest
repeatedly will update the manifest.json
file.
If your Git repository includes multiple directories, call the function from within the directory containing the content you wish to deploy. For example, if the project looks like:
Project Git Repository :
- README.md
- analysis (directory)
- prep.R
- experiments.Rmd
- results (directory)
- app.R - supporting (directory)
If you want to deploy the Shiny app in the results
directory, first make the results
directory your working directory and then call writeManifest
.
Project Git Repository:
- README.md
- analysis (directory)
- prep.R
- experiments.Rmd
- results (directory)
- app.R
- manifest.json - supporting (directory)
In this case, do not call writeManifest
from the project’s root directory. Posit Connect will include everything in the results
directory and supporting
directory in the deployment.
The writeManifest
function does its best to infer the correct information about your content. In some cases you may wish to be more explicit and can include the following arguments:
appPrimaryDoc
: The primary file in cases where there are more then onecontentCategory
: The type of content in cases where it is unclearimage
: The image you want to target when building or running content with off-host execution enabled in a Kubernetes environment
Below are some examples to show when you would need to use these explicit options:
A directory containing multiple R Markdown documents
Your project directory may contain multiple R Markdown documents:
report.Rmd email.Rmd
Use
appPrimaryDoc
to specify which R Markdown is the entry point for Posit Connect:::writeManifest(appPrimaryDoc = "report.Rmd") rsconnect
A directory containing HTML
Use
contentCategory
to distinguish between a website and a plot. For instance, if the directory contains multiple HTML files for a website, use:::writeManifest( rsconnectappPrimaryDoc = "index.html", contentCategory = "site" )
An R Markdown site (e.g. Bookdown)
R Markdown sites (including Bookdown) must use the “site” content category.
::writeManifest(contentCategory = "site") rsconnect
Target a specific image for off-host execution in Kubernetes
Use
image
to specify an image rather than having Posit Connect automatically select one (this image must be pre-configured by your Connect administrator):::writeManifest(..., rsconnectimage = "ghcr.io/rstudio/content-base:r4.0.5-py3.8.8-jammy")
Additional information can be found in the Publishing section.
Creating the Manifest File From Python
Support for creating manifests for Python content is provided by the rsconnect-python and rsconnect-jupyter packages.
Using the Python CLI
Install the latest version of the rsconnect-python
package from pip:
pip install rsconnect-python
Use the rsconnect write-manifest
command to create a manifest for your specific Python content type. Your current environment will also be frozen to a file that can be used to reproduce your package set on the Posit Connect server. For example:
rsconnect write-manifest notebook MyJupyterNotebook.ipynb
# Checking arguments... [OK]
# Inspecting python environment... [OK]
# Creating manifest.json... [OK]
# Creating requirements.txt... [OK]
Note that the tool will look for a requirements.txt
file in the source directory. Providing one will make deployments faster by installing only the packages you specify and allowing environments to be reused across deployments that have the same requirements.
If a requirements.txt
file is not found, rsconnect-python will inspect the current Python environment and create the file for you. Be sure to activate your virtual environment before deploying so the correct packages will be listed.
Use the --image
option with rsconnect write-manifest
to specify a target image for building or running content with off-host execution enabled in a Kubernetes environment.
Using the Jupyter Plugin
Install and activate the Jupyter plugin per the installation instructions in the Jupyter plugin documentation. When you open the notebook you wish to publish to Posit Connect, the plugin icon will appear in the toolbar. Select the plugin icon, then Create Manifest for git Publishing
. A dialog will open explaining what will be done and asking you to confirm. Once you confirm, a manifest.json
will be created and your current environment will be frozen to a file that will be used to restore the environment on the Posit Connect server.
Tracking the Manifest File
After the manifest.json
is generated, add and commit it to your local Git working copy, and be sure to push to the remote Git repository so that Connect can see the manifest.json
after fetching. This is roughly the equivalent done in a terminal:
git add manifest.json
git commit -m 'Adding manifest.json for Posit Connect deployment'
git push
Linking Git to Posit Connect
Connect users must have at least the publisher
role in order to create new content from a Git repository.
On the “Content” page, there is a button near the top labeled “Publish”. Clicking on this button will expand a menu which contains an item called “Import from Git”, which may be clicked to launch a new content wizard.
The new content wizard will first prompt for a Git repo URL, which may use https://
(recommended) or http://
remotes.
Repository URLs must not contain authorization. Private repository access requires configuration of GitCredential.Host
, GitCredential.Username
, and GitCredential.Password
, as described in the Admin Guide.
Once the repository URL has been entered, the next step requires specifying a branch name. A selection of candidate branch names collected from the remote repository will be listed.
Once the branch name has been entered, the next step will require specifying a target directory. The directory names listed will have been determined by searching for directories containing a manifest.json
file.
Once the target directory has been entered, an initial deployment is triggered.
Updating Content
To update Git-backed content, make any necessary code changes and then call rsconnect::writeManifest()
. Commit both the updated code and the updated manifest.json
file. Once the commit is made, you can either wait for Posit Connect to automatically deploy the changes or, from within the Posit Connect dashboard, manually tell Connect to “Update Now”.
Option 1: Connect Automatic Update
Connect will periodically check all Git-backed content for updates. By default this check occurs every 15 minutes, but administrators can configure a different interval. If the updated repository is found to contain changes to the relevant branch and path specified, a new deployment will automatically be triggered. Such an update may be from new commit(s) pushed to the remote Git repository, or from another branch being merged into the target branch such as when merging a pull request.
Automatic updates may be disabled or enabled in the Git metadata section in the Settings -> Info panel.
Option 2: Connect Manual Update
Git-backed content may be immediately checked for updates and potentially redeployed by clicking the “Update Now” button in the content Settings -> Info panel.
Limitations
Git-backed content cannot be re-deployed or updated via other means, such as by publishing from the RStudio IDE or
rsconnect::deployApp()
.Currently, Posit Connect Git-backed publishing does not support Git Large File Storage (LFS).
Posit Connect supports one set of credentials per host. Configuring multiple hosts with different sets of credentials is supported. Credentials must be configured on the Connect server. See the Admin guide for details.