Skip to main content

Bitrise Checks on GitHub

Abstract

Bitrise Checks is a Github app which provides an extended version of the classic status checks Bitrise sends back to GitHub.

Bitrise Checks is a Github app which provides an extended version of the classic status checks Bitrise sends back to GitHub. Bitrise Checks include a Bitrise build summary and a check status. You can view Bitrise Checks if you click the Details link of a pull request on GitHub. It unfolds the detailed build summary and build status Bitrise Checks attaches to your pull request on the Checks tab of GitHub.

GitHub Enterprise Server is not supported

Bitrise Checks is not supported in GitHub Enterprise Server deployments. If you would like to use Bitrise Checks in a GitHub Enterprise environment, we recommend using GitHub Enterprise Cloud.

Bitrise Checks on GitHub Checks
Bitrise Checks on GitHub Checks

There can be three different check statuses:

  • Success.

  • Failed.

  • Action required (in the case of manual pull request approval).

Installing Bitrise Checks

Using Bitrise Checks is just a few clicks away. Let’s do this!

Admin access only

Only users with the role of admin on the app's team can access all functions of the App Settings page of an app.

  1. Open your app on Bitrise.

  2. On the main page of the app, click on the App Settings icon: settings.svg.

    app-settings.png
  3. On the left, select Integrations from the menu options.

  4. Click the install our Bitrise Checks app to your GitHub repository LINK under the toggle. Don’t toggle the switch just yet, since you first need to install Bitrise Checks.

    This link will take you to GitHub's Bitrise Checks installation page.

    github_checks_install.png
  5. On the Install Bitrise Checks page, select the user or GitHub Organization you want to add Bitrise Checks to.

    Bitrise Checks on GitHub Checks
  6. Decide if you wish to install Bitrise Checks to all your repositories or just to a selected few. With this you grant rights to Bitrise Checks to integrate with your repository and use GitHub Checks to display check results.

    Bitrise Checks on GitHub Checks
  7. In the GitHub prompt, provide your GitHub password.

If all goes well, you land on the Bitrise Checks page of GitHub. You should see a blue note at the top-left corner of the page that Bitrise Checks has been successfully installed on your GitHub account.

Bitrise Checks on GitHub Checks

Enabling GitHub Checks on Bitrise

Once Bitrise Checks is installed on GitHub, you need to enable GitHub Checks on your app’s page on Bitrise.

Enabling GitHub Checks is limited

Please note that only Workspace owners and app admins can enable this toggle on the App Settings page of the app.

Admin access only

Only users with the role of admin on the app's team can access all functions of the App Settings page of an app.

  1. Open your app on Bitrise.

  2. On the main page of the app, click on the App Settings icon: settings.svg.

    app-settings.png
  3. On the left, select Integrations from the menu options.

  4. Scroll down and toggle on the GitHub Checks switch.

    Can't toggle the switch?

    If you can't toggle the switch, check out Can't enable GitHub Checks.

And you’re done! Now any pull request you open to your app on GitHub will be validated with Bitrise Checks and a build will get automatically started on Bitrise (if the pull request trigger is properly set on Bitrise).

You can easily get to your app’s page on Bitrise. If you click on the build summary or on View more details on Bitrise Checks link on the Checks tab, you’ll quickly get to your app’s Build page.

Can't enable GitHub Checks

There are two main reasons why you might not be able to toggle the switch to enable GitHub Checks:

  • You cannot toggle the switch unless you install Bitrise Checks FIRST. Once it’s done, you can go ahead and toggle the switch to the right to enable it.

  • If you have renamed or moved the GitHub repository of an app which has already been added to Bitrise and you have installed Bitrise Checks on it. The repository’s GitHub URL has obviously changed. GitHub Checks switch can only work if the URL on Github and on Bitrise fully match (no redirect URL is allowed). So in this case, you have to manually update the Repository URL of your app.

    Change_repo_URL.png

Switching to Bitrise Checks from previous CI checks

If you have been already using status checks on pull requests prior to merging, it must have been the ci/bitrise/... check system. To be able to use Bitrise Checks, you have to manually switch from ci/bitrise/... to Bitrise to access those detailed checks. Let’s see how!

Bitrise Checks on GitHub Checks
  1. Go to the Settings tab of your repository.

  2. Click Branches on the side menu. Under Require status checks to pass before merging, you can see ci/bitrise/... as the selected checks system.

    Bitrise Checks on GitHub Checks
  3. Select Bitrise instead of ci/bitrise/....

  4. Merge a pull request.

Disabling GitHub Checks

You can easily disable GitHub Checks on Bitrise if you toggle the ENABLE GITHUB CHECKS switch to the left on the Settings page of the app.

If you decide to uninstall Bitrise Checks from your GitHub account, you can click the Uninstall button on the Install GitHub Apps page.

Bitrise Checks on GitHub Checks

GitHub Checks test summary

If your app’s repository contains any UI or unit tests, you can run those tests by using the appropriate testing Steps in your Workflow, and if you add the Deploy to Bitrise.io Step, your test results will be displayed in our Test Reports page and you can also see them on GitHub Checks, too.

For example, if you have an Android app, you can use the Virtual Unit Testing for Android Step to be able to see all your test results on GitHub Checks.

test_reports.png

Step by Step error report

If a CI build runs, GitHub Checks' test summary displays the Steps' successful and failed tests in separate tabs on the left sidebar. If you click on a Step, a more detailed report summary comes up where a number of tests are listed with actionable error report. The build summary is available on the Bitrise tab.

Please note that GitHub Checks' test summary can only print detailed information of the following Steps:

  • Xcode Test for iOS

  • Android Unit Test

  • iOS Device Testing

  • Virtual Device Testing for Android

  • Flutter Test

You can export test results generated by any other Step to the Deploy to Bitrise.io Step in two ways:

  • We strongly recommend using our Export test results to the Test reports add-on Step: this Step locates the test results based on your inputs.

  • You can configure your own custom Script Step that creates and exports the necessary files.

Checking the test results of a failed Step

If your build has some failed tests, here is how to access them in GitHub Checks:

  1. Click the Bitrise Checks dropdown.

  2. Click on a Step and view the error report of the specific Step.

You can click on other Steps from here or the build summary. The View more details on Bitrise Checks link takes you to the build page on Bitrise.

Re-running a build using GitHub checks

Role requirement

To re-run a build using GitHub Checks, your GitHub account must connected to Bitrise, and you need to have at least Developer role in your app's team. If these conditions are not met, re-run checks will fail without an error.

For a complete list of user roles and role cheatsheets, check User roles on app teams.

If you would like to re-run a build using GitHub Checks:

  1. Open the pull request on GitHub where you would like to re-run checks.

  2. Open the Checks tab.

  3. Click Re-run all checks.

    re_run_test.png