A CLI tool and GitHub Action for running Posit Connect in Docker and executing commands against it.

Installation

Install as a tool using uv (recommended):

uv tool install git+https://github.com/posit-dev/with-connect.git

Or install from a local clone for development:

git clone https://github.com/posit-dev/with-connect.git
cd with-connect
uv tool install -e .

Requirements

Python 3.13+, or uv
Docker
A valid Posit Connect license file

Usage

Basic Usage

Run Posit Connect with default settings:

with-connect

This will:

Pull the specified Posit Connect Docker image
Start a container with your license file mounted
Wait for Connect to start
Bootstrap and retrieve an API key
Stop the container

Running Commands

Execute a command against the running Connect instance:

with-connect -- rsconnect deploy manifest .

Commands after -- are executed with CONNECT_API_KEY and CONNECT_SERVER environment variables set.

Important: When using the CLI, if you need to run multiple commands or reference the CONNECT_API_KEY and CONNECT_SERVER environment variables, you must wrap your command in bash -c with single quotes:

with-connect -- bash -c 'curl -f -H "Authorization: Key $CONNECT_API_KEY" $CONNECT_SERVER/__api__/v1/content'

Without bash -c, the environment variables would be evaluated before with-connect defines them.

Options

Option	Default	Description
`--version`	`release`	Posit Connect version. Use "latest" or "release" for the most recent version, or specify a version like "2024.08.0".
`--license`	`./rstudio-connect.lic`	Path to license file. This file must exist and be a valid Connect license.
`--image`		Container image to use, including tag (e.g., `posit/connect:2025.12.0`). Overrides `--version`.
`--config`		Path to optional rstudio-connect.gcfg configuration file
`--port`	`3939`	Port to map the Connect container to. Allows running multiple Connect instances simultaneously.
`-e`, `--env`		Environment variables to pass to the Docker container (format: KEY=VALUE). Can be specified multiple times.
`--stop`		Stop a running Connect container by ID, or use `CONTAINER_ID` env var if not specified.

Example:

with-connect --version 2024.08.0 --license /path/to/license.lic -- rsconnect deploy manifest .

Passing environment variables to the Docker container:

with-connect -e MY_VAR=value -e ANOTHER_VAR=123 -- rsconnect deploy manifest .

You can use this to override Connect server configuration by passing in CONNECT_ prefixed variables, following https://docs.posit.co/connect/admin/appendix/configuration/#environment-variables.

If you need env vars that are useful for the command running after --, just set them in the environment from which you call with-connect: the command will inherit that environment.

Start-Only Mode

If you omit the command after --, Connect will start and remain running. The tool outputs shell variables you can use to interact with Connect:

with-connect --license ./rstudio-connect.lic
# Outputs:
# CONNECT_API_KEY=...
# CONNECT_SERVER=http://localhost:3939
# CONTAINER_ID=...

You can eval the output to set the variables in your shell:

eval $(with-connect --license ./rstudio-connect.lic)
curl -H "Authorization: Key $CONNECT_API_KEY" $CONNECT_SERVER/__api__/v1/content
# Stop Connect when done (--stop without argument uses $CONTAINER_ID)
with-connect --stop

This is useful when you need to run multiple commands or use other tools against the running Connect instance.

GitHub Actions

This project contains a GitHub Action for use in CI/CD workflows. Use the @main tag to reference the action.

You will need to store your Posit Connect license file as a GitHub secret (e.g., CONNECT_LICENSE_FILE).

GitHub Action Inputs

The GitHub Action supports the following inputs:

Input	Required	Default	Description
`license`	Yes		Posit Connect license file contents (store as a GitHub secret)
`version`	No	`release`	Posit Connect version
`image`	No		Container image to use, including tag (e.g., `posit/connect:2025.12.0`). Overrides `version`.
`config-file`	No		Path to rstudio-connect.gcfg configuration file
`port`	No	`3939`	Port to map the Connect container to
`quiet`	No	`false`	Suppress progress indicators during image pull
`env`	No		Environment variables to pass to Docker container (one per line, format: KEY=VALUE)
`command`	No		Command to run against Connect (omit for start-only mode)
`stop`	No		Container ID to stop (use instead of starting a new container)

GitHub Action Outputs

When no command is provided (start-only mode), the action sets these outputs:

Output	Description
`CONNECT_API_KEY`	Connect API key for authentication
`CONNECT_SERVER`	Connect server URL (e.g., `http://localhost:3939`)
`CONTAINER_ID`	Docker container ID (use with `stop` input to stop the container)

Deploy a Connect Manifest

name: Integration tests with Connect
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - name: Test deployment
        uses: posit-dev/with-connect@main
        with:
          version: 2025.09.0
          license: ${{ secrets.CONNECT_LICENSE_FILE }}
          command: rsconnect deploy manifest .

Multiline Commands in GitHub Actions

Unlike the CLI, the GitHub Action automatically wraps commands in bash -c, so you can write multiline commands naturally without explicit wrapping:

- name: Run multiple commands
  uses: posit-dev/with-connect@main
  with:
    version: 2025.09.0
    license: ${{ secrets.CONNECT_LICENSE_FILE }}
    command: |
      echo "Starting deployment"
      rsconnect deploy manifest .
      curl -f -H "Authorization: Key $CONNECT_API_KEY" $CONNECT_SERVER/__api__/v1/content
      echo "Deployment complete"

The $CONNECT_API_KEY and $CONNECT_SERVER environment variables are available within your commands.

Note: For single-line commands with special characters (like $ or quotes), wrap the entire command in single quotes to prevent YAML parsing issues:

- name: Single line with special characters
  uses: posit-dev/with-connect@main
  with:
    version: 2025.09.0
    license: ${{ secrets.CONNECT_LICENSE_FILE }}
    command: 'curl -f -H "Authorization: Key $CONNECT_API_KEY" $CONNECT_SERVER/__api__/v1/content'

Set Environment Variables

- name: Test deployment with custom env vars
  uses: posit-dev/with-connect@main
  with:
    version: 2025.09.0
    license: ${{ secrets.CONNECT_LICENSE_FILE }}
    env: |
      MY_VAR=value
      ANOTHER_VAR=123
    command: rsconnect deploy manifest .

Specify a Custom Container Image

- name: Test deployment with custom image
  uses: posit-dev/with-connect@main
  with:
    image: rstudio/rstudio-connect:jammy-2025.09.0
    license: ${{ secrets.CONNECT_LICENSE_FILE }}
    command: rsconnect deploy manifest .

Multi-Step Workflows (Start-Only Mode)

For workflows that need to run multiple steps against Connect, or use other actions with the running instance, use start-only mode:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      # Start Connect without a command - it will keep running
      - name: Start Connect
        id: connect
        uses: posit-dev/with-connect@main
        with:
          version: 2025.09.0
          license: ${{ secrets.CONNECT_LICENSE_FILE }}
      # Use the outputs in subsequent steps
      - name: Deploy content
        run: rsconnect deploy manifest .
        env:
          CONNECT_API_KEY: ${{ steps.connect.outputs.CONNECT_API_KEY }}
          CONNECT_SERVER: ${{ steps.connect.outputs.CONNECT_SERVER }}
      # Use another action with Connect
      - name: Run integration tests
        uses: some-other-action@v1
        with:
          connect-url: ${{ steps.connect.outputs.CONNECT_SERVER }}
          api-key: ${{ steps.connect.outputs.CONNECT_API_KEY }}
      # Stop Connect when done
      - name: Stop Connect
        uses: posit-dev/with-connect@main
        with:
          stop: ${{ steps.connect.outputs.CONTAINER_ID }}

Minimum Version

Posit Connect 2022.10.0 or later is required. Earlier versions did not have the bootstrap endpoint used in this utility.