Skip to content

GitHub-Actions

github-badge

In short - Access the qbee.io API through custom GitHub actions

We provide several custom GitHub actions such that you can conveniently access our API from your automated GitHub CI without worrying about any details. The provided GitHub actions allow for a simple interaction with the qbee.io API which are accessible when from GitHub runners.

We introduce our custom GitHub actions and provide the corresponding repository links. At the end we provide a complete GitHub workflow example.

Authentication action

All the qbee.io API calls require an authorization token. To obtain that token we created the qbee-io/authenticate-action. Simply add

qbee-io/authenticate-action

name: qbee.io authentication
uses: qbee-io/authenticate-action@v1
id: qbee-auth
with:
    login: ${{ secrets.USERNAME_KEY }}
    password: ${{ secrets.PASSWORD_KEY }}

to your workflow file.

Input variables

  • login: the username you use to log into the qbee.io platform
  • password: the corresponding password

This information is sensitive and we recommend to store it in GitHub secrets such that it is encrypted.

Output variables

  • token: the authentication token needed for other API calls

to access the output you need to give the authentication step an id. Above we used

id: qbee-auth
Such that we get the token with the following command

${{ steps.qbee-auth.outputs.token }}

File upload action

To upload files to the qbee.io file manager from a GitHub action workflow we created qbee-io/file-upload-action. Simply include the following snipped

qbee-io/file-upload-action

name: qbee.io file upload
uses: qbee-io/file-upload-action@v1
with:
    token: ${{ steps.qbee-auth.outputs.token }}
    filename: 'file_to_upload_without_path'
    qbee_directory: 'path_in_qbee_file_manager'
    local_directory: 'path_to_file_in_github_repository'

to your yaml file.

Input variables

  • token: authentication token obtained from the previous step (make sure to equip the authentication step with an id that you can reference to)
  • filename: filename to upload without path
  • qbee_directory: path to directory in the qbee file manager where the file should be uploaded
  • local_directory: path to the local (GitHub) directory in which the file is located - default: ./

Setting up a complete GitHub action workflow

Here, we show how to set up an entire workflow from scratch where we set up a GitHub runner (using GitHub actions) to copy the desired files to the qbee.io file manager via API calls. With a new upload to the file manager a file distribution can be triggered on your remote device.

How to create a repository on GitHub

Check out the official repo creation documentation on how to create a repository on GitHub.

Once a repository is set up, before creating a runner, setup GitHub secrets as shown in the following screenshot to store your qbee.io credentials.

github-secrets

There we specify our qbee.io username USERNAME_KEY and password PASSWORD_KEY, as we do not want them to be exposed.

Once that is done, we create a GitHub actions which runs our setup script on the runners provided by GitHub (or you can set up your own runners). GitHub actions can be created as follows (we use "set up a workflow yourself")

github-secrets

We use the following demo script where we simply create a tar file out of the repository and upload it afterwards to the file manager.

main.yml

name: qbee.io upload
on:
  push:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      TARNAME: repo.tar

    steps:
    - uses: actions/checkout@v2

    - name: create tarball
      run: |
        mkdir ./tar
        tar --exclude='./.git' --exclude='./.github' --exclude='./tar' -czvf ./tar/$TARNAME .


    - name: qbee.io authentication
      uses: qbee-io/authenticate-action@v1
      id: qbee-auth
      with:
        login: ${{ secrets.USERNAME_KEY }}
        password: ${{ secrets.PASSWORD_KEY }}

    - name: qbee.io file upload
      uses: qbee-io/file-upload-action@v1
      with:
        token: ${{ steps.qbee-auth.outputs.token }}
        filename: ${{ env.TARNAME }}
        qbee_directory: 'github_actions_upload'
        local_directory: 'tar'

The tar file can for example be extracted on the devices with an appropriate command to run.

Comments on the yaml file

  • this action is triggered on pushes to the main branch
  • the runner is a virtual machine with an ubuntu OS as we specified ubuntu-latest
  • on that virtual machine (freshly created for you on every single run) the code from your repository is checked out using the actions/checkout@v2 option
  • we create a tar archive in the step create tarball on the virtual machine
  • authentication to qbee.io is performed via qbee-io/authenticate-action@v1
  • the upload to the file manager is performed via qbee-io/file-upload-action@v1

Note that your credentials aren't revealed as we use GitHub secrets to encrypt them.