# How to Update steipete/CodexBar: Build, Sign, and Release Workflow

> Learn how to update steipete/CodexBar by pulling the latest SwiftPM source, updating version strings, and running the release script to build, sign, and notarize. Publish your GitHub release.

- Repository: [Peter Steinberger/CodexBar](https://github.com/steipete/CodexBar)
- Tags: how-to-guide
- Published: 2026-07-07

---

**To update steipete/CodexBar, pull the latest SwiftPM source, bump version strings in [`Package.swift`](https://github.com/steipete/CodexBar/blob/main/Package.swift) and `WidgetExtension/Info.plist`, run [`./Scripts/release.sh`](https://github.com/steipete/CodexBar/blob/main/./Scripts/release.sh) to build, sign, and notarize the universal binary, then publish a GitHub release with an updated Sparkle appcast.**

CodexBar is a Swift 6 macOS 14+ menu-bar application that aggregates usage, quota, and cost data from dozens of AI coding providers. Updating the project involves three distinct layers: source-level version bumps, automated build-and-sign workflows, and distribution refreshes across GitHub Releases, Sparkle, and Homebrew Cask. This guide walks through the exact files, scripts, and commands required to update steipete/CodexBar from repository pull to verified production release.

## Pull the Latest Source and Prepare the Environment

Start by syncing the repository. According to the source code, CodexBar is a SwiftPM-only project with no Xcode workspace to manage.

```bash
git clone https://github.com/steipete/CodexBar.git
cd CodexBar
git checkout main
git pull

```

The modular architecture separates the core logic from the UI, allowing updates to the background `UsageFetcher` → `UsageStore` pipeline without touching the menu-bar interface. See [`docs/architecture.md`](https://github.com/steipete/CodexBar/blob/main/docs/architecture.md) for the full data flow diagram.

## Bump Version Strings and Validate Code

Version numbers appear in three locations that must remain synchronized before building.

1. **[`Package.swift`](https://github.com/steipete/CodexBar/blob/main/Package.swift)** – Update the `version` constant in the SwiftPM manifest.
2. **`WidgetExtension/Info.plist`** – Increment `CFBundleShortVersionString` for the app bundle version displayed in the UI.
3. **[`CHANGELOG.md`](https://github.com/steipete/CodexBar/blob/main/CHANGELOG.md)** – Add human-readable release notes to the top section.

After editing these files, run the formatting and linting checks enforced by the CI pipeline:

```bash
swiftformat Sources Tests
swiftlint --strict
make check   # Runs both tools sequentially

```

## Regenerate Assets and Build the Release

If the application icon changed, regenerate the `.icns` bundle before building:

```bash
./Scripts/build_icon.sh Icon.icon CodexBar

```

This script uses Xcode’s `ictool` under the hood. Next, execute the automated release pipeline:

```bash
./Scripts/release.sh

```

Internally, this script performs four critical steps:
- **Universal build** – Compiles `swift build -c release` for both `arm64` and `x86_64` architectures.
- **Packaging** – Assembles `CodexBar.app` with the Sparkle framework and regenerated icon.
- **Deep signing** – Applies `codesign --deep --timestamp` to ensure macOS 14+ compatibility.
- **Notarization** – Submits the zip to Apple’s notarization service and staples the returned ticket.

For manual control over signing without the full pipeline, use [`./Scripts/sign-and-notarize.sh`](https://github.com/steipete/CodexBar/blob/main/./Scripts/sign-and-notarize.sh) directly.

## Generate and Verify the Sparkle Appcast

Sparkle delivers automatic updates by reading an XML feed. Generate the new appcast entry pointing to your signed zip:

```bash
./Scripts/make_appcast.sh CodexBar-macos-universal-0.4.2.zip \
  https://raw.githubusercontent.com/steipete/CodexBar/main/appcast.xml

```

The script generates an `edSignature` using the private Sparkle key stored in `.mac-release.env`. Verify the entry resolves correctly before publishing:

```bash
./Scripts/verify_appcast.sh 0.4.2

```

## Publish the Release and Refresh Distribution Channels

Create a GitHub release with the semantic tag (e.g., `v0.4.2`) and attach the following assets:
- `CodexBar-macos-universal-0.4.2.zip` (the notarized application bundle)
- `CodexBar-macos-universal-0.4.2.dSYM.zip` (debug symbols for crash reporting)
- CLI tarballs for Linux and macOS (built automatically by the CI workflow)

Copy the release notes verbatim from the top section of [`CHANGELOG.md`](https://github.com/steipete/CodexBar/blob/main/CHANGELOG.md).

### Refresh Homebrew Cask

The CI workflow automatically updates [`../homebrew-tap/Casks/codexbar.rb`](https://github.com/steipete/CodexBar/blob/main/../homebrew-tap/Casks/codexbar.rb) to point at the new zip. Verify the distribution path works:

```bash
brew uninstall --cask codexbar || true
brew tap steipete/tap
brew install --cask codexbar

```

### Validate CLI and Sparkle Updates

Confirm the CLI binary reflects the new version:

```bash
codexbar --version

```

Test the Sparkle update path by keeping an older `CodexBar.app` in `/Applications`, launching it, and confirming it prompts to download the new version. For manual testing of the data pipeline, trigger a refresh that bypasses the standard `SettingsStore` cadence:

```bash
codexbar refresh --provider all

```

## Testing Updates via the Command Line

The CLI in `Sources/CodexBarCLI` reuses the same `UsageStore` as the GUI, ensuring parity between versions. Test provider configuration after updating:

```bash
codexbar config enable --provider openai
codexbar config set-api-key --provider openai --stdin <<<"$OPENAI_API_KEY"

```

Validate cost aggregation matches the UI:

```bash
codexbar cost --provider codex

```

## Summary

- **Synchronize versions** in [`Package.swift`](https://github.com/steipete/CodexBar/blob/main/Package.swift), `WidgetExtension/Info.plist`, and [`CHANGELOG.md`](https://github.com/steipete/CodexBar/blob/main/CHANGELOG.md) before building.
- **Automate the build** with [`./Scripts/release.sh`](https://github.com/steipete/CodexBar/blob/main/./Scripts/release.sh) to generate universal binaries, apply deep code signing, and staple Apple notarization tickets.
- **Update Sparkle** using [`./Scripts/make_appcast.sh`](https://github.com/steipete/CodexBar/blob/main/./Scripts/make_appcast.sh) and verify signatures with [`./Scripts/verify_appcast.sh`](https://github.com/steipete/CodexBar/blob/main/./Scripts/verify_appcast.sh).
- **Distribute via GitHub Releases** and verify Homebrew Cask updates with `brew install --cask codexbar`.
- **Test the CLI** using commands like `codexbar refresh --provider all` to ensure the `UsageFetcher` → `UsageStore` pipeline functions correctly after the update.

## Frequently Asked Questions

### What files must be edited to bump the version in CodexBar?

You must update three files: [`Package.swift`](https://github.com/steipete/CodexBar/blob/main/Package.swift) (SwiftPM version constant), `WidgetExtension/Info.plist` (`CFBundleShortVersionString`), and [`CHANGELOG.md`](https://github.com/steipete/CodexBar/blob/main/CHANGELOG.md) (release notes). These are verified during the build process and displayed in the application’s About panel.

### How does the automated release script differ from manual signing?

[`./Scripts/release.sh`](https://github.com/steipete/CodexBar/blob/main/./Scripts/release.sh) orchestrates the entire workflow—building universal binaries, packaging the app, applying `codesign --deep --timestamp`, notarizing with Apple, and generating the Sparkle appcast. Manual signing via [`./Scripts/sign-and-notarize.sh`](https://github.com/steipete/CodexBar/blob/main/./Scripts/sign-and-notarize.sh) handles only the signing and notarization steps, requiring you to manage builds and appcast generation separately.

### Where does CodexBar store usage data during updates?

The background `UsageFetcher` writes snapshot data to `UsageStore`, which both the menu-bar UI (`Sources/CodexBar`) and CLI (`Sources/CodexBarCLI`) read. Updating the app preserves this data in the user’s keychain and app group containers, ensuring continuity across versions.

### Can I build CodexBar without Apple notarization?

You can compile a local debug build using `swift build`, but distributing or updating the application requires notarization for macOS 14+ compliance. The [`./Scripts/release.sh`](https://github.com/steipete/CodexBar/blob/main/./Scripts/release.sh) script automates notarization using credentials stored in `.mac-release.env`, which is required for Sparkle auto-updates to function on Gatekeeper-enabled systems.