Navigation

GitHub Service

Overview

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

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

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 create a GitHub incoming webhook:

You will need to provide a configuration file of the following form when you create 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, Stitch 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 Stitch 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 a system user that 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 Stitch 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, Stitch executes the webhook function as a system user that has full access to MongoDB CRUD and Aggregation APIs and is not affected by any rules, roles, or permissions.

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

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