Publishing from VS Code or Positron

Both Visual Studio Code and Positron use the same extension to publish content to Posit Connect - Posit Publisher.

Installing Posit Publisher

Install Posit Publisher using the Extensions sidebar in VS Code or Positron: search for posit.publisher and click Install.

Alternatively, find it directly in the Visual Studio Code Marketplace or the Open VSX Registry.

Adding a deployment

To get started, open the extension by clicking the Posit Publisher icon in the sidebar.

Create a new deployment by clicking the Add Deployment button.

This opens a Create a New Deployment dialog with a series of steps:

  1. Select entrypoint file

    The first step in creating a deployment is selecting an entrypoint file. The entrypoint is the primary file for your content (app.R for a Shiny App, or main.py for a FastAPI project, for example).

    Select an open file listed in the dropdown, or click Open… to select any file in your workspace.

  2. Enter a title

    Next, you are prompted to enter a title for the deployment. This will be the name of the content when published to Posit Connect.

  3. Create a Credential

    The last few steps create a credential to authenticate to your Posit Connect server.

    Credentials are remembered by Posit Publisher. The next deployment you create, even within a different project, can re-use the credential(s) you have already created.

    1. Enter the Posit Connect server’s URL

      This is the URL of the Posit Connect server you are deploying to.

    2. Enter your API Key

      To authenticate, Posit Publisher uses an API key. To create one, see the Posit Connect documentation on creating and deleting API keys.

    3. Enter a nickname

      The last step for creating a credential is to provide a nickname for the server. This is a convenient name used throughout Posit Publisher.

When a deployment is created two things happen:

  • The deployment is selected in the Posit Publisher sidebar.
  • A configuration file, generated by Posit Publisher, opens in the editor.

Configuring your deployment

The configuration file contains fields that describe how the deployment will be deployed to Posit Connect.

The generated configuration is initialized based on the entrypoint file selected and your system. For example, if you selected a Python file as an entrypoint, Posit Publisher fills the Python version currently being used and sets the version field in the python section of the configuration file:

...

[python]
version = '3.12.4'
package_file = 'requirements.txt'
package_manager = 'pip'

It is recommended to review the generated configuration before deploying to ensure:

  • the existing settings in the configuration are correct
  • the files field includes all files needed for the content
  • any additional settings that are needed are added to the configuration

The settings and options supported in configuration files can be found in the Configuration File Reference documentation.

Configuring files

The files field of the configuration sets which files will be included in the deployment. You can edit the field manually or use the Project Files section in the sidebar to add or remove files from the configuration.

For more details see the Project Files documentation for Posit Publisher.

Deploy your project

Once your configuration is ready, deploy by clicking the Deploy Your Project button.

Posit Publisher's Home View with a deployment in progress.

Log

The Posit Publisher log can be found in the Posit Publisher Log panel in the bottom of the IDE.

Click View Log to show the log if it is not already visible.

The log is grouped into logical steps and shows the progress of the deployment.

Updating content

Once you have deployed your content to Posit Connect, clicking Deploy Your Project updates it.

Any changes to the configuration file or the included files are reflected in the content or its settings after updating.

Updating already deployed content

Posit Publisher can update existing content on Posit Connect even if you do not have a deployment and configuration file setup.

First, create a new deployment using the same entrypoint file.

After creating the deployment, press the update that previous deployment link in the Posit Publisher sidebar.

In the dialog that opens, enter the URL of the existing content that you want to update and press Enter.

Your deployment is now pointing at the existing content. The Deploy Your Project button now updates the content you specified using the provided URL.

Note

No confirmation is required to update a deployment. If you do so accidentally, use the Source Versions dialog in the Connect dashboard to activate the previous version and remove the erroneous one.

Tips

Opening the configuration file

To view or edit a configuration, click the Edit Configuration button to open the currently selected deployment’s configuration file.

Configurations are stored in the .posit/publish directory in your project next to your entrypoint.

Using the Posit Publisher button

If an entrypoint file is open clicking the Deploy with Posit Publisher button will either:

  • Start creating a deployment for that entrypoint
  • Select the deployment in the sidebar if a deployment using that entrypoint already exists

The button uses the Posit Publisher icon and is located in the editor window when the file is detected as a valid entrypoint.