# Vercel Deployment Menu Bar for macOS (Open Source)

A lightweight **macOS menu bar app** to **monitor Vercel deployments** in real time — see build/ready/error status at a glance and jump to details with one click.

![Vercel deployment status in macOS menu bar showing build/ready/error states](./vercel-menu-bar-deployment-status-macos.png)

**Features**
- Real-time deployment status (build, ready, error)
- Personal or Team tokens
- Comma-separated team and project filters
- Notarized, code-signed app (no Gatekeeper warnings)
- Native Swift app — lightweight and fast
- Quick access to deployment details from the menu bar

## Installation

### Pre-built Binary (Easiest)

1. Download the latest release from the [Releases](https://github.com/andrewk17/vercel-deployment-menu-bar/releases) page
2. Unzip and move the app to your Applications folder
3. Launch the app
4. Click the menu bar icon and select "Preferences" to configure your Vercel API token

### Build from Source

Requirements:
- macOS 13.0 or later
- Xcode 15.0 or later
- Swift 5.9 or later

```bash
# Clone the repository
git clone https://github.com/andrewk17/vercel-deployment-menu-bar.git
cd vercel-deployment-menu-bar

# Build the app
swift build -c release

# Package as .app bundle (creates a signed and notarized app)
./Scripts/package-app.sh

# The app will be created at: build/Vercel Deployment Menu Bar.app
```

#### For Developers: Code Signing & Notarization

The app is properly code signed and notarized to prevent macOS Gatekeeper warnings. If you're building for distribution:

1. **Prerequisites:**
   - Apple Developer account ($99/year)
   - Developer ID Application certificate installed
   - App Store Connect API key for notarization

2. **Setup App Store Connect API Key:**
   ```bash
   # Create directory for API key
   mkdir -p ~/.private_keys

   # Download your .p8 file from https://appstoreconnect.apple.com/access/api
   # Move it to ~/.private_keys/

   # Add to ~/.zshrc or ~/.bash_profile:
   export APPLE_API_KEY_ID="your-key-id"
   export APPLE_API_ISSUER="your-issuer-id"
   export APPLE_API_KEY_PATH="$HOME/.private_keys/AuthKey_XXXXXXXXXX.p8"
   ```

3. **Build and notarize:**
   ```bash
   ./Scripts/package-app.sh
   # The script will automatically sign and notarize the app
   ```

The build script will:
- Sign the app with your Developer ID certificate
- Submit to Apple's notary service
- Staple the notarization ticket
- Verify the signature

If notarization credentials aren't configured, the script will still sign the app but skip notarization.

## Configuration

### Step 1: Generate a Vercel API Token

1. Go to [Vercel Account Settings → Tokens](https://vercel.com/account/tokens)
2. Click "Create Token"
3. Give your token a name (e.g., "Menu Bar App")
4. Choose the scope:
   - **Personal Account**: Select your personal account scope
   - **Team Account**: Select the specific team you want to monitor
5. Set an expiration date (optional but recommended)
6. Click "Create Token"
7. **Important**: Copy the token immediately - you won't be able to see it again!

### Step 2: Configure the App

1. Launch "Vercel Deployment Menu Bar" from your Applications folder
2. Click the menu bar icon (upside-down triangle)
3. Select "Preferences"
4. Enter your API token in the "Token" field

### Step 3: Configure Team ID(s) (Only if you scoped the token to a team)

If you created a token scoped to a specific team, you **must** also enter your Team ID:

1. In the Preferences window, locate the "Team ID(s)" field
2. To find your Team ID:
   - Go to your [Vercel Dashboard](https://vercel.com/)
   - Select your team from the dropdown
   - Look at the URL - it will be: `https://vercel.com/[TEAM_ID]/~`
   - The `[TEAM_ID]` is what you need (e.g., if the URL is `https://vercel.com/acme-corp/~`, your Team ID is `acme-corp`)
   - Alternatively, go to Team Settings → General and find your Team Slug
3. Enter one Team ID, or multiple Team IDs as comma-separated values (e.g., `acme-corp, studio-team`)
4. Click save

**Note**: If you used a personal account token, you can leave the Team ID(s) field empty.

### Step 4: Optional Project Name Filter

To only show specific projects, set "Project Name(s)" in Preferences:

1. Enter one project name, or multiple as comma-separated values (e.g., `web-app, api`)
2. Only deployments from those projects will be shown

### Step 5: Start Monitoring

Once configured, the app will automatically start monitoring your deployments. The menu bar icon will update based on your latest deployment status.

## How It Works

The app uses the Vercel API to:
1. Fetch your deployment list periodically
2. Check the status of each deployment
3. Update the menu bar icon based on deployment states
4. Display deployment details in a convenient menu

## Requirements

- macOS 13.0+
- Vercel API token

## License

MIT License - see [LICENSE](LICENSE) file for details

## FAQ

### How do I monitor Vercel deployments from the macOS menu bar?

Install the Vercel Deployment Menu Bar app, configure it with your Vercel API token, and it will automatically display real-time deployment status in your macOS menu bar. The app polls the Vercel API and updates the status icon based on your latest deployments.

### Where do I find my Vercel Team ID?

If you're using a team-scoped Vercel API token, you need to provide your Team ID:

1. Go to your [Vercel Dashboard](https://vercel.com/)
2. Select your team from the dropdown
3. Look at the URL: `https://vercel.com/[TEAM_ID]/~`
4. Copy the `[TEAM_ID]` portion (e.g., if the URL shows `https://vercel.com/acme-corp/~`, your Team ID is `acme-corp`)
5. Alternatively, go to Team Settings → General to find your Team Slug

Enter this Team ID in the app's Preferences. You can also enter multiple Team IDs as comma-separated values. If you're using a personal account token, you can leave the Team ID(s) field empty.

### How do I fix the "damaged app" error on macOS?

The latest releases (v0.2.0+) are properly code-signed and notarized, so you shouldn't see this error. If you do:

1. Download the latest release from the [Releases](https://github.com/andrewshawcare/vercel-deployment-menu-bar/releases) page
2. If the error persists, right-click the app and select "Open" instead of double-clicking
3. For older versions, you may need to remove the quarantine attribute: `xattr -d com.apple.quarantine "/Applications/Vercel Deployment Menu Bar.app"`

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.