Start here

Build configuration

Last updated 14 September 2026

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
Each command runs in the same shell, so a variable set in one line is still there on the next. That also means a cd in one command affects the ones after it.

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:

VariableValue
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_REPOSITORYowner/name
MBC_BRANCHThe branch or tag being built
MBC_COMMITThe commit SHA, when we know it
CItrue — many tools switch off prompts and progress animations when they see it
MACBUILDCLOUDtrue, 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
LimitValueWhat happens past it
One artifact500 MBThat file is rejected; the build continues
One build, all artifacts1 GBFurther files are rejected
Your account, all artifacts20 GBNew artifacts are rejected until older ones expire
Retention30 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

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 cachedSize / filesWithout cacheWith cache
A signed iOS app, DerivedData161 MB1m 03s1m 05s — 2s slower
A Flutter app, DerivedData296 MB / 1,953 files20s16s
node_modules281 MB / 23,238 files4s8s — 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:

The rules

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.

imageWhat 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-v3Xcode 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

LimitFree minutesPaid
One build may run for30 minutes2 hours
Builds at the same time11, or one per seat
Builds waiting in your queue50
Build log20 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.


Something here wrong or missing? Tell us — we read every message, and documentation fixes go out the same day.