GitHub Integration

Connect your GitHub account to import issues, pull requests, and manage work from Sunsama.

Bring your GitHub issues and pull requests into your daily plan. Browse them by repo or project in a panel beside your task list, drag in what you’ll work on today, and see the full issue or PR without leaving Sunsama.

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.

    • Go to Settings > Integrations > GitHub and click Add GitHub account. You can connect one GitHub account.
    • 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 GitHub App or Manage App installations in Settings.
    • Or visit this link directly: Install Sunsama GitHub App
    • It’s possible someone in your organization has already installed the GitHub app.

The same settings page has an Include your activity from this tool in your Daily Highlights? toggle, and a Remove button for the account.

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.

Managing installations

Installations of the Sunsama GitHub App can be managed through the GitHub App installations section of the GitHub integration settings, or directly on GitHub through this link: Manage installations.

Understanding scopes and permissions

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

The Sunsama GitHub App 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)

Browsing and importing issues and pull requests

Open GitHub in the right hand panel (keyboard shortcut Shift I). Choose the Issues, PRs or Projects tab.

Finding issues and pull requests

  • Repo: pick a repository. Repos you’ve Recently contributed to are listed first.
  • Open or Closed: show open or closed items.
  • Assignee: show items Assigned to me, Unassigned or All.
  • Reviews (PRs only): filter by Approved review, Changes requested, Reviewed by you or Awaiting review from you.
  • Search: type a GitHub search query, like is:pr is:open.

On the Projects tab, select a project, then a column, to see its cards.

Importing issues and pull requests

When you’re ready to work on an issue or PR, pull it into your plan:

  1. Drag the card from the GitHub panel onto your task list.
  2. To timebox it right away, switch to calendar view (J) and drag the card onto your calendar at the time you’ll work on it.
  3. Click the card and choose Add to today (or hover and press S), or pick another date.

If you use the Gmail integration, GitHub notification emails in the Gmail panel also link to the PR, issue or discussion they’re about. Click the link to preview it and add it to a day.

Working with imported tasks

An imported issue or PR becomes a Sunsama task linked to the original. Click the GitHub icon on the task (or hover and press G) to open it in GitHub.

Open the Sunsama task to see the issue, pull request or discussion inside it, as GitHub shows it: its state, description and timeline, and for a PR its checks, reviewers and head branch. This view is read-only, except for labels: you can edit labels when your connection lets Sunsama make changes in that repository. With the read-only GitHub App, labels are shown and changed in GitHub. Comment in GitHub.

The Sunsama task works like a worksheet for the GitHub item. Add notes, subtasks, time tracking and comments there without touching what your collaborators see in GitHub. Closing an issue or merging a PR doesn’t complete the Sunsama task, and completing the task doesn’t change GitHub.

Sunny and Autoplan

Sunny can read your GitHub issues and pull requests when you ask about them, for example “which PRs are waiting on my review?”. Autoplan also looks at GitHub when it drafts your day. To stop Autoplan from using GitHub, open Integrations on the daily planning screen and turn GitHub off.

Troubleshooting and FAQ

I can’t see my organization’s private repositories

Install the Sunsama GitHub App for that organization, or ask an owner to approve your request. See Installing for an organization.

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.