Skip to main content

Setup

Add MemBrowse to your existing GitHub Actions workflow. If you already build your firmware in CI, this takes just a few minutes.

AI-assisted setup

If you use Claude Code, install the MemBrowse plugin and run the integration skill:

/plugin marketplace add membrowse/membrowse-action
/plugin install membrowse@membrowse-marketplace
/membrowse:membrowse-integrate

This will analyze your build system, verify your ELF outputs and linker scripts, create membrowse-targets.json, and set up all GitHub Actions workflows.

Prerequisites​

  • GitHub repository with your firmware project
  • ELF file output from your build
  • Linker script(s) defining memory regions (optional but recommended for accurate region tracking)
  • MemBrowse API key (from Project Settings)

Step 1: Add API Key to Secrets​

  1. Go to your GitHub repository
  2. Navigate to Settings > Secrets and variables > Actions
  3. Click New repository secret
  4. Name: MEMBROWSE_API_KEY
  5. Value: Your API key from Project Settings

Step 2: Update Workflow Triggers and Permissions​

Your workflow needs to run on both pushes to main and pull requests. Add pull-requests: write so MemBrowse can post PR comments, and a concurrency group to cancel outdated runs when new commits are pushed:

on:
pull_request:
push:
branches:
- main

permissions:
contents: read
pull-requests: write

concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true

Also make sure your checkout step uses fetch-depth: 2 so MemBrowse can read the commit's metadata and its parent. The action fetches any further history it needs on its own:

      - uses: actions/checkout@v5
with:
fetch-depth: 2

Step 3: Add MemBrowse Steps​

Add these steps after your build step. The continue-on-error: true ensures that a MemBrowse issue never blocks your CI pipeline:

      - name: Analyze memory
id: analyze
continue-on-error: true
uses: membrowse/membrowse-action@v1
with:
elf: build/firmware.elf # Path to your ELF file
ld: linker.ld # Path to your linker script(s)
target_name: my-target # Name for this build target
api_key: ${{ secrets.MEMBROWSE_API_KEY }}

- name: Post PR comment
if: ${{ !cancelled() && steps.analyze.outputs.report_path != '' && github.event_name == 'pull_request' }}
continue-on-error: true
uses: membrowse/membrowse-action/comment-action@v1
with:
api_key: ${{ secrets.MEMBROWSE_API_KEY }}
commit: ${{ github.event.pull_request.head.sha }}
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

That's it. Every push to main uploads a report to the MemBrowse Portal, and every PR gets a comment showing the memory impact.

MemBrowse updates existing comments instead of creating new ones, so each push to a PR updates the same comment rather than creating noise.

Failing CI on Budget Alerts​

The analysis step fails when a budget is exceeded, but continue-on-error: true stops that failure from failing the job. The report is still uploaded and the PR comment still shows the alert.

To make exceeded budgets fail CI, remove continue-on-error: true from the analysis step. The report_path condition on the comment step means the comment is still posted when the budget check fails, and skipped when no report was uploaded.

Skipping Builds for Non-Source Commits​

Not every commit affects your firmware. Documentation changes, CI config updates, or README edits don't change the ELF output, so there's no point rebuilding and re-analyzing. You can still give these commits memory data in the MemBrowse Portal.

Use identical: true to upload just the commit metadata without running a build or ELF analysis. MemBrowse records the commit and links it to the previous report's memory data.

A common pattern is to detect whether source files changed and conditionally skip the build:

      - name: Check for source changes
id: changes
uses: dorny/paths-filter@v3
with:
filters: |
firmware:
- 'src/**'
- 'lib/**'
- 'Makefile'
- '*.ld'

- name: Build firmware
if: steps.changes.outputs.firmware == 'true'
run: make all

- name: Analyze memory
id: analyze
continue-on-error: true
uses: membrowse/membrowse-action@v1
with:
elf: build/firmware.elf
ld: linker.ld
target_name: my-target
api_key: ${{ secrets.MEMBROWSE_API_KEY }}
identical: ${{ steps.changes.outputs.firmware != 'true' }}

When identical is true, elf is not required — no build output is needed.

If a commit gets no upload at all, it has no report in the portal. The next upload is compared against its nearest ancestor that has a report for that target.

Analysis Options​

These optional inputs change what MemBrowse measures and how it reports it. They work the same way on the action and on the onboard action.

Archive and Object Attribution (map_file)​

Pass your linker map file to see which .a library and .o object file each symbol comes from. The portal's Symbols view then adds an Archive column and filter. GNU LD, LLD and IAR map files are supported.

          map_file: build/firmware.map

The map file has to exist when the action runs. With GCC or Clang, generate it by adding -Wl,-Map=build/firmware.map to your linker flags. IAR and ESP-IDF generate one by default.

Real Region Sizes for Inflated Builds (limits)​

Some projects link with inflated region sizes, so the link still succeeds when the binary exceeds the real capacity of the target. Use limits to point at a linker script holding the real LENGTH of each region:

          ld: build/inflated.ld
limits: boards/my-board/real-memory.ld

Sections are still assigned to regions using ld, while utilization and overflow are reported against the sizes in limits. Regions must have the same ORIGIN in both scripts, otherwise the analysis fails. limits requires ld. Leave it out when the binary fits, because ld is already the real limit.

Excluding Alignment Padding (exclude_alignment)​

Padding from explicit . = ALIGN(n) statements can make usage jump when a small code change crosses an alignment boundary. Set exclude_alignment: true to leave that padding out, so usage and PR diffs follow the real code and data size:

          exclude_alignment: true
map_file: build/firmware.map # Recommended, see below

The padding is measured exactly with a GNU LD or LLD map file. Without one, it's estimated from ELF symbols. Turning this on lowers the reported usage from that commit onward, which shows as a one-time drop in your history.

Excluding Sections (skip_sections)​

List ELF sections to leave out of the report. Names must match exactly. Skipped sections don't count toward any region's usage, and their symbols are removed from the report:

          skip_sections: .noinit .user_data

Linker Script Include Directories (ld_include_dirs)​

If a linker script uses INCLUDE for a file that isn't next to it, list the directories to search. These are the directories you pass to the linker with -L. For example, pico-sdk 2.3 keeps its MEMORY block in an .incl file found this way:

          ld_include_dirs: build/ld-includes

Repository-Relative Source Paths (source_root)​

By default, symbols' source files are reported by basename, such as uart.c. Set source_root to report files under that directory by their relative path, such as src/drivers/uart.c. It's typically the checkout:

          source_root: .

Files outside the directory are still reported by basename. MemBrowse uses the source file as part of a symbol's identity, so the first upload after turning this on shows your in-repo symbols as moved.

Special Environments​

Container Jobs​

In a job with container:, the action doesn't install Python, so the image must include Python and pip. To post PR comments, it also needs the GitHub CLI (gh); without it, the comment action logs a warning and skips the comment.

Outside containers, the action installs its own Python without changing the version your build uses.

Checkout in a Subdirectory​

The action runs git from the workspace root. If you check out into a subdirectory with path:, as many Zephyr projects do, the root isn't a git repository. The report still uploads, but without the commit message, author, tags or ancestry.

Set GIT_DIR and GIT_WORK_TREE on the MemBrowse step, relative to the workspace root, and prefix the file paths with the same directory:

      - name: Analyze memory
uses: membrowse/membrowse-action@v1
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
target_name: my-target
api_key: ${{ secrets.MEMBROWSE_API_KEY }}

Use relative paths rather than ${{ github.workspace }}, because in container jobs that expression gives a host path that doesn't exist inside the container. A container job also needs git config --global --add safe.directory '*' before this step.

Action Reference​

Inputs (membrowse/membrowse-action@v1)​

InputRequiredDescription
elfNoPath to ELF file. Not required when identical=true.
ldNoPath to linker script(s), space-separated. Supports GNU LD, IAR ICF, Keil scatter and SEGGER .emProject files. If omitted, MemBrowse uses default Code/Data regions based on ELF section flags.
target_nameYesName for this build target
api_keyNoMemBrowse API key. Not required for tokenless PR uploads in open-source projects.
api_urlNoMemBrowse API base URL (default: https://api.membrowse.com)
linker_varsNoLinker script variable definitions, space-separated (e.g., __flash_size__=4096K __ram_size__=256K)
map_fileNoLinker map file for archive and object attribution
limitsNoLinker script with the real region sizes, for builds linked with inflated regions
exclude_alignmentNoLeave out ALIGN padding (default: false)
skip_sectionsNoSpace-separated ELF section names to exclude
ld_include_dirsNoSpace-separated directories to search for linker script INCLUDE files
source_rootNoDirectory that source files are reported relative to
dont_fail_on_alertsNoDon't exit with failure on budget alerts (default: false)
verboseNoLogging level: WARNING, INFO, or DEBUG (default: INFO)
pr_author_nameNoPR author name (auto-detected from GitHub event if not provided)
pr_author_emailNoPR author email (auto-detected from GitHub event if not provided)
identicalNoMetadata-only upload, skip ELF analysis (default: false)

Outputs​

OutputDescription
report_pathFile path to the generated JSON report file. Also set when the step fails on a budget alert. Empty if no report was uploaded.

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

The comment-action needs GH_TOKEN in its environment and supports two modes:

  • Summary mode (recommended) fetches per-target summaries from the MemBrowse API. It needs no report files, and its comment header links to the dashboard ("Explore what changed").
  • File mode reads local JSON report files, and needs no API key. Its comment has no dashboard link in the header.
InputRequiredDescription
api_keyNoMemBrowse API key. When provided with commit, enables summary mode.
commitNoCommit SHA to fetch summary for. Requires api_key.
json_filesNoSpace-separated list of JSON report file paths or glob pattern (e.g., reports/*.json). Used in file mode.
pr_numberNoPR number to post comment on. Resolved automatically if not provided.
api_urlNoMemBrowse API base URL (default: https://api.membrowse.com)
comment_templateNoPath to a custom Jinja2 template file for comment formatting. See template variables. The template must exist in the job's workspace, so check out your repository first.
footerNoAppend the MemBrowse footer to the comment (default: true)
verboseNoLogging level: WARNING, INFO, or DEBUG (default: WARNING)

Either json_files or both api_key + commit must be provided.

To use file mode, pass the analysis step's output to the comment-action:

      - name: Post PR comment
if: ${{ !cancelled() && steps.analyze.outputs.report_path != '' && github.event_name == 'pull_request' }}
uses: membrowse/membrowse-action/comment-action@v1
with:
json_files: ${{ steps.analyze.outputs.report_path }}
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

For more details, see the membrowse-action repository.

Troubleshooting​

Analysis step fails​

  • Verify the elf and ld paths are correct relative to the repository root
  • Ensure the build step actually produces the ELF file before the analysis step runs
  • Check the step logs. An exceeded budget also fails this step, unless dont_fail_on_alerts is set

PR comment not appearing​

  • Confirm pull-requests: write is set in permissions and GH_TOKEN is set on the comment step
  • The comment step only runs on pull_request events, not on pushes to main
  • Check that the analysis step uploaded a report (report_path is set)
  • In summary mode, check that MEMBROWSE_API_KEY is available to the step

API key issues​

  • Verify the secret name matches exactly: MEMBROWSE_API_KEY
  • Ensure the key is for the correct project in Project Settings
  • Fork and Dependabot PRs cannot access repository secrets, so the comment step can't run on them in this setup — see Open Source Projects for handling this

Next Steps​

  • Multiple targets? If you build for different boards, build types, or feature variants, see Multiple Targets
  • Historical data? Populate your project with past commits using Historical Onboarding
  • Open-source project? Handle fork PRs with the Open Source two-workflow setup