GitHub Service

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

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

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

Service Name
The name of this GitHub service interface. This must be unique from all other service interfaces in your application.

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

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.

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

Configuration Value
Webhook Name
Required. The name of the webhook. Each incoming webhook in a GitHub service interface must have a unique name.
Respond With Result
Required. If true, Realm sends the return value of the webhook function to GitHub in the response body.
Run Webhook As

Optional. The id of the Realm 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.
Request Validation
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.

Realm 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.


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.

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

exports = function(payload) {
const mongodb ="mongodb-atlas");
const requestlogs = mongodb.database("test").collection("requestlogs");
return requestlogs
"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.

  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.
Give Feedback