Deploying with Ship

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, such as Xcode Archive & Export for iOS or Android Build.
• The same Workflow must have the correct version of the Deploy to Bitrise.io Step after the Step that builds your app.

Once you built your app - that is to say, produced an APK or an IPA file -, 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:

1. Go to your app’s Ship page.
2. Click Settings in the top right corner.
3. Go to the General tab.

4. 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) .

5. 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:

• iOS code signing files.
• Android code signing files.

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:

1. Expose the Workflow that creates the installable file, and run the Workflow on Bitrise.
2. Open the Details page of your app’s chosen build version.
3. On the right, find the Public Install Page link or the QR code.
4. Copy the one you need and send it to the stakeholders (by email, for example).

To install it directly from Ship:

1. 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.

2. Under the name of the app, find and click the Install button.

Publishing an app online ⚓

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:

1. Open the Details page in Ship of your app’s chosen build version.

2. Go to Screenshots or Feature Graphic, depending on what you want to upload.

   

3. Drag and drop a file OR click Browse files and select the ones you wish to upload.
4. 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.

1. Open the Details page in Ship of your app’s chosen build version.
2. Go to the field you want to edit and click in the content field.
3. Edit the content.
4. 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:

1. Open your app’s Ship page.
2. Click Settings.
3. Go to the Notifications tab.

4. In the input field under Email notifications, type the email address.

   

5. 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:

1. Open your app’s Ship page.
2. Click Settings.
3. Go to the Notifications tab.
4. Use the toggles under the different event types.
5. Hit Save once all notifications are set.

Using Ship with unsupported Steps ⚓

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, you can use unsupported Steps - fastlane, for example - to build your app and still deploy it with Ship. All you need to do is make sure the app’s binary ends up in the right place.

Deploying iOS apps built with unsupported Steps ⚓

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 the BITRISE_DEPLOY_DIR directory.

Deploying Android apps built with unsupported 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.