Types of automations
Runway will automatically create new Slack or Teams channel(s) for each release. To create a release-specific channel, one of the following must be true:
- The Primary channel setting for your Slack or Teams integration contains a tokenized channel name (e.g.
release-{version}) - At least one notification has a tokenized channel name (e.g.
release-{version}) configured as a channel override
If multiple unique tokenized channel names are configured for different types of notifications, Runway will create channels matching each unique tokenized channel name if they don't exist already
Visit the Notification settings article for additional information on configuring release-specific channels.
If your app is configured with a Microsoft Teams integration, you must specify a Team that Runway should create release-specific channels in. This can be configured from the automation's settings modal.
Runway detects where the app version is referenced in your code and bumps it according to your team's bump version strategy (configurable from settings for this automation):
- Pre-kickoff, to current release version, on working branch: Runway will bump the version on your working branch to the current release version prior to kicking off your release.
- Post-kickoff, to current release version, on release branch: Runway will bump the version on your release branch to the current release version once your current release has been kicked off.
- Post-kickoff, to next version, on working branch: Runway will bump the version on your working branch to the next-up release version once your current release has been kicked off.
- Post-submission, to next version, on working branch: Runway will bump the version on your working branch to the next-up release version as soon as your current release has been submitted for review.
- Post-release, to next version, on working branch: Runway will bump the version on your working branch to the next-up release version as soon as your current version has been released to the app store.
By default, Runway will open a pull request against the target branch with the bump version commit. The copy for both the bump version commit message, the PR title and PR body are customizable from the Custom strings section in App Settings. If you have the Merge pull requests opened by Runway automation enabled, Runway will attempt to automatically merge the bump version PR as soon as all checks have passed.
Runway cannot automatically merge pull requests if all required checks on the PR have not passed. For example, if you require approvals to merge PRs into your target branch, approval requirements must be met before Runway can automatically merge.
If you'd prefer that Runway directly commit and push bump version commits to your target branch, you can enable the "Bypass pull requests" option on the automation. With this option enabled, Runway will create the bump version commit directly on your target branch and attempt to push up the new commit immediately.
If your repository has branch protection enabled for the target branch, and those branch protections include requiring pull requests to merge or restricting push access to your target branch, you'll need to update your branch protection rules to allow Runway to bypass requirements. Detailed instructions on how to set this up for each type of VCS integration are available here.
By default, Runway will detect the app version from your codebase by inspecting a handful of platform-specific files where versions are commonly found.
You can always configure an override list of version files in App Settings, which are not limited to any of the default file types and extensions.
The default file types that Runway will detect versions in are as follows:
iOS:
.pbxproj.xcconfig.plist.json.yaml
Android:
.gradle.json.yaml
React Native / OTA:
package.json
The table below describes the format (in regex) Runway is expecting to find the version in depending on the file type.
File type | Regular expression | Description | Example |
|---|---|---|---|
.pbxproj | MARKETING_VERSION = (\d+\.\d+\.\d+) | Matches the string MARKETING_VERSION = (case sensitive) followed by one or more digits separated by a . character | MARKETING_VERSION = 12.2.2 |
.xcconfig | MARKETING_VERSION = (\d+\.\d+\.\d+) | Matches the string MARKETING_VERSION = (case sensitive) followed by one or more digits separated by a . character | MARKETING_VERSION = 12.2.2 |
.plist | CFBundleShortVersionString<\/key>\s*<string>(\d+\.\d+\.\d+)<\/string> | Matches the CFBundleShortVersionString</key> string (case sensitive) followed by zero or more white space characters (spaces, tabs, line breaks), followed by the <string> string, followed by one or more digits separated by a . character, followed by the </string> string | CFBundleShortVersionString</key><string>2.2.2</string> |
.yaml | version:\s+?(\d+\.\d+\.\d+) | Matches the version: string, followed by one or more white space characters (spaces, tabs, line breaks), followed by one or more digits separated by a . character | version: 12.2.2 |
.gradle | versionName.*?(\d+\.\d+\.\d+)|versionString.*?(\d+\.\d+\.\d+) | Matches the versionName string, followed by zero or more of any character (except line breaks), followed by one or more digits separated by a . character OR the string versionString, followed by zero or more of any character (except line breaks), followed by one or more digits separated by a . character | versionName 12.2.2 |
.json | \"version\":\s+?\"(\d+\.\d+\.\d+)\" | Matches the "version": string (case sensitive), followed by one or more white space characters (spaces, tabs, line breaks), followed by the one or more digits separated by a . character wrapped in quotation marks | "version": "12.2.2" |
Default (all other file types) | (\d+\.\d+\.\d+) | Matches one or more digits separated by a . character | 12.2.2 |
Runway will promote code from your working branch to your release branch on the scheduled date.
By default, Runway will open a pull request against the release branch. You can customize the resulting PR title and body from the Custom strings section in App Settings. If you have the Merge pull requests opened by Runway automation enabled, Runway will attempt to automatically merge the code promotion PR as soon as all checks have passed.
Runway cannot automatically merge pull requests if all required checks on the PR have not passed. For example, if you require approvals to merge PRs into your release branch, approval requirements must be met before Runway can automatically merge.
Checking the "Bypass pull requests" option enables Runway to directly perform the code promotion by merging the working branch into the release branch without opening a pull request.
If your repository has the "Require a pull request before merging" branch protection setting enabled for the release branch, you'll need to add the Runway + GitHub app to the list of apps allowed to bypass the pull request requirement. Detailed instructions on how to enable this setting are available here.
This automation setting is only available for teams using GitHub as their VCS integration.
Runway will create a release branch off of your working branch for the next release on the scheduled date.
This automation will always be inactive for hotfix releases in Runway.
Runway will trigger the configured Release Candidate build workflow after release is kicked off.
This automation is not supported for teams using TravisCI as their CI/CD integration.
Runway will submit your selected build for review if all previous steps are ready (green).
There are three submission strategy options you can choose from for this automation:
- Submit for review on target date: Runway will submit for review on the specified target date if all previous steps are ready. If automated submission fails, you'll need to update to a future target submit date or release your update manually.
- Submit for review as soon as all previous steps are ready, no earlier than target date: Runway will submit for review as soon as all previous steps are ready, no earlier than the specified target date. If automated submission fails, you'll need release your update manually.
- Submit for review as soon as all previous steps are ready: Runway will submit for review as soon as all previous steps are ready. If automated submission fails, you'll need release your update manually.
You can pause automatic submission by clicking "Pause schedule" from the Schedule drawer in a release.
If automated submission fails, Runway will retry every 5 minutes up to a maximum of 5 times.
This automation will always be skipped (inactive) for hotfix releases in Runway.
Runway will release your app update (or start your phased release, if applicable) on the scheduled target release date if all previous steps are ready (green) and your app update has passed App Store review.
If automated release fails, Runway will attempt to release again every 5 minutes up to a maximum of 5 times. After that, you'll need to update to a future target release date, or release your update manually.
This automation will always be inactive for hotfix releases in Runway.
Runway will release your update to all users early if the release is healthy and has met the predefined conditions.
This automation is not available for OTA apps.
This automation can be configured with:
- One or more health metrics. Only releases whose health metrics are all healthy will trigger an early release to all users.
- At least one condition (such as minimum adoption threshold and minimum phased release day or staged rollout percentage). Only releases that have met the configured conditions will trigger an early release to all users.
You must configure at least one condition and one associated health metric for this automation.
Only releases that have met the configured conditions, and whose associated health metrics are healthy will trigger the automation to release to all users early.
When multiple AABs or APKs are associated with a given Android release version, Runway will look at health metrics for all builds — all must be within a ‘healthy’ threshold and must have met the configured conditions for the automation to trigger.
Runway will halt your phased release / staged rollout if if any associated health metrics fall outside of their defined thresholds.
This automation is not available for OTA apps.
This automation can be configured with:
- One or more health metrics. Any health metrics that fall outside of their defined thresholds will trigger the automation.
- At least one condition (such as minimum adoption threshold and minimum phased release day or staged rollout percentage). Only releases that have met the configured conditions will trigger a halt to the release.
You must configure at least one condition and one associated health metric for this automation.
Only releases that have met the configured conditions, and whose associated health metrics are healthy will trigger the automation to release to all users early.
When multiple AABs or APKs are associated with a given Android release version, Runway will look at health metrics for all builds — any builds with "unhealthy" health metrics will trigger the halt automation as long as all required conditions have been met.
Runway can automatically backmerge changes from the release branch to your working branch and any upcoming release branches. There are two backmerge strategy options to choose from.
At the end of the release cycle, Runway will create a backmerge branch and open a pull request to merge the release branch back into the working branch and any upcoming release branches.
A backmerge branch will only be created if commits are found on the release branch that are not on the base branch.
If the app also has the merge pull requests opened by Runway automation enabled, Runway will attempt to automatically merge the backmerge branch if all required checks have passed.
Any PRs merged into the release branch will be backmerged into the working branch and any upcoming release branches. This process will repeat anytime a new PR is merged into the release branch, so the working branch and upcoming release branches are always kept up to date as new work comes in.
Runway will always open a backmerge PR containing the new changes. You will be responsible for resolving any conflicts that might exist between the backmerge branch and the target branch.
If conflicts exist between the release branch and the target base branch, they must be manually resolved on the backmerge branch before merging. Runway will be unable to automatically merge backmerge PRs if unresolved conflicts exist in the open pull request.
Runway will delete version-specific release branches when the release is complete and tagged.
Only teams that are set up with version-specific release branches may enable this automation.
Runway will cherry pick commits from PRs that contain the specified text pattern in their title from the working branch into the desired release branch.
You can configure the text pattern that Runway will look for in the automation's settings modal (e.g.
runway-pick-{version}). If the text pattern contains the tokens {version} or {versionConcise}, work will be cherry picked onto the release branch for the version specified. If the text pattern does not contain a version-specific token, tagged work will be cherry picked into the next active release version. Note that the target release version must be kicked off in order for tagged work to be pulled in.Runway will always open a pull request with the cherry picked commits against the target release branch.
If the merge pull requests opened by Runway automation is enabled, Runway will attempt to automatically merge the PR once possible (e.g. when all blocking checks have passed).
You can also configure the automation to cherry pick all tagged work into a single PR branch – the automation will continue pulling in newly found tagged work into the same open PR. Note that choosing this option will require manually merging the PR containing all cherry picked fixes.
Runway's cherry picking behavior differs slightly depending on whether the tagged PR was squashed into the working branch, or merged with a merge commit.
If the tagged pull request was squashed, Runway will cherry-pick the squashed commit from the working branch, and squash the resulting pull request against the target release branch when merging automatically.
If the tagged pull request was merged with a merge commit, Runway will cherry-pick individual commits that were part of the tagged PR and open a pull request against the target release branch with the cherry-picked commits. Note that Runway will not cherry-pick the merge commit on the working branch. If Runway is able to automatically merge the resulting pull request against the target release branch, it will merge with a merge commit by default to match the merge style of the original tagged PR.
Runway scans the working branch for tagged PRs and runs the cherry picking sequence for tagged PRs in the order in which they were merged. If it encounters an error during the cherry-pick sequence (either due to a conflict or for any other reason), a notification is sent to Slack or Teams with details on the error, and the automation is blocked from proceeding with further cherry-picks until the error is manually resolved.
Runway will upload build artifacts (.ipa, .apk, or .aab files) from your CI/CD workflow artifacts to App Store Connect or the Play Console for distribution.
To set up this automation, you’ll configure a set of rules that define which artifacts (and from which CI/CD workflows) should be uploaded to which destination. You can also configure specific filenames that Runway should select for the upload action. Each rule requires the following settings:
- The kind of CI/CD workflow for the rule: this can be either the Release Candidate (RC) workflow or the Release workflow configured in your CI/CD integration settings
- The file name to look for when selecting which artifact to upload: this can be a plain string or it can contain any of the supported tokens
- The upload destination: this can be either the beta integration or app store integration for your app
You’ll also need to choose the Upload behavior which will define behavior when there are multiple successful CI/CD builds in a short period of time, and in case an artifact upload fails.
- Upload artifacts for newest build only: If there are multiple successful CI/CD builds in a short period of time, Runway will upload artifacts for the newest available build only.
- Upload artifacts for all builds – stop on failure: Artifact uploads will be attempted for all successful builds serially in order (based on the ordering of the CI/CD workflow build they’re part of). If an artifact upload fails after retry attempts, uploads for any newer builds that have finished will not be attempted.
- Upload artifacts for all builds – continue on failure: Artifact uploads will be attempted for all successful builds serially in order (based on the ordering of the CI/CD workflow build they’re part of). If an artifact upload fails after retry attempts, newer builds will proceed with upload attempts in order.
If an artifact upload attempt fails, Runway will retry twice before updating the status of the artifact upload to Failed
You can see the status of artifact uploads in the Upload status module of the Artifacts section for each build.
Failed uploads can be manually retried by clicking Retry from the Upload status module of the failed build.
Runway will automatically upload dSYMs generated as part of your build process from your CI/CD workflow artifacts to your stability monitoring provider.
To set up this automation, you’ll configure a set of rules that define which CI/CD workflows the automation should apply to, and (optionally) the specific file name for your dSYM zip. By default, Runway will look for any file names matching the following pattern:
{*}.dSYM.zipRunway will always upload dSYM files to the project defined in your stability monitoring integration settings.
If your CI/CD workflow packages all artifacts into a single
.zip file (the default for GitHub Actions and GitLab CI), Runway requires your dSYM artifacts to use a .dSYM.zip extension.Runway will update all issue tracking tickets associated with the release to the configured status upon release completion. You can choose the status you'd like tickets to be updated to.
Customize phased rollouts with blackout dates and times – Runway will pause and resume phased rollouts to avoid phased rollout percentage increments on the blackout dates and times you specify.
Blackout dates for iOS phased rollouts
Runway will automatically increase your staged rollout percentage over the course of multiple days based on your configured settings. You can optionally specify blackout dates and times on which your staged rollout will not increment.
To configure your incremental rollout, choose the number of days (2 - 7 days) and the staged rollout percentage for each day.
Automated staged rollout sequence
You can also specify blackout days and times during which your staged rollout percentage will not be incremented. Runway will resume the rollout once the blackout period has ended if at least 24 hours have passed since the last time the rollout was incremented.
Blackout dates for staged rollouts
If you halt a staged rollout during the course of an automated rollout, you must manually resume the staged rollout and update the staged rollout percentage going forward
Runway will create a new version of your app in App Store Connect once the next release is being prepared in Runway.
Runway will create a draft production release in the Play Console for the current release in Runway if needed, and keep the version name in sync if the version changes in Runway.
Runway will apply your default Export Compliance Information answers (as defined in App Settings) to new builds as they are uploaded to App Store Connect.
Runway will select the latest available build for release in App Store Connect. Note that there may be a processing delay of a few minutes.
Runway will stop automatically selecting the latest build when:
- a different build is manually selected in App Store Connect
- a different build is manually selected in Runway's submission step
- an RC build is manually selected as Active RC in Runway's Release candidate step, and that RC build has an associated app store build
Runway will take the latest available APK/AAB in the Play Console, and apply it to the Draft release on the production track. You can optionally choose to limit automatic selection to APKs/AABs that are already available on a testing track that you specify.
Runway will automatically selecting the latest build when:
- a different build is manually applied to the Production track in the Play Console
- a different build is manually selected in Runway's submission step
- an RC build is manually selected as Active RC in Runway's Release Candidate step, and that RC build has an associated app store build
Runway will automatically apply 'What's new' text or release notes from your chosen source to new release versions. There are two sources for release notes that you can choose from:
- Default release notes: You can define default 'What's new' text or release notes for each locale from App settings > App store defaults > Default notes. Runway will apply these default notes to each new release version.
- Previous release: Runway will use the 'What's new' text or release notes from the previous release version to populate notes for the current release.
Runway will apply 'What's New' text from your chosen source to new versions created in App Store Connect. You can continue to modify the text before you submit your update for review.
Runway will apply release notes from your chosen source to new versions created in the Play Console. You can continue to modify the text before you submit your update for review.
When submitting a new release for review, Runway will apply your default file attachment provided for reviewers (as defined in App Settings) to new versions created in App Store Connect.
Runway will promote any newly uploaded APKs/AABs to your testing track and start the rollout.
Runway will assign any new builds uploaded to TestFlight to your default beta groups for testing. External testers will have access once the build has been reviewed.
Runway will submit any new builds uploaded to TestFlight for beta review as soon as they finish processing.
Runway will apply beta testing notes to new beta builds as they become available. The source of the beta testing notes is configurable as follows:
- Carry over from previous beta build: Runway will apply the beta tester notes from the previous beta build to the most recent build.
- Generate changelog from diff since previous beta build: Runway will automatically generate a changelog from new work in the diff since the previous beta build.
- Generate changelog from diff since last completed release: Runway will automatically generate the complete changelog since the previous release's tag.
Runway will tag your production release commit at the end of each release cycle, and generate a summary of all work going out with the release. The summary will be added to a "Release" in your VCS integration, and will include a list of commits and their associated project management tickets.
Release in GitHub created by Runway
Your previous release must be tagged in order for Runway to accurately compute the summary of work for a release.
Runway may fail to tag your releases automatically in certain cases:
- Your previous release was not tagged
- The build that was released could not be associated with a Release Candidate (CI) build, and therefore could not be linked to a specific commit in your VCS
- Commit info is missing from your build in CI
In these cases, you can manually tag your release in Runway by going to the Release step, choosing a commit to tag, and clicking Create Tag.
When tagging your production release commit, Runway will attach all artifacts generated from your active production build workflow as assets on your release record.
This automation requires the Provide build artifact downloads automation to be enabled. Artifact downloads are currently only supported via GitHub Actions and Bitrise.
Runway will add appropriate labels and/or fix versions when they are missing from tickets that are associated with the release. These label and fix version patterns are defined in Integration settings > Feature affiliations for the app.
Missing labels or fix versions will be applied to a ticket if a piece of code work is in a given release (exists in that release’s diff) and that piece of code work references that ticket (in commit message, PR title, or former branch name)
The missing labels or fix versions are applied once code work enters the final release diff (i.e. exists on the release branch and is in the diff for the release).
Runway will mark releases as completed in your project management tool at the end of each release cycle. This automation is currently only supported for JIRA project management integrations.
Runway will download all artifacts generated from your CI build workflow, and provide direct download links to them from the Runway interface. Additionally, Runway will include artifact information in Slack or Teams build success notifications, including a link to find those downloads in Runway.
Artifact downloads are currently only supported via GitHub Actions and Bitrise.
Runway may create pull requests to fulfill various tasks on demand (for example, bumping your version in code on a development branch). If this automation is enabled, Runway will attempt to merge these PRs without manual approval.
Runway will create a new Runway release record for your next version when your current release is kicked off. This will assign a release pilot and provide a selectable upcoming release via the versions timeline in the App Overview screen.
Runway can automatically manage adding and removing users from App Store Connect and Play Console. This automation can be enabled at the Runway role level to invite users with specific roles to the appropriate store, and grant them the appropriate roles and permissions.
When users are removed from your app in Runway, they will also be removed from the corresponding store. This option is configurable, and can be disabled from the automation's settings.
The roles and permissions granted to users are based on the mapping of Runway roles to App Store Connect roles or Play Console permissions. See below for the default values of this mapping for each platform.
You can configure your own custom mapping rules for each app under App Settings > Team roles.
Users in Runway will automatically be invited to your app in App Store Connect, and assigned the appropriate roles based on their Runway roles.
The App Store Connect API key in use by Runway must have the "Admin" role in order to enable user sync.
Default mapping of Runway role to ASC role:
Runway Role | Default role on App Store Connect |
|---|---|
Admin | Admin |
EM | App Manager |
PM | App Manager |
Engineer | Developer |
Design | Marketing |
Ops | Customer Support |
Marketing | Marketing |
CX | Customer Support |
QA | Customer Support |
Approver | Customer Support |
For additional details on Apple Developer Program roles and associated permissions, see Apple’s documentation.
If a user is removed from your app in Runway, and the option to remove users from App Store Connect is enabled, Runway will revoke access to the corresponding app in App Store Connect.
Users in Runway will automatically be invited to your app in Google Play Console, and be granted the appropriate permissions based on their Runway roles.
You must update the permissions on the service account associated with your Runway Play integration to “Admin” in order to enable user sync. You can do this by visiting API Access > View Play Console permissions > Account permissions and selecting "Admin"
Default mapping of Runway role to permissions on the Play Console:
Runway Role | Play Console Permissions |
|---|---|
Admin | Admin (all permissions) |
EM |
|
PM |
|
Engineer |
|
Design |
|
Ops |
|
Marketing |
|
CX |
|
QA |
|
Approver |
|
For additional details on the Google Play Console’ developer account users and managing permissions, visit their documentation.
If a user is removed from your app in Runway, and the option to remove users from the Play Console is enabled, Runway will revoke access to the corresponding app in Play Console.
Runway will post an installation QR code on open PRs any time a new Build Distro bucket build is available for installation. Note that the bucket must be configured with a PR rule to pull in builds from open PRs against a base branch. This automation is only available for apps using GitHub as their VCS integration.
Runway will generate and apply build tester notes for new Build Distro bucket builds using the work items diff for the build.
By default, any time a Runway automation modifies code in your repository, it will open a pull request with the changes. If you have the Merge pull requests opened by Runway automation enabled, it will attempt to merge the pull request as soon as all checks have passed. However, in many cases teams choose to protect certain branches with required pull requests and lengthy integration checks, and Runway cannot merge open PRs until all of the requirements for the pull request have been met.
Certain Runway automations surface an option to Bypass pull requests and allow Runway to commit and push changes to the target branch directly. Teams may choose to enable this option if code changes are relatively trivial and harmless (e.g. version bumps) and they would prefer not to need to meet strict pull request criteria for these kinds of changes.
If a target branch has branch protections enabled, and the branch protections require pull requests for merging or restrict pushes to the target branch, you must first update the branch protection settings in your VCS in order for the Bypass pull requests automation setting to function properly.
To allow Runway to bypass required pull requests for your target branch, follow these steps:
- 1.Navigate to your repository settings in GitHub
- 2.Select Code and automation -> Branches and find the branch protection rule for the target branch you'd like to allow Runway to bypass pull requests for
- 3.Under the Require a pull request before merging option, make sure that the setting Allow specified actors to bypass required pull requests is enabled
- 4.Under the Allow specified actors to bypass required pull requests setting, add the "Runway + GitHub" app to add the Runway GitHub app to the list of apps allowed to bypass pull requests for the branch
If your branch protection rule additionally has the Require checks to pass before merging option enabled, Runway will need to first push changes to a branch so status checks can be run before automatically merging. In order to support this, your status checks must be configured to run on
push for branches matching the pattern runway-check-*. This will let status checks run on Runway-created branches, which will enable Runway to automatically merge changes into protected branches.
To enable Runway to bypass merge requests in GitLab and push directly to a target branch, follow these steps:
- 1.In GitLab, select Main menu > Projects and find your project
- 2.On the left sidebar, select Settings > Repository
- 3.Expand Protected branches
- 4.From the Branch dropdown list, select the target branch
- 5.From the Allowed to push list, select the user that originally installed the GitLab integration in Runway
GitLab's integration with Runway is OAuth-based, which means that the integration's scopes and permission are tied to those of the GitLab user that ran through the OAuth flow in Runway. To avoid unintentionally granting push access to a specific user (and to avoid integration issues if that user leaves the company), we strongly suggest setting up a service account user to use for authentication between GitLab and Runway.
To enable Runway to bypass pull request restrictions on Bitbucket and push directly to a target branch, follow these steps:
- 1.Go to a repository in a project
- 2.Choose Settings > Branch permissions and select the target branch
- 3.Under the Prevent changes without a pull request except by: restriction, select the user that originally installed the Bitbucket integration in Runway
Bitbucket's integration with Runway is OAuth-based, which means that the integration's scopes and permission are tied to those of the Bitbucket user that ran through the OAuth flow in Runway. To avoid unintentionally granting push access to a specific user (and to avoid integration issues if that user leaves the company), we strongly suggest setting up a service account user to use for authentication between Bitbucket and Runway.