Navigation

GitHub Service

GitHub is a web-based development platform for hosting and reviewing Git repositories. MongoDB Stitch supports setting up an incoming webhook to consume and process GitHub actions as part of a function.

You will need the following to integrate GitHub with your MongoDB Stitch app:

  • A GitHub Secret token

You will also need a MongoDB Stitch incoming webhook to receive requests from GitHub.

Add a GitHub Service to Your MongoDB Stitch App

Use the following procedure to add a GitHub service to your MongoDB Stitch app:

A. Add GitHub Service to the MongoDB Stitch App

1

Go to the MongoDB Atlas project associated with your MongoDB Stitch application.

Tip

If you have not set up your cluster or set up your MongoDB Stitch application, see Getting Started.

  1. Log into Atlas.
  2. Navigate to the project associated with your MongoDB Stitch application.
  3. Select Stitch Apps in the left-hand nav panel.
  4. Select the application you wish to integrate with the GitHub Service. You will be redirected to the MongoDB Stitch console.
2

Add the GitHub service.

  1. In the MongoDB Stitch console, click Services in the left-hand nav panel and then click Add Service.
  2. Select GitHub.
  3. Enter a name for your GitHub service.
  4. Click Add service

B. Create a MongoDB Stitch Incoming Webhook

A MongoDB Stitch Incoming Webhook is a callback URL used by third-party service providers to execute a function.

1

Click the Incoming Webhooks tab for your added GitHub service.

2

Click New Webhook.

3

Enter the following properties for the webhook.

Property Action
Name Enter the name for your new webhook.
Respond with Result Optional. Switch to enabled to send responses to URLs that invoke the incoming webhook.
Request Validation

Enter a secret you want to use to verify that the incoming requests from GitHub are from your account.

You will specify this secret to set up the Webhook on the GitHub repo later.

Output Type

Select the output type for the webhook function:

  • Select Array to return all documents from the function.
  • Select Single Document to return a single document from the function.
  • Select Boolean to return a boolean value indicating whether the function returned any output.
4

Specify the webhook function.

Use the function editor to write the webhook function code.

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

exports = function(args) {
    var mongodb = context.services.get("mongodb-atlas");
    var coll = mongodb.database("test").collection("requestlogs");
    coll.insertOne({
        "commits": args.commits,
        "pushed_by": args.pusher,
        "repo": args.repository.html_url
    })
}

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

5

Click Create.

Upon successful creation of the webhook, its Webhook URL is displayed.

Along with the GitHub Secret, you will use this URL in setting up a Webhook on the GitHub

C. Add Your Stitch Incoming Webhook to a GitHub Repository

Use the following procedure to add your MongoDB Stitch incoming webhook to a GitHub repository:

1

Log into GitHub.

Once logged in, go to the repository for which you plan to add the webhook.

2

Go to the Webhooks settings for the repo.

Click the Settings tab for the repo and select Webhooks from the left hand menu.

3

Add the MongoDB Stitch webhook to the repo.

  1. Click Add Webhook.
  2. Add the URL from your MongoDB Stitch webhook to the Payload URL field.
  3. Set the content type to application/json.
  4. Enter the GitHub Secret created early when defining the MongoDB Stitch incoming webhook.
  5. Choose the type of events you would like to receive information about.
  6. Click Add webhook.

Your MongoDB Stitch app is now integrated with GitHub. When the selected GitHub actions are performed, GitHub invokes the function that is associated with the MongoDB Stitch incoming webhook.

Learn more about GitHub’s webhook functionality at https://developer.github.com/webhooks/.