viamrobotics / build-action

Build your viam module for multiple architectures, using github CI and viam builders

build-action

This is a Github CI action which wraps Viam's cloud build system. Use this to build and publish your Viam module for multiple platforms.

If you run into trouble setting this up, file a bug on this repo or reach out on our Discord.

What is Viam cloud build?

Cloud build is cross-compilation infrastructure that we provide to module authors so you can publish your module for multiple platforms: x86, ARM Linux, and MacOS.

Your customers are deploying to different kinds of hardware, and prototyping on a laptop. Cloud build helps you to reach them everywhere without doing the heavy lifting of operating your own buildsystem.

Basic usage

1. Create a .github/workflows/viam-build.yml in your repo with these default contents:

   # see https://github.com/viamrobotics/build-action for help
   on:
     push:
       tags:
       - '[0-9]+.[0-9]+.[0-9]+'
   
   jobs:
     publish:
       runs-on: ubuntu-latest
       steps:
       - uses: actions/checkout@v3
       - uses: viamrobotics/build-action@v1
         with:
           # note: you can replace this line with 'version: ""' if you want to test the build process without deploying
           version: ${{ github.ref_name }}
           ref: ${{ github.sha }}
           key-id: ${{ secrets.viam_key_id }}
           key-value: ${{ secrets.viam_key_value }}

2. Add your build commands in your meta.json (instructions below). If you don't have a meta.json, start with the 'create' and 'upload' sections of our registry docs).

   Here's an example, taken from our golang wifi repo:

   {
     "module_id": "viam:golang-wifi-example",
     ...
     "build": {
       "build": "make module.tar.gz",
       "arch" : ["linux/amd64", "linux/arm64", "darwin/arm64"]
     }
   }

   You can test this command by running the following command on your development machine:

   viam module build local

   The command will run your build instructions without running a cloud build job.

3. Set up repo secrets using the auth instructions below

4. Create a tag like 0.0.1 and push to GitHub; your module should build and deploy on the desired platforms.

Auth instructions

1. Run viam organizations list to view your organization ID.
2. Create an organization API key by running the following command:

   viam organization api-key create --org-id YOUR_ORG_UUID --name descriptive-key-name
   

   This command outputs an ID + a value, both of which you will use in step 4 below. If the command doesn't exist, update your CLI version.
3. In the GitHub repo for your project, go to 'Settings' -> 'Secrets and variables' -> 'Actions'
4. Create two new secrets using the 'New repository secret' button:

• viam_key_id with the UUID from "Key ID:" in your terminal
• viam_key_value with the string from "Key Value:" in your terminal

5. All set! If you copy the YAML example above, it will use these secrets to authenticate to Viam. If you have already tried the action and it failed because the secrets were missing, you can trigger a re-run from your repo's 'Actions' tab.

Environment and base image

On Linux builds, you'll be using the same Debian layer that builds our golang RDK. If something is missing, you can apt-get install it.

For MacOS, you'll have a runner with most of the libraries for our golang RDK installed as homebrew packages. If something is missing, you can brew install it.

Examples

• Golang
  • CI yaml
  • meta.json
• C++
  • CI yaml
  • meta.json