Build configuration
Everything the .macbuildcloud.yml file understands, and the limits that apply to each part.
Put the file in the root of your repository. You can also paste the same content into the repository page on your dashboard — if both exist, the dashboard version wins, which lets you iterate on a broken build without pushing a commit each time.
01The smallest useful file
script:
- echo "hello from a real Mac"
- sw_vers
script is the only required section. Every other section is optional.
02script
Shell commands, run in order, in the root of your checkout. The build stops at the first command that exits non-zero, and that exit code becomes the build's exit code.
Long commands can be wrapped with a trailing backslash:
script:
- xcodebuild -project MyApp.xcodeproj -scheme MyApp \
-configuration Release \
-destination "generic/platform=iOS" \
build
03env
Environment variables available to every command. Values are not secret — they sit in your repository. For anything sensitive use secrets instead.
env:
FLAVOR: release
API_URL: "https://api.example.com"
Every build also gets these, set by us:
| Variable | Value |
|---|---|
| MBC_BUILD_NUMBER | A number that is different for every build and only ever goes up. Use it as your build number: TestFlight and Google Play refuse an upload whose build number they have already seen. |
| MBC_REPOSITORY | owner/name |
| MBC_BRANCH | The branch or tag being built |
| MBC_COMMIT | The commit SHA, when we know it |
| CI | true — many tools switch off prompts and progress animations when they see it |
| MACBUILDCLOUD | true, if your script needs to know where it is running |
script:
- flutter build ipa --build-number=$MBC_BUILD_NUMBER
04artifacts
Files to keep when the build finishes. Paths are relative to your checkout and may use wildcards. A directory, such as an .app bundle, is packed for you and arrives as a .tar.gz: Runner.app is downloaded as Runner.app.tar.gz.
artifacts:
- build/MyApp.ipa
- build/*.dSYM.zip
| Limit | Value | What happens past it |
|---|---|---|
| One artifact | 500 MB | That file is rejected; the build continues |
| One build, all artifacts | 1 GB | Further files are rejected |
| Your account, all artifacts | 20 GB | New artifacts are rejected until older ones expire |
| Retention | 30 days, or shorter if you set it | Deleted automatically, from disk and from the database. Change it under Activity & data in your account — you can make it shorter than 30 days, not longer. |
Artifacts are encrypted at rest. Downloads are available to your team from the dashboard, and you can create a share link that works without a login for 24 hours — or fewer, if you shorten it under Activity & data. A link keeps the lifetime it had when you created it, so changing the setting never kills links you already sent.
Every download, share link and build trigger is recorded in your account's activity log, which you can read and export as CSV from the same page.
05tests
Paths to JUnit XML reports. We read them after the build and show the totals and the failing cases on the build page.
tests:
- build/reports/**/*.xml
We read at most 40 files, 8 MB each, and show the first 50 failures. Reports are parsed on the build machine, not on our servers — your XML never reaches our control plane, only the counts and test names do.
06secrets and signing
Secrets are uploaded in the dashboard, never written in this file. Here you only name the ones this build may use.
secrets:
- SENTRY_TOKEN
signing:
certificate: DIST_CERT
profile: APPSTORE_PROFILE, WIDGET_PROFILE
- Names under secrets arrive as environment variables with the same name.
- certificate is imported into a throwaway keychain that exists only for this build.
- profile accepts several names separated by commas — an app with a widget or share extension needs one profile per bundle identifier.
Only the credentials named here are sent to the build machine. See code signing for the full walkthrough.
07cache
Folders to keep on the build machine between builds, so the next build does not rebuild or re-download them. Turn it on for the repository first — the switch is on your repository page. Until then this section is ignored.
cache:
- ~/Library/Developer/Xcode/DerivedData
- node_modules
- ios/Pods
Paths starting with ~/ are relative to the home folder on the build machine. Everything else is relative to your repository root. No wildcards: list each folder.
Whether it is worth turning on
Often it is not, and we would rather say so than let you find out. We measured this on our own hardware, on real projects:
| What was cached | Size / files | Without cache | With cache |
|---|---|---|---|
| A signed iOS app, DerivedData | 161 MB | 1m 03s | 1m 05s — 2s slower |
| A Flutter app, DerivedData | 296 MB / 1,953 files | 20s | 16s |
| node_modules | 281 MB / 23,238 files | 4s | 8s — twice as slow |
Restoring costs a second or two, and so does saving. If your build only takes a minute, that overhead is most of what the cache saves, and you can end up slightly behind — which is exactly what happened to the iOS app in the first row.
The rule of thumb: turn it on when a single build takes several minutes and most of that is compiling. Leave it off for short builds, and leave it off for folders your package manager fills.
Two things worth knowing:
- Measure before you cache packages. Unpacking a large cache can cost more than downloading the packages: caching node_modules made our test build take twice as long.
- A stale DerivedData can break a build in ways that look nothing like a cache problem. If a build starts failing for no reason you can see, press Clear cache on the repository page and build again. That is the first thing to try.
The rules
- At most 10 folders, 4 GB in total per repository. Over that, the cache is skipped and the build log says so.
- Saved only when a build succeeds — a half-installed folder never gets cached. If nothing in those folders changed since the cache was restored, we keep the one we have instead of writing it again.
- Kept on one build machine, encrypted on that machine with a key that is not stored there. Removed after 14 days without a build.
- Your next build is sent back to the machine that holds your cache. If that machine is busy or offline the build runs somewhere else and simply starts without a cache — we never make a build wait for one.
- Your source code is never kept. It goes with the virtual machine when the build ends, exactly as before.
08image
Which machine image to build on. Leave it out to get the default. Every build starts from a fresh copy of the image, so nothing from one build is left over for the next.
| image | What is on it |
|---|---|
macos-dual-xcode27.2-v1 (default) | Xcode 27.2 with the iOS 27.2 simulator, Flutter 3.47, Android SDK 36, Java 17, Ruby 4.0, CocoaPods 1.17, Node 24 |
macos-dual-xcode26.6-v3 | Xcode 26.6 with the iOS 26.5 simulator, Flutter 3.44, Android SDK 36, Java 17, Ruby 3.3, CocoaPods 1.16, Node 24 |
image: macos-dual-xcode26.6-v3
Near the top of every build log you can see which image the build ran on. If you name an image we do not offer, the build still runs, on the default image, and the log says so at the top. Build steps saved in the dashboard are checked when you save them.
In November 2026 the default moved from Xcode 26.6 to Xcode 27.2. That also moved Ruby from 3.3 to 4.0 and Flutter from 3.44 to 3.47. If a build that used to pass now fails, add the line above to stay on Xcode 26.6 while you sort it out; the previous image is still offered.
09Limits that apply to every build
| Limit | Free minutes | Paid |
|---|---|---|
| One build may run for | 30 minutes | 2 hours |
| Builds at the same time | 1 | 1, or one per seat |
| Builds waiting in your queue | 50 | |
| Build log | 20 MB, then truncated | |
Queue time is never billed. The clock starts when your first command runs and stops when the last one finishes.
10What is not allowed
The build machine can reach the internet and nothing else — not our systems, not other customers' machines. Outbound mail ports are blocked, and so are the ports mining pools commonly use.
We watch for crypto-mining software running in builds. A build that hits it is stopped; repeated hits pause the account. If we get that wrong, tell us and a person will read it — nothing of yours is deleted. The full rules are in the acceptable use policy.