Cloud builds

How it works

1. Your workflow checks out the code and builds the firmware on the GitHub runner.
2. The upload-artifact step records a GitHub-sourced build on embeddedci.com (repository, branch, commit, run) and attaches the firmware and its siblings with the same stem.
3. The build lists on the Builds page, and its files appear in the Flash tab of every BenchPod in your organization, with the wiring you passed to the action filled in.

The upload touches no BenchPod, so it is safe to run on every push.

Set up

1. Trust the repository in the web app under BenchPod → GitHub Actions (see Security & trusted repos).
2. Give the job permissions: id-token: write. The action authenticates with the job's GitHub OIDC token, so no API key or secret is stored in the repository.
3. Add the upload-artifact step after your build step.

Without the trusted repository or the permission, the step fails with a message naming what is missing.

Workflow example

name: firmware
on: [push]

permissions:
  id-token: write        # required: the action authenticates with the job's OIDC token
  contents: read

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5

      # Your existing build: any toolchain, any build system.
      - run: sudo apt-get install -y gcc-arm-none-eabi
      - run: make            # produces build/app.elf, build/app.hex, build/app.bin

      - uses: embeddedci-com/submit-job-action/upload-artifact@v1
        id: upload
        with:
          firmware: build/app.elf
          build_target: stm32f4
          openocd_target: target/stm32f4x.cfg
          swclk: "11"
          swdio: "12"
          nreset: "true"
          efuse: "1"

      - run: echo "Build ${{ steps.upload.outputs.build_id }}"

Inputs and outputs

Output: build_id, the embeddedci build the artifacts were attached to (empty when the upload was skipped by allow_missing_token).

Pull requests from forks cannot mint an OIDC token. Set allow_missing_token: "true" to skip the upload there instead of failing the job.

Flash an uploaded build

1. Open the pod from your BenchPod list and go to the Flash tab.
2. Pick the build under Firmware artifact. Each entry shows its branch and commit.
3. Check the OpenOCD target, SWD channels, reset and target power. They come from the action's inputs; change them if this pod is wired differently.
4. Click flash. The server runs OpenOCD against the pod and shows the result.

Nothing runs on your machine, so this works from any browser, for any pod your organization can reach.

Flashing from pytest, the SDK, MCP or the CLI

These flash either a local file or a build uploaded here. A local file needs no upload: OpenOCD runs on the machine that runs your code and talks to the pod's CMSIS-DAP probe over the network or the cloud, so that machine needs an OpenOCD build with the cmsis-dap TCP backend (newer than 0.12.0). An uploaded build is named by its build id (or latest) and/or its repository and branch or tag; on an embeddedci:<pod> connection embeddedci.com runs OpenOCD, as the Flash tab does, and on a LAN or USB connection the file is downloaded and flashed locally.

Without an artifact name the build's .elf is flashed, else its .hex, else its .bin. An omitted target config falls back to the openocd_target the upload recorded. Looking a build up needs a sign-in: an API key, benchpod login, or the GitHub Actions OIDC session the SDK already uses for a cloud pod. A flash run by embeddedci.com always verifies and resets; pass server_side=False (CLI: --server-side=false) on a LAN pod connection to flash with your own OpenOCD options.

Python SDK:

from embeddedci.benchpod import BenchPod

with BenchPod("embeddedci:my-pod", la_voltage=3.3) as bp:
    # SWD pins, reset and target config come from the pod's wiring profile.
    bp.flash(file="build/app.elf", target="target/stm32f4x.cfg", target_power=1)

pytest:

pytest --benchpod-connection=embeddedci:my-pod --benchpod-firmware=build/app.elf

# in the test:
def test_boots(benchpod, firmware):
    assert benchpod.flash(file=firmware, target="target/stm32f4x.cfg").ok

MCP (the agent passes a path on the host running the MCP server):

flash(file="build/app.elf", target="target/stm32f4x.cfg", target_power=1)

CLI:

benchpod flash --target target/stm32f4x.cfg --file build/app.elf

An uploaded build, from the SDK:

import os

with BenchPod("embeddedci:my-pod", la_voltage=3.3) as bp:
    # the newest build of main; embeddedci.com runs OpenOCD for a cloud pod
    result = bp.flash(build="latest", repo="my-org/my-firmware", ref="main", target_power=1)
    print(result.artifact["name"], result.artifact["sha"])

    # or the exact build the upload step printed (its build_id output)
    bp.flash(build=os.environ["BUILD_ID"])

From MCP:

flash(repo="my-org/my-firmware", ref="main", target_power=1)

From the CLI (no local OpenOCD needed over embeddedci.com):

benchpod flash --connection embeddedci:my-pod --repo my-org/my-firmware --ref main
benchpod flash --connection embeddedci:my-pod --build 3f9c2a1e-...   # the upload's build_id