Automatically Upload Symbols and Deploy Releases from CI

Uploading symbol files and deploying OTA updates from your CI system is a great way to automate the process of releasing new firmware versions. This guide will show you how to use the Memfault CLI to upload symbol files and deploy OTA updates from your CI system.

Methodology

The Memfault CLI is used to upload symbol files and deploy OTA updates, once the firmware has been built. The steps are as follows:

1. Build the firmware, generating a symbol file and an OTA payload. In Zephyr, this is typically a .elf file and a .bin file, respectively:

   • build/zephyr/zephyr.elf
   • build/zephyr/app_update.bin

   Memfault always recommends signing OTA artifacts, to protect devices from installing counterfeit/invalid firmware. Zephyr has built-in support for signed OTA images using MCUBoot.

2. Use the Memfault CLI to upload the symbol file, with the upload-mcu-symbols command:

   memfault upload-mcu-symbols build/zephyr/zephyr.elf

3. Use the Memfault CLI to create the Release and deploy the OTA update, with the upload-ota-payload and deploy-release commands:

   # note: this command both creates the Release, if it doesn't exist, and
   # uploads the OTA payload
   memfault upload-ota-payload \
     --hardware-version <hardware_version> \
     --software-type <software_type> \
     --software-version <software_version> \
     build/zephyr/app_update.bin
   
   memfault deploy-release \
     --release-version <software_version> \
     --cohort <cohort>

GitHub Action for Uploading Symbols

Memfault provides a simple GitHub Action for uploading symbol files. Here's an example of how to use it:

- name: Upload symbol file to Memfault
  uses: memfault/github-action-upload-symbols@v1
  with:
    MEMFAULT_ORG_TOKEN: ${{ secrets.MEMFAULT_ORG_TOKEN }}
    MEMFAULT_ORG_SLUG: ${{ secrets.MEMFAULT_ORG_SLUG }}
    MEMFAULT_PROJECT_SLUG: ${{ secrets.MEMFAULT_PROJECT_SLUG }}
    symbol_file: symbols.elf

See the action here: https://github.com/memfault/github-action-upload-symbols

GitHub Actions Example: Upload Symbols and Deploy Release

Here's a full example using GitHub Actions to build + upload + deploy a firmware release. This example is using Zephyr, but the principles are the same for other RTOSs or bare-metal projects.

Set up some GitHub Actions secrets, for the Organization Auth Token and the Memfault Organization and Project (for private repos, those last two don't need to be secrets).

And this is the example workflow file:

.github/workflows/memfault.yml

# Depending on your project needs, you can have the build + upload trigger on
# different conditions. This example only uploads + deploys when a tag is
# created.
on:
  pull_request:
    branches:
      - main
  push:
    branches:
      - main

  workflow_dispatch:

  # run on tag creation
  create:
    tags:

env:
  # these must be as returned by memfault_platform_get_device_info() in the
  # firmware being built
  HARDWARE_VERSION: mp
  SOFTWARE_TYPE: nrf91ns-fw

  # this Cohort will be the target for the release deployment
  COHORT: auto-ota

jobs:
  build:
    runs-on: ubuntu-latest
    # In a real implementation, it's likely a container would be used.
    # See a worked example here:
    # https://interrupt.memfault.com/blog/ncs-github-actions
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Build firmware
        # need to run as bash for '== "refs/tags/"*' to work
        shell: bash
        id: build
        run: |
          # create a version string. if it's a tag build, use the tag name,
          # otherwise use the most recent tag + git short sha
          cd nrfconnect-ci-app
          if [ -n "$GITHUB_REF" ]; then
            if [[ "$GITHUB_REF" == "refs/tags/"* ]]; then
              VERSION=$(echo $GITHUB_REF | sed 's/refs\/tags\///')
            else
              VERSION=$(git describe --tags --abbrev=0)
              VERSION="${VERSION}+$(git rev-parse --short HEAD)"
            fi
          else
            echo "ERROR: Cannot determine version"
            exit 1
          fi

          # save the version string to this step's output
          echo "version=${VERSION}" > ${GITHUB_OUTPUT}

          <your build commands here, i.e. west build>

      # if the Docker image used for the build doesn't already have Python,
      # you can install it with this GitHub Action
      - name: Set up Python
        id: python
        uses: actions/setup-python@v4
        with:
          python-version: 3.10

      - name: Upload payload and deploy release
        if: github.event_name == 'create' && github.event.ref_type == 'tag'
        run: |
          # install the memfault CLI
          pip install memfault-cli==1.0.6

          # upload the symbol file
          memfault \
            --org-token ${{ secrets.MEMFAULT_ORG_TOKEN }} \
            --org ${{ secrets.MEMFAULT_ORG }} \
            --project ${{ secrets.MEMFAULT_PROJECT }} \
            upload-mcu-symbols build/zephyr/zephyr.elf

          # create the release and upload the OTA payload. the version is from
          # the build step
          memfault \
            --org-token ${{ secrets.MEMFAULT_ORG_TOKEN }} \
            --org ${{ secrets.MEMFAULT_ORG }} \
            --project ${{ secrets.MEMFAULT_PROJECT }} upload-ota-payload \
            --hardware-version ${{ env.HARDWARE_VERSION }} \
            --software-type ${{ env.SOFTWARE_TYPE }} \
            --software-version ${{ steps.build.outputs.version }} \
            build/zephyr/app_update.bin

          memfault \
            --org-token ${{ secrets.MEMFAULT_ORG_TOKEN }} \
            --org ${{ secrets.MEMFAULT_ORG }} \
            --project ${{ secrets.MEMFAULT_PROJECT }} deploy-release \
            --release-version ${{ steps.build.outputs.version }} \
            --cohort ${{ env.COHORT }}