Skip to main content

Adding your first app

Abstract

Adding an app to Bitrise means setting up access to your repository so that you can run builds. Our project scanner determines the platform type and generates default Workflows to build and deploy your app.

Adding an app to Bitrise means setting up access to your repository so that you can run builds. During the process, we also run our project scanner that detects the platform type of your app - for example, iOS - and generate default Workflows with all the necessary Steps to build and deploy your app.

Currently we are supporting the following platforms/frameworks out of the box:

The project scanner

Supporting a platform/framework means that our project scanner can detect the type of the app and set up a basic Bitrise configuration based on the type. You can add any other app, too, regardless of how it's built but you'll have to configure it manually.

In this guide we describe how you can add a new app to Bitrise, connect your repository to Bitrise, set up SSH keys and initial configuration, and register a webhook.

  1. Log in to Bitrise.

  2. Click the Add your first app button.

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

    project-access.png

  4. Set the privacy of the app.

    Can't change an app's privacy

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

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

    • Public apps expose their bitrise.yml and their build logs to everyone. If you have a public app’s build URL, you can view its build log, to help with troubleshooting, for example. Public apps 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. If you choose this option for a private app, we will automatically use the repository's SSH URL.

      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. You can use either an SSH URL or an HTTPS URL. For public apps, always use HTTPS URLs.

    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 have a private app, provide an authorization method in the Authorize Bitrise section. The authorization method will depend on the URL set up in the previous step:

    • For SSH URLs, you'll need to set up an SSH key pair.

    • For HTTPS URLs, you'll need to add a Personal Access Token created on your Git provider's site.

    SSH key authorization

    HTTPS authorization

    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.

    https-auth.png

    Fine-grained access

    The Personal Access Token needs to have read access to the repository. We recommend using fine-grained Personal Access Tokens that do not have any additional rights to the repository or your Git provider account.

    • For GitHub and Gitlab repositories, add your GitHub/Gitlab Personal Access Token.

    • For a Bitbucket repository, add your username and a Personal Access Token.

    Configure authorization at any time

    You can skip authorization and proceed; you can configure it later:

  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 app, 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 app later.

    choose-branch.png

  8. Choose whether you want Bitrise to auto-detect your project type.:

    • Yes, auto-detect configuration: If you choose this option, 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.

    • No, skip auto-detection and configure settings manually: You will need to choose a project type, stack type, and build machine type.

    Project type

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

  9. If you chose automatic configuration and Bitrise successfully detected your project type, proceed to the next Step. If Bitrise failed to detect your project type, you have two options.

    • Try to fix the issue that caused the project scanner to fail. The logs we provide might be helpful. Once you're done select Retry automatic configuration.

    • Select Skip and configure manually. You'll need to choose the project type, and set up the project configuration based on the type you chose. If you select Other/Manual, you'll just need to select a stack type.

  10. Confirm the project build configuration and click I'm ready when done.

    The exact configuration options depend on your project type. You will always have the option to select a stack and the machine types for the selected stack. If you're not sure about these options, don't worry: you can change them later.

  11. Optionally, add an app icon by uploading an image.

    You can skip this and add an icon later if you wish.

  12. Optionally, allow Bitrise to set up a webhook in your repository.

    You need a webhook to automatically trigger builds. You can set up webhooks for your apps at any time so feel free to skip it for now.

    webhook-registration.png

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

In this section:

An app on Bitrise represents a Git repository that stores source code and has been connected to Bitrise to be able to run builds on it. As such, a Bitrise app isn't necessarily an actual application: it's just the code on which you run builds with Bitrise.

project scanner

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.

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.

stack