Continuous Integration

PLTcloud allows for uploading a release utilizing the pltutil command line tool (named pltcloud before v0.7.4). This tool can be included in a CI pipeline in order to automatically deploy a firmware build to PLTcloud.

../../_images/howto_ci_upload.png

Supported Environments

The pltutil CLI is distributed as a Debian package, which should work on Debian and other distributions supporting .deb files, and as .zip packages for generic Linux, macOS, and Microsoft Windows.

The CLI has been tested with Travis CI and GitHub Actions.

Other CI tools can be utilized as long as they run a supported OS and support the installation of custom packages.

See the pltutil CLI page for downloads, usage, and command-line options.

Pipeline Setup

These steps apply to any CI tool. The examples below show how to apply them.

Prerequisites

  • A Git repository containing DUT firmware image and test plans

  • A CI service that can build the repository

  • A PLTcloud organization, user and project

Prepare the release files

In order to upload a release, the PLT test plan, and any associated assets such as DUT firmware must be available in a directory. Configure the CI build to create or copy these files into a known directory, such as dist/.

Get the project UUID and release token

  • Log in to PLTcloud and select the Project menu item from the project drop-down in the top banner.

  • Copy the UUID from the Project Details page.

  • Select API Tokens from the drop-down menu under the user menu.

  • Select Add Release Token, login and copy the Release Upload Token.

  • Store both values using the secret storage of your CI service.

Example: GitHub Actions

Step 1: Build the firmware and test plans

Setup a GitHub Action workflow to build the firmware and copy test plans to a known directory.

For example, the Zephyr Action

in the Zephyr firmware for demo board project is used to build the firmware files and copy the test suites to a dist/ directory.

Step 2: Add the secrets

Add the project UUID as a GitHub secret named PROJECT_UUID, and the release token as a secret named API_TOKEN.

Step 3: Update the Workflow to deploy to PLTcloud

  • Add a step in .github/workflows/main.yml beneath step that builds the firmware.

    - uses: bcdevices/pltcloud-action@v1.2.1
      if: contains(github.ref, 'tags')
      with:
        API_TOKEN: ${{ secrets.API_TOKEN }}
        PROJECT_UUID: ${{ secrets.PROJECT_UUID }}
        FILES: "./dist/*demo*"
        VERSION: ${{ github.ref }}
    

See also

Example: Travis CI integration

../../_images/deployment_hwci_travis.png

This example requires a Travis CI account and the Travis CI client.

Step 1: Validate Travis CI build

The existing build should create all the necessary files for a release in the install or script life cycle.

For example:

.travis.yml
sudo: required
language: c
script:
- make dist

Step 2: Add section to install pltutil CLI

Add a before_deploy: section to .travis.yml in order to install the CLI tool.

before_deploy:
- sudo apt-get update
- sudo apt-get install -y musl
- wget https://download.pltcloud.com/cli/pltutil_0.7.7_amd64.deb
- sudo dpkg -i pltutil_0.7.7_amd64.deb

Step 3: Configure Project and Token environment variables

  • Add the project UUID as an environment variable in .travis.yml

    For example:

    env:
      global:
        PROJECT_UUID=672124b6-9894-11e5-be38-001d42e813fe
    
  • Encrypt the release token and add it to .travis.yml with the command travis encrypt API_TOKEN=*************** --add

Step 4: Add deployment

  • Add deployment section to .travis.yml

    deploy:
    - provider: script
      skip_cleanup: true
      script: pltutil -t "$API_TOKEN" -f "dist/*" -v "$TRAVIS_TAG" -p "$PROJECT_UUID"
      on:
        all_branches: true
        tags: true