diff --git a/cloud_docs/concepts/app-publishing.md b/cloud_docs/concepts/app-publishing.md
new file mode 100644
index 00000000..bcea8323
--- /dev/null
+++ b/cloud_docs/concepts/app-publishing.md
@@ -0,0 +1,274 @@
+---
+sidebar_position: 11
+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 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
+
+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 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.
+
+## 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:
+
+```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.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
+
+Publish your app from your project's directory:
+
+```bash
+serverpod cloud app publish
+```
+
+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
+```
+
+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).
+
+### 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:
+
+
+
+| 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.app.flutterSdk` in `scloud.yaml`.
+4. The version of the Flutter SDK on your computer.
+5. The latest stable release.
+
+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:
+ 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` 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 [`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`:
+
+```yaml title="scloud.yaml"
+project:
+ projectId: my-project
+ app:
+ identifiers:
+ 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` 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')`.
+
+### 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.
+
+## Limits
+
+- **Platforms:** App publishing builds for iOS and Android only.
+- **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
+
+- [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.
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)