Contributing

Architecture

The Coder Gateway plugin uses Gateway APIs to SSH into the remote machine, download the requested IDE backend, run the backend, then launches a client that connects to that backend using a port forward over SSH. If the backend goes down due to a crash or a workspace restart, it will restart the backend and relaunch the client.

There are three ways to get into a workspace:

Dashboard link.
"Connect to Coder" button.
Using a recent connection.

Currently the first two will configure SSH but the third does not yet.

Development

To manually install a local build:

Install Jetbrains Gateway
Run ./gradlew clean buildPlugin to generate a zip distribution.
Locate the zip file in the build/distributions folder and follow these instructions on how to install a plugin from disk.

Alternatively, ./gradlew clean runIde will deploy a Gateway distribution (the one specified in gradle.properties - platformVersion) with the latest plugin changes deployed.

To simulate opening a workspace from the dashboard pass the Gateway link via --args. For example:

./gradlew clean runIDE --args="jetbrains-gateway://connect#type=coder&workspace=dev&agent=coder&folder=/home/coder&url=https://dev.coder.com&token=<redacted>&ide_product_code=IU&ide_build_number=223.8836.41&ide_download_link=https://download.jetbrains.com/idea/ideaIU-2022.3.3.tar.gz"

Alternatively, if you have separately built the plugin and already installed it in a Gateway distribution you can launch that distribution with the URL as the first argument (no --args in this case).

If your change is something users ought to be aware of, add an entry in the changelog.

Generally we prefer that PRs be squashed into main but you can rebase or merge if it is important to keep the individual commits (make sure to clean up the commits first if you are doing this).

Testing

Run tests with ./gradlew test. By default this will test against https://dev.coder.com but you can set CODER_GATEWAY_TEST_DEPLOYMENT to a URL of your choice or to mock to use mocks only.

There are two ways of using the plugin: from standalone Gateway, and from within an IDE (File > Remote Development). There are subtle differences so it makes usually sense to test both. We should also be testing both the latest stable and latest EAP.

Plugin compatibility

./gradlew runPluginVerifier can check the plugin compatibility against the specified Gateway. The integration with Github Actions is commented until this gradle intellij plugin issue is fixed.

Releasing

Check that the changelog lists all the important changes.
Update the gradle.properties version.
Publish the resulting draft release after validating it.
Merge the resulting changelog PR.

`main` vs `eap` branch

Sometimes there can be API incompatibilities between the latest stable version of Gateway and EAP ones (Early Access Program).

If this happens, use the eap branch to make a separate release. Once it becomes stable, update the versions in main.

Supported Coder versions

Coder Gateway includes checks for compatibility with a specified version range. A warning is raised when the Coder deployment build version is outside of compatibility range.

At the moment the upper range is 3.0.0 so the check essentially has no effect, but in the future we may want to keep this updated.