Balsa supports all versions of Github, including GitHub.com, GitHub Enterprise Cloud, and GitHub Enterprise Server.
To sync with GitHub, you'll need a Personal Access Token. To create one, follow the instructions below. If you have questions or run into trouble, email us at support@balsa.com. We're happy to help!
Finding the Personal Access Tokens page
Getting to this page differs a bit, depending on which version of GitHub you're using:
- If you're using GitHub.com or GitHub Enterprise Cloud (not GitHub Enterprise Server on your company's domain), you can jump directly to the Personal Access Tokens page on GitHub here: https://github.com/settings/tokens.
If you're using on-premise GitHub Enterprise hosted on your company's domain, you can find the Personal Access Tokens page by expanding this section. (Click the black ▶ icon.)
1️⃣ First, click on your profile picture in the top right corner, then click "Settings":
2️⃣ Next, click "Developer settings" toward the bottom of the menu on the left:
3️⃣ Lastly, click "Personal access tokens" at the bottom of the menu on the left:
✅ You should now be on the "Personal access tokens" page. Continue below.
Creating a Personal Access Token
Once you're on the Personal Access Tokens page, create a token as follows:
1️⃣ Click "Generate new token" in the top right:
2️⃣ Type a name for the token. For simplicity (and so it's easy to remember), we recommend "Balsa":
3️⃣ Check the boxes for the permissions balsa needs (repo, read:org, and read:discussion):
4️⃣ Click "Generate token" at the bottom of the page:
5️⃣ Here's your token! You can copy it to your clipboard by clicking the clipboard icon. (Don't worry, the token in this screenshot isn't a real API token. 😅)
If your company uses GitHub Enterprise, you will probably see an "Enable SSO" button next to your token, like in the screenshot below. If you see this button, you'll need to perform a few extra steps later on. Just keep this browser tab open for now. We'll explain later!
6️⃣ Switch over to Balsa, and paste it in Settings, here:
If you saw an "Enable SSO" button in step 5️⃣ above, expand this section! (Click the black ▶ icon to the left.) If not, continue below.
Did you paste your Personal Access Token into GitHub? If not, do that now, before these steps. Otherwise you won't be able to see your token anymore!
👋 Hi! Your company uses GitHub SSO, so we have a couple extra steps. First, click the "Enable SSO" button:
Next, click the "Authorize" button next to your organization, in the menu that appears:
On the next screen, click the "Continue" button. This will take you to your company's SSO login flow in Okta, OneLogin, or similar.
Once you're done signing in, you'll see the following screen. Click "Continue".
You're done with the extra steps! 😅 Continue below.
7️⃣ Click "Save" at the bottom of the Settings screen:
🏁 You're done! GitHub should start syncing. If it doesn't, or you run into other problems, get in touch with us by emailing support@balsa.com.
