Skip to content

Getting Started with Shuttle

Shuttle is designed to help you manage, deploy, and distribute your applications with as little friction as possible. This document will help you grasp the essentials about Shuttle, as well as dive into more advanced capabilities.

Signing in

You can connect to your Shuttle account by authenticating with your email address or an external service like GitHub/GitLab. Please note that we require the bare minimum to authenticate you from GitHub/GitLab, we do not collect any data. For detailed information, please read our Privacy Policy.

To sign in with your email:

  • Click on the green Sign in button
  • Enter your email address
  • Check your mail and click on the link provided by Shuttle mail

To sign in with an external service:

  • Click on the green Sign in button
  • Choose the external service (GitHub or GitLab)
  • Review permissions and authorize Shuttle

Note:

Only the email authentication is available by default. You must configure Shuttle to enable external service (coming soon). If you're the owner, your first signin must be through the email authentication. You can't use external service until it's setup.

That's it!

Deployment and management

The main purpose of Shuttle is to help you gather your mobile binary deployments and manage their distribution. So let's start with a little bit of semantics. This will greatly help you understand how everything fits together and the approach Shuttle takes to simplify your workflow.

Shuttle can essentially be simplified to four main components: Apps, Environments, Releases, and Users.

  • App: A platform specific product. For your new groundbreaking app that you will release on both iOS and Android, you will have two separate apps in Shuttle, one for Android, and one for iOS.
  • Environment: An app can define its environment(s). They are channels or phases of distribution, according to your own business needs.
  • Releases: They are builds or versions of your app, and each one is related to one and only one environment. They hold your deployed binary, and they are the items visible to your users.
  • Users: They are the individuals allowed to access an app and an environment, and thus, all available releases for this app and this environment. Users permissions can vary according to the team they belong to.

Shuttle Components Schematic

Creating an app

To create an app, from the dashboard, click on the Apps tab. If you already have some apps, they will be listed here. You can create a new one with the Add new app button in the upper right. You have five fields to complete your creation:

  • App name: you do not need to bother putting the platform name in this field because it will be displayed in a list field underneath.
  • App path: this is the URL where your app will be available. It will be generated as you enter your Appname, but you can customize it. Since this is a user facing URL, you can make it short, simple, and without ambiguous characters.
  • Description: optional.
  • Platform: Android, iOS, and macOS.
  • Visibility: choose between private, internal, and public.

🤔 How does the visibility attribute work? 🤔

The visibility setting controls who can access the apps:

  • private means only administrators and the users who have been explicitly allowed can see the releases of the app.
  • internal means any authenticated user can see them (although users are explicitly added by administrators).
  • public means general availability to anyone, without authentication.

Visit the Permissions documentation to learn how to assign permissions on an app.


Settings

You can still edit all the settings of your app, except its platform. Head over to your app, click on the Settings tab, you can then edit the fields you want to change in the General tab. You can also remove completely your app (and all its releases) from the Settings tab.

Environments

The second tab of the app settings allows you to view and edit Environments. They are totally free to define, so that they suit perfectly your usual workflow. By default, Shuttle provides for each app two environments: Production and Testing. You must have at least one environment to deploy a release. Environments are useful to group releases of your app that are aimed at specific audiences. For instance, your Production environment might be aimed at your QA, allowing you to have feedback on binaries that will go live for your users. Testing environment might be aimed at your internal developers to gather feedback earlier and catch bugs before the QA does. 😉 Environments are intentionally left completely free, to suit your needs. You can create your own environments to match your workflow. Another valid suite of environments may be: Develop, Internal Testing, QA, and Archive.

To create a new environment, click on the New environment button. Then, enter the name of the environment. This name will generate the environment path (a user facing URL). You can customize this path, similarly to the app path.

Other settings that define your environment:

  • Versioning scheme: You can choose to control versioning with semantic version number only, or with both the semantic version number and the build number. For Apple platforms, this maps to CFBundleShortVersionString and CFBundleVersion in your Info.plist, as for Android this maps to versionName and versionCode in your build.gradle. If you select Version only, each new binary you upload must have a greater semantic version number to create a new release. If you select Version and build, each new binary you upload must have a greater semantic version number or a greater build number to create a new release. Another way to look at it: in Version and build mode, you only need to change the build number in your binary to generate a new release upon upload, whereas in Version only mode, you need to change the semantic version number to generate a new release. (However, as a general good practice, a semantic version number bump implies a bump in build number as well).
  • Bundle identifier/Package name: The environment will match only the binaries holding the identifier filled in here. This feature allows you to have separate Shuttle environments for your multiple targets, which might be useful if you have some staging web services, alternative versions, or white label flavors and variants.

As you can see, the combination of versioning scheme, bundle identifier/package name, and free environments is powerful to pinpoint your distribution workflow. Finally click on Create environment, and you are done!

Creating a release

To create a new release, go into your app, click on the Releases tab, then on the New release button.

You can directly upload your binary file: a .zip file containing your .app for macOS, an .ipa for iOS, and an .apk for Android. The upload starts automatically once you have dropped or selected the file, and you are redirected to the New release form.

Only a few fields are remaining.

First, the Environment. If your binary holds an identifier matching existing environments, the first one of them will be selected by default. You can select another environment in the dropdown list. Otherwise, you will have to create an environment matching the identifier of your binary. This identifier is shown to you just below the field, so that you know exactly which app identifier you are acting on.

Finally, you can fill in the title of the release and the release notes. If you leave the field blank, the generated title will have the following pattern: ${app-name} x.y.z or ${app-name} x.y.z (a.b) (depending on your versioning scheme, x.y.z being the semantic version number and a.b the build number).

You can also mention the commit hash and the integration identifier. (It is often used when your CI pushes your releases via Shuttle's API)

Click on the Create release button, your new release appears on the top of the Releases list.

Note: The icon of your app will be extracted from your binary, and will appear in Shuttle to help you and your users identify your release.

Distribution

Sharing from Shuttle

Shuttle offers many ways to achieve distribution.

Most of the time, you will want to send your users directly to a specific release. Just copy the URL of the release once you have created it.

However, if you want to automate your release process, the URL of a given release follows a straightforward scheme: https://your-instance.shuttle.tools/${app-path}/${environment-path}/${semantic-version-number}/${build-number}

Likewise, you might want to share with your users some general purpose URL:

  • Root of the app: https://your-instance.shuttle.tools/${app-path}
  • List of all releases: https://your-instance.shuttle.tools/${app-path}/releases
  • List of releases for a given environment: https://your-instance.shuttle.tools/${app-path}/${environment-path}

Please note that whether or not you share with them the links above, your users will be able to discover those resources from a single release page, by browsing through the links.

Downloading a release

Shuttle is responsive, with a special care taken for the single release download page. Your users will land on a page showing the icon, app name, release notes and other details, with a green button on top to install the app.

After opening the release link from a device (a Mac, an iOS device, or an Android device) and clicking on the install button, installation begins automatically for iOS. For other platforms, usual installation steps are needed after clicking the download/install button: dragging the unzipped .app file into the /Applications folder, or opening the .apk file from the downloads.

Shuttle does not alter the signature of your binary. According to your distribution and signature method (Ad Hoc, Enterprise…), do not forget to mention to your users the steps of installation (for instance, accepting the Enterprise certificate for In House deployment, or trusting unknown sources for Android).