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

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 .

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

Run Posit Connect with default settings:

with-connect

This will:

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

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.

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.

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).

The GitHub Action supports the following inputs:

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 .

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'

- 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 .

- 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 .

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