fship 0.2.0

Flutter Ship — orchestrate release workflows to Firebase App Distribution

fship — Flutter Ship

Memorable, easy CLI for orchestrating Flutter release workflows to Firebase App Distribution.

fship release qa                    # Interactive version bump + full release
fship release qa --version 1.2.4+46  # Exact version
fship release qa --bump patch       # Auto-increment patch

Quick Start

1. Install: pip install fship
2. Initialize: cd /path/to/flutter/project && fship init
3. Configure: Edit fship.yaml with your Firebase app IDs
4. Validate: fship validate
5. Release: fship release qa (or your flavor name)

Why fship?

Problem: Manual Flutter releases to Firebase App Distribution are tedious and error-prone.

• Manual version bumping in pubspec.yaml
• Manual changelog creation
• Manual git tagging
• Manual APK building for each flavor
• Manual Firebase distribution
• Human error: wrong version, missing tags, incomplete changelogs

Solution: fship automates the entire workflow in one command.

Features

✓ Interactive or Automated Version Bumping

• Interactive: choose version interactively
• Auto-increment: patch, minor, or major
• Exact version: specify exact version number

✓ Changelog Generation

• Auto-generate CHANGELOG.md from git history
• Uses git-chglog for professional formatting
• Customizable changelog templates

✓ Git Integration

• Auto-commit version changes
• Auto-create git tags
• Track release history in git

✓ Multi-Flavor Support

• Separate configurations per flavor (qa, uat, prod)
• Flavor-specific entrypoints, APK paths, Firebase app IDs
• Release to multiple flavors independently

✓ APK Building

• Automated Flutter APK build per flavor
• Configurable build output paths
• Build validation before distribution

✓ Firebase Distribution

• One-command distribution to Firebase App Distribution
• Customizable tester groups (testers, internal, external)
• Release notes auto-generated from git log
• Share links in output for easy distribution

✓ Dry-Run Mode

• Test version bumping, changelog, and tagging without building/distributing
• Perfect for validating setup

✓ Environment Management

• Auto-loads Firebase app IDs from .env.dev
• Interactive setup if config missing
• No hardcoded secrets in repo

How It Works (Full Flow)

1. Bump version in pubspec.yaml (interactive or auto)
2. Generate CHANGELOG.md via git-chglog
3. Generate release_note.txt from git log since last tag
4. Git commit version changes
5. Git tag the release
6. Build APK for the flavor
7. Distribute to Firebase App Distribution

Benefits

Manual Process	fship
15-20 min per release	2-3 min per release
Multiple error-prone steps	Single command
Manual version tracking	Git-backed versions
Manual changelog maintenance	Auto-generated from commits
Easy to forget steps	Enforced workflow
Hard to track history	Full git history preserved

What It Does (Full Flow)

1. Bump version in pubspec.yaml (interactive or auto)
2. Generate CHANGELOG.md via git-chglog
3. Generate release_note.txt from git log since last tag
4. Git commit version changes
5. Git tag the release
6. Build APK for the flavor
7. Distribute to Firebase App Distribution

Installation

Via PyPI (Recommended)

pip install fship

From Source (Development)

git clone https://github.com/MrShakila/F-ship.git
cd F-ship
pip install -e .

Setup (One Time)

cd /path/to/your/flutter/project

# Copy default config
fship init

# Edit fship.yaml — set your Firebase app IDs, entry points, APK paths
vi fship.yaml

# Validate setup
fship validate

fship.yaml Example

flavors:
  qa:
    firebase_app_id_env: APPIDANDROID_QA
    entrypoint: lib/main_qa.dart
    apk_path: build/app/outputs/flutter-apk/app-qa-release.apk
    groups: testers

  prod:
    firebase_app_id_env: APPIDANDROID_PROD
    entrypoint: lib/main_prod.dart
    apk_path: build/app/outputs/flutter-apk/app-prod-release.apk
    groups: testers

Usage

Interactive Version Bump

fship release qa
# Current version: 1.2.3+45
# New version: 1.2.4+46
# [shows full release workflow with progress]

Exact Version (Non-Interactive)

fship release qa --version 1.2.4+46

Auto-Increment

fship release qa --bump patch    # 1.2.3+45 → 1.2.4+0
fship release qa --bump minor    # 1.2.3+45 → 1.3.0+0
fship release qa --bump major    # 1.2.3+45 → 2.0.0+0

Dry Run (Skip Build & Distribution)

fship release qa --skip-build --skip-distribute
# Only bumps version, generates changelog, commits, tags

Prerequisites

• Python 3.11+
• Flutter SDK
• Firebase CLI: npm install -g firebase-tools
• git-chglog: brew install git-chglog (macOS) or npm install -g git-chglog

Environment Setup

First run creates .env.dev template:

fship release qa
# Creates .env.dev with placeholders, prompts you to fill in Android app IDs

Edit .env.dev with your Firebase Android app IDs:

# .env.dev (add to .gitignore)
APPIDANDROID_QA=1:123456:android:abcdef...
APPIDANDROID_UAT=1:345678:android:ghijkl...
APPIDANDROID_PROD=1:789012:android:mnopqr...

Get app IDs from Firebase Console > Project Settings > Your apps (Android).

fship automatically loads from .env.dev when you run fship release.

Commands

fship release <flavor> [--version X.Y.Z+B] [--bump patch|minor|major] [--skip-build] [--skip-distribute]
fship init                         # Copy default fship.yaml
fship validate                     # Check tools and config
fship version                      # Show fship version
fship --help                       # Full help

Troubleshooting

"fship.yaml not found"

fship init
vi fship.yaml  # customize

"Firebase CLI not found"

npm install -g firebase-tools
firebase login

"git-chglog not found"

brew install git-chglog
# or
npm install -g git-chglog

"Commits/tags not created, but version was bumped"

• Ensure you're in a git repo and have uncommitted changes allowed
• Check git status

Development

git clone https://github.com/MrShakila/F-ship.git
cd F-ship
pip install -e .
fship --help