Skip to main content

Getting started with macOS projects

Abstract

Get started on Bitrise by signing up via email or a Git provider, connecting a repository, and running the first build for your macOS project.

In this guide, we’ll walk you through how to add a macOS project to Bitrise, how to run Xcode tests, manage your code signing files and deploy the finished app to bitrise.io and to the App Store.

Adding a macOS project to Bitrise

  1. Log in to Bitrise and go to the Dashboard.

  2. Click the New CI project button.

  3. Under Project access, select the Workspace that will own the project.

    project-access.png

  4. Set the privacy of the project.

    Privacy is final

    You cannot change this setting later! If you realize you've accidentally added your project as a public project even though you need it to be private, you'll have to delete the project and add it again.

    • Private projects are only accessible to you, your Workspace members and those who are invited to work on a project. They require authentication to access the repository of the project.

    • Public projects expose their bitrise.yml and their build logs to everyone. If you have a public project’s build URL, you can view its build log, to help with troubleshooting, for example. Public projects do not require authentication and they cannot have SSH keys.

  5. Select one of two options to set your repository URL:

    • With the Select remote repository option, you can select a repository from a list of repos from a connected Git provider account. Choose the Git provider from the dropdown menu, then click Select a repository... and select the repository from the list.

      select-repo-open.png

    • The Enter URL manually option does not require a connected Git provider account: you can simply enter the URL and proceed to the authentication phase. We strongly recommend using an SSH URL, unless you are setting up a public project.

    Repository URL

    You will be able to change your project's repository URL later. You can also connect or disconnect your account to Git provider services at any time.

    If you signed up for Bitrise using a Git provider account, that one is already connected and you can select any of your repositories from it.

  6. If you use an OAuth connection, you need to add an SSH key in the Authorize Bitrise section.

    You don't need SSH keys if:

    add-ssh-key.png

    • Auto-add a generated SSH key to your repository: We recommend using this option. We automatically generate an SSH key pair and register the public key to your repository. Requires your connected Git provider account to have admin rights to the repository.

    • Copy a generated SSH key to your Git provider manually: We generate an SSH key pair for you and you can copy the public key and register it manually to your Git provider. It is useful if, for example, you need to access multiple repositories with the same SSH key.

    • Add your own SSH key to Bitrise: You can generate your own SSH key and paste the private key here after choosing this option. You also need to add the public key to the repository manually. To generate your SSH key pair: Generating your own SSH keypair.

    Configure SSH keys at any time

    If you can't set up a valid, working SSH key connection at this time, don't worry: proceed with adding your project. You can set up the SSH connection afterwards: Configuring SSH keys.

  7. Select the default branch of your repository. This branch should contain the configuration of your project.

    • If you successfully configured SSH access in the previous step or if you're adding a public project, Bitrise will parse your repository and allow you to select a branch from a dropdown menu.

    • If you didn't configure repository access, you need to type the branch name manually.

    You can change the default branch of the project later.

    choose-branch.png

  8. In the next step, choose Yes, auto-detect configuration. Bitrise will scan your repository and attempt to set up a stack and default Workflows based on the results of the scan. In most cases, we recommend choosing this option.

    Project type

    Detecting a project type serves to assist in the initial configuration of your project. But don't worry, you can change every setting, including the project type, at any time after you added the project.

  9. Wait while Bitrise is validating your project. We look for your configuration files and set up your app based on them.

    Shared schemes only

    The validation will fail if you do not have a shared scheme in your project. You can still point Bitrise manually to your Xcode scheme but if it’s shared, we automatically detect it for you.

  10. Select the export method. You can modify this later - for now, select development.

    Getting started with MacOS apps

    Once you clicked it, you should see your:

    • Project or Workspace path.

    • Scheme name.

    • Export method.

    • macOS stack.

  11. Register a webhook when prompted so that Bitrise can start a build automatically when code is pushed to your repository, or a pull request is created.

  12. Once you are done, click View Project Page to go to the newly added project's home page. From there, you can start editing your Workflows and run builds.

Testing your macOS app

Once you created your app, the first build will run based on the automatically created primary workflow. You can check it out in the app’s Workflow Editor: click the app’s name on your Dashboard then click the Workflow tab

If your app does not have test targets defined, the primary workflow will NOT include the Xcode Test for Mac Step.

If you have test targets defined, the primary Workflow of a macOS app includes the two Steps you need to run your Xcode tests, and view their results on bitrise.io:

  • Xcode Test for Mac

  • Deploy to Bitrise.io

Code signing files

Running Xcode tests and deploying their results to Bitrise do not require any code signing files. So don’t worry about them just yet!

The Xcode Test for Mac Step runs the pre-defined Xcode tests. It has a default configuration that does not need to be modified: if the tests are written correctly, they will work. You can find the same configuration options in Xcode, too.

The Deploy to Bitrise.io will deploy the following to the Logs and Artifacts tab of the build:

  • your Xcode test results.

  • your raw xcodebuildoutput log.

The Deploy to Bitrise.io Step also exports the results of the Xcode Test for Mac Step to the Test Reports add-on.

Code signing and exporting a macOS app

To install and test the app on other physical devices, you will need to create and export an .app or .pkg file. This requires setting up code signing. In the example, we’ll be exporting an app with the development export method: you cannot upload such an app to Testflight but you can test it, for example, on the devices of your internal testers.

Automatic Provisioining

The example procedure described here uses manual provisioning, with the Certificate and profile installer Step. However, Bitrise also supports automatic provisioning but it is not in the scope of this guide.

You will need:

  • the automatically created deploy workflow.

  • a Development certificate (a .p12 certificate file).

  • a Development type Provisioning Profile. For a macOS project, the file extension of the provisioning profile is .provisionprofile.

  1. Set the code signing type of your project in Xcode to either manual or automatic (Xcode managed), and generate the package file locally.

  2. Collect and upload the code signing files.

    The tool can also upload your code signing files to Bitrise - we recommend doing so! Otherwise, upload them manually: enter the Workflow Editor and select the Code signing tab, then upload the files in their respective fields.

  3. Go to your app’s Workflow Editor, and select the deploy workflow in the WORKFLOW dropdown menu in the top left corner.

  4. Check that you have the Certificate and profile installer Step in your Workflow. It must be before the Xcode Archive for Mac Step (you can have other Steps between the two, like Xcode Test for Mac).

  5. Check the Export method input under the app/pkg export configs input group of the Xcode Archive for Mac Step.

    If you selected development when you added the app to Bitrise, you don’t need to change the input. Otherwise, manually set it to development.

    macOS_export_method.png

  6. Start a build.

If you uploaded the correct code signing files, the Certificate and profile installer Step should install your code signing files and the Xcode Archive for Mac Step should export an .app or .pkg file with the development export method. If you have the Deploy to Bitrise.io Step in your workflow, you can find the binary package file on the Artifacts tab of the build page.

Deploying the app to the App Store Connect

If you set up your code signing files and created an .app or .pkg file for your internal testers, it is time to involve external testers and then to publish your macOS app to the App Store. Let’s see how!

Developer ID

If you want to distribute your app outside the App Store, you can sign it with a Developer ID. This method is not in the scope of this guide but on Bitrise, it works the same way: you just need to upload the appropriate code signing files.

To deploy to the App Store, you will need these code signing files:

  • a Mac App Distribution certificate.

  • a Mac Installer Distribution certificate.

  1. On your local machine, set up App Store code signing for your project in Xcode, and export an .app or .pkg file. If this fails locally, it will definitely fail on Bitrise, too!

  2. Collect and upload the code signing files.

  3. Go to the app’s Workflow Editor and create a new Workflow: click the + button next to the Workflow dropdown menu, enter the name of your new Workflow and in the BASED ON dropdown menu, select deploy. This way the new Workflow will be a copy of the basic deploy Workflow.

  4. Click on the the app/pkg export methods , and set the Export Method input of the Xcode Archive for Mac Step to app-store.

    You can export multiple binaries with different export methods: use the Export macOS Xcode archive Step in your Workflow, to do so.

  5. Add the Deploy to App Store Connect - Application Loader (formerly iTunes Connect) Step to your workflow, after the Xcode Archive for Mac Step but preferably before the Deploy to Bitrise.io Step.

  6. Provide your Apple credentials in the Deploy to App Store Connect - Application Loader (formerly iTunes Connect) Step.

    The Step will need your:

    • Apple ID.

    • password or, if you use two-factor authentication on iTunes Connect, your application password.

    Don’t worry, the password will not be visible in the logs or exposed - that’s why it is marked SENSITIVE.

And that’s it! Start a build - if everything went well, you should see your app on Testflight. From there, you can distribute it to external testers or release it to the App Store.

In this section:

The bitrise.yml file stores your entire build configuration for an app. It specifies your stack and the build triggers, and defines the Workflows of the app. When you make changes on the graphical UI of our Workflow Editor, you actually modify the bitrise.yml file.

stackapp

The Bitrise Workflow Editor allows you to edit your Workflows, configure Steps, upload files (including code signing files) and manage your app's triggers and stacks on a graphical user interface. It is available both online and offline.

A Workflow is a collection of Steps, Environment Variables, and other configurations. When Bitrise starts a build, it runs one or more Workflows according to the configuration defined in the bitrise.yml file.

A Step is a block of script execution that encapsulates a build task on Bitrise: the code to perform that task, the inputs and parameters you can define for the task, and the outputs the task generates.