---
title: "Configuring a macOS application on CircleCI"
description: "Get started with CI/CD on the macOS execution environment by walking through an example application and configuration file for your first macOS project."
platform: "Cloud"
doc_version: "unversioned"
last_updated: "2026-10-15"
cloud_plans: "Free, Performance, Scale"
version_control: "All supported providers"
---

> For current CircleCI product defaults, deprecated patterns, and Cloud/Server differences, see [AGENTS.md](https://circleci.com/docs/AGENTS.md).
>
> For the complete documentation index and site structure, see [llms.txt](https://circleci.com/docs/llms.txt).

# Configuring a macOS application on CircleCI

**Cloud plans:** Free, Performance, Scale

**Version control:** [All supported providers](https://circleci.com/docs/guides/integration/version-control-system-integration-overview/)

This document describes how to get started with CI/CD using a **macOS execution environment** on CircleCI. If you need to learn the basics of CircleCI, see the [Getting Started Guide](https://circleci.com/docs/guides/getting-started/getting-started/). You may also want to visit the documentation for [Testing and Setting Up iOS Projects](https://circleci.com/docs/guides/test/testing-ios/).

## Prerequisites

To follow along with this document you will need:

*   An [account](https://circleci.com/signup/) on CircleCI.
    
*   An Apple computer with Xcode installed on it (if you want to open the example project).
    

## Overview of the macOS executor

The macOS execution environment is used for iOS and macOS development, allowing you to test, build, and deploy macOS and iOS applications on CircleCI. The macOS executor runs jobs in a macOS environment and provides access to iPhone, iPad, Apple Watch, and Apple TV simulators.

Before we get to setting up the macOS executor, we will need to set up our example application.

## Example application

The example application is a simple macOS app. The app runs a 5 minute timer and contains a single unit test. Real-world applications will be far more complex. This app serves as an introduction to the macOS execution environment.

In this example app, CircleCI is configured to help with the following:

*   Run tests using Xcode on the macOS virtual machine whenever we push a change to the repository.
    
*   Create and upload the compiled application as an artifact after tests have run successfully.
    

You can check out the example application’s repo on [GitHub](https://github.com/CircleCI-Public/circleci-demo-macos).

If you would like to test running the code in the example configuration file (below) yourself, either fork or duplicate the example application from GitHub. The example configuration file is not guaranteed to work on any/all Xcode projects.

## Example configuration file

Our application does not make use of any external tools or dependencies, so we have a fairly simple `.circleci/config.yml` file. Below, each line is commented to indicate what is happening at each step.

For a full list of supported Xcode versions, see the [Using macOS](https://circleci.com/docs/guides/execute/using-macos/#supported-xcode-versions) page.

```yaml
version: 2.1

jobs: # a basic unit of work in a run
  test: # your job name
    macos:
      xcode: 27.0.0 # indicate your selected version of Xcode
    resource_class: m4pro.medium # specify a resource class (e.g. m4pro.medium or m4pro.large)
    steps: # a series of commands to run
      - checkout  # pull down code from your version control system.
      - run:
          name: Run Unit Tests
          command: xcodebuild test -scheme circleci-demo-macos

  build:
    macos:
      xcode: 27.0.0 # indicate your selected version of Xcode
    resource_class: m4pro.medium # specify a resource class (e.g. m4pro.medium or m4pro.large)
    steps:
      - checkout
      - run:
          # build our application
          name: Build Application
          command: xcodebuild
      - run:
          # compress Xcode's build output so that it can be stored as an artifact
          name: Compress app for storage
          command: zip -r app.zip build/Release/circleci-demo-macos.app
      - store_artifacts: # store this build output. Read more: https://circleci.com/docs/guides/optimize/artifacts/
          path: app.zip
          destination: app

workflows:
  test_build:
    jobs:
      - test
      - build:
          requires:
            - test
```

The example `.circleci/config.yml` above covers the following:

*   Specify an [`executor`](https://circleci.com/docs/reference/configuration-reference/#macos).
    
*   Pull code using the [`checkout`](https://circleci.com/docs/reference/configuration-reference/#checkout) key.
    
*   Run tests with Xcode.
    
*   Build the application.
    
*   Compress the application and store it using the [`store_artifacts`](https://circleci.com/docs/reference/configuration-reference/#storeartifacts) key.
    

You can learn more about the `.circleci/config.yml` file in the [Configuration Reference](https://circleci.com/docs/reference/configuration-reference/).

## Next steps

The macOS executor is commonly used for testing and building iOS applications, which can be more complex in their continuous integration configuration. If you are interested in building and/or testing iOS applications, consider checking out our following docs that further explore this topic:

*   [Testing iOS Applications on macOS](https://circleci.com/docs/guides/test/testing-ios/)
    
*   [Setting Up Code Signing for iOS Projects](https://circleci.com/docs/guides/execute/ios-codesigning/)