Skip to content

Commit f5f4c1d

Browse files
stevewardvgrlam-stead
authored
Migrate existing Teams integration documentation (#59411)
Co-authored-by: Vanessa <vgrl@github.com> Co-authored-by: Anne-Marie <102995847+am-stead@users.noreply.github.com>
1 parent 4cc7c37 commit f5f4c1d

15 files changed

Lines changed: 549 additions & 4 deletions

‎content/integrations/concepts/featured-github-integrations.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -76,7 +76,7 @@ The {% data variables.product.github %} for Teams app lets you subscribe to your
7676

7777
You can also open and close issues, comment on your issues and pull requests, approve deployments, and see detailed references to issues and pull requests without leaving Microsoft Teams. The app will also ping you personally on Teams if you are mentioned as part of any {% data variables.product.github %} notifications that you receive in your channels or personal chats.
7878

79-
For more information, see the integration's [README](https://github.com/integrations/microsoft-teams/blob/master/Readme.md) in the `integrations/microsoft-teams` repository.
79+
For more information, see [AUTOTITLE](/integrations/how-tos/teams).
8080

8181
{% ifversion fpt or ghec %}
8282

‎content/integrations/how-tos/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,6 @@ versions:
88
ghec: '*'
99
children:
1010
- /slack
11+
- /teams
1112
contentType: how-tos
1213
---
13-

‎content/integrations/how-tos/teams/customize-notifications.md‎

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
---
2+
title: 'Customizing notifications for {% data variables.product.github %} in Teams'
3+
shortTitle: Customize notifications
4+
intro: 'Customize {% data variables.product.github %} notifications to manage your work within Teams.'
5+
versions:
6+
fpt: '*'
7+
ghes: '*'
8+
ghec: '*'
9+
contentType: reference
10+
---
11+
12+
You can customize your notifications by subscribing to activity that is relevant to your Microsoft Teams channel, and unsubscribing from activity that is less helpful to your project.
13+
14+
### Notifications enabled by default
15+
16+
The following notifications are enabled by default, but you can disable any of them using the `@GitHub Notifications unsubscribe owner/repo [feature]` command.
17+
18+
|Feature|Description|
19+
|-------|-----------|
20+
|`issues`|Opened, closed, or reopened issues.|
21+
|`pulls`|New, merged, closed, or reopened pull requests.|
22+
|`commits`|New commits on the default branch (usually `main`).|
23+
|`comments`|New comments on issues and pull requests.|
24+
|`deployments`|Deployment status updates.|
25+
|`releases`|New releases and pre-releases published.|
26+
27+
> [!NOTE]
28+
> Repository notifications are also enabled by default. You will be notified when your repository is made public or deleted. This notification cannot be disabled, as repository updates are destructive activities.
29+
30+
### Notifications disabled by default
31+
32+
The following notifications are disabled by default, but you can enable any of them using the `@GitHub Notifications subscribe owner/repo [feature]` command.
33+
34+
|Feature|Description|
35+
|-------|-----------|
36+
|`reviews`|Pull request reviews.|
37+
|`workflows`|{% data variables.product.prodname_actions %} workflow runs and approval notifications.|
38+
|`branches`|Branch creation and deletion.|
39+
|`discussions`|Discussions created or answered.|
40+
|`+label:"your label"`|Filter issues, pull requests, and comments based on their labels.|
41+
42+
You can subscribe or unsubscribe from multiple settings at once. For example:
43+
44+
* To turn on activity for pull request reviews and comments, use `@GitHub Notifications subscribe owner/repo reviews comments`.
45+
* To turn off activity for issues and pull requests, use `@GitHub Notifications unsubscribe owner/repo issues pulls`.
46+
47+
## Filtering notifications
48+
49+
You can further customize your notifications with branch and label filters. Branch filters allow you to filter commit notifications based on branch names, while label filters allow you to filter issue and pull request notifications based on labels applied to them.
50+
51+
### Branch filters for commit notifications
52+
53+
Branch filters allow you to filter commit notifications based on branch names. By default when you subscribe to the `commits` event, you will get notifications for your default branch. However, you can choose to filter on a specific branch, or a pattern of branches or all branches.
54+
55+
|Example configuration|Description|
56+
|-------|-----------|
57+
|`@GitHub Notifications subscribe owner/repo commits`|Receive commit notifications for the default branch.|
58+
|`@GitHub Notifications subscribe owner/repo commits:main`|Only receive commit notifications for the `main` branch.|
59+
|`@GitHub Notifications subscribe owner/repo commits:feature/*`|Receive commit notifications for all branches that start with `feature/`.|
60+
|`@GitHub Notifications subscribe owner/repo commits:*`|Receive commit notifications for all branches.|
61+
62+
You can unsubscribe from the commits feature using `@GitHub Notifications unsubscribe owner/repo commits`.
63+
64+
>[!NOTE] You may have previously used the `commits:all` filter to receive commit notifications for all branches. This filter is {% data variables.release-phases.closing_down %}. To receive commit notifications for all branches, use the `commits:*` filter instead. If you have previously set up the `commits:all` filter, it will continue to work until you update your configuration to use the `commits:*` filter.
65+
66+
### Label filters for issue and pull request notifications
67+
68+
Label filters allow you to filter notifications based on labels applied to issues and pull requests. When a label filter is set, only notifications for events including the specified label will be sent. For more information about labels, see [AUTOTITLE](/issues/using-labels-and-milestones-to-track-work/managing-labels) and [AUTOTITLE](/issues/tracking-your-work-with-issues/using-issues/filtering-and-searching-issues-and-pull-requests).
69+
70+
Currently, it is only possible to have one required label filter per repository. The table below shows which event types are affected by label filters.
71+
72+
|Event type|Is filtered by label|
73+
|-------|-----------|
74+
|Pull requests|{% octicon "check" aria-label="Included" %}|
75+
|Issues|{% octicon "check" aria-label="Included" %}|
76+
|Comments|{% octicon "check" aria-label="Included" %}|
77+
|Reviews|{% octicon "check" aria-label="Included" %}|
78+
|Commits/Pushes|{% octicon "x" aria-label="Not included" %}|
79+
|Branches|{% octicon "x" aria-label="Not included" %}|
80+
81+
#### Creating label filters
82+
83+
To create a label filter, use the following command format:
84+
85+
```text copy
86+
@GitHub Notifications subscribe [owner/repo] +label:"your label"
87+
```
88+
89+
This creates a required-label filter with the value `your label`. Incoming events that support filters are discarded unless they have that label.
90+
91+
#### Updating label filters
92+
93+
You can update an existing label filter by specifying a new label value:
94+
95+
```text copy
96+
@GitHub Notifications subscribe [owner/repo] +label:"new label"
97+
```
98+
99+
This will replace the "your label" filter with the "new label" filter.
100+
101+
#### Removing label filters
102+
103+
You can remove an existing label filter by using the unsubscribe command with the `+label` option:
104+
105+
```text copy
106+
@GitHub Notifications unsubscribe [owner/repo] +label:"new label"
107+
```
108+
109+
This will remove the "new label" filter, and the channel will receive all notifications for the subscribed events without any label filtering.
110+
111+
#### Viewing active label filters
112+
113+
To view the currently active label filters for a channel, use the following command:
114+
115+
```text copy
116+
@GitHub Notifications subscribe list features
117+
```
118+
119+
#### Valid filters
120+
121+
The {% data variables.product.github %} app in Teams supports the most common special characters for label filters, including all emojis that Teams and {% data variables.product.github %} provide as standard. Rarely, you may encounter a label that contains a special character that is not supported. For example, any multibyte character not encoded as `:foo:`, or labels using the `,` character may not work as expected.
122+
123+
## {% data variables.product.prodname_actions %} workflow notifications
124+
125+
You can subscribe to {% data variables.product.prodname_actions %} workflow run notifications from your channel or personal app using "workflows" feature, using the format `@GitHub Notifications subscribe owner/repo workflows`.
126+
127+
When you are subscribed to "workflows", the following functionality is available:
128+
129+
* You will get notified when a new workflow run is triggered.
130+
* You can track the approval notifications as a reply in the thread and you can approve the notifications directly from the channel or personal app.
131+
* Once the workflow is completed, you will get an update as a reply in the thread so that you can see the complete context and history of the workflow run.
132+
* If something fails, you can choose to rerun the workflow in place and you can also enable debug logs if needed.
133+
134+
>[!NOTE] After March 10, 2025 and for {% data variables.product.prodname_ghe_server %} version 3.17 onwards, you will no longer be notified about the progress of individual workflow jobs. See the [{% data variables.product.github %} changelog](https://github.blog/changelog/2025-02-03-deprecation-of-real-time-github-actions-workflow-job-events-in-slack-and-microsoft-teams-apps/) for more details.
135+
136+
### Workflow notification filters
137+
138+
You can filter workflow notifications by using the following options:
139+
140+
|Filter|Description|
141+
|-------|-----------|
142+
|`name`|Filter by the name of the workflow.|
143+
|`actor`|Filter by the user who triggered the workflow.|
144+
|`branch`|Filter by the branch the workflow is running on. In cases where the `pull_request` event is included, the branch will be the target branch the pull request is created for.|
145+
|`event`|Filter by the event that triggered the workflow (e.g., push, pull_request).|
146+
147+
You can configure workflow notification filters with the following format:
148+
149+
```text copy
150+
@GitHub Notifications subscribe owner/repo workflows:{name:"your workflow name" event:"workflow event" branch:"branch name" actor:"username"}
151+
```
152+
153+
You can also pass multiple values for each filter, separated by commas. For example:
154+
155+
```text copy
156+
@GitHub Notifications subscribe owner/repo workflows:{name:"your workflow name","another workflow name" event:"workflow event","another workflow event" branch:"branch name","another branch name" actor:"username","another-username"}
157+
```
158+
159+
By default, when you configure workflow notifications without passing any filters, it is configured for workflows triggered via pull requests targeting your default branch. You can pass one or multiple entries.
160+
161+
You can unsubscribe from workflow notifications using the command: `@GitHub Notifications unsubscribe owner/repo workflows`.
162+
163+
>[!NOTE] To receive {% data variables.product.prodname_actions %} notifications in Teams, the {% data variables.product.github %} app requires additional permissions. When you attempt to subscribe to workflows for the first time, you will be prompted to grant these permissions.
164+
165+
## Deployment notifications
166+
167+
You can also configure separate deployment notifications. These deployments can happen from {% data variables.product.prodname_actions %} or from external sources using the deployments API. See [AUTOTITLE](/rest/deployments/deployments).
168+
169+
You can subscribe or unsubscribe to deployment notifications using the following commands:
170+
171+
```text copy
172+
@GitHub Notifications subscribe owner/repo deployments
173+
@GitHub Notifications unsubscribe owner/repo deployments
174+
```
175+
176+
>[!NOTE] If you are using {% data variables.product.prodname_actions %} and want to track your deployments to environments, the `workflows` feature is recommended, as it provides a more complete picture and the ability to approve your deployments directly from Teams.

‎content/integrations/how-tos/teams/index.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
title: '{% data variables.product.github %} integration in Teams'
3+
shortTitle: Teams
4+
intro: Learn how to use the {% data variables.product.github %} integration in Teams.
5+
versions:
6+
fpt: '*'
7+
ghes: '*'
8+
ghec: '*'
9+
children:
10+
- /integrate-github-with-teams
11+
- /use-github-in-teams
12+
- /customize-notifications
13+
- /schedule-reminders
14+
contentType: how-tos
15+
---

‎content/integrations/how-tos/teams/integrate-github-with-teams.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
---
2+
title: 'Integrating {% data variables.product.github %} with Teams'
3+
shortTitle: Integrate GitHub with Teams
4+
intro: 'Set up the GitHub integration with Teams to improve collaboration and streamline workflows.'
5+
versions:
6+
fpt: '*'
7+
ghes: '*'
8+
ghec: '*'
9+
---
10+
11+
## About the {% data variables.product.github %} integration for Teams
12+
13+
The {% data variables.product.github %} integration for Microsoft Teams gives you and your teams visibility into your {% data variables.product.github %} projects directly in Teams channels. You can triage issues, collaborate on pull requests, and keep track of changes without leaving Teams.
14+
15+
With the {% data variables.product.github %} integration for Teams, you can:
16+
17+
* Get **{% data variables.product.github %} notifications** in Teams channels.
18+
* Use **commands** to take actions on {% data variables.product.github %}.
19+
* See **previews** when sharing links to {% data variables.product.github %} resources.
20+
{% ifversion fpt or ghec %}
21+
* Initiate a {% data variables.copilot.copilot_coding_agent %} session from Teams, using the context of a Teams thread.
22+
{% endif %}
23+
24+
{% data reusables.integrations.github-teams-permissions %}
25+
26+
## Prerequisites
27+
28+
To use the {% data variables.product.github %} integration for Teams, you need:
29+
30+
* A {% data variables.product.github %} account.
31+
* A Teams workspace where you have permission to install apps.
32+
33+
{% ifversion not ghes %}
34+
35+
## Installing the {% data variables.product.github %} integration for Teams in a single workspace
36+
37+
1. Go to the [{% data variables.product.github %} integration for Teams](https://teams.microsoft.com/l/app/ca9e26b7-dce5-44a0-b2b7-a70a3d65ce25) listing in the Teams app store.
38+
1. Click **Add**.
39+
1. Follow the prompts to sign in to Teams and approve access.
40+
1. In Teams, run `@GitHub Notifications signin` and follow the prompts to connect your {% data variables.product.github %} account.
41+
42+
{% ifversion ghec %}
43+
44+
### Installing the Teams app for {% data variables.product.prodname_ghe_cloud %} with data residency
45+
46+
If you use {% data variables.product.prodname_ghe_cloud %} with data residency on {% data variables.enterprise.data_residency_site %}, install the data-residency app from [AppSource](https://appsource.microsoft.com/en-us/product/office/WA200008122) and sign in with your {% data variables.product.prodname_ghe_cloud %} account when prompted.
47+
48+
{% endif %}
49+
50+
{% endif %}
51+
52+
{% ifversion ghes %}
53+
54+
## Installing the {% data variables.product.github %} integration for Teams on {% data variables.product.prodname_ghe_server %}
55+
56+
1. In the management console for your {% data variables.product.prodname_ghe_server %} instance, open "Chat integrations" and enable {% data variables.product.github %} Chat Integration.
57+
1. Select the Microsoft Teams tab and follow the link to register an app in Microsoft Azure.
58+
1. Record the application (client) ID and tenant ID, then create a client secret.
59+
1. Back in the management console, choose **Deploy to Azure** and follow the prompts to provision the Teams bot.
60+
1. Enter the app ID, tenant ID, and client secret in the Teams configuration, then save the settings.
61+
1. Download the generated manifest and upload it to Teams. For more information, see [Upload your app to Teams](https://learn.microsoft.com/en-us/microsoftteams/platform/concepts/deploy-and-publish/apps-upload).
62+
1. Install the app in Teams and run `@GitHub Notifications signin` to connect your {% data variables.product.github %} account.
63+
64+
>[!NOTE] If your {% data variables.product.prodname_ghe_server %} instance is not reachable from the public internet, provide the proxy URL when configuring the Teams bot in Azure.
65+
66+
{% endif %}
67+
68+
## Further reading
69+
70+
* [AUTOTITLE](/integrations/how-tos/teams/use-github-in-teams) - Learn how to use the {% data variables.product.github %} integration for Teams.
71+
* [AUTOTITLE](/integrations/how-tos/teams/customize-notifications) - Learn how to customize your {% data variables.product.github %} notifications in Teams.

‎content/integrations/how-tos/teams/schedule-reminders.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
title: Scheduling pull request reminders in Teams
3+
shortTitle: Schedule reminders
4+
intro: 'Set up reminders for pending pull request reviews in Teams.'
5+
versions:
6+
fpt: '*'
7+
ghes: '*'
8+
ghec: '*'
9+
contentType: how-tos
10+
---
11+
12+
You can schedule reminders for pending pull request reviews in Microsoft Teams channels or in the {% data variables.product.github %} personal app. Reminders are available for organizations, not personal accounts.
13+
14+
## Scheduling reminders in a channel
15+
16+
1. In a Teams channel, run `@GitHub Notifications schedule ORGANIZATION`.
17+
1. Select **Create new reminder**.
18+
1. Configure the days, times, timezone, and repository or team filters for the reminder.
19+
1. Save the reminder.
20+
21+
To edit or remove reminders for the organization, run `@GitHub Notifications schedule ORGANIZATION` again. To list all reminders configured in the channel, run `@GitHub Notifications schedule list`.
22+
23+
## Scheduling reminders in the personal app
24+
25+
1. Open the {% data variables.product.github %} personal app in Teams.
26+
1. Run `schedule ORGANIZATION`.
27+
1. Select **Create new reminder** and configure your reminder settings.
28+
1. Save the reminder.
29+
30+
In the personal app, you can list reminders with `schedule list`.
31+
32+
>[!NOTE] To configure reminders for an organization, you must be a member of the organization and have write access to at least one repository.
33+
34+
## Further reading
35+
36+
* [AUTOTITLE](/integrations/how-tos/teams/customize-notifications)
37+
* [AUTOTITLE](/integrations/reference/teams-command-reference)

0 commit comments

Comments
 (0)