GitHub Teams Integration

This guide explains how to deploy an Indent webhook to the cloud for managing access to GitHub Teams for your organization. This webhook can be run as a Google Cloud Function.

Take a look at the direct code examples that run in these webhooks:

• terraform-gcloud-github-teams-pull-webhook
• terraform-gcloud-github-teams-webhook.

This page assumes that you or someone on your team has already completed the Quickstart. If you haven't already, we would recommend you check it out - it should take 5 minutes. By the end you should have a working Space you can integrate with this webhook.

One-minute demo

Under 10-minute walkthrough

Prerequisites

• GitHub Account
  • GitHub Organization with at least one team
  • Personal Access Token with the following scopes:
    • admin:org: : Add and remove users to GitHub Teams for the authenticated organization owner or team maintainer

Overview

You'll pull GitHub Teams from your organization into Indent (optionally, you can import teams manually), then set up automated change management. You will deploy this webhook as a Google Cloud Function.

Step 0: Configure your cloud provider

Google Cloud

Let's get all the Google Cloud-specific items ready before you get started:

• Google Cloud Project with these APIs enabled:
  • Google Cloud Functions API
  • Google Cloud Build API
• Terraform
  • Optional: Terraform's guide to working with the Google Provider.

Step 1: Create a GitHub Organization and Teams

1. If you don't have one already, create a new GitHub Organization.
2. Invite your members to the new GitHub Organization.
3. Create Teams within your new GitHub Organization and assign members to each Team.
4. Transfer ownership of your working repositories to each Team, then configure read and write permissions for each repo.

Step 2: Deploy the pull update webhook

1. Sign into your Indent Space.
2. Navigate to your Webhooks.
3. Click +New and start configuring a new Webhook.
   • Under Webhook Name, enter a name for this webhook
   • Select Pull update, in the Kind of Webhook dropdown.
   • Under Supported Kind of Resource select GitHub Team or type github.v1.Team.
   • Turn off testing mode.
   • Click Create Webhook > at the bottom. You'll come back to this page in the next step to get the Signing Secret.

Download the setup files

Download the example from GitHub:

curl https://codeload.github.com/indentapis/examples/tar.gz/main | tar -xz --strip=3 examples-main/webhooks/pull/terraform-gcloud-github-teams-pull-webhook
cd terraform-gcloud-github-teams-pull-webhook

Follow the instructions in the GitHub README to complete the deployment process.

1. After you finish deploying your webhook, enter the HTTP endpoint from Google Cloud Functions as the Webhook URL field in your new Webhook.
2. Save the Webhook.
3. Go to your Resources and click the dropdown arrow next to New
4. Select Pull Update and a modal window appears with a list of resources you can pull.
5. Choose the slider for GitHub Teams then press Start Pulling Updates

The webhook will update your Resources with all the GitHub teams for your organization. Now when you search "github" on the Resources page search bar, you will see all your GitHub Teams as available Resources. Next, you'll automate team membership changes when access is granted or revoked.

Step 3: Link Slack users to GitHub

1. Navigate to Resources again and click the user Resource you want to allow access to GitHub Teams.
2. In the Resource page, add a new Label to the user.
   • Under Label name, enter "github/id"
   • Under Label value enter the user's GitHub username.
   • Save the Resource.

You can also update users in bulk. Select a list of users and export the list to a CSV where you can edit the user labels.

Step 4: Deploy the change webhook

Google Cloud

Download the example:

curl https://codeload.github.com/indentapis/examples/tar.gz/main |tar -xz --strip=3 examples-main/webhooks/change/terraform-gcloud-github-teams-webhook
cd terraform-gcloud-github-teams-webhook

Follow the instructions in the GitHub README to complete the deployment process, then save the new webhook in your Indent configuration.

Step 5: Configure your Indent policies

1. Click Apps in the Indent Dashboard and click on your communication app.

2. Open Access Request Rules and add github.v1.Team to the "Kinds of Resources," your app can manage.

   • Alternatively, you can add individual Teams based on Resource ID in this section.

3. Configure the approvers for granting access to your GitHub Teams.

Step 6: Make a test request

1. Go to Request Access.
2. Select your GitHub Team from the dropdown and enter a reason for access.
3. Once the access is approved, check the group's page to confirm membership.

Congrats! You’ve just configured requesting and managing GitHub Team access with Indent.

---

Import teams manually

1. Sign into your Indent Space.
2. Go to your Resources.
3. Click +New to create a new Resource:
   • Under Resource Kind, type in "github.v1.Team"
   • Enter the name of your GitHub Team.
   • Enter the ID of your GitHub Team.

How do I get my GitHub Team's ID?

• Visit the GitHub REST API documentation page.
• Get the GitHub Team's unique ID via one of the methods described.
• Use the Team ID as the Resource ID in the Indent Resource Creation Page.