In this tutorial we'll take a closer look at integrating GitHub with Bitrise, using SSH keys, webhooks and more.
Connecting your GitHub account
You can join Bitrise with your existing GitHub account. In order to do so, you just have to click the “Log In with GitHub” button on the Sign In page. The next step is a standard OAuth flow, this means you have to enter your credentials in the GitHub’s login page. Your password won't be shared with Bitrise ever.
If you already have a Bitrise account it's still possible to link it to GitHub. Go to your Account settings and flip the switch on the left side right next to the logo. This will take you through the exact same OAuth flow I mentioned before.
If you have a working connection you can use the joined GitHub account for one-click login plus Bitrise will be able to view all your personal repositories including public and private ones. That's quite handy if you are going to automate delivery workflows for apps located inside the protected area. 🔒
Setting up an SSH key
Connecting your GitHub account is just the first chapter of the whole story. Bitrise can now see your repositories, but it won't be able to check out the actual source code. You have to give explicit access for this by registering an SSH key-pair for every single repository. You might ask the question:
What the heck is an SSH key-pair?
The SSH protocol is used for remote logins in a secure way. It employs public key cryptography or also known as asymmetric cryptography. A key-pair is a combination of a public and a private key. Anyone who has the public key can encrypt data, but only the person who holds the corresponding private key can decrypt and read it.
You can connect to GitHub using SSH, they support public key authentication. Bitrise can automatically generate and setup the required key-pairs for newly created apps if you have admin access for the given repository. Keys can be generated manually, by using the following command:
If you choose the manual setup, you can simply copy & paste the keys to both GitHub (public key) and Bitrise (private key). If a key is compromised for some reason you can simply throw it away and generate a new one for future use.
Keys can be used in a local scope (per repository), or you can associate SSH and GPG keys with your account. This means using an account-wide key will grant access to everything that's visible for you. I prefer going with the separate key per repo approach, because giving global access to a consumer can be risky sometimes.
Use SSH keys wherever you can!
SSH keys can be used to clone git repositories directly to your computer. This way you can avoid using the username and password combination, which is quite a security risk nowadays without any 2fa method enabled. Take my advice, turn on 2fa now and enforce it for your entire organization as well.
Another best practice is to use an SSH config file, mine looks somewhat like this:
You can utilize the same approach for remote logins. Just append your public key inside the ~/.ssh/authorized_keys file. Now you can use the ssh <Host> command instead of specifying user names, ports or identity files. It's fast & secure! 😉
Summarizing this, we can say that using the SSH protocol with key-pairs is the best way to communicate with remote git repositories and servers. Bitrise has excellent support that turns the whole process into a single click for setting up keys on GitHub. If you ever need to upload a key manually to a GitHub repo, you can find this option under the repository’s Settings tab, just look for the Deploy keys menu item. 🔑
Organizations and access policy
I've only talked about private repositories until this point. Let's have a quick look at organizations and access control. You might have noticed that during the OAuth process there was a Grant button next to some organizations, but some were marked as available immediately. What's the reason behind this?
By default, GitHub organizations are completely accessible for third-party applications. However, you can set up a restriction policy through the organization’s settings page. You can access this from your personal settings too, just click the organization name on the bottom left corner and select the Third-party access menu.
If you enable restrictions only those third-party apps can see your repositories who have explicitly requested permissions using the grant button. This way you can be sure that no member from your organization will accidentally leak private data, as only users with the proper role can approve pending authorization requests. 😅
If you forgot to press the grant button for some reason, you can go to your personal settings page on GitHub, select the Applications menu and click the Authorized OAuth Apps tab. There you can click on any OAuth app to grant or revoke access.
Quick note: Bitrise has organization support too. You can create one by pressing the + icon. Organization owners can manage their repositories. Existing Bitrise apps can be transferred between accounts and organizations. (More info here.)
Personal Access Tokens (PATs)
Personal access tokens function like ordinary OAuth access tokens. They can be used instead of a password for Git over HTTPS, or can be used to authenticate to the API over Basic Authentication.
Some Bitrise steps are designed to use PATs to communicate with GitHub. You can generate or revoke them under the Personal access tokens settings. You can provide a description for each token, that's basically a name and a scope. You should be pretty careful here, never give more scope to a token than it actually needs.
PATs can be stored safely on Bitrise. The Secrets tab in the Workflow editor gives you safe storage where every variable is stored encrypted, they are not exposed in the bitrise.yml file and you can hide them on the UI by marking them protected. 🤫
Comment on GitHub Pull Request is one specific example for a step that uses a Personal Access Token. Anyway if you ever need to store PATs or any sensitive information on Bitrise, don't forget that Secrets are specially made for this.
Webhooks
In my previous article about migrating Travis to Bitrise I've already mentioned webhooks and GitHub status checks. If you connected your GitHub account, Bitrise can automatically register the required webhooks for your repository with just one click during the setup or later on in the Code tab of the app.
By adding a webhook you can trigger a build based on certain events. If you want to add the webhook by hand you should go to the Code tab on Bitrise, press the Setup manually button, select the service you want to use and finally copy the URL and paste it under the git repo settings / Webhooks / Add webhook page in the Payload URL field.
Status checks for pull requests
The advantage of having a webhook with a trigger is that Bitrise can do automatic status checks for your pull requests. This comes in handy if you'd like to do some extra sanity checks or validations. The trigger mechanism setup is a no-brainer if you already have a working webhook integration. Just open the Workflow editor and see for yourself under the Triggers tab. 🚫🧠
Status image
The last thing that I wanted to mention is quite a funny one if you are old enough. Do you remember the classic little pixelated badges in the footer of every webpage? The valid XHTML and some other standards are mostly dead by now, but badges are here to stay and Bitrise has some really neat support for build status images. 💀
If you want to have a quick look at your latest build status on GitHub, you should embed the build status image directly into your readme file. Simply select your preferred format and copy & paste the contents of the Embed field from Bitrise. 🤩
As you can see Bitrise ❤️ GitHub, you can create a deeply integrated secure workflow for yourself or for your entire organization. Personal data protection and security are really important for these guys. Let's go ahead, try out for yourself!
