Continuous Integration

PLTcloud allows for uploading a release utilizing a command line client. This client can be included in your CI pipeline in order to automatically deploy a firmware build to PLTcloud.

Supported Environments

The PLTcloud client is distributed as a Debian package and should work on Debian and other distributions supporting .deb files.

The PLTcloud 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.

Usage

pltcloud -t <TOKEN> -v <VERSION> -p <UUID> -f <GLOB>

-t token    API Token
-f string   File specifier
-v version  Release version
-p uuid     Project UUID

Files can be specified with patterns such as: **/prefix*, grandparent/**/child?, **/parent/*, or even just ** (which will include all files and directories recursively).

Example: Travis CI integration

Prerequisites

  • A Travis CI account and Travis CI client

  • A Git repository containing DUT firmware image and test plans

  • A PLTcloud organization, user and project

Step 1: Validate Travis CI build

In order to upload a release, the PLT test plan, and any associated assets such as DUT firmware must be available in a directory.

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 PLTcloud 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/pltcloud_0.3.0_amd64.deb
- sudo dpkg -i pltcloud_0.3.0_amd64.deb

Step 3: Configure Project and Token environment variables

  • 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 detail page and as an environment variable in .travis.yml

    For example:

    env:
      global:
        PROJECT_UUID=672124b6-9894-11e5-be38-001d42e813fe
    
  • Select API Tokens from the drop-down menu under the user menu.

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

  • Encrypt the 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: pltcloud -t "$API_TOKEN" -f "dist/*" -v "$TRAVIS_TAG" -p "$PROJECT_UUID"
      on:
        all_branches: true
        tags: true
    

Example: GitHub Actions

Prerequisites

  • A GitHub account and repository containing DUT firmware image and test plans

  • Access to GitHub Actions

  • A PLTcloud organization, user and project

Step 1: Validate firmware build and test plans

In order to upload a release, the PLT test plan, and any associated assets such as DUT firmware must be available in a directory.

The existing GitHub Action build the firmware and copy test plans to a known directory.

For example, the Zephyr Action in the Zephyr firmware for demo board project builds the firmware files and copies the test suites to a dist/ directory.

Step 2: Configure project and token secrets

  • 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 detail page and a secret named PROJECT_UUID in your GitHub project.

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

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

  • Add the release token to GitHub secrets and name it API_TOKEN

Step 3: Create an Action to deploy to PLTcloud

  • Create a new action folder pltcloud in same folder as existing actions, for example .github/actions/pltcloud.

  • Create a new file named Dockerfile in the pltcloud action folder with the following contents:

    .github/actions/pltcloud/Dockerfile
    FROM debian:stretch
    
    LABEL "com.github.actions.name"="PLTcloud publish"
    LABEL "com.github.actions.description"="Publish to PLTcloud"
    LABEL "com.github.actions.icon"="package"
    LABEL "com.github.actions.color"="blue"
    
    LABEL "repository"="https://github.com/bcdevices/ly10-zephyr-fw"
    LABEL "homepage"="https://github.com/bcdevices/ly10-zephyr-fw"
    LABEL "maintainer"="Blue Clover Devices"
    
    WORKDIR /usr/src
    
    RUN set -xe \
      && apt-get update \
      && apt-get install -y --no-install-recommends \
      musl \
      ca-certificates \
      bash \
      wget \
     && rm -rf /var/lib/apt/lists/*
    
    RUN wget https://download.pltcloud.com/cli/pltcloud_0.3.0_amd64.deb
    RUN dpkg -i pltcloud*_amd64.deb
    
    ADD entrypoint.sh /entrypoint.sh
    ENTRYPOINT ["/entrypoint.sh"]
    
  • Create a new file named entrypoint.sh in the pltcloud actions folder with the following contents:

    .github/actions/pltcloud/entrypoint.sh
    #!/bin/bash -l
    
    pltcloud -t "$API_TOKEN" -f "dist/*" -v "${GITHUB_REF:10}" -p "$PROJECT_UUID"
    
  • Make sure the entrypoint.sh file is executable using chmod u+x entrypoint.sh

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

    - uses: .github/actions/action-pltcloud
      if: contains(github.ref, 'tags')
      env:
        API_TOKEN: ${{ secrets.API_TOKEN }}
        PROJECT_UUID: ${{ secrets.PROJECT_UUID }}