Migrating to a New Workflow Version

RStudio Connect is a platform used to deploy and host Shiny Applications, R Markdown Documents, and other such projects. In order for RStudio Connect to support these R projects, RStudio Connect must have access to valid installations of all R packages that these projects require. These packages are usually installed to an RSConnect-specific location at the time of package deployment. In the context of Metworx, these packages are stored on the disk used when creating the workflow.

If you choose to “upgrade” a workflow--that is, if you choose to turn off your current workflow and attach its disk to another workflow with a newer version--then you may need to reinstall RSConnect’s packages to be compatible with backend changes of the newer workflow.

For example, if you started a project on a 20.12.2 workflow, but now wish to continue that project on a 21.08 workflow, you will need to reinstall your RSConnect packages after attaching the older disk to the 21.08 workflow.

Here’s how to do that:

Option 1: Let RSConnect handle it for you

Note: If you plan to use this process, it is best to have a workflow with many (8+) available cores on its head node.

This option can only be used if the “patch” version of R has changed on the new workflow (e.g. R4.0.2 on 20.12 to R4.0.5 on 21.08). In this case, when you try to access your applications, RSConnect will automatically detect package issues and attempt to update your packages for you.

First, load the RSConnect Content page: rsc_migrate_content_page.png

Select the project you wish to load. You will see a message saying your packages are being updated: rsc_migrate_pkgs_updating.png

Be patient, as this can take anywhere from a few minutes to several hours, depending on how many cores your workflow has and how many packages need to be updated.

You will know this has worked when your app loads:


You will only have to do this once for each app. Additionally, RSConnect shares package installations between applications. Once this process has completed for an app, other applications that use the same packages (and the same versions of those packages) should be able to update faster.

Option 2: Force RSConnect to update its entire package library


  • If you plan to use this process, it is best to have a workflow with many (8+) available cores on its head node.


  • You must have sudo access on your Workflow to do this.

This option will force all packages RSConnect is aware of to reinstall, which will ensure compatibility on your current workflow.

  1. Open a terminal on your workflow. The easiest way to do this is to load RStudio, create a new R Session, then navigate to the “Terminal” tab. If you do not already have a terminal window open you can open one through Tools → Terminal → New Terminal.


  1. Run the following commands:

sudo /opt/rstudio-connect/bin/migrate rebuild-packrat -force

  1. Wait until the command finishes (again, this could take anywhere from five minutes to several hours, depending on how many packages need to be updated) rsc_migrate_migrate_script_output.png

For in-depth details about what we’re doing here, check out [this documentation from RStudio](https://docs.rstudio.com/connect/admin/appendix/cli/#commands_2

Option 3: Start from scratch

If neither of the two options above are available to you, then the next easiest way to upgrade your workflow is to simply start the workflow with a blank disk, redownload your projects, and redeploy to RSConnect.