
membrowse
MemBrowse memory tracking integration for embedded firmware projects
- version
- 1.3.0
- GitHub stars
- 49
Install
/plugin install membrowse@membrowse-marketplaceRun it inside Claude Code after adding the marketplace with /plugin marketplace add membrowse/membrowse-action.
Contents
Discovered from sourceSkills 1
MemBrowse Integration Skill
You are integrating MemBrowse memory analysis into a project that produces ELF binaries. This works for both embedded firmware (STM32, ESP32, nRF, RISC-V) and non-embedded targets (Linux x86/x64 applications, game engines, system software). Follow these steps to identify build targets, create the configuration file, set up GitHub workflows, and optionally add a MemBrowse badge to the README.
Step 1: Gather Project Configuration
Before exploring the codebase, gather project-level configuration. Auto-detect what you can, then ask the user only what requires their input.
1.1 Auto-detect submodules and default branch
# Detect submodules (non-empty output means submodules exist)
git submodule status
# Detect default branch
git symbolic-ref refs/remotes/origin/HEAD
1.2 Ask the user
Use AskUserQuestion to ask:
- Is this an open-source project that accepts pull requests from forks? (This determines the workflow pattern — open-source projects need a two-workflow setup so PR comments work for fork PRs.)
Step 2: Explore the Codebase to Identify Build Targets
Understand what the project builds and how.
2.1 Search for Build System Files
Use the Glob tool to find build configuration files:
**/Makefile***/CMakeLists.txt**/*.mk**/meson.build**/Cargo.toml**/platformio.ini
For embedded projects, also search for board/port directories:
**/boards/**/ports/
Check existing CI workflows by reading files in .github/workflows/.
2.2 Analyze Existing CI Workflows
Read existing workflow files to understand:
- What targets are currently built
- What setup commands are used
- Where ELF files are output
2.3 Find Linker Scripts (Embedded Projects)
Linker scripts define memory regions (FLASH, RAM, etc.) and are mainly used in embedded projects. Non-embedded projects typically don't have custom linker scripts — this is fine, MemBrowse will use default Code/Data regions based on ELF sections.
Use the Glob tool to find linker scripts:
**/*.ld**/*.lds
Use the Grep tool to check Makefiles for linker script references:
- Pattern:
LDSCRIPT|\.ld|-TinMakefile*and*.mkfiles
2.4 Find ELF Output Locations
Use the Grep tool to search for ELF references in CI workflow files:
- Pattern:
\.elf|\.out|firmware|build/in.github/workflows/*.yml
Common embedded patterns:
build/firmware.elfbuild-BOARDNAME/firmware.elfbuild/PROJECT_NAME.elf
Common non-embedded patterns:
build/myapp(no extension — usefilecommand to confirm it's ELF)target/release/myapp(Rust)builddir/myapp(Meson)
Step 3: Collect Target Information
For each target you identify, gather:
| Field | Description |
|---|---|
target_name | Unique identifier (e.g., stm32-pybv10, esp32-devkit, linux-x64) |
setup_cmd | Commands to install build dependencies |
build_cmd | Commands to compile the project (include map file generation flags — see below) |
elf | Path to output ELF file after build |
ld | Space-separated linker script paths (can be empty) |
map_file | Path to the generated linker map file (empty if toolchain doesn't support it) |
linker_vars | Optional: variable definitions for linker parsing (e.g., "__flash_size__=4096K") |
partition_table | ESP-IDF targets only (ESP-IDF, Arduino-ESP32, PlatformIO): the build's compiled partition table, so flash is measured against the app partition (see Field Notes) |
partition_name | Optional, with partition_table: the app slot the firmware is flashed to, when the table's app slots differ in size (see Field Notes) |
Generating Map Files
Map files enable archive/object file attribution — MemBrowse can show which .a library or .o object file each symbol comes from. Map files are build artifacts generated by the linker, so the build_cmd must include the appropriate flags.
When constructing build_cmd, check if the project's toolchain supports map file generation and add the flag. Use the Grep tool to inspect Makefiles/CMakeLists.txt for the toolchain and existing linker flags (e.g., LDFLAGS, target_link_options, CMAKE_EXE_LINKER_FLAGS).
Toolchain-specific flags:
| Toolchain | Flag to add | Example map_file path |
|---|---|---|
| GCC / Clang (Make) | -Wl,-Map=path/to/output.map in LDFLAGS | build/firmware.map |
| GCC / Clang (CMake) | -DCMAKE_EXE_LINKER_FLAGS="-Wl,-Map=${PWD}/build/output.map" | build/output.map |
| IAR EWARM | Map files generated by default | Debug/Exe/project.map |
| ESP-IDF | Map file generated by default at build/<project>.map | build/<project>.map |
| Rust (Cargo) | RUSTFLAGS="-C link-args=-Wl,-Map=output.map" | output.map |
How to add map generation to the build command:
- Make-based projects: Check if the Makefile already passes
-Wl,-Mapor has aMAPvariable. If not, append the flag via a Make variable override, e.g.,make BOARD=PYBV10 LDFLAGS_EXTRA="-Wl,-Map=build/firmware.map"— but check that the Makefile actually usesLDFLAGS_EXTRAor an equivalent. If the Makefile doesn't expose a way to add linker flags, the map file may need to be skipped for that target. - CMake projects: Pass
-DCMAKE_EXE_LINKER_FLAGS="-Wl,-Map=${PWD}/build/output.map"at configure time. - ESP-IDF projects: The build system generates a map file automatically at
build/<project_name>.map. No flag changes needed — just set themap_filefield. - IAR projects: Map files are generated by default. Check the project settings for the output path.
If the toolchain doesn't support map file generation or there's no clean way to add the flag to the build command, leave map_file empty — MemBrowse will still work, just without library-level attribution.
Python Version for the Build
Every generated workflow pins Python with actions/setup-python before the build runs (PYTHON_VERSION in the templates). Never leave it floating on the runner's default Python — the runner image changes over time, and build tools such as PlatformIO, pioarduino, ESP-IDF and Zephyr's west only support specific Python versions.
Pick the version in this order:
- The version used by the project's existing CI workflows (
python-version:in.github/workflows/*.yml) - A version declared by the project (
.python-version,requires-pythoninpyproject.toml, or the build tool's documented requirement) - Otherwise
'3.13'— supported by PlatformIO Core (3.9+) and pioarduino (3.10–3.14)
Use one version for all targets. The MemBrowse actions install their own Python for the analysis and do not change the Python your build uses.
Platform-Specific Setup Commands
x86/x64 Linux (non-embedded):
sudo apt-get update && sudo apt-get install -y build-essential
# Add project-specific libraries as needed (e.g., libssl-dev, libffi-dev)
ARM Cortex-M (STM32, SAMD, NXP, etc.):
sudo apt-get update && sudo apt-get install -y gcc-arm-none-eabi libnewlib-arm-none-eabi
ESP32/ESP8266:
# Usually handled by project CI scripts or ESP-IDF setup
. $IDF_PATH/export.sh
RISC-V:
# Check project docs for specific toolchain
sudo apt-get update && sudo apt-get install -y gcc-riscv64-unknown-elf
PlatformIO (including pioarduino):
pip install platformio==6.1.19
Always pin PlatformIO Core to an exact version — never pip install -U platformio or an unpinned pip install platformio. New Core releases can break existing platforms: PlatformIO Core 6.2.0 breaks pioarduino and other ESP-IDF-based builds at link time with ModuleNotFoundError: No module named 'SCons.Tool.FortranCommon'. Use the version the project's existing CI pins; otherwise use the version that built successfully in Step 5 (pio --version), or 6.1.19.
Build with pio run -e <env>; the ELF is written to .pio/build/<env>/firmware.elf. PlatformIO installs toolchains on first build, so no apt packages are usually needed.
Step 4: Ask User to Confirm Targets
Before building or verifying anything, present the discovered targets to the user for a quick sanity check. For each target, show:
- Target name
- Setup command
- Build command
- ELF output path
- Linker script path(s) (or "none — will use default Code/Data regions")
- Map file path (if build command generates one — enables library/object attribution)
Ask the user:
- Which targets should be included?
- Are the build commands and paths correct?
- Any missing setup commands?
This catches obvious mistakes before investing time in Step 5 (local verification).
Step 5: Verify Targets Locally
Before adding targets to the configuration file, verify each target end-to-end: build succeeds, ELF is found, and membrowse report produces valid output.
Note: If the required toolchain (e.g., gcc-arm-none-eabi, ESP-IDF) is not available locally, skip this step and defer verification to CI. Proceed to Step 6 and let the first workflow run validate the configuration. If the build is straightforward and the toolchain is available, local verification is strongly recommended — it catches issues much faster than round-tripping through CI.
5.1 Install membrowse
pip install membrowse # if not already installed
5.2 Build and Verify ELF
For each target, run the build command and confirm the ELF file exists:
# Run the build
make clean && make BOARD=PYBV10 # embedded example
cmake -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo && cmake --build build # non-embedded example
# Confirm the ELF file exists
ls -la build/firmware.elf # embedded
file build/myapp # non-embedded — confirm "ELF" in output
If the ELF is not found, check the build output for the actual output path.
5.3 Run membrowse report
Run membrowse report on the built ELF to verify the full analysis pipeline. This is the single most important verification step — it catches bad ELF paths, unparseable linker scripts, missing linker variables, and unsupported binary formats all at once.
With linker scripts (embedded):
membrowse report path/to/firmware.elf "path/to/linker.ld"
Without linker scripts (non-embedded or no custom layout):
membrowse report path/to/binary
With map file (for library/object attribution):
membrowse report path/to/firmware.elf "path/to/linker.ld" --map-file path/to/output.map
With linker variable definitions:
membrowse report path/to/firmware.elf "path/to/linker.ld" --def __flash_size__=4096K
What to check in the output
The human-readable output should show:
- Memory regions — either parsed from linker scripts (e.g., FLASH, RAM) or default Code/Data regions
- Usage percentages — non-zero usage for at least some regions
- No errors — if there are parsing errors or warnings, fix them before proceeding
To inspect the full JSON output (useful for debugging):
membrowse report path/to/firmware.elf "path/to/linker.ld" --json
Check that the JSON contains:
memory_regionswith non-zerousedvaluessymbolsarray (non-empty if built with-gdebug symbols)sectionsarray with expected ELF sections (.text,.data,.bss, etc.)
Common issues at this step
- Linker parse error with undefined variable: Add the variable via
--def VAR=VALUE. Note the value for thelinker_varsfield in targets.json. - Linker script not found: The path may be relative to a subdirectory or generated during build — check the build directory.
- No symbols in output: Binary was built without debug info. Add
-gto compiler flags or use-DCMAKE_BUILD_TYPE=RelWithDebInfo. Sections and regions will still work, but source file attribution requires debug symbols. - "Unsupported binary format": The file is not ELF. Use
file path/to/binaryto check. Look for the intermediate ELF before anyobjcopyconversion. - Zero usage in all regions: The linker scripts may define regions that don't match the ELF sections. Try running without linker scripts first (
membrowse report path/to/elf) to see default Code/Data analysis, then compare.
If you cannot resolve a failure after trying the common fixes above, stop and ask the user for help using AskUserQuestion before proceeding. Do not skip a failing target or move on to creating configuration files with unverified targets.
5.4 Ask User to Verify
Show the user the full human-readable membrowse report output for each target. This is the concrete proof that the target configuration works — memory regions, usage percentages, and any warnings are all visible here.
Ask the user to confirm:
- Does the memory report output look reasonable for each target?
- Are the memory regions and usage percentages correct?
- If symbols are missing, is that expected (no
-gflag)?
Only proceed to create the configuration file after the user approves the membrowse report output.
Step 6: Create membrowse-targets.json
Create .github/membrowse-targets.json with the verified targets. The file is a flat JSON array — each element is one target.
Embedded example (with map file):
[
{
"target_name": "stm32-pybv10",
"setup_cmd": "sudo apt-get update && sudo apt-get install -y gcc-arm-none-eabi",
"build_cmd": "make -C ports/stm32 BOARD=PYBV10 LDFLAGS_EXTRA=\"-Wl,-Map=build-PYBV10/firmware.map\"",
"elf": "ports/stm32/build-PYBV10/firmware.elf",
"ld": "ports/stm32/boards/stm32f405.ld",
"map_file": "ports/stm32/build-PYBV10/firmware.map",
"linker_vars": ""
}
]
Non-embedded example (CMake with map file):
[
{
"target_name": "linux-x64",
"setup_cmd": "sudo apt-get update && sudo apt-get install -y build-essential",
"build_cmd": "cmake -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_EXE_LINKER_FLAGS=\"-Wl,-Map=$PWD/build/myapp.map\" && cmake --build build",
"elf": "build/myapp",
"ld": "",
"map_file": "build/myapp.map",
"linker_vars": ""
}
]
ESP-IDF example (map file generated by default):
[
{
"target_name": "esp32",
"setup_cmd": ". $IDF_PATH/export.sh",
"build_cmd": "idf.py build",
"elf": "build/project_name.elf",
"ld": "build/esp-idf/esp_system/ld/memory.ld build/esp-idf/esp_system/ld/sections.ld",
"map_file": "build/project_name.map",
"linker_vars": "",
"partition_table": "build/partition_table/partition-table.bin"
}
]
Field Notes
-
target_name: Must be unique across targets, used as the target identifier in MemBrowse -
elf: Path to any ELF binary — embedded firmware (.elf) or non-embedded executables/shared libraries (no extension or.so) -
ld: Space-separated linker script paths for embedded projects; empty string""for non-embedded (analysis will use default Code/Data regions based on ELF sections like.text,.data,.bss) -
map_file: Path to the linker map file generated by the build command; empty string""if the build doesn't produce one. Must match the path used in the-Wl,-Map=flag inbuild_cmd. Supports GNU LD and IAR EWARM formats. -
linker_vars: Only needed if linker scripts use undefined variables (e.g.,"__flash_size__=4096K"); leave empty for non-embedded -
partition_table: Set it for every ESP-IDF-based target (plain ESP-IDF, Arduino-ESP32, PlatformIO with either framework; the ELF has a.flash.appdescsection). The ESP-IDF linker scripts describe the MMU windows the CPU sees flash through (4 MB on the ESP32, up to 64 MB on the P4), not the space the app has, so without it flash use is shown far too low. With it, the window regions are replaced by oneapp_partitionregion measured against the smallest app slot, holding the image exactly as esptool writes it. Use the compiled table, not the CSV:build/partition_table/partition-table.binforidf.py,.pio/build/<env>/partitions.binfor PlatformIO.ldmust listmemory.ld, plussections.ldwhere the framework has one:idf.py:build/esp-idf/esp_system/ld/memory.ld build/esp-idf/esp_system/ld/sections.ld.- PlatformIO, Arduino-ESP32 3.x:
~/.platformio/packages/framework-arduinoespressif32-libs/<chip>/ld/memory.ldandsections.ld(<chip>isesp32,esp32s3,esp32c6, ...). - PlatformIO, Arduino-ESP32 2.x:
~/.platformio/packages/framework-arduinoespressif32/tools/sdk/<chip>/ld/memory.ld, plussections.ldwhen present (2.0.17 has none for the S3;memory.ldalone is enough). - PlatformIO,
framework = espidf: thememory.ld/sections.ldgenerated under.pio/build/<env>/esp-idf/esp_system/ld/.
Check the build's log or map file for which framework package (and version) the env really used.
ldpaths are not shell-expanded (no~), so copy files from outside the repo next to the ELF at the end ofbuild_cmdand list those copies. Setpartition_tablefrom a target's first report on: adding it to a target already on MemBrowse changes its regions. Omit the field for other targets. -
partition_name: The report measures against the smallest app slot (ESP-IDF's own rule: an OTA image must fit every slot). That is right forfactory+ equalota_Nslots, but some tables keep a small slot for a different app, e.g. meshtastic's 640 KBflashApp(an OTA loader) next to its 2.3 MBapp; against it the firmware shows as 356% full. When the compiled table's app slots differ in size (the report logs a warning), setpartition_nameto the slot the firmware is flashed to: theota_0slot (PlatformIO's rule,app/app0in most tables) orfactorywhen there is no OTA slot. Leave it empty otherwise. -
setup_cmd: Commands to install build dependencies before building (skill-specific; the workflow runs this before the build step) -
build_cmd: Use-gor-DCMAKE_BUILD_TYPE=RelWithDebInfoto include debug symbols — this lets MemBrowse attribute memory to source files and symbols
Step 7: Create GitHub Workflows
Based on the project type identified in Step 1, create workflows in .github/workflows/.
Choose the appropriate pattern:
- Pattern A (Single target, private repo): One workflow with inline build and analysis
- Pattern B (Multiple targets, private repo): One workflow with matrix build + comment job
- Pattern C (Open-source / fork PRs): Two workflows — report + comment via
workflow_run
Zephyr Projects: Checkout in a Subdirectory
Zephyr projects often check out the repository into a subdirectory so the west workspace can sit around it (e.g. actions/checkout with path: <app>, used with zephyrproject-rtos/action-zephyr-setup and app-path: <app>). Check the project's existing CI for this. The MemBrowse action runs git from the workspace root ($GITHUB_WORKSPACE). When the checkout is in a subdirectory, the root is not a git repository and every git call fails silently. The report still uploads, but without commit message, author, tags or ancestry.
When the checkout uses path:, set GIT_DIR and GIT_WORK_TREE on the MemBrowse step, relative to the workspace root, and prefix the elf, ld and map_file paths with the same directory:
- name: Analyze memory
uses: membrowse/membrowse-action@v1
# The checkout lives under <app>/, but action steps run from the
# workspace root. Point git at the checkout so MemBrowse reads the
# commit message and author from it.
env:
GIT_DIR: <app>/.git
GIT_WORK_TREE: <app>
with:
elf: <app>/build/zephyr/zephyr.elf
ld: <app>/build/zephyr/linker.cmd
map_file: <app>/build/zephyr/zephyr.map
# ...
Use relative paths, not ${{ github.workspace }}: in container jobs github.workspace gives the host path, which does not exist inside the container. A container job also needs git config --global --add safe.directory '*' before this step, or git refuses the checkout because a different user owns it.
Zephyr builds produce zephyr.elf, the linker script linker.cmd and zephyr.map in <build-dir>/zephyr/. With sysbuild they are in <build-dir>/<app-name>/zephyr/.
Pattern A: Single Target, Private Repo
Create one workflow file: membrowse.yml
Use this when there is only one target and the repo does not accept fork PRs.
name: MemBrowse Memory Report
on:
pull_request:
push:
branches:
- main # Change to match the project's default branch
permissions:
contents: read
pull-requests: write
concurrency:
group: ${{ github.workflow }}-${{ github.event_name == 'push' && github.sha || github.ref }}
cancel-in-progress: ${{ github.event_name == 'pull_request' }}
jobs:
analyze:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v5
with:
fetch-depth: 2
# Only include submodules line if user confirmed submodules in Step 1
# submodules: recursive
- name: Set up Python
uses: actions/setup-python@v6
with:
python-version: 'PYTHON_VERSION'
- name: Install packages
run: |
# TARGET_SETUP_CMD goes here
- name: Build
run: |
# TARGET_BUILD_CMD goes here
# For non-embedded: e.g., cmake -B build && cmake --build build
# For embedded: e.g., make -C ports/stm32 BOARD=PYBV10
- name: Run MemBrowse analysis
uses: membrowse/membrowse-action@v1
with:
target_name: TARGET_NAME
elf: TARGET_ELF
ld: TARGET_LD
# Only include map_file if the target has a map file
# map_file: TARGET_MAP_FILE
# Only include linker_vars if the target has linker_vars values
# linker_vars: TARGET_LINKER_VARS
api_key: ${{ secrets.MEMBROWSE_API_KEY }}
api_url: ${{ vars.MEMBROWSE_API_URL }}
verbose: INFO
# Uncomment to allow CI to pass even when memory budgets are exceeded
# dont_fail_on_alerts: true
- name: Post PR comment
if: github.event_name == 'pull_request'
uses: membrowse/membrowse-action/comment-action@v1
with:
api_key: ${{ secrets.MEMBROWSE_API_KEY }}
api_url: ${{ vars.MEMBROWSE_API_URL }}
commit: ${{ github.event.pull_request.head.sha }}
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
Template substitutions: Replace TARGET_NAME, TARGET_SETUP_CMD, TARGET_BUILD_CMD, TARGET_ELF, TARGET_LD, TARGET_MAP_FILE, and TARGET_LINKER_VARS with values from the single target in membrowse-targets.json. Since there's only one target, values are inlined directly. Replace PYTHON_VERSION in every template as described in Python Version for the Build.
Pattern B: Multiple Targets, Private Repo
Create one workflow file: membrowse.yml
Use this when there are multiple targets and the repo does not accept fork PRs.
name: MemBrowse Memory Report
on:
pull_request:
push:
branches:
- main # Change to match the project's default branch
permissions:
contents: read
pull-requests: write
concurrency:
group: ${{ github.workflow }}-${{ github.event_name == 'push' && github.sha || github.ref }}
cancel-in-progress: ${{ github.event_name == 'pull_request' }}
jobs:
load-targets:
runs-on: ubuntu-latest
outputs:
matrix: ${{ steps.set-matrix.outputs.matrix }}
steps:
- name: Checkout repository
uses: actions/checkout@v5
- name: Load target matrix
id: set-matrix
run: echo "matrix=$(jq -c '.' .github/membrowse-targets.json)" >> $GITHUB_OUTPUT
analyze:
needs: load-targets
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
include: ${{ fromJson(needs.load-targets.outputs.matrix) }}
steps:
- name: Checkout repository
uses: actions/checkout@v5
with:
fetch-depth: 2
# Only include submodules line if user confirmed submodules in Step 1
# submodules: recursive
- name: Set up Python
uses: actions/setup-python@v6
with:
python-version: 'PYTHON_VERSION'
- name: Install packages
run: ${{ matrix.setup_cmd }}
- name: Build
run: ${{ matrix.build_cmd }}
- name: Run MemBrowse analysis
uses: membrowse/membrowse-action@v1
with:
target_name: ${{ matrix.target_name }}
elf: ${{ matrix.elf }}
ld: ${{ matrix.ld }}
map_file: ${{ matrix.map_file }}
linker_vars: ${{ matrix.linker_vars }}
partition_table: ${{ matrix.partition_table }}
partition_name: ${{ matrix.partition_name }}
api_key: ${{ secrets.MEMBROWSE_API_KEY }}
api_url: ${{ vars.MEMBROWSE_API_URL }}
verbose: INFO
# Uncomment to allow CI to pass even when memory budgets are exceeded
# dont_fail_on_alerts: true
comment:
needs: analyze
if: github.event_name == 'pull_request'
runs-on: ubuntu-latest
steps:
- name: Post combined PR comment
if: ${{ env.MEMBROWSE_API_KEY != '' }}
uses: membrowse/membrowse-action/comment-action@v1
with:
api_key: ${{ secrets.MEMBROWSE_API_KEY }}
api_url: ${{ vars.MEMBROWSE_API_URL }}
commit: ${{ github.event.pull_request.head.sha }}
env:
MEMBROWSE_API_KEY: ${{ secrets.MEMBROWSE_API_KEY }}
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
Pattern C: Open Source / Fork PRs
Create two workflow files: membrowse-report.yml and membrowse-comment.yml
Use this when the project accepts PRs from forks. Fork PRs don't have access to secrets, so the report workflow uploads data to the MemBrowse API, and a separate workflow_run-triggered workflow fetches the summary and posts the PR comment.
membrowse-report.yml
name: MemBrowse Memory Report
on:
pull_request:
push:
branches:
- main # Change to match the project's default branch
concurrency:
group: ${{ github.workflow }}-${{ github.event_name == 'push' && github.sha || github.ref }}
cancel-in-progress: ${{ github.event_name == 'pull_request' }}
jobs:
load-targets:
runs-on: ubuntu-latest
outputs:
matrix: ${{ steps.set-matrix.outputs.matrix }}
steps:
- name: Checkout repository
uses: actions/checkout@v5
- name: Load target matrix
id: set-matrix
run: echo "matrix=$(jq -c '.' .github/membrowse-targets.json)" >> $GITHUB_OUTPUT
analyze:
needs: load-targets
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
include: ${{ fromJson(needs.load-targets.outputs.matrix) }}
steps:
- name: Checkout repository
uses: actions/checkout@v5
with:
fetch-depth: 2
# Only include submodules line if user confirmed submodules in Step 1
# submodules: recursive
- name: Set up Python
uses: actions/setup-python@v6
with:
python-version: 'PYTHON_VERSION'
- name: Install packages
run: ${{ matrix.setup_cmd }}
- name: Build
run: ${{ matrix.build_cmd }}
- name: Run MemBrowse analysis
uses: membrowse/membrowse-action@v1
with:
target_name: ${{ matrix.target_name }}
elf: ${{ matrix.elf }}
ld: ${{ matrix.ld }}
map_file: ${{ matrix.map_file }}
linker_vars: ${{ matrix.linker_vars }}
partition_table: ${{ matrix.partition_table }}
partition_name: ${{ matrix.partition_name }}
# Fork PRs cannot read repository secrets, so api_key is empty there.
# That is fine: for PRs to public repositories the action uploads the
# report tokenless, so no API key is needed. The key is only used for
# push events and same-repo PRs.
api_key: ${{ secrets.MEMBROWSE_API_KEY }}
api_url: ${{ vars.MEMBROWSE_API_URL }}
verbose: INFO
# Uncomment to allow CI to pass even when memory budgets are exceeded
# dont_fail_on_alerts: true
membrowse-comment.yml
IMPORTANT: The workflows: value below must exactly match the name: field of the report workflow above (MemBrowse Memory Report). If they don't match, the comment workflow will never trigger.
name: MemBrowse PR Comment
on:
workflow_run:
workflows: [MemBrowse Memory Report]
types:
- completed
jobs:
comment:
runs-on: ubuntu-latest
# Run even if some builds failed — but skip cancelled runs and skipped runs
# (e.g. draft PRs, where nothing is built or uploaded, so the summary lookup
# would 404 on a commit with no report).
if: >
github.event.workflow_run.event == 'pull_request' &&
github.event.workflow_run.conclusion != 'cancelled' &&
github.event.workflow_run.conclusion != 'skipped'
permissions:
contents: read
pull-requests: write
steps:
- name: Checkout repository
uses: actions/checkout@v5
- name: Post combined PR comment
if: ${{ env.MEMBROWSE_API_KEY != '' }}
uses: membrowse/membrowse-action/comment-action@v1
with:
api_key: ${{ secrets.MEMBROWSE_API_KEY }}
api_url: ${{ vars.MEMBROWSE_API_URL }}
commit: ${{ github.event.workflow_run.head_sha }}
env:
MEMBROWSE_API_KEY: ${{ secrets.MEMBROWSE_API_KEY }}
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
Onboard Workflow (All Patterns)
Always create a separate membrowse-onboard.yml workflow for historical analysis:
name: Onboard to MemBrowse
on:
workflow_dispatch:
inputs:
num_commits:
description: 'Number of commits to process'
required: true
default: '100'
type: string
jobs:
load-targets:
runs-on: ubuntu-latest
outputs:
matrix: ${{ steps.set-matrix.outputs.matrix }}
steps:
- name: Checkout repository
uses: actions/checkout@v5
- name: Load target matrix
id: set-matrix
run: echo "matrix=$(jq -c '.' .github/membrowse-targets.json)" >> $GITHUB_OUTPUT
onboard:
needs: load-targets
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
include: ${{ fromJson(needs.load-targets.outputs.matrix) }}
steps:
- name: Checkout repository
uses: actions/checkout@v5
with:
# Onboard iterates through historical commits, so it needs full history
fetch-depth: 0
# Only include submodules line if user confirmed submodules in Step 1
# submodules: recursive
- name: Set up Python
uses: actions/setup-python@v6
with:
python-version: 'PYTHON_VERSION'
- name: Install packages
run: ${{ matrix.setup_cmd }}
- name: Run MemBrowse Onboard Action
uses: membrowse/membrowse-action/onboard-action@v1
with:
target_name: ${{ matrix.target_name }}
num_commits: ${{ github.event.inputs.num_commits }}
build_script: ${{ matrix.build_cmd }}
elf: ${{ matrix.elf }}
ld: ${{ matrix.ld }}
map_file: ${{ matrix.map_file }}
linker_vars: ${{ matrix.linker_vars }}
partition_table: ${{ matrix.partition_table }}
partition_name: ${{ matrix.partition_name }}
binary_search: 'true'
api_key: ${{ secrets.MEMBROWSE_API_KEY }}
api_url: ${{ vars.MEMBROWSE_API_URL }}
Step 8: Inform User About Secrets and Variables
After creating the files, tell the user they need to configure:
-
Repository Secret:
MEMBROWSE_API_KEY— API key from the MemBrowse dashboardLocation: Repository Settings → Secrets and variables → Actions → New repository secret
-
Repository Variable (optional):
MEMBROWSE_API_URL— custom API URL if not using the default (https://api.membrowse.com)Location: Repository Settings → Secrets and variables → Actions → Variables → New repository variable
Step 9: Provide Testing Instructions
Tell the user how to test:
- Test Report Workflow: Create a PR to trigger the report workflow
- Test Onboard Workflow: Go to Actions → "Onboard to MemBrowse" → Run workflow (start with 10 commits)
- Verify PR Comments: After the report workflow completes, check the PR for a memory usage comment
Step 10: Add MemBrowse Badge to README (Optional)
Before adding a badge, ask the user:
- Is this project open source, or do you have public access enabled in the MemBrowse portal?
If the project is private and public access is not enabled, skip the badge — it will return a 404. Inform the user they can enable public access later in Project Settings on the MemBrowse portal.
10.1 Find the README File
Use the Glob tool to find README files:
README*readme*
10.2 Determine the Badge URL
The badge URL format is:
[](https://membrowse.com/public/{owner}/{repo})
Get the owner and repo name from the git remote:
git remote get-url origin
Parse the URL to extract {owner}/{repo} (e.g., micropython/micropython).
10.3 Add the Badge
Add the badge near the top of the README, typically:
- After the main title/heading
- Alongside other badges if present
- Before the project description
Example placement:
# Project Name
[](https://membrowse.com/public/owner/repo)
Project description here...
If other badges exist, add it inline:
# Project Name
[](...)
[](...)
[](https://membrowse.com/public/owner/repo)
10.4 Ask User for Confirmation
Before modifying the README:
- Show the user the badge that will be added
- Ask where they want it placed (if multiple badge locations exist)
- Confirm the owner/repo extracted from git remote is correct
- Remind them that public access must be enabled in MemBrowse Project Settings for the badge to work
Next Steps
After the integration is working, mention these optional features the user can explore:
- Memory budgets: Set RAM/Flash budgets in the MemBrowse portal. PRs that exceed budgets will show alerts. Use
dont_fail_on_alerts: truein the action to prevent CI failure on budget alerts. - Onboard options: The onboard action supports
build_dirs(only rebuild when specific directories change) andinitial_commit(start from a specific commit hash). - Skip unchanged commits: Use the
identicalinput with a paths-filter action to skip MemBrowse analysis on commits that don't touch source code (e.g., docs-only changes). - Custom PR comment template: Use
comment_templatein the comment action to customize the PR comment format with a Jinja2 template. - Quiet PRs: Set
skip_unchanged: truein the comment action to post no comment on PRs that change no memory region and trigger no budget alert. An existing MemBrowse comment is still updated.
Troubleshooting Reference
Symbols not appearing in report
Ensure the binary is compiled with debug symbols (-g flag, or -DCMAKE_BUILD_TYPE=RelWithDebInfo for CMake). Without debug info, MemBrowse can still report section-level usage but cannot attribute memory to individual source files and symbols.
PR comments not appearing
- Permissions: Ensure the workflow has
pull-requests: writepermission. - Open-source projects: Fork PRs cannot write comments directly. Use the two-workflow pattern (Pattern C) with
workflow_run. - Workflow name mismatch: In Pattern C, the
workflows:value inmembrowse-comment.ymlmust exactly match thename:field inmembrowse-report.yml(i.e.,"MemBrowse Memory Report").
API key issues
- Verify the secret is named exactly
MEMBROWSE_API_KEYin repository settings. - Fork PRs do not have access to repository secrets, so
api_keyis empty in those runs. For PRs to public repositories the action uploads the report tokenless, so no API key is needed there. Theworkflow_runcomment workflow then posts the comment from the base repo context, where the secret is available.
Git metadata missing
Ensure fetch-depth: 2 is set on the checkout step for report workflows (the parent commit is needed for diff metadata). The onboard workflow needs fetch-depth: 0 since it iterates through historical commits. With too little history, MemBrowse cannot detect branch and commit metadata correctly.
If the commit SHA and branch are present but the commit message, author and tags are empty, the repository is probably checked out into a subdirectory (actions/checkout with path:, common in Zephyr/west projects). Set GIT_DIR and GIT_WORK_TREE on the MemBrowse step. See Zephyr Projects: Checkout in a Subdirectory.
Unsupported binary format
MemBrowse requires ELF binaries. If your build produces .bin, .hex, or other non-ELF formats, locate the intermediate ELF file (usually in the build directory before the final conversion step). For non-embedded projects, the output binary is typically already ELF — verify with file path/to/binary (should show "ELF").
Builds fail in CI
- Ensure all dependencies are in
setup_cmd - If the build tool rejects the Python version (common with PlatformIO/pioarduino and ESP-IDF), change
python-versionin theSet up Pythonstep of the report and onboard workflows No module named 'SCons.Tool.FortranCommon'in a PlatformIO build: PlatformIO Core is too new for the platform. Pin an exact Core version insetup_cmd(e.g.pip install platformio==6.1.19)- Check if submodules need
submodules: recursiveon the checkout step - Verify paths are relative to repository root
Linker parsing fails
- Add required variables to
linker_varsinmembrowse-targets.json - Check linker scripts exist at the specified paths (some are generated during build)
- Empty
ldfield is valid — analysis will use default Code/Data regions
Sponsors
Details
- Marketplace
- membrowse/membrowse-action
- Source
- membrowse/membrowse-action
- Category
- Community