Skip to main content

GitHub app configuration

Abstract

Configure the Bitrise Github app integration via the API: change the connection type from OAuth to the GitHub app, enable full permissions for the GitHub app, set additional linked repositories, and remove other authorization methods.

After you successfully installed a Bitrise GitHub app, you can use it as your default Git connection method. Configure the Bitrise GitHub app integration via the API:

  • Change the connection type from OAuth to the GitHub app.

  • Enable the full permissions defined for the GitHub app.

  • Set additional linked repositories.

  • Remove the service credential user and other authorization methods as they aren't required for the GitHub app.

Changing the connection type from OAuth to the GitHub app

Change your GitHub connection from an OAuth application to the Bitrise Github app through the API via the POST /apps/{app-slug}/change-connection-type endpoint. The accepted values are:

  • github

  • github-app

To change the connection type to the GitHub app:

curl -X 'POST' \
  'https://api.bitrise.io/v0.1/apps/APP-SLUG/change-connection-type' \
  -H 'accept: application/json' \
  -H 'Authorization: ACCESS-TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "connection_type": "github-app"
}'

Changing a connection is a non-destructive action: other authentication methods aren't removed. You can check if your builds still work. If there is an issue, you can change back to an OAuth connection.

To revert the connection:

curl -X 'POST' \
  'https://api.bitrise.io/v0.1/apps/APP-SLUG/change-connection-type' \
  -H 'accept: application/json' \
  -H 'Authorization: ACCESS-TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "connection_type": "github"
}'

Extending GitHub app permissions to builds

The Bitrise GitHub App generates a short-term, temporary token for each build that is triggered via the app. This token has only one permission by default: content:read. This means the build can access the GitHub repository but can't do anything else.

You can extend these permissions so that you can perform other operations during a build. For example, this can enable users to push Git tags from their builds, create custom status reports, put a label on a pull request, or push a new version number.

Use the use_full_permission parameter of the PUT /apps/APP-SLUG/github-app-connection-configuration endpoint to extend permissions:

curl -X 'PUT' \
  'https://api.bitrise.io/v0.1/apps/APP-SLUG/github-app-connection-configuration' \
  -H 'accept: application/json' \
  -H 'Authorization: ACCESS-TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "use_full_permission_set": true
}'

More information

Read more about extending permissions and how to do it on the GUI: Extending GitHub app permissions to the builds.

Setting additional linked repositories

A linked repository is a repository that a Bitrise project can access using a GitHub app installation but it's not the project's primary repository. When an additional repository is linked to your Bitrise GitHub app installation, the tokens generated for the build can access the additional repository.

Read more about additional linked repositories: Additional linked repositories via a GitHub App.

Use the POST /apps/APP-SLUG/github-app-connection-configuration/update-linked-repositories to link an additional repository. You have two choices:

  • Manually listing the full names of the repository.

    curl -X 'POST' \
  'https://api.bitrise.io/v0.1/apps/APP-SLUG/github-app-connection-configuration/update-linked-repositories' \
  -H 'accept: application/json' \
  -H 'Authorization: ACCESS-TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "repositories": ["org1/repo1", "org1/repo2"]
}'

  • Set the unlimited_repo_access field to true to let the builds access all the current and future repositories.

    curl -X 'POST' \
  'https://api.bitrise.io/v0.1/apps/APP-SLUG/github-app-connection-configuration/update-linked-repositories' \
  -H 'accept: application/json' \
  -H 'Authorization: ACCESS-TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "unlimited_repo_access": true
}'

Removing the OAuth connection

If your GitHub app connection works, you can remove the components of the OAuth connection. This includes:

Removing the service credential user

To remove the service credential user:

curl -X 'DELETE' \
  'https://api.bitrise.io/v0.1/apps/APP-SLUG/service-credential-user' \
  -H 'Authorization: ACCESS-TOKEN'

Removing SSH or HTTP authorization

To remove previous authorization methods:

curl -X 'DELETE' \
  'https://api.bitrise.io/v0.1/apps/APP-SLUG/repository-authorization ' \
  -H 'Authorization: ACCESS-TOKEN'
In this section: