@radhya/mach 1.8.3 → 1.8.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +83 -57
  2. package/dist/index.js +174 -97
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -26,23 +26,23 @@ mach build --platform android
26
26
 
27
27
  ## Commands
28
28
 
29
- | Command | Description |
30
- |---------|-------------|
31
- | `mach login` | Authenticate with Mach Dashboard |
32
- | `mach init` | Create a new Mach project |
33
- | `mach link` | Link local directory to an existing project |
34
- | `mach me` | Show current logged-in user |
35
- | `mach build` | Start a cloud build (iOS / Android) |
36
- | `mach maestro` | Queue managed Maestro tests for a build or artifact |
37
- | `mach submit` | Submit to App Store or Google Play |
38
- | `mach credentials` | Manage iOS certificates, provisioning profiles & Android keystores |
39
- | `mach credentials:service` | Upload App Store Connect or Google Play service credentials |
40
- | `mach env` | Manage environment variables and secrets |
41
- | `mach config` | Show resolved configuration for a build profile |
42
- | `mach start` | Start the Metro development server |
43
- | `mach device` | Register test devices for ad-hoc distribution |
44
- | `mach audit` | Run automated security checks on your project |
45
- | `mach agent` | Start the local device discovery agent for Install Hub |
29
+ | Command | Description |
30
+ | -------------------------- | ------------------------------------------------------------------ |
31
+ | `mach login` | Authenticate with Mach Dashboard |
32
+ | `mach init` | Create a new Mach project |
33
+ | `mach link` | Link local directory to an existing project |
34
+ | `mach me` | Show current logged-in user |
35
+ | `mach build` | Start a cloud build (iOS / Android) |
36
+ | `mach maestro` | Queue managed Maestro tests for a build or artifact |
37
+ | `mach submit` | Submit to App Store or Google Play |
38
+ | `mach credentials` | Manage iOS certificates, provisioning profiles & Android keystores |
39
+ | `mach credentials:service` | Upload App Store Connect or Google Play service credentials |
40
+ | `mach env` | Manage environment variables and secrets |
41
+ | `mach config` | Show resolved configuration for a build profile |
42
+ | `mach start` | Start the Metro development server |
43
+ | `mach device` | Register test devices for ad-hoc distribution |
44
+ | `mach audit` | Run automated security checks on your project |
45
+ | `mach agent` | Start the local device discovery agent for Install Hub |
46
46
 
47
47
  ## Managed Maestro Testing
48
48
 
@@ -73,16 +73,16 @@ mach build --platform ios --local
73
73
 
74
74
  ### Build Options
75
75
 
76
- | Flag | Description |
77
- |------|-------------|
78
- | `--platform` | `ios` or `android` (required) |
79
- | `--profile` | Build profile from `mach.config.json` (default: `production`) |
80
- | `--local` | Run build on local machine |
81
- | `--dry-run` | Generate build script without running it |
82
- | `--simulator` | iOS Simulator build (no signing needed) |
83
- | `--auto-version` | Force Android versionCode lookup via Google Play API |
84
- | `--verbose` | Enable detailed build logging |
85
- | `--json-output` | Write build metadata (`buildId`, Dashboard URL, status) to a JSON file for CI/CD |
76
+ | Flag | Description |
77
+ | ---------------- | -------------------------------------------------------------------------------- |
78
+ | `--platform` | `ios` or `android` (required) |
79
+ | `--profile` | Build profile from `mach.config.json` (default: `production`) |
80
+ | `--local` | Run build on local machine |
81
+ | `--dry-run` | Generate build script without running it |
82
+ | `--simulator` | iOS Simulator build (no signing needed) |
83
+ | `--auto-version` | Force Android versionCode lookup via Google Play API |
84
+ | `--verbose` | Enable detailed build logging |
85
+ | `--json-output` | Write build metadata (`buildId`, Dashboard URL, status) to a JSON file for CI/CD |
86
86
 
87
87
  ### CI Build URLs
88
88
 
@@ -140,23 +140,39 @@ definitions:
140
140
  script:
141
141
  - npm ci
142
142
  - npm install -g @radhya/mach@latest
143
- - mach submit --latest --platform android --profile $MACH_SUBMIT_PROFILE --track ${MACH_ANDROID_TRACK:-internal} --release-status ${MACH_ANDROID_RELEASE_STATUS:-completed}
143
+ - mach submit --latest --platform android --profile $MACH_SUBMIT_PROFILE --track ${MACH_ANDROID_TRACK:-internal} --release-status ${MACH_ANDROID_RELEASE_STATUS:-completed} ${MACH_ANDROID_ROLLOUT:+--rollout $MACH_ANDROID_ROLLOUT} ${MACH_ANDROID_CHANGES_NOT_SENT_FOR_REVIEW:+--changes-not-sent-for-review}
144
144
  ```
145
145
 
146
+ Android submission uses the Google Play Developer API directly, so Bitbucket/Linux runners do not need Ruby or Fastlane for `.aab` uploads. iOS submission still uses Fastlane `pilot`; run it on the macOS GitLab runner, the same runner class used for iOS builds.
147
+
146
148
  Required Bitbucket variables:
147
149
 
148
- | Variable | Required | Description |
149
- |----------|----------|-------------|
150
- | `MACH_TOKEN` | Yes | Dashboard access token for CI/CD auth |
151
- | `MACH_BUILD_PROFILE` | Yes | Build profile from `mach.config.json`, e.g. `production` |
152
- | `MACH_SUBMIT_PROFILE` | Yes | Profile used by `mach submit --latest`, e.g. `production` |
153
- | `MACH_ANDROID_TRACK` | Android submit | Google Play track, e.g. `internal`, `alpha`, `beta`, `production` |
154
- | `MACH_ANDROID_RELEASE_STATUS` | Android submit | Google Play release status: `completed`, `draft`, `halted`, or `inProgress` |
155
- | `SLACK_WEBHOOK_URL` | Slack | Incoming webhook for build notifications |
156
- | `SLACK_MESSAGE_PREFIX` | Slack | Message prefix such as project/environment name |
150
+ | Variable | Required | Description |
151
+ | ------------------------------------------ | -------------- | --------------------------------------------------------------------------- |
152
+ | `MACH_TOKEN` | Yes | Dashboard access token for CI/CD auth |
153
+ | `MACH_BUILD_PROFILE` | Yes | Build profile from `mach.config.json`, e.g. `production` |
154
+ | `MACH_SUBMIT_PROFILE` | Yes | Profile used by `mach submit --latest`, e.g. `production` |
155
+ | `MACH_ANDROID_TRACK` | Android submit | Google Play track, e.g. `internal`, `alpha`, `beta`, `production` |
156
+ | `MACH_ANDROID_RELEASE_STATUS` | Android submit | Google Play release status: `completed`, `draft`, `halted`, or `inProgress` |
157
+ | `MACH_ANDROID_ROLLOUT` | Android submit | Optional staged rollout fraction for `inProgress`, e.g. `0.1` |
158
+ | `MACH_ANDROID_CHANGES_NOT_SENT_FOR_REVIEW` | Android submit | Optional flag to commit Play changes without automatically sending review |
159
+ | `SLACK_WEBHOOK_URL` | Slack | Incoming webhook for build notifications |
160
+ | `SLACK_MESSAGE_PREFIX` | Slack | Message prefix such as project/environment name |
157
161
 
158
162
  Before enabling CI, make sure `mach.config.json` is committed, credentials are uploaded in the Dashboard, and Android service credentials are attached to the exact package id.
159
163
 
164
+ For iOS submit, use a macOS GitLab runner:
165
+
166
+ ```yaml
167
+ submit_ios:
168
+ tags:
169
+ - macos
170
+ script:
171
+ - npm ci
172
+ - npm install -g @radhya/mach@latest
173
+ - mach submit --latest --platform ios --profile $MACH_SUBMIT_PROFILE
174
+ ```
175
+
160
176
  ## Credential Management
161
177
 
162
178
  Manage iOS certificates, provisioning profiles, Android keystores, and App Store Connect API keys — all stored securely in the Dashboard.
@@ -236,8 +252,8 @@ Create a `mach.config.json` in your project root:
236
252
  "production": {
237
253
  "android": { "track": "internal", "releaseStatus": "completed" },
238
254
  "ios": {
239
- "ascAppId": "1234567890",
240
- "appleTeamId": "XXXXXXXXXX"
255
+ "ascAppId": "",
256
+ "appleTeamId": ""
241
257
  }
242
258
  }
243
259
  }
@@ -246,22 +262,22 @@ Create a `mach.config.json` in your project root:
246
262
 
247
263
  ### Root Properties
248
264
 
249
- | Property | Description |
250
- |----------|-------------|
251
- | `projectId` | Auto-generated UUID linking to your Dashboard project |
252
- | `name` | App display name |
265
+ | Property | Description |
266
+ | ------------- | --------------------------------------------------------------------------------------------------------------- |
267
+ | `projectId` | Auto-generated UUID linking to your Dashboard project |
268
+ | `name` | App display name |
253
269
  | `nodeVersion` | Node.js version to use on the build machine (e.g. `"24"`, `"20.11.0"`). Switches via nvm before installing deps |
254
270
 
255
271
  ### Profile Properties
256
272
 
257
- | Property | Description |
258
- |----------|-------------|
259
- | `extends` | Inherit settings from another profile |
260
- | `environment` | Dashboard Secret Environment to use (`development`, `staging`, `production`) |
261
- | `developmentClient` | `true` to build with `expo-dev-client` |
262
- | `distribution` | `internal` for installable/testing builds or `store` for App Store / Play Store release builds |
263
- | `preBuild` / `postBuild` | Shell command or script reference to run around the build |
264
- | `envGroups` | Array of environment group names to merge into this profile |
273
+ | Property | Description |
274
+ | ------------------------ | ---------------------------------------------------------------------------------------------- |
275
+ | `extends` | Inherit settings from another profile |
276
+ | `environment` | Dashboard Secret Environment to use (`development`, `staging`, `production`) |
277
+ | `developmentClient` | `true` to build with `expo-dev-client` |
278
+ | `distribution` | `internal` for installable/testing builds or `store` for App Store / Play Store release builds |
279
+ | `preBuild` / `postBuild` | Shell command or script reference to run around the build |
280
+ | `envGroups` | Array of environment group names to merge into this profile |
265
281
 
266
282
  ### Environment Groups
267
283
 
@@ -317,11 +333,13 @@ Mach can automatically determine the next `versionCode` by querying Google Play
317
333
  **Setup:** Upload a Google Service Account JSON via `mach credentials` → Service Credentials for the exact Android package being queried.
318
334
 
319
335
  **Usage:**
336
+
320
337
  ```bash
321
338
  mach build --platform android --auto-version
322
339
  ```
323
340
 
324
341
  Or in config:
342
+
325
343
  ```json
326
344
  "android": { "versionCode": "auto" }
327
345
  ```
@@ -342,6 +360,12 @@ mach submit --latest --platform ios --profile production
342
360
  # Android track and release status can be supplied on the command or in mach.config.json
343
361
  mach submit --latest --platform android --profile production --track internal --release-status completed
344
362
 
363
+ # Staged rollout example
364
+ mach submit --latest --platform android --profile production --track production --release-status inProgress --rollout 0.1
365
+
366
+ # If Play asks for explicit review handling
367
+ mach submit --latest --platform android --profile production --track internal --changes-not-sent-for-review
368
+
345
369
  # Submit a specific build id
346
370
  mach submit --platform android --build-id <build-id>
347
371
  ```
@@ -352,7 +376,9 @@ For Android, Mach resolves the package from `mach.config.json` / Expo config and
352
376
  mach credentials:service --platform android --package-name com.example.app --file ~/Downloads/play-service-account.json
353
377
  ```
354
378
 
355
- Android submit reads `submit.<profile>.android.track` and `submit.<profile>.android.releaseStatus`, falling back to `submit.production.android.*`, then `internal` / `completed`. Valid Google Play release status values are `completed`, `draft`, `halted`, and `inProgress`.
379
+ Android submit reads `submit.<profile>.android.track`, `submit.<profile>.android.releaseStatus`, and optional `submit.<profile>.android.rollout`, falling back to `submit.production.android.*`, then `internal` / `completed`. Valid Google Play release status values are `completed`, `draft`, `halted`, and `inProgress`. Use `rollout` only with `inProgress` or `halted`; it must be greater than `0` and less than `1`.
380
+
381
+ Android submit does not require Fastlane. Mach uploads the `.aab`, assigns the returned `versionCode` to the requested track, and commits the edit through the Google Play Developer API. Transient Google Play failures are retried up to four times before the command fails. iOS submit uses Fastlane `pilot`; run it from a macOS GitLab runner. If `--ssh-host` or `submit.<profile>.ios.sshHost` is set, Mach can also upload the `.ipa` and App Store Connect API key to that macOS runner, run `pilot` remotely, then remove the remote temp files.
356
382
 
357
383
  If `--profile` is provided with `--latest`, Mach chooses the latest successful build from that profile only. This avoids accidentally submitting a staging or preprod build to production.
358
384
 
@@ -408,11 +434,11 @@ mach submit --latest --platform android --profile production
408
434
 
409
435
  ## Environment Variables Reference
410
436
 
411
- | Variable | Description |
412
- |----------|-------------|
413
- | `MACH_TOKEN` | Personal access token for CI/CD (skips login) |
414
- | `MACH_DEBUG` | Set to `1` to print resolved build profile and platform details |
415
- | `MACH_P12_PASSWORD` | iOS certificate password (avoids interactive prompt) |
437
+ | Variable | Description |
438
+ | ------------------- | --------------------------------------------------------------- |
439
+ | `MACH_TOKEN` | Personal access token for CI/CD (skips login) |
440
+ | `MACH_DEBUG` | Set to `1` to print resolved build profile and platform details |
441
+ | `MACH_P12_PASSWORD` | iOS certificate password (avoids interactive prompt) |
416
442
 
417
443
  ## Requirements
418
444