Github action for computing FLASH and D/IRAM deltas between versions for commenting on PRs and releases.
This repository provides a reusable action for computing changes between builds (e.g. for PRs and releases) of your flash and D/IRAM usage for esp-idf projects.
It can calculate and post size delta tables on both pull requests as well as releases:
Table of Contents
The output of this action is a comment on the PR or release showing the changes in flash and D/IRAM usage between the current build and the target branch (for PRs) or previous release (for releases).
It runs idf_size.py to compute the sizes, outputting the reults into a simple .json file, before running a Python script to compute the deltas and format them into a markdown table.
The primary use case for this action is to be run on pull requests and releases, so that the size changes will be automatically computed and added to the PR or release notes for ease of use.
For an example repository which uses this action, see esp-cpp/template:
- esp-cpp/template build.yml - uses this action on pull requests
- esp-cpp/template package_main.yml - uses this action on releases
You can use this action in your GitHub workflows. Below are example workflows for pull requests and releases.
This action can be used to compute the flash and D/IRAM size changes for pull requests. It will compare the current branch (the PR branch) against the target branch (e.g. main or develop).
You will need to ensure that the build artifacts are available in the build directory (or whatever directory you specify in the build-path input). This typically means you will need to run the build step before this action.
Here is an example workflow for pull requests:
name: Build and Compute Size Delta (PR) on: [pull_request] jobs: build: name: Build the project permissions: issues: write # to post PR comments runs-on: ubuntu-latest steps: - uses: actions/checkout@v5 - name: Build the code uses: espressif/esp-idf-ci-action@v1 with: esp_idf_version: v5.5 target: esp32s3 path: '.' - name: Determine Size Delta uses: esp-cpp/esp-idf-size-delta@v1 with: app_name: "My ESP-IDF App" app_path: "." idf_target: esp32s3 idf_version: v5.5 idf_component_manager: "1" # enable component manager base_ref: ${{ github.event.pull_request.base.sha }} flash_total_override: 1500000 # optional, number of bytes for app partition in flash for percentage calculationYou can also use this action to generate a size report without comparing against a base reference. This is useful for standalone builds or when you only want to see the current size state without deltas.
Simply omit the base_ref input or set it to an empty string:
name: Build and Show Size Report on: [push] jobs: build: name: Build and report size runs-on: ubuntu-latest steps: - uses: actions/checkout@v5 - name: Build the code uses: espressif/esp-idf-ci-action@v1 with: esp_idf_version: v5.5 target: esp32s3 path: '.' - name: Show Size Report uses: esp-cpp/esp-idf-size-delta@v1 with: app_name: "My ESP-IDF App" app_path: "." idf_target: esp32s3 idf_version: v5.5This will generate a simpler table showing only the current size metrics without base/delta columns.
This action can also be used to compute the flash and D/IRAM size changes for releases. When used on release events, it will automatically compare against the previous tag chronologically. If no previous tag exists, it will show a size-only report without comparison.
You will need to ensure that the build artifacts are available in the build directory (or whatever directory you specify in the build-path input). This typically means you will need to run the build step before this action.
name: Build and Compute Size Delta (Release) on: release: types: [published] jobs: build: name: Compute Size Delta for Release runs-on: ubuntu-latest permissions: contents: write # to allow updating release notes steps: - name: Determine Size Delta uses: esp-cpp/esp-idf-size-delta@v1 with: app_name: "My ESP-IDF App" app_path: "." idf_target: esp32s3 idf_version: v5.5 idf_component_manager: "1" # enable component manager # base_ref and head_name are automatically detected for releases flash_total_override: 1500000 # optional, number of bytes for app partition in flash for percentage calculationNote: The action will automatically:
- Find the previous tag chronologically when processing a release
- Use that tag as the base reference for comparison
- Set the base column name to the actual tag name (e.g., "v1.0.0") for clear labeling
- Set the head column name to the current release tag (e.g., "v1.1.0") for clear labeling
- Fall back to a size-only report if it's the first release (no previous tags)
inputs: app_name: description: 'Name of the ESP-IDF app (for reporting)' required: true app_path: description: 'Relative path to the ESP-IDF app (contains CMakeLists.txt)' required: true idf_version: description: 'ESP-IDF version to setup' required: false default: 'v5.5' idf_target: description: 'ESP-IDF target (defaults to IDF_TARGET env var or "esp32")' required: false idf_component_manager: description: 'Set IDF_COMPONENT_MANAGER ("0" to disable)' required: false default: '0' head_name: description: 'Name of the head app (for reporting, defaults to "PR", auto-set to tag name for releases)' required: false default: 'PR' base_name: description: 'Name of the base app (for reporting, defaults to "Base", auto-set to tag name for releases)' required: false default: 'Base' base_ref: description: 'Git ref/sha to use as base for delta (optional - auto-detected for PRs and releases, or omit for size-only report)' required: false post_comment: description: 'Whether to post a PR comment (true/false)' required: false default: 'true' flash_total_override: description: 'Override total FLASH bytes for percentage (optional)' required: false default: '' github_token: description: 'GitHub token' required: false default: ${{ github.token }} checkout_token: description: 'Token to use for checkout actions (defaults to GITHUB_TOKEN)' required: false default: '' outputs: markdown: description: 'Markdown report for this app' value: ${{ steps.mkdown.outputs.markdown }}