Historical Onboarding

Populate your MemBrowse project with memory data from past commits. This is a one-time, optional step that gives you historical trends from day one instead of waiting for new commits to build up a baseline.

When to Use This

You're adding MemBrowse to an existing project and want to see historical memory trends immediately
You want to identify when a past memory regression was introduced

You only need to run this once. After that, your regular CI workflow will track every new commit automatically.

Create the Onboard Workflow

Create .github/workflows/membrowse-onboard.yml:

name: Onboard to MemBrowse
on:
  workflow_dispatch:
    inputs:
      num_commits:
        description: 'Number of commits to process'
        required: true
        default: '50'
        type: string

jobs:
  onboard:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
        with:
          fetch-depth: 0

      # Add your build tool setup here (e.g., arm-none-eabi-gcc)

      - name: Historical analysis
        uses: membrowse/membrowse-action/onboard-action@v1
        with:
          num_commits: ${{ github.event.inputs.num_commits }}
          build_script: make all              # Your build command
          elf: build/firmware.elf             # Path to your ELF file
          ld: linker.ld                       # Path to your linker script(s)
          target_name: my-target              # Must match your CI workflow
          api_key: ${{ secrets.MEMBROWSE_API_KEY }}
          # linker_vars: "__flash_size__=512K"  # Optional: linker variable definitions

Start small

Each commit requires a full build, so processing many commits can take a while. Start with 10-20 commits to verify everything works, then run again with a larger number. GitHub Actions has a 6-hour job timeout.

Multiple targets

If you followed the Multiple Targets setup with membrowse-targets.json, use the matrix pattern instead:

jobs:
  setup:
    runs-on: ubuntu-latest
    outputs:
      targets: ${{ steps.read-targets.outputs.targets }}
    steps:
      - uses: actions/checkout@v5

      - name: Read targets configuration
        id: read-targets
        run: echo "targets=$(jq -c '.targets' .github/membrowse-targets.json)" >> $GITHUB_OUTPUT

  onboard:
    needs: setup
    runs-on: ubuntu-latest
    strategy:
      matrix:
        target: ${{ fromJson(needs.setup.outputs.targets) }}
    steps:
      - uses: actions/checkout@v5
        with:
          fetch-depth: 0

      # Add your build tool setup here (e.g., arm-none-eabi-gcc)

      - name: Historical analysis for ${{ matrix.target.name }}
        uses: membrowse/membrowse-action/onboard-action@v1
        with:
          num_commits: ${{ github.event.inputs.num_commits }}
          build_script: ${{ matrix.target.build_script }}
          elf: ${{ matrix.target.elf }}
          ld: ${{ matrix.target.ld }}
          target_name: ${{ matrix.target.name }}
          api_key: ${{ secrets.MEMBROWSE_API_KEY }}
          linker_vars: ${{ matrix.target.def }}

Action Reference

Inputs (`membrowse/membrowse-action/onboard-action@v1`)

Input	Required	Description
`num_commits`	No	Number of historical commits to process (required unless `commits` is provided)
`commits`	No	Space-separated list of commit hashes and/or tags to process. Mutually exclusive with `num_commits` and `initial_commit`.
`build_script`	Yes	Shell command to build the firmware
`elf`	Yes	Path to generated ELF file after build
`ld`	No	Path to linker script(s), space-separated. If omitted, MemBrowse uses default Code/Data regions based on ELF section flags.
`target_name`	Yes	Target platform name
`api_key`	Yes	MemBrowse API key
`api_url`	No	MemBrowse API base URL (default: `https://api.membrowse.com`)
`linker_vars`	No	Linker script variable definitions, space-separated (e.g., `__flash_size__=4096K __ram_size__=256K`)
`build_dirs`	No	Space-separated directories that trigger rebuilds. Commits with no changes in these directories upload metadata-only reports. Mutually exclusive with `binary_search`.
`initial_commit`	No	Start processing from this commit hash instead of HEAD~N. Only valid with `num_commits`.
`initial_parent`	No	Set the parent of the first commit when using `commits`. Used to chain multiple onboard runs together. Only valid with `commits`.
`binary_search`	No	Use binary search to minimize builds — builds endpoints first, compares memory fingerprints, and only builds midpoints where changes are detected (default: `false`). Mutually exclusive with `build_dirs`.
`verbose`	No	Logging level: `WARNING`, `INFO`, or `DEBUG` (default: `WARNING`)

Onboarding Specific Commits

Instead of processing the last N commits, you can pass a specific list of commit hashes or tags using the commits input. This is useful for onboarding release versions or specific milestones:

      - name: Historical analysis
        uses: membrowse/membrowse-action/onboard-action@v1
        with:
          commits: "v1.0 v1.1 v2.0 v2.1 v3.0"
          build_script: make all
          elf: build/firmware.elf
          ld: linker.ld
          target_name: my-target
          api_key: ${{ secrets.MEMBROWSE_API_KEY }}

Chaining multiple runs

Use initial_parent to chain runs together. This sets the parent of the first commit, so the commit chain in MemBrowse is continuous across separate onboard runs:

      - name: Onboard v2.x releases
        uses: membrowse/membrowse-action/onboard-action@v1
        with:
          commits: "v2.0 v2.1 v2.2"
          initial_parent: v1.9
          build_script: make all
          elf: build/firmware.elf
          ld: linker.ld
          target_name: my-target
          api_key: ${{ secrets.MEMBROWSE_API_KEY }}

Minimizing Builds with Binary Search

For large histories, use binary_search to reduce the number of builds. It builds the first and last commit, compares their memory fingerprints, and only builds midpoints where changes are detected:

      - name: Historical analysis (binary search)
        uses: membrowse/membrowse-action/onboard-action@v1
        with:
          num_commits: 200
          build_script: make all
          elf: build/firmware.elf
          ld: linker.ld
          target_name: my-target
          api_key: ${{ secrets.MEMBROWSE_API_KEY }}
          binary_search: true

Running the Workflow

Go to your repository on GitHub
Click the Actions tab
Select Onboard to MemBrowse from the left sidebar
Click Run workflow
Enter the number of commits to process (default: 50)
Click Run workflow

The action checks out each historical commit, runs your build script, and uploads the memory report. Commits that fail to build are skipped automatically.

Troubleshooting

Build fails on older commits

The onboarding action checks out each historical commit and runs your build script. Ensure:

All build dependencies are installed in the workflow
The build script works for older commits (watch for renamed files, removed targets, etc.)
The action skips commits that fail to build, so partial results are still uploaded

When to Use This​

Create the Onboard Workflow​

Multiple targets​

Action Reference​

Inputs (membrowse/membrowse-action/onboard-action@v1)​

Onboarding Specific Commits​

Chaining multiple runs​

Minimizing Builds with Binary Search​

Running the Workflow​

Troubleshooting​

Build fails on older commits​