Navigation

GitHub Service

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

The GitHub Service in MongoDB Stitch supports setting up an incoming webhook to consume and process GitHub actions as part of a function. There are no service actions or service rules for the GitHub service.

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

  • A GitHub Account
  • A GitHub Repository

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

Add a GitHub Service

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

To set up a GitHub service in MongoDB Stitch:

  1. Click Services in the left navigation pane and click Add a Service.
  2. Select Github.
  3. Enter a name for your service in the Service Name box.
  4. Click Add Service.

Incoming Webhooks

A MongoDB Stitch incoming webhook is a callback URL used by third-party service providers to execute a function in your Stitch app. The documentation page on Service Webhooks describes how to create an incoming webhook.

If you’d like to learn more about GitHub’s webhook functionality, and the payloads that will be provided to MongoDB Stitch when events occur, see GitHub’s webhook documentation at https://developer.github.com/webhooks/.

Additional Settings

When creating a webhook for the GitHub service, you will be asked to provide a Github Secret in Request Validation.

When adding the webhook to your GitHub repository, you will need to provide this secret. We recommend generating a random string to maximize security.

As an example, GitHub suggests running the following command in a terminal to generate a secret:

ruby -rsecurerandom -e 'puts SecureRandom.hex(20)'

However, you can generate the secret any way you would like.

Adding your 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. 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. The documentation page on Service Webhooks describes where to find this URL.
    3. Set the content type to application/json.
    4. Enter the GitHub Secret you generated 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.

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.