## 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](https://developer.github.com/apps/) OAuth flow
* Select one or more repos to grant access to
{% hint style="warning" %}
You must be logged in as a GitHub user with **admin** permissions in selected repo, or as an **owner** in the GitHub org.
{% endhint %}
* 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}`
{% hint style="info" %}
Runway expects version strings that adhere to [Semantic Versioning](https://semver.org/) principles — formatted as `x.y.z` (representing `major.minor.patch`).
{% endhint %}
### **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](https://docs.runway.team/automations/types-of-automations).
### How to update branch protection settings in GitHub
{% hint style="info" %}
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 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.
{% endhint %}
#### Rulesets
If your team uses rulesets, follow these steps to configure repository rulesets to allow Runway to bypass pull requests:
1. Navigate to your repository settings in GitHub
2. Select **Code and automation -> Rules -> Rulesets** and find the ruleset that you'd like to allow Runway to bypass pull requests for
3. Add Runway to the **Bypass list**
#### Branch protection rules
If your team uses branch protection rules, follow these steps to allow Runway to bypass required pull requests for your target branch:
1. Navigate to your repository settings in GitHub
2. Select **Code and automation -> Branches** and find the branch 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
5. 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
6. *(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
{% hint style="info" %}
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.`
{% endhint %}
### Ensure Runway can run status checks if needed
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 add the Runway + GitHub app and mark it as **Exempt** to the bypass list of your repository's ruleset that contains the "Require a pull request before merging" branch rule. This 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](#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](https://docs.runway.team/automations/types-of-automations#kick-off-release) 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
