Ship overview ⚓
Ship is a deployment solution that aims to save users a lot of headache. With Ship, you have complete control over your app’s distribution, its version history, and all the important metadata - and you can manage all that in one place.
Deployment with Ship includes automatic re-sign and artifact generation and we store all the previous versions too. The app’s metadata, all the marketing copy, and screenshots can also be edited on the spot and non-developer people can manage it.
You can do a whole lot of things with Ship:
- View all the build versions of your app.
- View and edit all the details of a given build version, including a description, screenshots, and the most important parameters, such as the app size or the supported device types.
- Send your app directly to testers with a link to the public install page.
- Deploy a given build version to App Store Connect and/or the Google Play Console, once you set up publishing.
-
Switch between platforms on the Version History page in the case of cross-platform projects.
Getting started with Ship ⚓
You have two options to open Ship:
- On the Add-ons tab of the app: this option takes you to Ship’s home page.
- From the Builds page: this option takes you to the build’s Ship page.
When first logging in, you might not have a single build version available to publish. But don’t worry, that can be fixed quickly.
- In one of your Workflows, you need a Step that builds your app. By default, Xcode Archive & Export for iOS, Gradle Runner and Android Build are automatically supported.
- The same Workflow must have the correct version of the Deploy to Bitrise.io Step after the Step that builds your app.
- The Deploy to Bitrise.io Step must export the relevant file: an APK file for Android apps and the
.xcarchive
file for iOS apps. If you use either one of the Xcode Archive & Export for iOS, Gradle Runner and Android Build Steps, you don’t have to change anything in the default configuration of the Deploy to Bitrise.io Step to export the relevant files.
Once you successfully built your app, you will be able to start using Ship.
Configuring and publishing an app with Ship ⚓
To publish an app on Ship, you need to:
- Build an app that has at least one exposed Workflow.
- Configure publishing on the Settings page.
- Push the Publish button.
iOS and Android apps have their own set of settings on the Settings page; for cross-platform app, both iOS and Android settings must be configured.
Exposing a Workflow’s artifacts to Ship ⚓
Exposing a Workflow’s artifacts means that the products of the Workflow will be available in Ship: for example, if your Workflow produces an APK, you can publish that using Ship. By default, all Workflows are exposed if they contain the correct version of the Deploy to Bitrise.io Step. If you are happy with that, just leave the field as is.
If, however, you add a Workflow here, only that Workflow will be exposed.
To expose a Workflow’s artifacts to Ship:
- Go to your app’s Ship page.
- Click Settings in the top right corner.
- Go to the General tab.
-
In the Expose Artifacts From the Selected Workflow to Ship text box, add all the Workflows you need.
Be aware that if your app is cross-platform, there are TWO such text boxes: one for iOS and one for Android. Separate the different Workflow names with a comma (for example,
build, deploy, release_build_android
) . - Scroll down to the bottom of the page and click Save.
Code signing files ⚓
On the Settings page, you can choose between different code signing files. You can upload these files - iOS provisioning profiles and certificates, Android keystore files and Service Account JSON files - in the usual way:
Code signing files are required to publish an app to any online store, or to install them to test devices.
Installing an app on a test device ⚓
To install an app on a device, there are three options:
- Send the public install page link to all the testers and other stakeholders.
- Send the QR code: scanning it takes you to the public install page of the app.
- Log in to Ship from the device and install it directly from there.
To send the public install page link or the QR code:
- Expose the Workflow that creates the installable file, and run the Workflow on Bitrise.
- Open the Details page of your app’s chosen build version.
- On the right, find the Public Install Page link or the QR code.
- Copy the one you need and send it to the stakeholders (by email, for example).
To install it directly from Ship:
-
Log in to Ship from a supported device.
Click on the Devices tab to find out if a given device is registered. Read our guide on how to register your devices on Bitrise.
-
Under the name of the app, find and click the Install button.
Publishing an app online ⚓
To configure publishing an iOS app to App Store Connect (formerly known as iTunes Connect), you have to:
- Choose the provisioning profiles and code signing identities to be used.
- Set the app specific password.
- Set the Apple Developer Account email.
- Set the App SKU: this is a unique ID you give to your app for internal tracking. It’s not visible to customers.
Once you configured publishing for the app, you do not have to set these options every time, only if you want to change some of them.
To configure publishing an app for iOS:
- Open your app’s Ship page and click Settings in the top right corner.
- Go to the General tab.
- Go to the iOS Settings section.
- Expose a Workflow that creates the .ipa you want to publish, and run the Workflow on Bitrise.
-
Select the code signing files you want to use.
Make sure you choose the files appropriate for the export method you used to create the .ipa file. For example, if your .ipa was exported using the
app-store
method, choose an App Store provisioning profile and a Distribution certificate (code signing identity). - Enter the Apple Developer Account Email and the App Specific Password to be able to publish to the App Store.
- Enter the App SKU.
- Go back to the Details page and click Publish.
To configure publishing an Android app to Google Play Console, you can:
- Choose the Android keystore files and the Service Account JSON file.
- Set the track you want to use to release your app.
Once you configured publishing for the app, you do not have to set these options every time, only if you want to change some of them.
To configure publishing an app for Android:
- Open your app’s Ship page and click Settings in the top right corner.
- Go to the Android Settings section.
- Expose a Workflow that creates the APK you want to publish.
- Enter the track you want to use to publish to the Google Play Console.
- If your Android app contains multiple modules, enter the exact module under Module.
- Choose the appropriate keystore file and the Service Account JSON file.
- Head back to the Version History page and select the version you wish to publish. If your app has multiple flavors, you can filter for the right flavor and select it for publishing.
- Fill out the Details page and click Publish.
Publishing status and logs ⚓
Once you clicked Publish in Ship, the process starts according to the configured settings. You can view the status of the active publishing process on top of the Details page of the app.
To view the logs of any publishing process, go to the Activity tab. From there, you can download the logs by clicking Download Build Log to troubleshoot any errors after a failed publish.
App details ⚓
The purpose of the app Details page is to update the most important information about your app, as you want that information to appear in your online store of choice, for example.
The details include:
- A description of the app.
- Screenshots and feature graphics of the app, arranged by the different supported devices.
- Metadata such as version number, size, version code, SDK version, and so on. The exact parameters depend on the type of the app. This is automatically exported to Ship by the Deploy to Bitrise.io Step.
Adding screenshots or feature graphics ⚓
You can add screenshots for an app to be published. Once you added screenshots or graphics to one build version of the app, they are automatically added to all subsequent versions. If you want to display different screenshots, you can modify it, otherwise you can leave it alone.
To add screenshots or feature graphics to your app details page:
- Open the Details page in Ship of your app’s chosen build version.
-
Go to Screenshots or Feature Graphic, depending on what you want to upload.
- Drag and drop a file OR click Browse files and select the ones you wish to upload.
- Once done, click Save in the top right corner.
Updating the app’s descriptions ⚓
You can update the app’s description, or all its other textual details in the same way. The types of text fields that you have available depend on the type of the app.
- Open the Details page in Ship of your app’s chosen build version.
- Go to the field you want to edit and click in the content field.
- Edit the content.
- Click Save in the top right of the Details tab.
Notifications ⚓
Ship can send emails about three different events:
- A new build version of an app is available in Ship.
- Ship successfully published the app.
- Ship failed to publish the app.
These notifications can be sent to any number of different email addresses. When a new email address is added to the notifications list, Ship sends a confirmation email to the address: after confirmation, notifications should work.
Adding a new email address ⚓
To add a new email address to the notification list for an app:
- Open your app’s Ship page.
- Click Settings.
- Go to the Notifications tab.
-
In the input field under Email notifications, type the email address.
- Click Add.
The address should appear in the list below, with Pending as its status. An email is sent to the address: the recipient must click Confirm Notifications in the email to start receiving notifications.
Configuring notifications ⚓
You can pick and choose the Ship events about which you want to notify different people. For example, it’s possible to only send notifications about a failed publishing event if you do not want to be bothered when things go well! And of course you can send different notifications to different email addresses.
To configure notifications:
- Open your app’s Ship page.
- Click Settings.
- Go to the Notifications tab.
- Use the toggles under the different event types.
- Hit Save once all notifications are set.
Using Ship for apps built with cross-platform frameworks ⚓
By default, Ship works with the Android Build, Gradle Runner and the Xcode Archive & Export for iOS Steps. The output of these Steps are automatically exported by the Deploy to Bitrise.io Step to Ship.
However, for apps built with cross-platform frameworks, such as React Native or Flutter, you might not use these Steps in your Workflows. But don’t worry: you can use Steps that are not supported by default to build your app and still deploy it with Ship. All you need to do is make sure the right files end up in the right place.
Deploying iOS apps built with cross-platform frameworks ⚓
The Deploy to Bitrise.io Step looks for an .xcarchive.zip
file to export to Ship in the case of an iOS app. If you do not want to use the Xcode Archive & Export for iOS Step, you just need to make sure that:
- There is a Step in your exposed Workflow that exports an
.xcarchive.zip
file of your app. That is, the Step you use needs to create an Xcode Archive and needs to package it in a zip file. - This Step exports the
.xcarchive.zip
file into theBITRISE_DEPLOY_DIR
directory.
Deploying Android apps built with different Steps ⚓
The Deploy to Bitrise.io Step looks for an APK or an AAB file in the BITRISE_DEPLOY_DIR
directory.
If you do not want to use the Android Build or the Gradle Runner Steps, you just need to make sure that:
- There is a Step in your exposed Workflow that exports an APK or AAB file of your app.
- This Step exports the APK or AAB file into the
BITRISE_DEPLOY_DIR
directory.