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 out of the box:
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.
Adding a new app to Bitrise ⚓
To add a new app to Bitrise go to your Dashboard and press the Add new App button.
In case this is the first application in Bitrise, the Dashboard shows you the quickstart guide instead of a list of your uploaded apps. There you can choose to add your first app right away.
Connecting a repository ⚓
After you’ve selected adding a new app, you find yourself on the Create New App page.
Select your app’s privacy setting: it can be either public or private.
- 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.ymland 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.
Bitrise gives you options to connect any kind of Git repository to it. GitHub, GitLab and Bitbucket are supported out of the box. If you’ve already authorized Bitrise, for example, with your GitHub, you will see Bitrise automatically list all your repositories, so you can just click on the one you’d like to connect.
If you haven’t authorized Bitrise against the provider hosting your repository, it will ask for permission.
It then lists your repositories as above. If you’d like to connect git repository hosted by other than GitHub or Bitbucket, select the Other / Manual tab.
You have to add the Git URL of the repository you would like to connect.
Setting up SSH keys ⚓
SSH keys serve the role of secure transfer between services. In the case of Bitrise, it asks for your permission to be authorized at your Git provider, for example, GitHub.
Being authorized is important as Bitrise has to have a working SSH connection to your repository to be able to clone it. There are several ways to make it work. Automatically, by adding it manually, or by using your own key.
Automatic setup ⚓
In the case of GitHub, GitLab and Bitbucket repository setups, Bitrise generates a public and private SSH key pair and ask whether you like the idea of adding that into your repository automatically as deploy key, or you’d like to add it by hand.
You need admin rights to the repository to be able to auto-add the key to it. In any other case, copy the public key from here and add it to your repository at your Git provider.
The auto-add option adds the generated key as a read-only deploy key to your repository, it’s the best for your security.
Manual setup ⚓
If you have private dependencies or submodules, you have to add the generated SSH key manually to your profile at your Git provider instead. That’s because deploy keys are only valid for one repository.
When the system asks if you need to use an additional private repository, click I need to and copy the key.
GitHub ⚓
Bitbucket ⚓
GitLab ⚓
Using your own key ⚓
This option can be used if you also have the private key of the given user. You just have to paste the private key and Bitrise will be able to access the repositories.
Setting up configuration ⚓
After Setting up the SSH key for your project, Bitrise downloads your code to make sure it can access the repository. It also runs an automatic repository scanner script to find the best initial configuration for your project. Currently Bitrise detect iOS, Android, Xamarin, Ionic / Cordova, Flutter, React Native and fastlane projects out of the box.
You can configure other types of projects too, but that requires a manual configuration.
Automatic project configuration ⚓
Enter the name of the default branch of your repository where your project is located. This branch should include the configuration of your project. Once you hit Next, Bitrise automatically starts the validation of the repository.
During validation Bitrise makes sure it has access to the given branch, using the SSH key you set up.
If the validation is successful, Bitrise scans your repository and give you a default Workflow based on the configuration of the project.
Manual project configuration ⚓
If the validation fails, choose the Restart scanning without validation option.
In this case, you have to configure the project manually. Click Next. You will see the Validating Repository message again but this time Bitrise only checks if it has access to the specified repository.
Choose the project type and specify the necessary inputs. You can also select the stack on which you wish to run your builds.
Adding an app icon with the project scanner ⚓
You can select an image that your iOS/Android project already contains, and use it as an app icon on Bitrise. If your project doesn’t contain any images, you can add a custom image from your local computer too. This way you can personalize your apps and build types. Let’s see how it works!
When adding your app to Bitrise, our project scanner automatically detects app images and also offers a custom image upload option.
-
Click the + sign on your Dashboard to add an app to Bitrise.
Once the project scanner has validated your project, you can set up your build configuration from the available options.
- At App icon, either Choose an Icon from your App or Upload a Custom Image by clicking the + button.
- Click Choose Image and Proceed.
- Continue with setting up a webhook.
You can always change an app icon if you go to the Settings tab of your app and click the + on the APP ICON.
Webhook setup ⚓
Once project configuration is finished, Bitrise offers you the chance to immediately register a webhook in your repository. After the webhook is set up, any code change in your repository will trigger the automatically created primary Workflow by default.
Read about webhooks in detail in our Webhooks section.
