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 pipeline will track every new commit automatically.

Setup

The onboard job uses the spec:inputs system to toggle between normal and onboarding mode. Define the inputs in your .gitlab-ci.yml and forward them to the template include:

spec:
  inputs:
    num-commits:
      default: "50"
      description: "Number of historical commits to process during onboard"
    onboard:
      type: boolean
      default: false
      description: "Run only the onboard job (skips analyze and comment jobs)"
---

include:
  - project: 'membrowse/gitlab-ci'
    ref: v1
    file: '/membrowse.yml'
    inputs:
      num-commits: $[[ inputs.num-commits ]]
      onboard: $[[ inputs.onboard ]]

membrowse-onboard:
  extends: .membrowse-onboard
  image: registry.example.com/my-project/build-image:latest
  variables:
    MEMBROWSE_BUILD_SCRIPT: "./scripts/build.sh"
    MEMBROWSE_ELF: build/firmware.elf
    MEMBROWSE_LD: "linker.ld"
    MEMBROWSE_TARGET_NAME: stm32f4

Image is required

The .membrowse-onboard template does not define a default image. Use an image that has both your build toolchain and Python 3 + pip — typically your existing CI build image.

Running the Onboard Pipeline

1. Go to CI/CD > Pipelines > Run pipeline
2. Set the onboard input to true
3. Optionally adjust num-commits (default: 50)
4. Click Run pipeline

When onboard is true, the analyze and comment jobs are automatically skipped — only the onboard job runs. The job checks out each historical commit, runs your build script, analyzes the ELF, and uploads the report. Commits that fail to build are skipped automatically.

Start small

Each commit requires a full build, so processing many commits takes time. Start with 10-20 commits to verify everything works, then run again with a larger number.

Onboard Variables

Variable	Required	Default	Description
MEMBROWSE_BUILD_SCRIPT	Yes		Shell command to build firmware (e.g., make all)
MEMBROWSE_ELF	Yes		Path to generated ELF file after build
MEMBROWSE_TARGET_NAME	Yes		Target name (must match your regular CI pipeline)
MEMBROWSE_API_KEY	Yes		MemBrowse API key
MEMBROWSE_LD	No		Space-separated linker script paths
MEMBROWSE_LINKER_VARS	No		Space-separated VAR=VALUE definitions
MEMBROWSE_NUM_COMMITS	No	num-commits input	Override number of commits per-job
MEMBROWSE_BUILD_DIRS	No		Space-separated directories that trigger rebuilds
MEMBROWSE_INITIAL_COMMIT	No		Start from this commit hash instead of HEAD~N
MEMBROWSE_API_URL	No	https://api.membrowse.com	API base URL (for self-hosted MemBrowse)

Optimizing Onboard Speed

Use MEMBROWSE_BUILD_DIRS to skip rebuilds for commits that don't touch relevant source directories. Commits with no changes in these directories upload metadata-only reports:

membrowse-onboard:
  extends: .membrowse-onboard
  image: registry.example.com/my-project/build-image:latest
  variables:
    MEMBROWSE_BUILD_SCRIPT: "make all"
    MEMBROWSE_ELF: build/firmware.elf
    MEMBROWSE_TARGET_NAME: stm32f4
    MEMBROWSE_BUILD_DIRS: "src lib"

Use MEMBROWSE_INITIAL_COMMIT to start from a specific commit hash instead of going back N commits from HEAD:

  variables:
    MEMBROWSE_INITIAL_COMMIT: "abc123def456"

Troubleshooting

Build fails on older commits

The onboard job checks out each historical commit and runs your build script. Ensure:

• All build dependencies are installed in your CI image
• The build script works for older commits (watch for renamed files, removed targets, etc.)
• The onboard job skips commits that fail to build, so partial results are still uploaded

Pipeline runs both onboard and analyze jobs

• Ensure your spec:inputs block defines the onboard input and it's forwarded in the include: block (see Setup)
• When onboard is true, the analyze and comment jobs should show as "skipped" in the pipeline