page_type	description	products	languages
sample	This sample demonstrates how to use the Microsoft Graph connector API to create a custom connector that indexes issues and repositories from GitHub.	ms-graph github copilot-m365	typescript

Microsoft Graph TypeScript GitHub connector sample

Microsoft Graph connectors let you add your own data to the semantic search index and have it power various Microsoft 365 experiences. This TypeScript application shows you how to use the Microsoft Graph connector API to create a custom connector that indexes issues and repositories from GitHub. This connector sample powers experiences such as Microsoft Search, Copilot in Teams, the Microsoft 365 App, and more.

Experiences

The Microsoft Graph connector experiences that will be enabled in the sample include:

• Microsoft Search
• Context IQ in Outlook on the web
• Microsoft 365 Copilot
• Microsoft 365 app: Quick Access & My Content
• Type Down Suggestions (Query formulation)
• Simplified admin experience in the Teams admin center (Microsoft 356 App)

Prerequisites

• Node.js 18 or higher
• A Microsoft work or school account with the Global administrator role. If you don't have a Microsoft account, you can sign up for the Microsoft 365 Developer Program to get a free Microsoft 365 subscription.
• A GitHub account

Microsoft 365 app requirements

If you want to enable the simplified admin experience in the Teams admin center, you will also need the following.

• The devtunnel CLI or ngrok.
• Custom Teams app uploading must be enabled in your Microsoft 365 tenant.

Register an app in Azure portal

1. Go to the Azure Active Directory admin center and sign in with an administrator account.

2. In the left pane, select Azure Active Directory, and under Manage, select App registrations.

3. Select New registration.

4. Complete the Register an application form with the following values, and then select Register.

   • Name: GitHub Connector
   • Supported account types: Accounts in this organizational directory only
   • Redirect URI: Leave blank

5. On the GitHub Connector overview page, copy the values of Application (client) ID and Directory (tenant) ID. You will need both in the following section.

6. Select API Permissions under Manage.

7. Remove the default User.Read permission under Configured permissions by selecting the ellipses (...) in its row and selecting Remove permission.

8. Select Add a permission, and then select Microsoft Graph.

9. Select Application permissions, and add the following permissions:

   • ExternalConnection.ReadWrite.OwnedBy
   • ExternalItem.ReadWrite.OwnedBy

10. Select Grant admin consent for..., and then select Yes when prompted.

11. Select Certificates & secrets under Manage, and then select New client secret.

12. Enter a description and choose an expiration time for the secret, and then select Add.

13. Copy and save the new secret. You will need it in the following section.

Important

This client secret is never shown again, so make sure you copy it now.

Generate a GitHub personal access token

1. Login to your GitHub account and access your profile page.

2. Select Developer settings.

3. Select Personal access tokens, choose Fine-grained tokens, then select Generate new token.

4. Complete the New fine-grained personal access token form with the following values, then select Generate Token

   • Name: Graph Connector
   • Expiration: 60 days
   • Repository Access: All repositories
   • Repository Permissions: Set Issues, Contents and Metadata to Read-only.

5. Copy and save the newly generated token. You will need it in the following section.

Configure the connector sample

1. Open .env and update the following values. Alternatively, make a copy of .env named .env.development and change the values there.

   Setting	Value
   CLIENT_ID	The Application (client) ID of your app registration in the Azure portal.
   CLIENT_SECRET	The client secret of your app registration in the Azure portal.
   TENANT_ID	The Directory (tenant) ID of your app registration in the Azure portal.
   GITHUB_REPO_OWNER	The GitHub user or organization to read data from.
   GITHUB_REPO	The GitHub repository to ingest issues from. Must be owned by the user or organization set in gitHubRepoOwner.
   GITHUB_TOKEN	Your GitHub personal access token.
   PORT_NUMBER	The port number to listen on when using the simplified admin experience in the Teams admin center
   PLACEHOLDER_USER_ID	A user ID in your Microsoft 365 tenant. You can get the user ID of a user in the Azure portal. Select an Azure Active Directory user and copy the value of their Object ID.

Run the application to create a connection

This sample offers two ways of creating a connection. You can create one interactively, selecting steps from the sample's command line menu, or you can create a connector using the simplified admin experience in the Teams admin center.

Note

You do not have to do use both of these methods - once a connection is created, you can continue to the Ingest items section.

Create a connection in interactive mode

In this step, you will build and run the sample as an interactive console app. This code sample will create a new connection, register the schema, and then push GitHub repo or issues into that connection.

1. Open your command-line interface (CLI) in the directory where package.json is located.
2. Use the command npm start to run the sample.
3. Select [1] Create a connection.
   • Enter a unique identifier (alphanumeric characters only), name, and description for that connection.
   • Select which GitHub content data will be ingested into the connection (repositories or issues).
4. Select [4] Register schema for current connection option, and then wait for the operation to complete.
   • Select which schema to use (repositories or issues).

The connection is now ready to ingest items.

Create a connection in simplified admin mode

There are additional configuration steps to run the sample in simplified admin mode.

Create a dev tunnel

The simplified admin experience in the Teams admin center communicates with the sample connector by sending an HTTP POST request. In this section you will create a dev tunnel to allow the Teams admin center to send the POST to the sample running on your local development machine.

1. If you do not have the devtunnel CLI installed, follow these instructions to install.

2. Run the following command to login to the dev tunnel service. You can login with either a Microsoft Azure Active Directory account, a Microsoft account, or a GitHub account.

   devtunnel user login

3. Run the following commands to create a tunnel. Copy the Tunnel ID from the output.

   devtunnel create --allow-anonymous

4. Run the following command to assign a port to the tunnel. Replace tunnel-id with the Tunnel ID copied in the previous step, and port-number with the HTTP port set in your appsettings.json.

   devtunnel port create tunnel-id -p port-number

5. Run the following command to host the tunnel. Replace tunnel-id with the Tunnel ID copied in the previous step.

   devtunnel host tunnel-id

6. Copy the URL labeled Connect via browser.

   [!NOTE] The output shows two URLs for Connect via browser. Be sure to copy only one of them.

Create a Teams app package

1. Make a copy of the sample-manifest.json named manifest.json.
2. In manifest.json, replace YOUR_CLIENT_ID_HERE with the Application (client) ID of your app registration in the Azure portal.
3. In manifest.json, replace YOUR_DEV_TUNNEL_URL_HERE with your dev tunnel URL.
4. Create a ZIP file containing manifest.json, color.png, and outline.png.

Upload the app package

1. Open the Microsoft Teams admin center in your browser.
2. Select Teams apps, then Manage apps.
3. Select Upload new app.
4. Select Upload in the pop-up, then browse to the ZIP file you created in the previous step.
5. Follow the prompts to confirm and upload the ZIP file.

Run the application

1. Open your command-line interface (CLI) in the directory where package.json is located.
2. Use the command npm run serve to run the sample.

Enable the connector in Teams admin center

1. Open the Microsoft Teams admin center in your browser.
2. Select Teams apps, then Manage apps.
3. Search for "GitHub Connector", then select GitHub Connector Admin-dev.
4. Select Graph Connector.
5. Toggle on the Connection status.

The connection is now ready to ingest items.

Ingest items

1. Use the command npm start to run the sample in interactive mode.
2. Select [2] Select existing connection. Select the connection you created before.
3. Select [5] Push items to current connection.
   • Select [1] Issues.

Surface the data in Search

In this step, you will create search verticals and result types to customize the search results in Microsoft SharePoint, Microsoft Office, and Microsoft Search in Bing.

Create a vertical

1. Sign into the Microsoft 365 admin center by using the global administrator role.
2. Select Settings > Search & intelligence > Customizations.
3. Select Verticals, then select Add.
4. Enter a name in the Name field and select Next.
5. Select Connectors, then select the connection you created previously. Select Next.
6. On the Add a query page, leave the query blank. Select Next.
7. On the Filters page, select Next.
8. Select Add Vertical
9. Select Enable vertical, then select Done.

Note

It may take a few hours before your new vertical shows up in Microsoft Search.

Code of conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.