GitHub + Microsoft Teams Integration
Help Your Teams Communicate and Collaborate Better
GitHub is the world's leading software development platform. Microsoft Teams is one of the most popular communication platforms where modern development teams come together to build world-class products and services. With two of your most important workspaces connected, you'll stay updated on what's happening on GitHub without leaving Microsoft Teams.
Developers spend a considerable amount of time communicating with the team, monitoring the issues, pull requests and deployment statuses. This necessitates constant switching of context between GitHub and Microsoft Teams (collaborate). The GitHub integration for Microsoft Teams gives you and your teams full visibility into your GitHub projects right in your Teams channels, where you generate ideas, triage issues and collaborate with other teams to move projects forward.
GitHub integration for Microsoft Teams is now GA and is built and maintained by GitHub.
Table of Contents
Installing the GitHub integration for Teams
Requirements
This app officially supports GitHub.com (which includes our GitHub Enterprise cloud-hosted offering) and Teams.microsoft.com.
Installation
You can go to Microsoft teams app store and install GitHub app or you can directly install from here.
Upon installing, a welcome message is displayed as shown in the following image. Use the @GitHub handle to start interacting with the app.
Get Started
At this point, your Teams and GitHub user accounts are not linked. To link the two accounts, authenticate to GitHub using a @github signin command.
Subscribe notifications
You can subscribe to get notifications for pull requests and issues for an Organization or Repository's activity using @github subscribe <organization>/<repository> command.
Before you subscribe, a Microsoft Teams app needs to be installed in GitHub and you need to grant access to the repositories you would like to subscribe.
If you originally gave the app access to "All repositories" and you've created a new private repository on GitHub after installing the GitHub integration for Teams, the @github subscribe command will work automatically on your new repository. If you installed the app on a subset of repositories, the app will prompt you to install it on the new repository.
You need to be an organization / account owner to install the app. If you dont have access, you can request your account owner to configure the Microsoft Teams app to grant access to the repositories you need work on. You can find this app in your organization settings -> applications -> installed apps. This is a one time activity and after that you can subscribe to repository / organization in the channel of your choice.
The @github command also supports unsubscribe. To unsubscribe to notifications from a repository, use @github unsubscribe <organization>/<repository>
Customize notifications
You can customize your notifications by subscribing to activity that is relevant to your Teams channel, and unsubscribing from activity that is less helpful to your project.
You can configure them using following commands:
@github subscribe owner/repo [feature]
@github unsubscribe owner/repo [feature]
Below features are enabled by default, and can be disabled with the @github unsubscribe owner/repo [feature] command:
- issues - Opened / closed / ReOpened
- pulls - New / merged / Close / ReOpen
- commits - New commits on the default branch (usually main)
- comments - New comments on issues and pull requests
These are disabled by default, and can be enabled with the '@github subscribe owner/repo [feature]' command:
- reviews - Pull request reviews
- +label:"your label" - Filter issues, pull-requests and comments based on their labels.
To see the list of subscribed features, use @github subscribe list features
Filters
Branch filters for commits
Branch filters allow filtering commit notifications. By default when you subscribe for commits feature, you will get notifications for your default branch (i.e. main). However, you can choose to filter on a specific branch, or a pattern of branches or all branches.
@github subscribe org/repo commitsfor commit notifications from a default branch.@github subscribe org/repo commits:*for commit notifications across all the branches.@github subscribe org/repo commits:myBranchfor commit notifications from a specific branch.@github subscribe org/repo commits:users/*for commit notifications from a pattern of branches.
You can unsubscribe commits feature using `@github unsubscribe org/repo commits.
Label filters for issues and prs
Label filters allow filtering incoming events based on a whitelisted label. You can add a lable filter with subscribe command
@github subscribe owner/repo +label:priority:HIGH
This creates a required-label filter with the value priority:HIGH. Incoming events that support filters discarded unless they have that label. To update the existing filter just enter a new one, the old one will be updated. Currently, we only support having one filter. Multiple filters might be supported in the future.
The notifications that are filtered by label are:
- issues
- pull requests
- reviews
- comments (for both issues and pull requests)
You can remove a filter by with unsubscribe command '@github unsubscribe owner/repo +label:priority:HIGH'
It is common to have certain special characters in labels. Therefore we added support for the most common special characters for label filters. Here a few examples:
- label:priority:HIGH
- label:teams/designers
- label:"DO NOT MERGE"
- label:"very important"
- label:":construction: WIP"
PR and Issue notification cards and Threading
Notifications for any PR and Issue are grouped under a parent card as replies. The parent card always shows the latest status of the PR/Issue along with other meta-data like title, description, assignees, reviewers, labels and checks. Threading gives context and helps improve collaboration in the channel.
Any new event that happens on a pull request or issue (like comment/review/close/merge) is added as a reply to the parent card.
Note: In case of Draft PRs, updates are not notified in the channel. Once the Draft PR is moved to ready, the channel will start getting the notifications
Move conversations into next steps
Teams conversations often lead to decisions and actionable takeaways. You can perform following actions on GitHub directly from Microsoft Teams:
- Create issue
- Close and ReOpen issue
- Comment on issue and pull request
Users need to be signed into GitHub to perform these actions from Teams. In case the user did not sign in and tried to perform this action, the user gets a notification to sign in before performing the action.
Unfurling GitHub links
When you share links to GitHub activities and properties in the channel, more details are automatically extracted and shown as preview in Microsoft Teams channel. We support link previews for:
- pull requests
- issues
- comments
- code snippets
- repositories
- accounts or organizations
Previews of links will not be shown if the repository is private and the user that shared the link:
- Not signed in to their GitHub account
- The repository is not authorized i.e the Microsoft Teams app is not installed in the GitHub repo.
Personal app experience
As part of personal app experience, you can now subscribe to your repositories and receive notifications for:
- issues
- pull requests
- commits
All the commands available in your channel are now available for Personal chat for GitHub.
You can also signin to GitHub with Personal app chat and avoid separate signin in your channels.
Schedule Reminders
You can now schedule reminders for pending pull requests. With this feature you can now get periodic reminders of pending pull requests as part of your channel or personal chat.
Channel reminders
From Teams' channel, user can run following command to configure a reminder for pending pull requests on your Organization or Repository.
@github schedule organization/repository
This will create reminder for weekdays at 9.30 AM. However, if you want to configure reminder for a different day or time, you can achieve that by passing day and time as explained below.
@github schedule organization/repository <Day format> <Timeformat>
| Command | Functionality |
|---|---|
@github schedule <organization> |
Creates a default reminder on the organization for weekdays at 9.30 AM |
@github schedule <organization>/<Repository> |
Creates a default reminder on the repository for weekdays at 9.30 AM |
@github schedule <organization>/<Repository> everyday 14:30 |
Creates reminder on the repository for everyday at 2:30 PM |
@github schedule <organization>/<Repository> Mon,Tue 14:30 |
Creates reminder on the repository for Monday and Tuesday at 2:30 PM |
@github schedule <organization> Mon-Wed,Fri 9,14:30 |
Creates reminder on the organization for Monday, Tuesday, Wednesday and Friday at 9:00 AM and 2:30 PM |
- In a channel only organization admin can configure reminders.
- The day formats supported are weekdays, weekends, everyday and individual days or the sequence can be given with Mon ,Tue ,Wed,Thu,Fri,Sat,Sun.
- The time format is 24 scale and we only support 30 minute intervals. The timezone is automatically taken from the Microsoft Teams timzone.
You can remove reminders from a channel by running the following command
@github unschedule organization/repository
You can get the list of reminders configured in a channel by running
@github schedule list
Personal reminders
You can configure similar reminders in your personal chat too.
- In personal chat, reminders can be configured only at the organization level. Repository level filter is not supported.
- You need to be a member of the organization to configure reminders in the personal chat.
Command reference
The following table lists all the commands you can use in your Microsoft Teams channel.
| Command | Functionality |
|---|---|
| @github signin | Connect to your GitHub Account |
| @github subscribe / | Subscribe to and Organization or Repository |
| @github subscribe / [feature] | Subscribe to specific feature in an Organization or Repository |
| @github subscribe list | List the subscriptions in the channel |
| @github subscribe list features | List the subscriptions in the channel and the features subscribed |
| @github unsubscribe / | Unsubscribe from Organization or Repository |
| @github unsubscribe / [feature] | Unsubscribe a specific feature in an Organization or Repository |
| @github signout | Disconnect with your GitHub Account and remove all subscriptions |
Authorization
By granting the app access, you are providing the following authorizations to your GitHub and Microsoft Teams accounts:
Teams permission scopes
| Permission scope | Why we need it |
|---|---|
| Access private conversations between you and the App | To message you with instructions. |
| Add link previews to GitHub.com to messages | To render rich links to github.com |
| Add github commands | To add the @github command to your Team channels |
| View the organization's name, email domain, and icon | To store subscriptions you set up |
| Post messages as the app | To notify you of activity that happens on GitHub |
GitHub permission scopes
| Permission scope | Why we need it |
|---|---|
| Read access to issues, metadata, pull requests, and repository projects | To render previews of links shared in Teams |
Future work
We're constantly at work to improve the app, and soon you’ll see new features stated below. To request additional capabilities please request a feature.
Some ideas under consideration:
- GitHub Actions support
- Support for GHES
Feedback
Please create an issue to request a feature or report a problem.