Contributing

Add your extension in the extensions/ subdirectory.

To help you get started, call make create-extension DIR=my_extension_name to create a new extension directory with the necessary files. Note, you will need to manually create your manifest.json file.

Required files

manifest.json

Use rsconnect or rsconnect-python to generate a manifest, which is required as part of the extension bundle

connect-extension.qmd

A file that has the name of your extension, the categories it falls into, and a brief description

connect-extension.qmd

connect-extension.toml
---
title: extension title
categories:
    -
---

extension description

Connect Gallery

The Connect Gallery displays apps, dashboards, and reports that can be easily added to Posit Connect servers.

This section covers how to ready your content for the gallery, add it, and release new updates.

Additional Requirements

The extension section in manifest.json

Content in the gallery requires some additional details in the manifest.json file to display, install on Connect, and automatically release using automation in this repository.

Below is an example of the additional details that need to be manually added to the manifest.json:

manifest.json

{
  ...
  "extension": {
    "name": "my-content-name",
    "title": "My Content Name",
    "description": "A lovely, detailed description of the content.",
    "homepage": "https://github.com/posit-dev/connect-extensions/tree/main/extensions/my-content-name",
    "version": "0.0.0"
  }
}

It is recommended to begin with "version": "0.0.0" to avoid triggering a release during development of your content. When you are ready to release to the gallery check the Adding content to the Connect Gallery section.

README.md

In the above extension section there is a homepage link that we provide in the Connect Gallery letting users see documentation related to the apps, dashboards, and reports available to install.

Gallery content should include a README.md file in its directory so when the homepage is visited there is documentation to assist users. It should include a description of how the content can be used and any additional setup instructions.

Language version constraints

To ensure that content in the gallery is installable on as many Posit Connect servers as possible we use the language version constraints feature to broaden the language versions Connect can use for a piece of content.

All content in the gallery should include requires specifications for the language(s) it utilizes.

Here is an example of what needs to be included in a manifest.json:

manifest.json

{
  ...
  "environment": {
    "python": {
      "requires": ">=3.8, <4"
    },
    "r": {
      "requires": ">=4.2, <5"
    }
  },
  ...
}

Adding content to the Connect Gallery

Once your content has the requirements above it is ready to be added to the Connect Gallery.

The Connect Gallery uses GitHub Workflows to automate releases of new content when pull requests in this repo merge into main.

To add content to the Connect Gallery, follow the steps below:

Adding simple content

“Simple content” refers to content that can be bundled into a TAR file without any additional steps. Most content will fall into this category.

Note

If you can run

tar -czf my-extension-name.tar.gz ./extensions/my-extension-name

and the resulting TAR file can be published by uploading the bundle to Posit Connect, then it is piece of simple content.

To add simple content look for the simple-extension-changes section in the .github/workflows/extensions.yml file and add a new filter:

filters: |
  ...
  my-content-name: extensions/my-content-name/**

A good example is how reaper is setup.

This will make any code changes to your content trigger a few things:

• lint: ensuring your content has everything it needs to be added to the gallery
• package: creating a TAR file of the content’s directory to test in pull requests and to be released
• release: When the version in the manifest.json is incrased and merged to main, releases the content to users of Posit Connect

Lastly set the version in the manifest.json file to your initial release.

When the changes above are merged the first release will be kicked off, and your content will be in the gallery. 🚀

Adding custom built content

“Custom built content” refers to content that requires additional steps prior to be being packaged into a TAR file.

Setting up custom built content is a bit more complex since it involves setting up the environment needed to build the content.

Creating a custom workflow

To faciliate control over how the content is being built we utilize custom GitHub Workflows. See the Creating a custom workflow guide how to get started.

Calling the custom workflow

Once the custom workflow is created we need to head back to the general .github/workflows/extensions.yml file.

It is recommended to see how publisher-command-center is setup as an example for how to use your new custom workflow.

Once your custom workflow is setup, set the version in the manifest.json file to your initial release.

When the changes above are merged the first release will be kicked off, and your content will be in the gallery. 🚀

Updating content in the Connect Gallery

To update already released content in the Connect Gallery simply increment the version field in the extension section of the manifest.json file and open a pull request with the changes.

manifest.json

{
  ...
  "extension": {
    ...
    "version": "1.1.0"
  }
}

When that pull request is merged, GitHub Workflows will automatically create a new GitHub Release for the content changed, update the content list, and update Connect Gallery.

Checking if your extension will release

If you would like to check if merging a pull request will trigger a new release you can do that by looking at the logs for the GitHub Actions.

Click on the “Checks” tab for a Pull Request and look at the Extension Workflow run.

Click on the Job related to the content being updated and view the logs for the /./.github/actions/release-extension action.

It will either say:

The manifest version is ‘1.1.0’ and the released version is ‘1.0.0’

🚀 Will release! The manifest version is greater than the released version.

or:

The manifest version is ‘1.0.0’ and the released version is ‘1.0.0’

😴 Holding back from release: The manifest version is not greater than the released version.

Manually testing content

Packaged TAR files are included as artifacts in the Extension Workflow runs.

Click on the “Checks” tab for a Pull Request and look at the Extension Workflow run. At the bottom, “Artifacts” are available, and if your content changed in the Pull Request then a my-extension-name.tar.gz file will be available.

It can be downloaded, and tested using the publish via bundle feature in Posit Connect.

Removing a release from the Connect Gallery

If released content needs to be reverted, or content removed entirely, follow the steps below:

Removing a single release

Open a pull request to remove the release:

1. Remove the release from the content list in extension.json
   • If the removed release is the latest release, update the latestVersion field for that piece of content to the previous release
   • Versions are sorted in descending order, so the latest release should be the first element in the versions array
2. Revert the content’s version in the manifest.json file to the previous release

Once the pull request is merged continue with the steps below:

1. Remove the associated release from the GitHub Releases page.
2. Remove the associated tag from the GitHub Tags page.

Removing an entire piece of content

Removing an entire piece of content from the gallery is similar to removing a single release, but with a few additional notes:

• Instead of removing a single list from the content list in extension.json remove the entire content object.
• Instead of reverting the version in the manifest.json file to the previous release, instead set the version to 0.0.0 to avoid a release.

And after the pull request is merged:

• Remove all associated releases for the content from the GitHub Releases page.
• Remove all associated tags for the content from the GitHub Tags page.

Removing Content

Removing content from the extensions/ subdirectory that has already been added to the Connect Gallery requires that you follow instructions in the above Removing an entire piece of content section.

In addition references to the content in GitHub workflows will need to removed.