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.

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

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:

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

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 is not affected by any rules, roles, or permissions.
  • 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 Realm 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, Realm executes the webhook function as the system user, which has full access to MongoDB CRUD and Aggregation APIs and is not affected by any rules, roles, or permissions.

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.

Request Payload

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.

Example Webhook Function

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.

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.