home / skills / firebase / firebase-tools / update-pubsub-emulator

update-pubsub-emulator skill

safe

This skill guides updating the Pub/Sub emulator locally, packaging, uploading, and validating new versions for reliable development.

npx playbooks add skill firebase/firebase-tools --skill update-pubsub-emulator

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.6 KB

---
name: Update Pub/Sub Emulator
description: How to update the Pub/Sub emulator
---

# Update Pub/Sub Emulator

1.  **Update Local Emulator**
    Run the following command to make sure you have the latest version of the pubsub emulator installed via gcloud:
    ```bash
    gcloud components update pubsub-emulator
    ```

2.  **Locate Emulator Directory**
    The emulator represents a directory likely located at `<gcloud-install-path>/platform/pubsub-emulator`.
    You can find the exact path by running the emulator and checking the output, or by inspecting where `gcloud` is installed (e.g. `which gcloud` usually points to a bin directory, and the platform directory is a sibling of `bin`).
    Verify the version by running the emulator or checking the `VERSION` file if it exists.

3.  **Package the Emulator**
    Zip the directory found in the previous step. Name it `pubsub-emulator-<version>.zip`.
    Ensure the zip structure is such that the top-level directory inside the zip is `pubsub-emulator`.
    *Note: The existing code expects the binary at `pubsub-emulator-<version>/pubsub-emulator/bin/cloud-pubsub-emulator` inside the cache, which usually means the zip contains a root folder `pubsub-emulator`.*

4.  **Upload to Storage**
    Upload the zip file to the Firebase preview bucket:
    ```bash
    gsutil cp pubsub-emulator-<version>.zip gs://firebase-preview-drop/emulator/
    ```
    Make the file publicly readable if necessary (usually the bucket permissions handle this, or use `gsutil acl ch -u AllUsers:R ...`).

    **Note:** For the version 0.8.27 update, this step was already done.

5.  **Calculate Metadata**
    Calculate the file size in bytes, MD5 checksum, and SHA256 checksum of the zip file.
    ```bash
    # Size
    ls -l pubsub-emulator-<version>.zip
    
    # MD5 (macOS: `md5`, Linux: `md5sum`)
    md5 pubsub-emulator-<version>.zip
    
    # SHA256 (macOS: `shasum -a 256`, Linux: `sha256sum`)
    shasum -a 256 pubsub-emulator-<version>.zip
    ```

6.  **Update Configuration**
    Edit `src/emulator/downloadableEmulatorInfo.json`:
    - Update `pubsub.version` to the new version.
    - Update `pubsub.expectedSize`.
    - Update `pubsub.expectedChecksum` (MD5).
    - Update `pubsub.expectedChecksumSHA256`.
    - Update `pubsub.remoteUrl` and `pubsub.downloadPathRelativeToCacheDir`.

7.  **Verify**
    Run the emulators to ensure the new version is downloaded and starts correctly.
    ```bash
    firebase emulators:start --only pubsub
    ```

8. **Add a Changelog Entry**
    Add a changelog entry to `CHANGELOG.md` like '- Updated Pub/Sub emulator to version <version>'

Overview

This skill explains how to update the Google Cloud Pub/Sub emulator used by Firebase emulators. It walks through obtaining the latest emulator, packaging and uploading the artifact, updating emulator metadata, and verifying the new version runs locally. The goal is a reproducible, verifiable update process so the emulator downloads and starts correctly for all developers and CI systems.

How this skill works

The process checks for the latest emulator via gcloud, locates the installed emulator directory, and packages it into a zip with the expected internal layout. The zip is uploaded to a storage bucket, checksums and file size are calculated, and the emulator metadata JSON is updated so the Firebase tooling can download the new version. Finally, the emulators are started to verify the update.

When to use it

Releasing a new Pub/Sub emulator version to developer machines or CI
Updating emulator metadata after packaging a fixed or patched binary
Replacing an out-of-date emulator that fails to start or behaves inconsistently
Preparing a controlled emulator rollout for a team or organization

Best practices

Confirm the gcloud-managed emulator is up-to-date before packaging (gcloud components update pubsub-emulator).
Keep the zip root folder named pubsub-emulator so cache paths resolve correctly.
Record exact size and both MD5 and SHA256 checksums to ensure download integrity.
Upload artifacts to a controlled storage bucket and validate public access or appropriate ACLs before publishing metadata changes.
Run firebase emulators:start --only pubsub locally to verify download and startup before announcing the update.

Example use cases

Publish a patched emulator binary after fixing a runtime bug that caused crashes in integration tests.
Roll out a newer emulator version to CI so nightly builds use the same local Pub/Sub behavior developers have locally.
Replace an emulator that changed internal paths by re-packaging with the correct top-level directory layout.
Validate checksum mismatches by recalculating MD5 and SHA256 and updating the metadata JSON accordingly.

FAQ

What folder structure must the zip contain?

The top-level directory inside the zip must be named pubsub-emulator and include the bin/cloud-pubsub-emulator binary at pubsub-emulator/bin/cloud-pubsub-emulator so the cache path matches expectations.

Which checksums do I need to record?

Record both MD5 (expectedChecksum) and SHA256 (expectedChecksumSHA256), plus the exact file size in bytes (expectedSize) to ensure integrity and correct metadata.

How do I verify the new emulator is used after publishing metadata?

Run firebase emulators:start --only pubsub and observe the download step and startup logs; confirm the VERSION file or emulator output reports the new version.