From 8e886d864f3c2f80d6e71a93231e603a7909f071 Mon Sep 17 00:00:00 2001 From: Crazelu Date: Sat, 14 Nov 2026 15:28:54 +0100 Subject: [PATCH 01/12] docs: Add an App publishing page for Serverpod Cloud --- cloud_docs/concepts/app-publishing.md | 229 ++++++++++++++++++++++++++ 1 file changed, 229 insertions(+) create mode 100644 cloud_docs/concepts/app-publishing.md diff --git a/cloud_docs/concepts/app-publishing.md b/cloud_docs/concepts/app-publishing.md new file mode 100644 index 00000000..c74ab750 --- /dev/null +++ b/cloud_docs/concepts/app-publishing.md @@ -0,0 +1,229 @@ +--- +sidebar_position: 11 +description: Serverpod Cloud builds your Flutter app and uploads it to TestFlight and Google Play. Check the setup with app doctor, then publish from the CLI. +--- + +# App publishing + +Getting a Flutter app to testers means signing builds, matching store settings, and uploading to TestFlight and Google Play. With app publishing, you run one command: Serverpod Cloud builds your Flutter app for iOS and Android, signs it, and uploads it to the stores you connected in the console. + +You publish from the Cloud CLI. The `app doctor` command checks your app's setup before you publish, and each problem it reports links to a section of this page. + +## What app publishing does + +App publishing supports two platforms: + +
+ +| Platform | Store | Where each build lands | +| -------- | ----------- | --------------------------------------------- | +| iOS | App Store | TestFlight, ready for your testers | +| Android | Google Play | A draft release on the internal testing track | + +
+ +When you publish, the CLI uploads your Flutter app's source code. Serverpod Cloud builds it in release mode on its own build machines, with the Flutter version you choose. It then signs each build and uploads it to the store. You don't need Xcode, Android Studio, or a Mac to publish. + +Releasing a build from TestFlight or the internal testing track to the public store stays in App Store Connect and Play Console. + +## Connect the stores + +Before you can publish for a platform, connect its store in the [Serverpod Cloud console](https://console.serverpod.dev). Open your project, then open the **App Stores** tab. Each store has a setup guide that walks you through the steps: + +- **App Store:** Join the Apple Developer Program, register your app's bundle ID, create the app in App Store Connect, and add an App Store Connect API key. Only the project owner can add the key. +- **Google Play:** Sign up for Play Console, create the app, choose an upload key, and invite Serverpod Cloud's service account to your app in Play Console. Serverpod Cloud can create the upload key for you, or you can upload the keystore you already sign the app with. + +The `app doctor` command shows whether each connection is complete, and links to the setup guide when it isn't. + +## Check your app with app doctor + +Run `app doctor` from your project's directory before you publish: + +```bash +serverpod cloud app doctor +``` + +It checks the Flutter version, each store connection, and the setup of your Flutter app: + +```text +! Flutter version: Not pinned, so builds use the latest stable release. + Request a version with --flutter-version, or pin one in environment.flutter of the app's pubspec.yaml. + +Android + ✓ Google Play Console connection + ✓ Package name: com.acme.app + ✗ Release signing: Release builds do not use the keystore from Serverpod Cloud. + Learn more: https://docs.serverpod.dev/cloud/concepts/app-publishing#android-release-signing + ! App icon: The app uses the default Flutter icon. + Learn more: https://docs.serverpod.dev/cloud/concepts/app-publishing#app-icon + +iOS + ✓ App Store connection + ✓ Bundle ID: com.acme.app + ✓ Export compliance + ✓ App icon + +1 check failed. Fix it before you publish the app. +``` + +A check marked `✗` makes the build or the upload fail, so fix it before you publish. A check marked `!` is a warning: the app can be published, but the result may not be what you want. + +The command finds your Flutter app from `project.appDir` in `scloud.yaml`, the current directory, or your server's workspace. Pass `--app-dir` to check an app somewhere else, and `--platforms ios` or `--platforms android` to check one platform. + +## Publish your app + +Publish your app from your project's directory: + +```bash +serverpod cloud app publish +``` + +The command builds every platform your app has code for, and stops with a link to the setup guide if a platform's store isn't connected. It shows the progress of each build and ends when the builds are uploaded to the stores. To publish one platform, pass `--platforms`: + +```bash +serverpod cloud app publish --platforms ios +``` + +To start the builds and return right away, pass `--no-await`. The command then prints the `app show` command that follows the builds. + +If your Flutter app is part of a Dart workspace, the upload includes the workspace packages it depends on. To leave files out of the upload, list them in a [`.scloudignore` file](/cloud/concepts/deployments#configure-whats-included). + +## Follow your builds + +Each publish creates an app upload with one build per platform. The upload ID that `app publish` and `app list` print identifies it. Use these commands to follow the builds: + +
+ +| Command | What it shows | +| ------------------------------------------- | ------------------------------------------------------------ | +| `serverpod cloud app list` | Recent publishes, newest first | +| `serverpod cloud app status` | The latest build of each platform with a connected store | +| `serverpod cloud app show ` | The builds of one upload, followed until they end | +| `serverpod cloud app log ` | The build log of one platform, followed until the build ends | +| `serverpod cloud app artifacts ` | Download links for the built files, valid for ten minutes | +| `serverpod cloud app cancel ` | Cancels the builds of an upload that are still running | + +
+ +When a build fails, `app show` and `app status` print the `app log` command that shows why. + +## Setup requirements + +These are the parts of your Flutter app that `app doctor` checks. Each one has a section below. + +### Flutter version {#flutter-version} + +Serverpod Cloud builds your app with the first Flutter version it finds, in this order: + +1. The `--flutter-version` option of `app publish`, such as `--flutter-version 3.50.0`. +2. A single version in `environment.flutter` of your app's `pubspec.yaml`. +3. `project.flutterSdk` in `scloud.yaml`. +4. The version of the Flutter SDK on your computer. +5. The latest stable release. + +To build with the version you develop with, pin it in your app's `pubspec.yaml`: + +```yaml title="pubspec.yaml" +environment: + sdk: ^3.8.0 + flutter: 3.50.0 +``` + +The version must be a Flutter release version, and it can't be lower than the Flutter version your app's `pubspec.lock` requires. When `app doctor` warns that the version isn't pinned, the builds use the latest stable release, which can change between two publishes. + +### App identifiers {#app-identifiers} + +The stores identify your app by its bundle ID on iOS and its package name on Android. Serverpod Cloud reads them from your Flutter app: the bundle ID from the Xcode project in `ios/`, and the package name from `applicationId` in `android/app/build.gradle.kts`. + +A new Flutter app uses a `com.example` placeholder, which the stores don't accept. Replace it with your own identifier, such as `com.yourcompany.yourapp`, in both places. The identifier must match the app you created in App Store Connect and Play Console. + +To publish with a different identifier than the one in your app's files, set it in `scloud.yaml`: + +```yaml title="scloud.yaml" +project: + projectId: my-project + appIdentifiers: + ios: com.yourcompany.yourapp + android: com.yourcompany.yourapp +``` + +### Android release signing {#android-release-signing} + +Google Play only accepts builds signed with your app's upload key. Serverpod Cloud stores that key and passes it to each Android build through these environment variables: + +
+ +| Variable | Value | +| --------------------------- | ------------------------------------ | +| `ANDROID_KEYSTORE_PATH` | The path of the upload keystore file | +| `ANDROID_KEYSTORE_PASSWORD` | The password of the keystore | +| `ANDROID_KEY_ALIAS` | The alias of the upload key | +| `ANDROID_KEY_PASSWORD` | The password of the upload key | + +
+ +Your app's Gradle build file must read these variables and sign release builds with them. A new Flutter app signs release builds with the debug key instead, which Google Play rejects. + +Add a `release` signing config to `android/app/build.gradle.kts` that reads the variables, and use it for release builds: + +```kotlin title="android/app/build.gradle.kts" +android { + // ... + + val isServerpodCloudBuild = System.getenv("SERVERPOD_APP_BUILD") != null + + signingConfigs { + if (isServerpodCloudBuild) { + create("release") { + storeFile = file(System.getenv("ANDROID_KEYSTORE_PATH")) + storePassword = System.getenv("ANDROID_KEYSTORE_PASSWORD") + keyAlias = System.getenv("ANDROID_KEY_ALIAS") + keyPassword = System.getenv("ANDROID_KEY_PASSWORD") + } + } + } + + buildTypes { + release { + signingConfig = if (isServerpodCloudBuild) { + signingConfigs.getByName("release") + } else { + signingConfigs.getByName("debug") + } + } + } +} +``` + +Serverpod Cloud sets `SERVERPOD_APP_BUILD` on its builds, so release builds on your computer keep using the debug key. Apps created with `serverpod create` already include this setup. + +The `app doctor` command checks that your Gradle build file names all four variables. You can read them in any way Gradle supports, such as `providers.environmentVariable("ANDROID_KEY_ALIAS")` or, in a Groovy `build.gradle`, `System.getenv('ANDROID_KEY_ALIAS')`. + +### iOS export compliance {#ios-export-compliance} + +App Store Connect asks whether each build uses encryption, because apps that use some kinds of encryption need export compliance documentation. Until a build answers it, App Store Connect holds the build and your testers can't install it. + +Answer it once in your app's `ios/Runner/Info.plist`, inside the top-level ``. If your app uses no encryption, or only encryption that is exempt, such as HTTPS calls to your server, set `ITSAppUsesNonExemptEncryption` to `false`: + +```xml title="ios/Runner/Info.plist" +ITSAppUsesNonExemptEncryption + +``` + +If your app uses encryption that isn't exempt, set it to `` and provide the documentation in App Store Connect. Apple's [ITSAppUsesNonExemptEncryption reference](https://developer.apple.com/documentation/bundleresources/information-property-list/itsappusesnonexemptencryption) explains which encryption is exempt. + +### App icon {#app-icon} + +A new Flutter app has the Flutter logo as its icon. Testers see this icon on their home screen, and the stores show it on your app's listing. The `app doctor` command warns while your app still has it. + +Replace the icon files on each platform: + +- **Android:** The `ic_launcher.png` files in the `mipmap-*` folders of `android/app/src/main/res`. +- **iOS:** The images in `ios/Runner/Assets.xcassets/AppIcon.appiconset`. + +Each platform needs the icon in several sizes. A package such as [flutter_launcher_icons](https://pub.dev/packages/flutter_launcher_icons) creates every size for both platforms from one image. + +## Related + +- [Deployments](/cloud/concepts/deployments): how to deploy the server your app talks to. +- [scloud.yaml schema](/cloud/reference/scloud-yaml-schema): the project configuration file the `app` commands read. From d365f4f7fc34ca495674593a84deee45b8089e66 Mon Sep 17 00:00:00 2001 From: Crazelu Date: Sat, 14 Nov 2026 16:39:32 +0100 Subject: [PATCH 02/12] docs: Say that app doctor checks for the debug key --- cloud_docs/concepts/app-publishing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cloud_docs/concepts/app-publishing.md b/cloud_docs/concepts/app-publishing.md index c74ab750..e54291d6 100644 --- a/cloud_docs/concepts/app-publishing.md +++ b/cloud_docs/concepts/app-publishing.md @@ -197,7 +197,7 @@ android { Serverpod Cloud sets `SERVERPOD_APP_BUILD` on its builds, so release builds on your computer keep using the debug key. Apps created with `serverpod create` already include this setup. -The `app doctor` command checks that your Gradle build file names all four variables. You can read them in any way Gradle supports, such as `providers.environmentVariable("ANDROID_KEY_ALIAS")` or, in a Groovy `build.gradle`, `System.getenv('ANDROID_KEY_ALIAS')`. +The `app doctor` command checks that your release build type doesn't sign with the debug key alone, and that your Gradle build file names all four variables. You can read them in any way Gradle supports, such as `providers.environmentVariable("ANDROID_KEY_ALIAS")` or, in a Groovy `build.gradle`, `System.getenv('ANDROID_KEY_ALIAS')`. ### iOS export compliance {#ios-export-compliance} From 5870249c8a077d71a25d89309ec518d1fb98eb78 Mon Sep 17 00:00:00 2001 From: Crazelu Date: Sat, 14 Nov 2026 16:44:13 +0100 Subject: [PATCH 03/12] docs: Add the Limits section to the App publishing page --- cloud_docs/concepts/app-publishing.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/cloud_docs/concepts/app-publishing.md b/cloud_docs/concepts/app-publishing.md index e54291d6..aa368626 100644 --- a/cloud_docs/concepts/app-publishing.md +++ b/cloud_docs/concepts/app-publishing.md @@ -223,6 +223,12 @@ Replace the icon files on each platform: Each platform needs the icon in several sizes. A package such as [flutter_launcher_icons](https://pub.dev/packages/flutter_launcher_icons) creates every size for both platforms from one image. +## Limits + +- **Platforms:** App publishing builds for iOS and Android only. +- **First Android build:** Google Play only accepts the first build of a new app from Play Console. Download it with `app artifacts` and upload it in Play Console once. Later builds upload on their own. +- **Monthly builds:** Each plan includes a number of app builds per month. When they are used up, `app publish` stops with an error until the next month. + ## Related - [Deployments](/cloud/concepts/deployments): how to deploy the server your app talks to. From 64748aa3aa8078b25acc3497a77f624b61377f2c Mon Sep 17 00:00:00 2001 From: Crazelu Date: Sat, 14 Nov 2026 17:06:08 +0100 Subject: [PATCH 04/12] docs: Drop the manual first Android build from the App publishing page --- cloud_docs/concepts/app-publishing.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/cloud_docs/concepts/app-publishing.md b/cloud_docs/concepts/app-publishing.md index aa368626..3960d8f1 100644 --- a/cloud_docs/concepts/app-publishing.md +++ b/cloud_docs/concepts/app-publishing.md @@ -31,7 +31,7 @@ Releasing a build from TestFlight or the internal testing track to the public st Before you can publish for a platform, connect its store in the [Serverpod Cloud console](https://console.serverpod.dev). Open your project, then open the **App Stores** tab. Each store has a setup guide that walks you through the steps: - **App Store:** Join the Apple Developer Program, register your app's bundle ID, create the app in App Store Connect, and add an App Store Connect API key. Only the project owner can add the key. -- **Google Play:** Sign up for Play Console, create the app, choose an upload key, and invite Serverpod Cloud's service account to your app in Play Console. Serverpod Cloud can create the upload key for you, or you can upload the keystore you already sign the app with. +- **Google Play:** Sign up for Play Console, create the app with your app's package name, choose an upload key, and invite Serverpod Cloud's service account to your app in Play Console. Serverpod Cloud can create the upload key for you, or you can upload the keystore you already sign the app with. The `app doctor` command shows whether each connection is complete, and links to the setup guide when it isn't. @@ -226,7 +226,6 @@ Each platform needs the icon in several sizes. A package such as [flutter_launch ## Limits - **Platforms:** App publishing builds for iOS and Android only. -- **First Android build:** Google Play only accepts the first build of a new app from Play Console. Download it with `app artifacts` and upload it in Play Console once. Later builds upload on their own. - **Monthly builds:** Each plan includes a number of app builds per month. When they are used up, `app publish` stops with an error until the next month. ## Related From 939dbb3a5189276aede604dbe9ef7ccc42f1b974 Mon Sep 17 00:00:00 2001 From: Crazelu Date: Mon, 16 Nov 2026 18:56:26 +0100 Subject: [PATCH 05/12] docs: Unlist the App publishing page until launch --- cloud_docs/concepts/app-publishing.md | 1 + 1 file changed, 1 insertion(+) diff --git a/cloud_docs/concepts/app-publishing.md b/cloud_docs/concepts/app-publishing.md index 3960d8f1..40c9aad1 100644 --- a/cloud_docs/concepts/app-publishing.md +++ b/cloud_docs/concepts/app-publishing.md @@ -1,5 +1,6 @@ --- sidebar_position: 11 +unlisted: true description: Serverpod Cloud builds your Flutter app and uploads it to TestFlight and Google Play. Check the setup with app doctor, then publish from the CLI. --- From 29e6b619ee852e6f78f8db1bdf6b68ee34ac5ab0 Mon Sep 17 00:00:00 2001 From: Crazelu Date: Mon, 16 Nov 2026 18:56:26 +0100 Subject: [PATCH 06/12] docs: Apply review wording to the App publishing page --- cloud_docs/concepts/app-publishing.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/cloud_docs/concepts/app-publishing.md b/cloud_docs/concepts/app-publishing.md index 40c9aad1..c360775e 100644 --- a/cloud_docs/concepts/app-publishing.md +++ b/cloud_docs/concepts/app-publishing.md @@ -8,7 +8,7 @@ description: Serverpod Cloud builds your Flutter app and uploads it to TestFligh Getting a Flutter app to testers means signing builds, matching store settings, and uploading to TestFlight and Google Play. With app publishing, you run one command: Serverpod Cloud builds your Flutter app for iOS and Android, signs it, and uploads it to the stores you connected in the console. -You publish from the Cloud CLI. The `app doctor` command checks your app's setup before you publish, and each problem it reports links to a section of this page. +You publish from the Cloud CLI. The `app doctor` command checks your app's setup before you publish and tells you how to fix each problem it finds. ## What app publishing does @@ -79,7 +79,7 @@ Publish your app from your project's directory: serverpod cloud app publish ``` -The command builds every platform your app has code for, and stops with a link to the setup guide if a platform's store isn't connected. It shows the progress of each build and ends when the builds are uploaded to the stores. To publish one platform, pass `--platforms`: +The command builds every platform your app has code for and whose store is connected. It skips a platform whose store isn't connected and prints a link to its setup guide. It shows the progress of each build and ends when the builds are uploaded to the stores. To publish one platform, pass `--platforms`: ```bash serverpod cloud app publish --platforms ios @@ -122,7 +122,7 @@ Serverpod Cloud builds your app with the first Flutter version it finds, in this 4. The version of the Flutter SDK on your computer. 5. The latest stable release. -To build with the version you develop with, pin it in your app's `pubspec.yaml`: +If none of the first three sets a version, the build uses the Flutter SDK on the computer you publish from. To build every publish with the same version, set it in your app's `pubspec.yaml`: ```yaml title="pubspec.yaml" environment: @@ -134,7 +134,7 @@ The version must be a Flutter release version, and it can't be lower than the Fl ### App identifiers {#app-identifiers} -The stores identify your app by its bundle ID on iOS and its package name on Android. Serverpod Cloud reads them from your Flutter app: the bundle ID from the Xcode project in `ios/`, and the package name from `applicationId` in `android/app/build.gradle.kts`. +The stores identify your app by its bundle ID on iOS and its package name on Android. Serverpod Cloud reads them from your Flutter app: the bundle ID from the Xcode project in `ios/`, and the package name from `applicationId` in `android/app/build.gradle.kts` or `build.gradle`. A new Flutter app uses a `com.example` placeholder, which the stores don't accept. Replace it with your own identifier, such as `com.yourcompany.yourapp`, in both places. The identifier must match the app you created in App Store Connect and Play Console. @@ -196,7 +196,7 @@ android { } ``` -Serverpod Cloud sets `SERVERPOD_APP_BUILD` on its builds, so release builds on your computer keep using the debug key. Apps created with `serverpod create` already include this setup. +Serverpod Cloud sets `SERVERPOD_APP_BUILD` on its builds, so release builds on your computer keep using the debug key. Apps created with `serverpod create` in Serverpod 4.1.2 or later already include this setup. The `app doctor` command checks that your release build type doesn't sign with the debug key alone, and that your Gradle build file names all four variables. You can read them in any way Gradle supports, such as `providers.environmentVariable("ANDROID_KEY_ALIAS")` or, in a Groovy `build.gradle`, `System.getenv('ANDROID_KEY_ALIAS')`. From 62d78b56d13a62d8607092bb17741c247d0222f5 Mon Sep 17 00:00:00 2001 From: Crazelu Date: Mon, 16 Nov 2026 18:56:26 +0100 Subject: [PATCH 07/12] docs: Move the app settings in scloud.yaml under project.app --- cloud_docs/concepts/app-publishing.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/cloud_docs/concepts/app-publishing.md b/cloud_docs/concepts/app-publishing.md index c360775e..8023893f 100644 --- a/cloud_docs/concepts/app-publishing.md +++ b/cloud_docs/concepts/app-publishing.md @@ -69,7 +69,7 @@ iOS A check marked `✗` makes the build or the upload fail, so fix it before you publish. A check marked `!` is a warning: the app can be published, but the result may not be what you want. -The command finds your Flutter app from `project.appDir` in `scloud.yaml`, the current directory, or your server's workspace. Pass `--app-dir` to check an app somewhere else, and `--platforms ios` or `--platforms android` to check one platform. +The command finds your Flutter app from `project.app.dir` in `scloud.yaml`, the current directory, or your server's workspace. Pass `--app-dir` to check an app somewhere else, and `--platforms ios` or `--platforms android` to check one platform. ## Publish your app @@ -118,7 +118,7 @@ Serverpod Cloud builds your app with the first Flutter version it finds, in this 1. The `--flutter-version` option of `app publish`, such as `--flutter-version 3.50.0`. 2. A single version in `environment.flutter` of your app's `pubspec.yaml`. -3. `project.flutterSdk` in `scloud.yaml`. +3. `project.app.flutterSdk` in `scloud.yaml`. 4. The version of the Flutter SDK on your computer. 5. The latest stable release. @@ -143,9 +143,10 @@ To publish with a different identifier than the one in your app's files, set it ```yaml title="scloud.yaml" project: projectId: my-project - appIdentifiers: - ios: com.yourcompany.yourapp - android: com.yourcompany.yourapp + app: + identifiers: + ios: com.yourcompany.yourapp + android: com.yourcompany.yourapp ``` ### Android release signing {#android-release-signing} From f3a08238692e8f111ea70132a167af569f0058e3 Mon Sep 17 00:00:00 2001 From: Crazelu Date: Mon, 16 Nov 2026 18:56:26 +0100 Subject: [PATCH 08/12] docs: Add app setup to the App publishing page --- cloud_docs/concepts/app-publishing.md | 24 +++++++++++++++++++++--- 1 file changed, 21 insertions(+), 3 deletions(-) diff --git a/cloud_docs/concepts/app-publishing.md b/cloud_docs/concepts/app-publishing.md index 8023893f..72381c95 100644 --- a/cloud_docs/concepts/app-publishing.md +++ b/cloud_docs/concepts/app-publishing.md @@ -1,14 +1,14 @@ --- sidebar_position: 11 unlisted: true -description: Serverpod Cloud builds your Flutter app and uploads it to TestFlight and Google Play. Check the setup with app doctor, then publish from the CLI. +description: Serverpod Cloud builds your Flutter app and uploads it to TestFlight and Google Play. Set up the app with app setup, check it with app doctor, then publish from the CLI. --- # App publishing Getting a Flutter app to testers means signing builds, matching store settings, and uploading to TestFlight and Google Play. With app publishing, you run one command: Serverpod Cloud builds your Flutter app for iOS and Android, signs it, and uploads it to the stores you connected in the console. -You publish from the Cloud CLI. The `app doctor` command checks your app's setup before you publish and tells you how to fix each problem it finds. +You publish from the Cloud CLI. The `app setup` command prepares your Flutter app for the stores, and the `app doctor` command checks your app's setup before you publish and tells you how to fix each problem it finds. ## What app publishing does @@ -36,6 +36,24 @@ Before you can publish for a platform, connect its store in the [Serverpod Cloud The `app doctor` command shows whether each connection is complete, and links to the setup guide when it isn't. +## Set up your app + +Run `app setup` from your project's directory to prepare your Flutter app for the stores: + +```bash +serverpod cloud app setup +``` + +For each platform, the command checks the [app identifier](#app-identifiers). If your app still uses Flutter's `com.example` placeholder, it asks for a new identifier and writes it into your app's files. It then saves the identifier to your Serverpod Cloud project. For Android, it also checks the [release signing](#android-release-signing). + +To set the identifiers without a prompt, such as in CI, pass them as options: + +```bash +serverpod cloud app setup --non-interactive --android-package-name com.yourcompany.yourapp --ios-bundle-id com.yourcompany.yourapp +``` + +Pass `--platforms ios` or `--platforms android` to set up one platform, and `--app-dir` to set up an app somewhere else. + ## Check your app with app doctor Run `app doctor` from your project's directory before you publish: @@ -136,7 +154,7 @@ The version must be a Flutter release version, and it can't be lower than the Fl The stores identify your app by its bundle ID on iOS and its package name on Android. Serverpod Cloud reads them from your Flutter app: the bundle ID from the Xcode project in `ios/`, and the package name from `applicationId` in `android/app/build.gradle.kts` or `build.gradle`. -A new Flutter app uses a `com.example` placeholder, which the stores don't accept. Replace it with your own identifier, such as `com.yourcompany.yourapp`, in both places. The identifier must match the app you created in App Store Connect and Play Console. +A new Flutter app uses a `com.example` placeholder, which the stores don't accept. Replace it with your own identifier, such as `com.yourcompany.yourapp`, in both places. The [`app setup`](#set-up-your-app) command does this for you. The identifier must match the app you created in App Store Connect and Play Console. To publish with a different identifier than the one in your app's files, set it in `scloud.yaml`: From ad1e8557fece25ee8cf546019eb0c5223905ecf7 Mon Sep 17 00:00:00 2001 From: Crazelu Date: Mon, 16 Nov 2026 18:56:26 +0100 Subject: [PATCH 09/12] docs: Document dart defines for app publish --- cloud_docs/concepts/app-publishing.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/cloud_docs/concepts/app-publishing.md b/cloud_docs/concepts/app-publishing.md index 72381c95..8bbaed3b 100644 --- a/cloud_docs/concepts/app-publishing.md +++ b/cloud_docs/concepts/app-publishing.md @@ -107,6 +107,27 @@ To start the builds and return right away, pass `--no-await`. The command then p If your Flutter app is part of a Dart workspace, the upload includes the workspace packages it depends on. To leave files out of the upload, list them in a [`.scloudignore` file](/cloud/concepts/deployments#configure-whats-included). +### Dart defines + +To build your app with compile-time values, pass them as with `flutter build`. Use `--dart-define` for one value, and `--dart-define-from-file` for a file in JSON or `.env` format: + +```bash +serverpod cloud app publish --dart-define-from-file .env --dart-define FLAVOR=production +``` + +You can repeat both options. A later file replaces the values of an earlier one, and a `--dart-define` value replaces the value of the same key from a file. + +To build every publish with the same files, set `dartDefineFromFile` in `scloud.yaml` to a path or a list of paths, relative to `scloud.yaml`. The `--dart-define-from-file` option replaces this setting: + +```yaml title="scloud.yaml" +project: + projectId: my-project + app: + dartDefineFromFile: .env +``` + +Serverpod Cloud always sets `SERVER_URL` to the URL of your project's server, so `getServerUrl` from `serverpod_flutter` connects the app to it. A `SERVER_URL` value you pass is ignored. + ## Follow your builds Each publish creates an app upload with one build per platform. The upload ID that `app publish` and `app list` print identifies it. Use these commands to follow the builds: From b2feefcffaf01a22462052c2a6a401a9457ccf19 Mon Sep 17 00:00:00 2001 From: Crazelu Date: Mon, 16 Nov 2026 18:56:26 +0100 Subject: [PATCH 10/12] docs: Count monthly app builds per project --- cloud_docs/concepts/app-publishing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cloud_docs/concepts/app-publishing.md b/cloud_docs/concepts/app-publishing.md index 8bbaed3b..d999d1c3 100644 --- a/cloud_docs/concepts/app-publishing.md +++ b/cloud_docs/concepts/app-publishing.md @@ -267,7 +267,7 @@ Each platform needs the icon in several sizes. A package such as [flutter_launch ## Limits - **Platforms:** App publishing builds for iOS and Android only. -- **Monthly builds:** Each plan includes a number of app builds per month. When they are used up, `app publish` stops with an error until the next month. +- **Monthly builds:** Your plan sets how many times you can publish each project per month. A publish counts once one of its builds succeeds, however many platforms it builds for, so a publish where every build fails doesn't count. The count resets on the first of each month, in UTC. ## Related From 8549a519b469609d8247e6328ffe09487f5f69db Mon Sep 17 00:00:00 2001 From: Crazelu Date: Mon, 16 Nov 2026 18:56:26 +0100 Subject: [PATCH 11/12] docs: Document the app settings in the scloud.yaml schema --- cloud_docs/reference/scloud-yaml-schema.md | 84 ++++++++++++++++++++-- 1 file changed, 78 insertions(+), 6 deletions(-) diff --git a/cloud_docs/reference/scloud-yaml-schema.md b/cloud_docs/reference/scloud-yaml-schema.md index a80c04ac..ee2bc1b5 100644 --- a/cloud_docs/reference/scloud-yaml-schema.md +++ b/cloud_docs/reference/scloud-yaml-schema.md @@ -6,9 +6,9 @@ description: "The schema for scloud.yaml: every key, its type, what the Cloud CL # scloud.yaml schema -A Serverpod project deployed to Serverpod Cloud has a `scloud.yaml` file at its root. The file links the local project to a Cloud project, optionally pins the Dart SDK used for builds, and lists commands to run before or after each deploy. +A Serverpod project deployed to Serverpod Cloud has a `scloud.yaml` file at its root. The file links the local project to a Cloud project, optionally pins the Dart SDK used for builds, configures how your Flutter app is published, and lists commands to run before or after each deploy. -Two commands write the file: `serverpod cloud launch` creates it on first setup, and `serverpod cloud project link` creates or updates it when you link your codebase to a Cloud project. You can also hand-edit it at any time, and the Cloud CLI preserves your `dartSdk` and hook scripts across later commands. See [How the Cloud CLI updates the file](#how-the-cloud-cli-updates-the-file) for the exact per-field rules. +Two commands write the file: `serverpod cloud launch` creates it on first setup, and `serverpod cloud project link` creates or updates it when you link your codebase to a Cloud project. You can also hand-edit it at any time, and the Cloud CLI preserves your `dartSdk`, app settings, and hook scripts across later commands. See [How the Cloud CLI updates the file](#how-the-cloud-cli-updates-the-file) for the exact per-field rules. ## File location @@ -33,7 +33,7 @@ The CLI keeps the header when it rewrites the file. ## Schema -One top-level key, `project`, with three fields. +One top-level key, `project`, with four fields. ### projectId @@ -57,6 +57,76 @@ project: dartSdk: "^3.10.3" ``` +### app + +**Type:** map. **Optional.** + +Holds the settings that the `serverpod cloud app` commands use to build and publish your Flutter app. See [App publishing](/cloud/concepts/app-publishing) for how publishing works. + +```yaml title="scloud.yaml" +project: + projectId: "my-app" + app: + dir: "../my_app_flutter" + flutterSdk: "3.50.0" + identifiers: + ios: "com.yourcompany.yourapp" + android: "com.yourcompany.yourapp" + dartDefineFromFile: ".env" +``` + +#### dir + +**Type:** string. **Optional.** + +The path of your Flutter app directory, relative to `scloud.yaml`. When unset, the CLI uses the current directory if it holds a Flutter app, or else the Flutter app in your server's workspace or next to your server directory. The `--app-dir` option replaces this setting. If the directory doesn't exist, the command stops with an error. + +```yaml title="scloud.yaml" +project: + app: + dir: "../my_app_flutter" +``` + +#### flutterSdk + +**Type:** string. **Optional.** + +The Flutter release version to build your app with, such as `3.50.0`. The `--flutter-version` option and a single version in `environment.flutter` of your app's `pubspec.yaml` take priority over this setting. See [Flutter version](/cloud/concepts/app-publishing#flutter-version) for the full selection order. + +```yaml title="scloud.yaml" +project: + app: + flutterSdk: "3.50.0" +``` + +#### identifiers + +**Type:** map with the optional string keys `ios` and `android`. **Optional.** + +The bundle ID (`ios`) and package name (`android`) to publish your app with, in place of the ones in your app's files. A platform without a value uses the identifier in your app's files. A value can't be empty or Flutter's `com.example` placeholder. See [App identifiers](/cloud/concepts/app-publishing#app-identifiers). + +```yaml title="scloud.yaml" +project: + app: + identifiers: + ios: "com.yourcompany.yourapp" + android: "com.yourcompany.yourapp" +``` + +#### dartDefineFromFile + +**Type:** string or list of strings. **Optional.** + +The files with the dart defines to build your app with, in JSON or `.env` format. Each path is relative to `scloud.yaml`. The CLI reads a list in order, and a later file replaces the values of an earlier one. The `--dart-define-from-file` option replaces this setting. See [Dart defines](/cloud/concepts/app-publishing#dart-defines). + +```yaml title="scloud.yaml" +project: + app: + dartDefineFromFile: + - ".env" + - ".env.production" +``` + ### scripts **Type:** map. **Optional.** @@ -136,10 +206,11 @@ Both `serverpod cloud launch` and `serverpod cloud project link` rewrite `scloud - **`projectId`** is set to the project the command targets. Treat it as managed by the CLI. Hand-edits won't survive the next run. - **`dartSdk`** is preserved as you wrote it, unless the command sets a new value. +- **`app`** is preserved entirely. - **`scripts.pre_deploy`** is merged. Your custom hooks are kept. Hooks that the CLI considers "suggested" (for example `serverpod generate` for projects that need it) are re-added on every run, even if you removed them. - **`scripts.post_deploy`** is preserved entirely. -In practice, hand-edit `dartSdk` and `post_deploy` freely, and add your own `pre_deploy` hooks alongside any suggested ones. Editing `projectId` by hand has no lasting effect. To change which project the file points at, use `serverpod cloud project link`. +In practice, hand-edit `dartSdk`, `app`, and `post_deploy` freely, and add your own `pre_deploy` hooks alongside any suggested ones. Editing `projectId` by hand has no lasting effect. To change which project the file points at, use `serverpod cloud project link`. ## Validation errors @@ -161,17 +232,18 @@ At path "project.projectId": Expected String, got int A field's value is the wrong type. The path tells you which field; the expected and actual types tell you what to change. -### Wrong format for a script field +### Wrong format for a string-or-list field ```text At path "project.scripts.pre_deploy": Expected one of String, [String] ``` -The `pre_deploy` or `post_deploy` value is neither a string nor a list of strings. Change it to either form (see [`pre_deploy`](#pre_deploy) for examples). +The `pre_deploy`, `post_deploy`, or `app.dartDefineFromFile` value is neither a string nor a list of strings. Change it to either form (see [`pre_deploy`](#pre_deploy) and [`dartDefineFromFile`](#dartdefinefromfile) for examples). ## Related - [Project identifier rules](/cloud/reference/project-id-rules) - [Dart SDK versions](/cloud/reference/dart-sdk-versions) +- [App publishing](/cloud/concepts/app-publishing) - [Deployment hooks](/cloud/concepts/deployment-hooks) - [CLI reference: `project` command](/cloud/reference/cli/commands/project) From 7bcb01f306e3a87d63beca36a5c7a67239b44e2a Mon Sep 17 00:00:00 2001 From: Crazelu Date: Tue, 17 Nov 2026 13:28:47 +0100 Subject: [PATCH 12/12] chore: list app publishing in sidebar --- cloud_docs/concepts/app-publishing.md | 1 - 1 file changed, 1 deletion(-) diff --git a/cloud_docs/concepts/app-publishing.md b/cloud_docs/concepts/app-publishing.md index d999d1c3..bcea8323 100644 --- a/cloud_docs/concepts/app-publishing.md +++ b/cloud_docs/concepts/app-publishing.md @@ -1,6 +1,5 @@ --- sidebar_position: 11 -unlisted: true description: Serverpod Cloud builds your Flutter app and uploads it to TestFlight and Google Play. Set up the app with app setup, check it with app doctor, then publish from the CLI. ---