@radhya/mach 1.8.4 → 1.8.12
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.
- package/README.md +109 -55
- package/dist/index.js +214 -101
- 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
|
|
30
|
-
|
|
31
|
-
| `mach login`
|
|
32
|
-
| `mach init`
|
|
33
|
-
| `mach link`
|
|
34
|
-
| `mach me`
|
|
35
|
-
| `mach build`
|
|
36
|
-
| `mach maestro`
|
|
37
|
-
| `mach submit`
|
|
38
|
-
| `mach credentials`
|
|
39
|
-
| `mach credentials:service` | Upload App Store Connect or Google Play service credentials
|
|
40
|
-
| `mach env`
|
|
41
|
-
| `mach config`
|
|
42
|
-
| `mach start`
|
|
43
|
-
| `mach device`
|
|
44
|
-
| `mach audit`
|
|
45
|
-
| `mach agent`
|
|
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
|
|
77
|
-
|
|
78
|
-
| `--platform`
|
|
79
|
-
| `--profile`
|
|
80
|
-
| `--local`
|
|
81
|
-
| `--dry-run`
|
|
82
|
-
| `--simulator`
|
|
83
|
-
| `--auto-version` | Force Android versionCode lookup via Google Play API
|
|
84
|
-
| `--verbose`
|
|
85
|
-
| `--json-output`
|
|
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,67 @@ 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. Mach still writes Android submission status to the submissions table, which gives the Dashboard the same history view without starting the macOS runner. iOS submission is queued through Mach and executed on the configured macOS GitLab runner, so the public command is the same from macOS, Linux, Windows, or CI.
|
|
147
|
+
|
|
146
148
|
Required Bitbucket variables:
|
|
147
149
|
|
|
148
|
-
| Variable
|
|
149
|
-
|
|
150
|
-
| `MACH_TOKEN`
|
|
151
|
-
| `MACH_BUILD_PROFILE`
|
|
152
|
-
| `MACH_SUBMIT_PROFILE`
|
|
153
|
-
| `MACH_ANDROID_TRACK`
|
|
154
|
-
| `MACH_ANDROID_RELEASE_STATUS`
|
|
155
|
-
| `
|
|
156
|
-
| `
|
|
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, the user-facing command is universal:
|
|
165
|
+
|
|
166
|
+
```bash
|
|
167
|
+
mach submit --latest --platform ios --profile $MACH_SUBMIT_PROFILE
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
The macOS runner executes the internal runner command after the Mach API triggers GitLab:
|
|
171
|
+
|
|
172
|
+
```yaml
|
|
173
|
+
skye_m4_ios_submit:
|
|
174
|
+
stage: submit
|
|
175
|
+
tags:
|
|
176
|
+
- m4-mini
|
|
177
|
+
- ios-build
|
|
178
|
+
rules:
|
|
179
|
+
- if: '$MACH_ACTION == "submit_ios"'
|
|
180
|
+
when: on_success
|
|
181
|
+
- when: never
|
|
182
|
+
script: |
|
|
183
|
+
source ~/.zshrc || source ~/.bashrc || true
|
|
184
|
+
export AWS_DEFAULT_REGION="ap-south-1"
|
|
185
|
+
|
|
186
|
+
export MACH_TOKEN=$(aws ssm get-parameter \
|
|
187
|
+
--name "/skye/submissions/$SUBMIT_ID/token" \
|
|
188
|
+
--with-decryption \
|
|
189
|
+
--query 'Parameter.Value' \
|
|
190
|
+
--region ap-south-1 \
|
|
191
|
+
--output text)
|
|
192
|
+
|
|
193
|
+
aws ssm delete-parameter --name "/skye/submissions/$SUBMIT_ID/token" --region ap-south-1 || true
|
|
194
|
+
|
|
195
|
+
if [ -n "${BUILD_ID:-}" ]; then
|
|
196
|
+
mach submit --local --submit-id "$SUBMIT_ID" --project-id "$PROJECT_ID" --platform ios --profile "${MACH_SUBMIT_PROFILE:-production}" --build-id "$BUILD_ID"
|
|
197
|
+
else
|
|
198
|
+
mach submit --local --submit-id "$SUBMIT_ID" --project-id "$PROJECT_ID" --platform ios --profile "${MACH_SUBMIT_PROFILE:-production}" --latest
|
|
199
|
+
fi
|
|
200
|
+
after_script:
|
|
201
|
+
- aws ssm delete-parameter --name "/skye/submissions/$SUBMIT_ID/token" --region ap-south-1 2>/dev/null || true
|
|
202
|
+
```
|
|
203
|
+
|
|
160
204
|
## Credential Management
|
|
161
205
|
|
|
162
206
|
Manage iOS certificates, provisioning profiles, Android keystores, and App Store Connect API keys — all stored securely in the Dashboard.
|
|
@@ -246,22 +290,22 @@ Create a `mach.config.json` in your project root:
|
|
|
246
290
|
|
|
247
291
|
### Root Properties
|
|
248
292
|
|
|
249
|
-
| Property
|
|
250
|
-
|
|
251
|
-
| `projectId`
|
|
252
|
-
| `name`
|
|
293
|
+
| Property | Description |
|
|
294
|
+
| ------------- | --------------------------------------------------------------------------------------------------------------- |
|
|
295
|
+
| `projectId` | Auto-generated UUID linking to your Dashboard project |
|
|
296
|
+
| `name` | App display name |
|
|
253
297
|
| `nodeVersion` | Node.js version to use on the build machine (e.g. `"24"`, `"20.11.0"`). Switches via nvm before installing deps |
|
|
254
298
|
|
|
255
299
|
### Profile Properties
|
|
256
300
|
|
|
257
|
-
| Property
|
|
258
|
-
|
|
259
|
-
| `extends`
|
|
260
|
-
| `environment`
|
|
261
|
-
| `developmentClient`
|
|
262
|
-
| `distribution`
|
|
263
|
-
| `preBuild` / `postBuild` | Shell command or script reference to run around the build
|
|
264
|
-
| `envGroups`
|
|
301
|
+
| Property | Description |
|
|
302
|
+
| ------------------------ | ---------------------------------------------------------------------------------------------- |
|
|
303
|
+
| `extends` | Inherit settings from another profile |
|
|
304
|
+
| `environment` | Dashboard Secret Environment to use (`development`, `staging`, `production`) |
|
|
305
|
+
| `developmentClient` | `true` to build with `expo-dev-client` |
|
|
306
|
+
| `distribution` | `internal` for installable/testing builds or `store` for App Store / Play Store release builds |
|
|
307
|
+
| `preBuild` / `postBuild` | Shell command or script reference to run around the build |
|
|
308
|
+
| `envGroups` | Array of environment group names to merge into this profile |
|
|
265
309
|
|
|
266
310
|
### Environment Groups
|
|
267
311
|
|
|
@@ -317,11 +361,13 @@ Mach can automatically determine the next `versionCode` by querying Google Play
|
|
|
317
361
|
**Setup:** Upload a Google Service Account JSON via `mach credentials` → Service Credentials for the exact Android package being queried.
|
|
318
362
|
|
|
319
363
|
**Usage:**
|
|
364
|
+
|
|
320
365
|
```bash
|
|
321
366
|
mach build --platform android --auto-version
|
|
322
367
|
```
|
|
323
368
|
|
|
324
369
|
Or in config:
|
|
370
|
+
|
|
325
371
|
```json
|
|
326
372
|
"android": { "versionCode": "auto" }
|
|
327
373
|
```
|
|
@@ -342,6 +388,12 @@ mach submit --latest --platform ios --profile production
|
|
|
342
388
|
# Android track and release status can be supplied on the command or in mach.config.json
|
|
343
389
|
mach submit --latest --platform android --profile production --track internal --release-status completed
|
|
344
390
|
|
|
391
|
+
# Staged rollout example
|
|
392
|
+
mach submit --latest --platform android --profile production --track production --release-status inProgress --rollout 0.1
|
|
393
|
+
|
|
394
|
+
# If Play asks for explicit review handling
|
|
395
|
+
mach submit --latest --platform android --profile production --track internal --changes-not-sent-for-review
|
|
396
|
+
|
|
345
397
|
# Submit a specific build id
|
|
346
398
|
mach submit --platform android --build-id <build-id>
|
|
347
399
|
```
|
|
@@ -352,7 +404,9 @@ For Android, Mach resolves the package from `mach.config.json` / Expo config and
|
|
|
352
404
|
mach credentials:service --platform android --package-name com.example.app --file ~/Downloads/play-service-account.json
|
|
353
405
|
```
|
|
354
406
|
|
|
355
|
-
Android submit reads `submit.<profile>.android.track` and `submit.<profile>.android.
|
|
407
|
+
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`.
|
|
408
|
+
|
|
409
|
+
Android submit does not require Fastlane. Mach uploads the `.aab`, assigns the returned `versionCode` to the requested track, commits the edit through the Google Play Developer API, and records the submission in the Dashboard. Transient Google Play failures are retried up to four times before the command fails. iOS submit queues a managed submission through Mach and runs Fastlane `pilot` on the macOS GitLab runner. Runner jobs call `mach submit --local ...`; users and CI call the normal `mach submit --platform ios ...` command. 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
410
|
|
|
357
411
|
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
412
|
|
|
@@ -408,11 +462,11 @@ mach submit --latest --platform android --profile production
|
|
|
408
462
|
|
|
409
463
|
## Environment Variables Reference
|
|
410
464
|
|
|
411
|
-
| Variable
|
|
412
|
-
|
|
413
|
-
| `MACH_TOKEN`
|
|
414
|
-
| `MACH_DEBUG`
|
|
415
|
-
| `MACH_P12_PASSWORD` | iOS certificate password (avoids interactive prompt)
|
|
465
|
+
| Variable | Description |
|
|
466
|
+
| ------------------- | --------------------------------------------------------------- |
|
|
467
|
+
| `MACH_TOKEN` | Personal access token for CI/CD (skips login) |
|
|
468
|
+
| `MACH_DEBUG` | Set to `1` to print resolved build profile and platform details |
|
|
469
|
+
| `MACH_P12_PASSWORD` | iOS certificate password (avoids interactive prompt) |
|
|
416
470
|
|
|
417
471
|
## Requirements
|
|
418
472
|
|