GitHub

Set up

Navigate to the Integration settings view

1. Select an app in the top left corner from the Switcher

2. Navigate to App Settings by clicking the gear icon (⚙️) at the top of the Timeline sidebar

3. Click on Integrations in the sidebar

Connect GitHub

• Find the GitHub integration module under the Version control section

• Click the Connect button

• You’ll be taken through a standard GitHub app OAuth flow

  • Select one or more repos to grant access to

You must be logged in as a GitHub user with admin permissions in selected repo, or as an owner in the GitHub org.

• GitHub redirects you back to Runway

  • If you granted access to more than one repo, Runway will present you with a dropdown to select a specific repo

Add a release tag pattern

• Runway uses this to read tags from GitHub and delineate your releases, and also to generate tags when auto-tagging releases upon completion

• Pattern accepts the string {version} as a stand-in for the release version, e.g. v{version}

Runway expects version strings that adhere to Semantic Versioning principles — formatted as x.y.z (representing major.minor.patch).

Add a release branch pattern

• For GitFlow or similar, pattern accepts the string {version} as a stand-in for the release version, e.g. release-ios-{version}

  • You can assign different patterns to different types of releases using the Release type dropdown

• Omit pattern for trunk-based, e.g. main

  • Be sure to select all types in the Release type dropdown

Add any additional branches

• Working branch: your main working branch, e.g. development

• Staging branch: if you create your Release Candidate builds from a branch other than your release branch, set that here

• Deploy branch: if you create your final builds from some branch other than your release branch, set that here

Adjusting permissions in GitHub

Certain permissions need to be configured in GitHub in order for Runway to execute automations.

How to update branch protection settings in GitHub

GitHub now offers two different ways to protect your repository's branches: "classic" branch protection rules, and rulesets. Of the two options, rulesets provide much more flexibility in how rules and bypasses are defined, and are much easier to get working with Runway. If your team is already using rulesets, click here for instructions on how to configure repository rulesets to allow Runway to bypass pull requests. If your team is still using branch protection rules, we highly recommend considering migrating to rulesets, which provide much better granularity and scoping for different types of repository rules.

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 the list of apps allowed to bypass pull requests for the branch

1. Under the Restrict who can push to matching branches setting, add the "Runway + GitHub" app to the list of apps allowed to push to the protected branch

1. (Optional — to allow Runway to create new branches) Under the Restrict pushes that create matching branches setting, add the "Runway + GitHub" app to the list of apps allowed to create matching branches

If you're seeing 422 Reference update failed errors and you have ensured that your branch protection settings are appropriately configured, the error may be due to an illegal branch pattern.

To test, please try to create the branch directly in GitHub and see if you receive the following error:

Sorry, that branch name is invalid.

Ensure Runway can run status checks if needed

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.

How to configure GitHub branch rulesets to enable pull request bypass

Enabling pull request bypass for Runway if your team is using GitHub rulesets is surprisingly simple thanks to the flexible and layered nature of how rulesets work. At a high level, simply adding the GitHub + Runway app to the bypass list of your repository's ruleset that contains the "Require a pull request before merging" branch rule will grant the Runway GitHub app permission to merge to directly to the target branch.

The Runway + GitHub app should be added to the bypass list of any enabled rulesets that target the branches you'd like Runway to commit directly into and that enable any of the following rules:

• Require a pull request before merging - required for enabling committing version bumps directly onto your team's target branch.

• Require status checks to pass - required to enable committing and pushing version bumps to your team's target branch without requiring status checks to first pass in a different branch.

Consider also adding Runway to the bypass list of any rulesets that contain the following rules:

• Block force pushes - Runway needs to be able to force push to newly created hotfix branches if your team uses the "Create hotfix and cherry-pick fixes" flow to create hotfix releases and choose specific fix commits to be included in the hotfix branch

• Restrict deletions - required to enable the Delete version-specific release branches at the end of the release cycle automation

• Restrict creations - required to enable the Kick off release on target date automation or functionality in the Runway dashboard if your team uses version-specific release branches

How to configure GitHub tag rulesets to enable tag creation

Add the Runway + GitHub app to the bypass list for any active rulesets on the selected repositories where Runway needs to create tags, if those rulesets include any of the following rules:

• Restrict creations - required for creating new tags