upcode_ci 0.10.35

A collection of tools used by Upcode team

upcode_ci

A collection of CI/CD automation tools used by the Upcode team. It ships a single upcode executable that wraps the repetitive Flutter, Google Cloud, and Firebase tasks that surround a typical app: code generation, formatting, analysis, versioning, environment management, protobuf compilation, and distribution.

Installation

dart pub global activate upcode_ci

This installs the upcode command globally. Make sure ~/.pub-cache/bin is on your PATH.

Quick start

Every upcode command must be run from a directory that contains an upcode.yaml file. The file describes where the Flutter app, API, and private material live, and which Google Cloud project to target.

cd my-project        # directory containing upcode.yaml
upcode flutter:all   # run a command
upcode help          # list every command
upcode help <command>

If upcode.yaml is missing, the command exits with:

You need to call this command from the same directory as you upcode.yaml file.

fvm support

When the target Flutter project is fvm-configured — it has a .fvmrc file or a .fvm/ directory in any parent directory — and the fvm binary is on PATH, upcode runs flutter and dart through fvm so the pinned SDK is used. If fvm is not installed it falls back to the bare flutter/dart executables.

Configuration

upcode.yaml lives at the root of your repository. Keys may be overridden per invocation with global options (see below).

# Google Cloud
google_project_id: my-project
google_project_location: europe-west1

# Application identifiers
base_application_id: com.example.app
# Optional per-platform overrides; default to base_application_id
android_application_id: com.example.app.android
ios_application_id: com.example.app.ios

# Directories (paths relative to upcode.yaml)
private_dir: private          # holds service_account.json
flutter_dir: app              # the Flutter module
api_dir: api                  # the backend module
api_dockerfile_dir: api       # optional, defaults to api_dir
protos_dir: app/res/protos    # optional, defaults to <flutter_dir>/res/protos
protos_output_dir: generated  # optional

# Module lists (optional)
modules: [app, packages/core] # defaults to [flutter_dir]
generated: [app]              # modules that run build_runner; defaults to none
analyzed: [app]               # modules analyzed by flutter:analyze; defaults to modules
formatted:                    # modules formatted by flutter:format; defaults to modules
  - app:
      exclude: [lib/l10n/**, '**/*.pb.dart'] # globs relative to the module
  - packages/core
tested: [app]                 # modules tested by flutter:test; defaults to modules

# Nested maps consumed by the version commands
api: { ... }
api_config: { ... }

Key	Required	Description
google_project_id	yes	Google Cloud / Firebase project id.
google_project_location	for API commands	Cloud project location, e.g. europe-west1.
base_application_id	yes	Default application id; falls back for Android and iOS.
android_application_id	no	Overrides base_application_id for Android.
ios_application_id	no	Overrides base_application_id for iOS.
private_dir	for Google/Firebase commands	Directory containing service_account.json.
flutter_dir	yes	Path to the Flutter module.
api_dir	for API commands	Path to the backend module. A Dart backend is detected by a pubspec.yaml inside it.
api_dockerfile_dir	no	Dockerfile location when it lives outside api_dir.
protos_dir	no	Source .proto directory.
protos_output_dir	no	Generated protobuf output directory.
modules	no	Modules acted on by default. Defaults to [flutter_dir].
generated	no	Modules flutter:buildrunner runs in. Defaults to none.
analyzed / formatted / tested	no	Per-task module overrides. Default to modules.
windows	for Windows builds	The Windows app's identity: name, binary_name and installer_id. See below.

flutter:format and dart:format always skip generated files (*.g.dart, *.freezed.dart, lib/generated/, and similar). To skip more, write the module as a map with an exclude list of glob patterns relative to that module, as in app above. Use ** to match across directories (lib/l10n/**), and quote patterns that start with *, which YAML otherwise reads as an alias.

Windows app identity

Flutter has no flavors on Windows, so an app that ships more than one environment there sets its identity per environment:

env:
  prod:
    windows:
      name: Example                # window title, Start menu entry, data folder
      binary_name: example         # the executable, without .exe
      installer_id: 9C1F6A52-3E0B-4D7A-8F21-6B5E2C4D9A10 # Inno Setup AppId
  dev:
    windows:
      name: Example Dev
      binary_name: example_dev
      installer_id: 2B7D4E91-0A6C-4F38-B5D2-E8C1937A4F06

flutter:environment set writes it to windows/environment.cmake, for windows/CMakeLists.txt to include(), and windows/environment.iss, for an Inno Setup script to #include. An environment without a windows section gets neither file, and any left by an earlier one are removed. Give each environment its own installer_id and never change it once shipped: it is what lets an install upgrade in place. Both files are generated, so add them to .gitignore.

Editor support

upcode.schema.json is a JSON Schema for upcode.yaml that gives completion, hover docs, and typo checks. Add this line at the top of upcode.yaml (works in VS Code with the YAML extension and in JetBrains IDEs):

# yaml-language-server: $schema=https://raw.githubusercontent.com/long1eu/upcode_ci/master/upcode.schema.json

Authentication

Commands that talk to Google Cloud, Firebase, or the Play Store authenticate with the project's service account. Place its key at <private_dir>/service_account.json. There is no fallback: if private_dir is not set or the key file is missing, the command fails with an error that names the missing setting or file.

Global options

Every command accepts these options, which override the matching upcode.yaml values for that run:

--flutter_dir            The Flutter module to run the command in.
--private_dir            The private module.
--api_dir                The API module.
--api_dockerfile_dir     Dockerfile location when outside api_dir.
--protos_dir             The protos module.
--google_project_location  The project location.

Commands

Run upcode help <command> for the full options of any command.

Flutter

Command	Description
flutter:all	Generate every derived Dart file: runs flutter:buildrunner, flutter:i18n, and protos.
flutter:buildrunner	Run build_runner to generate Flutter files.
flutter:i18n	Generate the internationalization files.
flutter:analyze	Run the analyzer; exits non-zero on issues.
flutter:format	Run the formatter; exits non-zero when changes are needed.
flutter:test	Run the tests across the configured modules.
flutter:version	Manage the Flutter app version. Subcommands: read, increment, set.
flutter:releaseNotes	Save the latest commits as release notes.

Dart

Command	Description
dart:analyze	Run the analyzer; exits non-zero on issues.
dart:format	Run the formatter; exits non-zero when changes are needed.

Distribution

Command	Description
fad	Work with Firebase App Distribution. Subcommands: upload, ai-test, deleteOldReleases.
testlab	Run Android integration tests on Firebase Test Lab. Subcommand: run.
flutter:fastlane	Distribute the app on the App Store and Play Store.

Protobufs

Command	Description
protos	Generate implementations and the API descriptor from .proto files. Flags: --all, --flutter (alias --dart), --backend (alias --js), --descriptor.

API

Command	Description
api:deploy	Build and deploy the backend. Subcommands: gcloud_build_image, endpoints, gateway, service, all.
api:environment	Manage API environments. Subcommands: create, set.
api:version	Update the API version from the cloud version. Subcommands: read, increment.

Environments & Google

Command	Description
environment	Set the active environment for both the API and Flutter app. Subcommand: set.
flutter:environment	Manage Flutter environments. Subcommand: set.
google	Google API operations, e.g. google fcm send to send a push notification.

An environment is a collection of settings that isolates the services upcode manages from one another, so that changes to a service in one environment never affect the same service in another.

License

See LICENSE.