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

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 Add service in the left-hand nav panel.
  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 pipeline.

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

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

Specify the webhook pipeline stage(s).

For the displayed pipeline stage, hover over the stage to reveal the EDIT and DELETE buttons.

Click Edit and edit the following:

Field Action
Service Select the service for the stage.
Action

Select the action for the service. For a list of actions available, see Service Actions.

In the text box below the Action, enter the arguments to the specified action.

Note

You cannot directly reference the incoming request body and query parameters in the arguments specification.

Instead, to reference the incoming request body and/or query parameters in the stage, first define variables that reference the request body and/or query parameters in the Bind data to %%vars section. Then reference the variables in the arguments using the %%vars.<variable> expansion or reference the whole variables document with the expansion %%vars.

For example, if the specified is the built-in action literal, you would specify an argument that defines items:

{"items": ["%%vars"]}
Bind data to %%vars

Optional. Switch Bind data to %%vars to enabled to define variables to use as arguments to the action.

Note

You cannot directly reference the incoming request body and query parameters in the arguments specification.

Instead, to reference the incoming request body and/or query parameters in the stage, first define variables that reference the request body and/or query parameters in the Bind data to %%vars section. Then reference the variables in the arguments using the %%vars.<variable> expansion or reference the whole variables document with the expansion %%vars.

In the Bind data to %%vars text box, specify the variables.

For example, the following defines variables that references the fields commits, pusher, the repository.html_url from the request payload.

{
  "commits": "%%args.commits",
  "pushed_by": "%%args.pusher",
  "repo": "%%args.repository.html_url"
}

You can reference these variables in the action arguments section as "%%vars.commits", "%%vars.pushed_by", and "%%vars.repo" or you can reference the whole variables document with the expansion %%vars.

Click Done. To add more stages to the pipeline, click Add Stage and repeat this step.

Example: The following incoming webhook pipeline consists of two stages.

Service Action Args Let (Bind data to %%vars)
built-in literal
{ "items": [ "%%vars" ] }
{
  "commits":"%%args.commits",
  "pushed_by":"%%args.pusher",
  "repo":"%%args.repository.html_url"
}
mongodb-atlas insert
{
  "database": "test",
  "collection": "requestlogs"
}
 
  • The first stage defines documents using information from the request payload.
  • The second stage inserts these documents into the requestlogs collection in the test database.
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 pipeline that is associated with the MongoDB Stitch incoming webhook.

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

←   Amazon SES HTTP Service  →