Release OTA Updates from A CI/CD Pipeline with Thistle

Thistle Technologies provides a software solution to over-the-air (OTA) updates for embedded devices. .

In this blog post, we announce the release of the GitHub action “Create OTA Release”, which helps to create an OTA update release, and publishes it to Thistle's backend platform to update devices running the Thistle Update Client (TUC). With this action, one will be able to automate the OTA release process, for example, from a CI/CD pipeline on GitHub. Our goal is to make deployment of OTA updates easy.

How to use the action

To use this action (thistletech/ota-release-action), one needs to create an account in the Thistle Control Center, and obtain the API token ("Project Access Token"). In case a locally managed OTA update signing key is used (which is the only supported option as of v1.2.0), one also needs to go through the Configuration step to create a password-protected Minisign private key with the trh init command. Confidential information, including the API token, the private signing key, and signing key password shall be configured as GitHub repository secrets, and is further referred to as action parameters.

An example GitHub workflow for file update is as follows. In the action’s input parameters, artifacts_dir is the path to a directory on the GitHub runner machine where OTA update artifacts reside, persist_dir_on_device is the device-side path to a directory in which device state information is kept, and base_install_path_on_device is the device-side path to a directory where OTA artifacts are installed.

name: 'OTA Release'

on: push: tags: # Trigger release by tagging - 'release-v*'

jobs: ota_release: name: 'OTA Release' runs-on: 'ubuntu-latest' steps: - name: 'Checkout source' uses: 'actions/checkout@v4'

  - name: 'Create artifacts for OTA release'
    run: |
      ...
      [build artifacts from source]
      [run tests on artifacts]
      ...
      rm -rf artifacts
      mkdir -p artifacts
      ...
      [copy built artifacts to directory artifacts/]
      ...

  - name: 'OTA Release'
    uses: 'thistletech/ota-release-action@v1'
    with:
      release_name: 'OPTIONAL RELEASE NAME'
      release_type: 'file'
      artifacts_dir: 'artifacts'
      persist_dir_on_device: '/tmp/persist'
      base_install_path_on_device: '/tmp/ota'
      project_access_token: ${{ secrets.PROJECT_ACCESS_TOKEN }}
      signing_key_management: 'local'
      signing_key: ${{ secrets.SIGNING_KEY }}
      signing_key_password: ${{ secrets.SIGNING_KEY_PASSWORD }}

Two other release types, rootfs and zip_archive are also supported. Examples of the corresponding configurations are as below.

For rootfs update

      - name: 'OTA Release'
        uses: 'thistletech/ota-release-action@v1'
        with:
          release_name: 'OPTIONAL RELEASE NAME'
          release_type: 'rootfs'
          rootfs_img_path: '/path/to/rootfs.img'
          persist_dir_on_device: '/tmp/persist'
          project_access_token: ${{ secrets.PROJECT_ACCESS_TOKEN }}
          signing_key_management: 'local'
          signing_key: ${{ secrets.SIGNING_KEY }}
          signing_key_password: ${{ secrets.SIGNING_KEY_PASSWORD }}

For zip archive update (for which the artifacts are zipped before being uploaded to the backend)

      - name: 'OTA Release'
        uses: 'thistletech/ota-release-action@v1'
        with:
          release_name: 'OPTIONAL RELEASE NAME'
          release_type: 'zip_archive'
          zip_archive_dir: '/path/to/uncompressed_artifacts_dir'
          persist_dir_on_device: '/tmp/persist'
          base_install_path_on_device: '/tmp/ota'
          project_access_token: ${{ secrets.PROJECT_ACCESS_TOKEN }}
          signing_key_management: 'local'
          signing_key: ${{ secrets.SIGNING_KEY }}
          signing_key_password: ${{ secrets.SIGNING_KEY_PASSWORD }}

For a complete list of action inputs, please refer to the GitHub project’s README.md.

Signing key management

Currently (as of v1.2.0) only locally managed (i.e., on machines running the CI/CD pipeline) OTA update signing keys are supported by the ota-release-action action. Thistle also supports service-managed signing keys based on Cloud KMS. We will add the support of remotely managed OTA update signing keys in future versions of this GitHub action.

Conclusion

Thistle always strives to make it easy and flexible to deploy security capabilities to devices. In this blog post, we introduced a GitHub action to allow releasing of OTA updates from a CI/CD pipeline on GitHub, and walked through its usage examples for various types of OTA update releases. We will introduce further improvements in later versions of the GitHub action.