One of my motivations for writing jDeploy was to allow you to build native app bundles from a single development environment, unlike existing toolchains (e.g. jpackage), which require a Mac to build Mac apps, a Windows box to build Windows apps, and a Linux box to build Linux apps. In my view, this workflow didn’t live up to the ethos of WORA (write-once-run-anywhere) that has always been the most fundamental of Java’s value propositions. As I expressed last week, I’m satisfied that jDeploy has successfully slain this dragon: You can now build native bundles for all platforms from any platform.

In this article, I’d like to take this a step further. Once you’ve published your app successfully once or twice, you’re probably ready to automate the process. One workflow I’m particularly fond of is to bind the “publish” step to a GitHub release, so that whenever I create a new tag or release, it will automatically publish the corresponding version using jDeploy. Using GitHub actions, this is remarkably easy to do. I have set up such a workflow on the SwingSet app as a demonstration.

The GitHub action workflow is as follows:

name: Publish with jDeploy

on:
  push:
    tags: '*'

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v3
    - name: Set up JDK 11
      uses: actions/setup-java@v3
      with:
        java-version: '11'
        distribution: 'temurin'
        cache: maven
    - name: Set up Node
      uses: actions/setup-node@v2
      with:
        node-version: '16.x'
        registry-url: 'https://registry.npmjs.org'
      env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
    - name: Set up Git Config
      run: |
          git config user.name "GitHub Actions Bot"
          git config user.email "<>"
    - name: Build with Maven
      run: mvn -B package --file pom.xml
    - name: Publish with jDeploy
      run: |
        npm version "$GITHUB_REF_NAME"
        npx jdeploy publish
      env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

One thing to notice here is how minimal this workflow is. It is just a basic Maven build workflow with the addition of a set-up step for Node, and a deploy step. The jDeploy portion is only the last step:

    - name: Publish with jDeploy
      run: |
        npm version "$GITHUB_REF_NAME"
        npx jdeploy publish
      env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

There are three things to notice here:

1. We need to set the NODE_AUTH_TOKEN environment variable with an authentication token that we generate on npmjs.com. I’ll discuss this further in a moment.

2. We set the package version to match the version of our GitHub release with npm version "$GITHUB_REF_NAME"
This saves us from having to manually update the “version” property in our package.json file for every release.

3. We install jDeploy and run “publish” in a single step using the npx jdeploy publish command.

And we’re done. Now, whenever I create a new GitHub tag, it will automatically publish the SwingSet demo with my latest version. And, as usual, users who already have the app installed will automatically receive the update the next time they launch the app.

Using this Workflow in Your Own App

Applying this workflow to your own app only takes a couple of minutes. If your app uses Maven, then you can pretty much copy this workflow into your repository unchanged. If you require some custom build steps, then you can just add them before the “Publish with jDeploy” step.

Steps:

1. Create a file at the path .github/workflows/jdeploy.yml in your app’s GitHub repository, and paste in the contents of this workflow file.

2. Log into your account on npmjs.com, then click on your avatar in the upper-right, and select the “Access Tokens” menu item from the menu that opens up:

3. Click the “Generate New Token” button in the upper right:

4. You’ll be prompted to enter your password again, then you’ll see a form as follows:

5. Enter a name for the token in the “Name” field - this can be whatever you want. And select the “Publish” option. Then press the “Generate Token” button.

6. Once you have your token, you need to add it as a “secret” in your GitHub repository, so you’ll need to log into GitHub, navigate to your app’s repository, and click the “Settings” tab.

7. In the left side menu, you should see a “Secrets” option. Expand this to reveal an “Actions” sub-option, then click on that option.

8. Click on the “New Repository Secret” button in the upper right:

9. This will open a form as shown below. Enter “NPM_TOKEN” as the secret name to correspond with the secret name that is in the workflow file. For the value, you should paste in the token that you generated in step 4 (on npmjs.com).

10. You should be done. Next step is to test it out.

Testing Your Workflow

Personally, I’ve never had a GitHub action work the first time. Usually it will fail with some error or another on the first couple of tries, but let’s be positive here and hope for the best. Our workflow will be triggered when you add a new tag or release in GitHub, so let’s do that now.

Open up your GitHub repository in the browser, and look for the “Releases” block on the right column:

Click on the “Releases” heading to go to the “Releases” section, and then press the “Draft New Release” button in the upper right.

Click on the “Choose a Tag” button, and enter a version for your release.

Then press the “Create new tag: {{YOUR VERSION}} on publish”.

For the release title, you can enter anything you like, but I usually just use the same value that I used for the tag. E.g. If my tag is “1.0.11”, then I also set the release title to “1.0.11”. But you’re the king of your own castle and you can title your releases however you like.

Enter some comments in the description field, and then press “Publish Release”.

And you’re done.

If you want to watch the workflow as it progresses, you can click on the “Actions” tab, and then click on the row corresponding to your workflow.

If all went well, you can check out your app’s download page at https://www.jdeploy.com/~YOUR_PACKAGE_NAME and the version listed should match the your latest release.

If you already have your app installed, you can launch/relaunch it and it will automatically download your latest release, and launch it.

Self-hosting and More Advanced Options

One of the most frequent questions I get from potential users is “Can I self-host”? This is generally referring to the fact that jDeploy uses npm as a CDN for jDeploy apps, and some users would rather use their own hosting. Next time, I’ll cover a few different ways to achieve this with jDeploy. I’ll also build on our basic GitHub actions work flow to add some other nice features such as adding the native installer bundles to the GitHub release as packages, rather than using the jDeploy-supplied download page.

If you are in the “I want to use jDeploy, but I need to be able to self-host” boat, please let me know in the comments. Try to include why you need self-hosting, and elaborate on what you mean by self-hosting, as self-hosting may mean different things to different people.

Let me know what you like to read

This newsletter and its associated jDeploy project is devoted to making Java a more compelling platform for desktop app development. I write a mix of long-form essays, tutorials, and news updates related to Java on the desktop. I try to post a new article once per week. You can check out the back-issues to get a taste for the focus and style. Depending on what readers prefer, I may change the ratio of “essay” to “tutorial” articles. If you have a preference, please let me know either in the comments or via email. Also, if you would like to share your own experiences with Java, continuous integration, and the desktop, I’m always interested in reading other developers’ perspectives, so please leave a comment to share.

Don’t forget to subscribe to be notified when new articles are posted. Until next time, happy coding!

One last thing: New Developer Mailing List

One bit of house-keeping before I close off here. I have created a Google Group that is intended for developers who are deploying apps with jDeploy. This will allow me to alert you to upcoming changes that affect apps that use jDeploy. I decided to create a separate mailing list for this, rather than piggy-back onto the newsletter because the readership of this newsletter includes many people who are interested in Java on the desktop, but who aren’t actually deploying apps with jDeploy, and I would like to keep the signal-to-noise ratio high.

If you are using jDeploy at all, I encourage you to join this group, so that I can notify you of changes that affect you.