Getting Started

Get up and running with BuildMagic in minutes. This guide walks you through creating your account, connecting your repository, and running your first build.

Step 1: Create Your Account

Sign up with your GitHub or GitLab account, or with an email address and password. Connecting a Git provider is what lets BuildMagic browse and clone your repositories, so you will be asked for it either way.

  1. Go to the sign up page.
  2. Click Sign in with GitHub or Sign in with GitLab.
  3. Authorize BuildMagic to access your account.
  4. You'll be redirected to the dashboard with a default team already created for you.

Step 2: Connect Your Repository

Once signed in, your connected Git provider gives BuildMagic access to browse and clone your repositories.

  1. Go to Applications in the sidebar.
  2. Click Add Application.
  3. Select your Git provider — you'll see a list of your repositories.
  4. Choose the repository that contains your mobile project.
  5. Select the project type (Flutter, iOS Native, Android Native, or React Native).
  6. Click Create.

BuildMagic automatically creates a default build workflow for your app based on the project type you selected.

Step 3: Add a buildmagic.yaml (Recommended)

For full control over your build, add a buildmagic.yaml file to the root of your repository. This defines exactly which commands run during your build:

workflows:
  build:
    name: Build
    instance_type: mac_mini_m4
    scripts:
      - name: Install dependencies
        script: |
          cd $CM_PROJECT_PATH
          pod install --repo-update
      - name: Build
        script: |
          cd $CM_PROJECT_PATH
          xcodebuild archive \
            -workspace MyApp.xcworkspace \
            -scheme MyApp \
            -archivePath /tmp/build/App.xcarchive \
            -configuration Release
    artifacts:
      - "/tmp/build/**/*.xcarchive"

See the full buildmagic.yaml reference for all options and examples for every project type.

You can also edit the config directly in the dashboard under your app's Settings > buildmagic.yaml tab without modifying your repo.

Step 4: Run Your First Build

  1. Open your newly created application.
  2. Go to the Builds tab.
  3. Click Start Build.
  4. Select the workflow and branch you want to build.
  5. Click Start.

Your build will be queued and picked up by an available worker. You can watch the build logs in real-time directly in the dashboard.

Step 5: Set Up Code Signing (Optional)

If you want to produce signed builds that can be installed on devices or published to the App Store or Google Play, you'll need to configure code signing. See the Code Signing guide for detailed instructions.

What Happens During a Build?

When you start a build, BuildMagic runs through the following steps automatically:

  1. Clone — Your repository is cloned into a clean build environment.
  2. Install Dependencies — Package managers run to install your project's dependencies (flutter pub get, pod install, npm install, or Gradle sync).
  3. Test — Unit tests run if configured in your workflow.
  4. Build — Your app is compiled for the target platform.
  5. Sign — If code signing is configured, the build output is signed with your certificates.
  6. Publish — If publishing is configured, the signed build is uploaded to TestFlight, App Store Connect, or your distribution channel.

Each step produces real-time log output that you can follow in the dashboard. If any step fails, the build stops and you can see exactly what went wrong.

Next Steps