Github Integration

Installation and Account management

Sunsama’s GitHub integration is managed through a “GitHub App”. There are two main steps to connect your Sunsama and GitHub.

1. Authorizing Sunsama to know who you are on GitHub.
   • Click the “Add Account” button in the GitHub integrations settings.
   • This is enough for the integration to work with just your public GitHub activity. If you only need to use Sunsama with public repositories, issues, pull requests and projects: you’re done.
2. Installing the Sunsama GitHub App for every account for which you want to access private repositories (and their issues, pull requests and projects)
   • Click “Install app” or “Manage app installations” button in Settings.
   • Or visit this link directly: https://github.com/apps/sunsama/installations/new
   • It’s possible someone in your organization has already installed the GitHub app.

Installing the Sunsama GitHub App

The Sunsama GitHub app can be installed for Personal accounts and Organization accounts.

Installing for a Personal account

Anyone can install the Sunsama GitHub App for their personal account. Aside from private repositories, doing so also gives Sunsama access to which repositories (that it can access) you’ve most recently contributed to. This allows Sunsama to surface the most relevant repositories more readily:

Installing for an Organization

The installation interface guides you through the process of installing the Sunsama GitHub App for any Organizations you’re a part of.

If you have the necessary permissions, you’ll be able to install just like you can for your personal account. If you don’t have this permission, GitHub will prompt you to “request” the installation of the GitHub App, instead. Until this has been approved, you won’t be able to access the private repositories for this organization inside Sunsama.

📘

Installing GitHub Apps for an Organization is done by “owners” or the organization or, alternatively, requires the “GitHub App manager” role. This role can be assigned by organization owners to give other organization members the ability to install either one or many GitHub Apps. See their documentation for more details: https://docs.github.com/en/organizations/managing-programmatic-access-to-your-organization/adding-and-removing-github-app-managers-in-your-organization

If your company doesn't show up in that list, perhaps they haven't added you to their account as a member?

Managing installations

Installations of the Sunsama GitHub App can be managed through the GitHub App installations sections of the GitHub integration settings, or directly on GitHub through this link: https://github.com/apps/sunsama/installations/new

Understanding Scopes and Permissions

Sunsama’s integration with GitHub allows you to control which organizations and which repos in an organization Sunsama can access.

Sunsama only requests read-only permissions for Issues, Pull Requests, Projects, Discussions and limited repository meta data. At no point can Sunsama read actual code, be it entire files, or the contents of pull requests. Sunsama uses these permissions to allow you to:

• pull in GitHub issues, PRs into your task list
• automatically surface the work you did in GitHub (comments, PRs, discussions) in your end of day review (see Daily Highlights)

Troubleshooting and FAQ

Quickly add a Github issue to your task list using the URL

Rather than browsing through the GitHub integration panel to add a task to your Sunsama task list, you can use the URL of that issue from GitHub. Simply paste the URL of the issue into a new Sunsama task's title, and Sunsama will automatically create a full task containing the GitHub issue's details.

This is a good option if you are already viewing the issue in GitHub and want to quickly create a Sunsama task for it without having to find it in the integration panel.