Deploy-BlueOS-Extension

An action for building a BlueOS Extension and deploying it to a Docker registry.

Automatically builds for multiple hardware architectures, and provides inputs for common BlueOS Extension metadata variables to pass to your Dockerfile when building.

Input Variables

Variable	Description	Required?	Example
docker-username	Your username for your Docker registry of choice*. Should be stored in a GitHub Action Secret. *Currently only Docker Hub is supported. MUST be lowercase.	YES	secrets.DOCKER_USERNAME
docker-password	The password for your Docker registry authentication. Should be stored in a GitHub Action Secret. Recommended to set the secret to a Docker Hub Access Token.	YES	secrets.DOCKER_PASSWORD
github-token	Your authentification token for GitHub, for uploading image artifacts to a release/tag.	YES (if building for releases)	Should be set to secrets.GITHUB_TOKEN
build-platforms	A comma-separated string of the architectures to build for. Defaults to the ones BlueOS is automatically built for.	NO	'linux/arm/v7,linux/arm64/v8,linux/amd64'
image-name	The base name for the Docker Images and GitHub Artifacts.	YES	'extension-name'
image-prefix	An optional prefix for the Docker Image name. Defaults to 'blueos-'.	NO	'blueos-'
image-tag	An optional override for the Docker Image tag pushed to the registry. Defaults to the source repository branch or tag name.	NO	'custom-tag'
author		NO	'Author Name'
author-email		NO	'[email protected]'
maintainer	The maintaining organisation or developer. Defaults to the repository owner.	NO	'Devs-R-US'
maintainer-email		NO	'[email protected]'
dockerfile-location	The location of the Dockerfile to be used for the build. Defaults to the repository's root directory.	NO	'/.container'
skip-checkout	Skip the checkout step (e.g. if a previous Action has already checked out the repository).	NO	'false'

Example Usage

To start with, make a Docker repository in your registry accound with the name {image-prefix}{image-name}. Note that image-prefix defaults to blueos- if left unspecified.

name: Deploy BlueOS Extension Image

on:
  push:
  # Run manually
  workflow_dispatch:
  # NOTE: caches may be removed if not run weekly
  #  -> may be worth scheduling for every 6 days

jobs:
  deploy-docker-image:
    # set the agent to run on
    runs-on: ubuntu-latest
    steps:
      - name: Deploy BlueOS Extension
        uses: BlueOS-community/Deploy-BlueOS-Extension@v1
        # specify the desired variables
        with:
          docker-username: ${{ secrets.DOCKER_USERNAME }}
          docker-password: ${{ secrets.DOCKER_PASSWORD }}
          github-token: ${{ secrets.GITHUB_TOKEN }}
          # image-name should not start with blueos- (see image-prefix)
          image-name: 'something-creative'

You may also wish to define some GitHub Action Variables, which can be modified later / by repository forkers without needing to change the action file. The QuickStart-Python-Extension is an example of this.

Outputs

Built images are pushed to Docker Hub, tagged with:

• the image-tag value (if one is specified), or
• the code repository branch name (when triggered by a code push), or
• the name of the GitHub tag (when triggered by the creation of a GitHub release), and
• latest, if the initial image tag is SemVer-compliant (to reflect that it is the most recently released version)