Docs Menu
Docs Home
/
MongoDB Atlas
/
Atlas App Services
/
Reference
/
Third-Party Services [Deprecated]

GitHub Service [Deprecated]

On this page

  • Overview
  • Configuration Parameters
  • Service Actions
  • Incoming Webhooks
  • Configuration
  • Request Payload
  • Example Webhook Function
  • Configure GitHub
  • Add a Webhook to a GitHub Repository

Important

Third Party Services & Push Notifications Deprecation

Third party services and push notifications in App Services have been deprecated in favor of creating HTTP endpoints that use external dependencies in functions.

Webhooks have been renamed to HTTPS Endpoints with no change in behavior. You should migrate existing Webhooks.

Existing services will continue to work until November 1, 2024.

Because third party services and push notifications are now deprecated, they have been removed by default from the App Services UI. If you need to manage an existing third party service or push notification, you can add the configurations back to the UI by doing the following:

  • In the left navigation, under the Manage section, click App Settings.

  • Enable the toggle switch next to Temporarily Re-Enable 3rd Party Services, and then save your changes.

Overview

GitHub is a web-based development platform for hosting and reviewing Git repositories.

The Atlas App Services GitHub service allows your application to react to events in a GitHub repository, such as new pull requests or issues.

Configuration Parameters

You will need to provide values for the following parameters when you create a GitHub service interface:

<Service Name>/config.json
{
  "name": "<Service Name>",
  "type": "github",
  "config": {}
}
Parameter
Description
Service Name
config.name
The name of this GitHub service interface. This must be unique from all other service interfaces in your application.

Service Actions

GitHub Services do not provide any service actions. Use an incoming webhook to respond to events in your GitHub repo.

Incoming Webhooks

Note

Convert GitHub Webhooks to Endpoints

GitHub Service webhoooks are deprecated in favor of custom HTTPS endpoints. To learn how to migrate your existing GitHub webhooks to endpoints, see Convert Webhooks to HTTPS Endpoints.

GitHub can invoke one or more webhooks whenever a particular event occurs in a repository. If you'd like to learn more about GitHub's webhook functionality, including detailed reference information about GitHub event types, see GitHub's Webhook documentation.

Configuration

You will need to provide values for the following parameters when you configure a GitHub incoming webhook:

You will need to provide a configuration file of the following form when you configure a GitHub incoming webhook:

{
  "name": <string>,
  "respond_result": <boolean>,
  "run_as_user_id": <string>,
  "run_as_user_id_script_source": <string>,
  "options": {
    "secret": <string>
  },
}
Configuration Value
Description
Webhook Name
name
Required. The name of the webhook. Each incoming webhook in a GitHub service interface must have a unique name.
Respond With Result
respond_result
Required. If true, App Services sends the return value of the webhook function to GitHub in the response body.
Run Webhook As
run_as_user_id
run_as_user_id_script_source

Optional. The id of the App Services user that executes the webhook function when the webhook is called.

There are three ways to configure the execution user:

  • System: The execution user is the system user, which has full access to MongoDB CRUD and Aggregation APIs and bypasses all rules and schema validation.

  • User Id: You select a specific application user to execute the function.

  • Script: You define a function that returns the id of the execution user.

You can specify the user id directly in run_as_user_id or provide a stringified Atlas Function that accepts the webhook payload and returns the user id in run_as_user_id_script_source. If you do not specify a specific user id or a function that resolves to a user id, App Services executes the webhook function as the system user that has full access to MongoDB CRUD and Aggregation APIs and bypasses all rules and schema validation.

Request Validation
config.secret
The GitHub Secret string that GitHub includes with incoming requests to prove that the requests are valid. You must specify this value in the settings of your GitHub repo when you provide a webhook URL.

Request Payload

App Services automatically passes a payload document as the first argument to incoming webhook functions. In a GitHub Service incoming webhook the payload object represents the GitHub event that caused GitHub to call the webhook.

Note

The exact content of GitHub payload documents varies depending on the event type that it represents. For a detailed description of a specific event type's payload document, refer to GitHub's Event Types & Payloads documentation.

Example Webhook Function

The following webhook function inserts incoming data into a MongoDB collection.

exports = function(payload) {
    const mongodb = context.services.get("mongodb-atlas");
    const requestlogs = mongodb.database("test").collection("requestlogs");
    return requestlogs
      .insertOne({
        "commits": payload.commits,
        "pushed_by": payload.pusher,
        "repo": payload.repository.html_url
      })
      .then(({ insertedId }) => `Inserted document with _id: ${insertedId}`)
}

The payload document is passed by the GitHub service and contains information from the request.

Configure GitHub

Add a Webhook to a GitHub Repository

  1. Log into GitHub.

  2. Navigate to the repository that you want to subscribe to.

  3. Click the Settings tab of the repository and select Webhooks from the left hand menu.

  4. Click Add Webhook.

  5. Add the webhook URL to the Payload URL field.

  6. Set the content type to application/json.

  7. Enter the GitHub Secret. This should match the value you provided in the webhook configuration.

  8. Choose the type of events that you want to subscribe to.

  9. Click Add webhook.

Back

AWS