• Realm >
• Tutorial >
• 2: Write a Client

Write a GitHub Issue Tracker with MongoDB Realm

Overview

In this tutorial, you will build a cloud application in order to track issues created on GitHub repos using MongoDB Realm. This app will:

• Send an automatic response, with a greeting and helpful links, to all new issues created on your GitHub repo.
• Record all new issues created on your GitHub repo to a MongoDB Atlas cluster.
• Send you a weekly summary of all the new issues created.

This tutorial should take around 30 minutes.

Outcome

You will learn how to:

• Execute serverless application logic with MongoDB Realm Functions.
• Respond to database and scheduled triggers.
• Save and use static data, such as API keys, using values and secrets.
• Use the GitHub API within your MongoDB Realm app.
• View incoming requests and application events using MongoDB Realm Application Logs.

Prerequisites

• Create a Realm app. If you have completed the task tracker tutorial, you can use the same backend Realm app.
• (Recommended) Create a GitHub repository.

Procedure

Link a MongoDB Atlas Cluster

This tutorial requires a linked Atlas cluster and a GitHub repository.

1

Create a Repository

To begin your application, create a GitHub repository. Use this repository to maintain your application’s source code and for developers to submit issues to track ideas, tasks, or bugs. To create a repository, navigate to https://github.com/new and specify a repository name. Set the repository to ‘public’ and click the option to initialize it with a README file.

2

Create an HTTP Service

To communicate with GitHub from a MongoDB Realm application, you must communicate over the HTTP protocol via an HTTP Service. This allows you to react to GitHub events, such as creating a new issue on your repo. To create an HTTP service, navigate to the 3rd Party Services page and click the “Add a Service” in the MongoDB Realm UI. Configure your service options by clicking the option for an HTTP Service and specify your service name before clicking “Add Service” on the bottom right.

3

Create a Webhook for Your Service

Creating a webhook allows MongoDB Realm to execute a function when someone opens a new GitHub issue on your repository. To create a webhook for your newly created HTTP service, click your service name and click the “Add incoming webhook” button.

To configure your webhook settings, specify a name for your webhook. Copy the Webhook URL. GitHub utilizes this Webhook URL to execute the function logic for your HTTP Service. Click the “Save” button to save your webhook.

Finally, add some logic to your webhook function. In the function, add any console.log statement. This console.log will be printed to your application logs when someone opens a new issue on your repository. It should look something like the following.

copy

 exports = function(payload, response) {
  console.log('- github event triggered -');
  return true;
};

Note

After pasting the code into your function editor, click the “Save” button. Click the “Review and Deploy Changes” option on the top of the screen.

4

Configure GitHub to Use the Webhook URL

To communicate between GitHub and Realm, configure GitHub with your Webhook URL, causing MongoDB Realm to execute the function logic upon the creation of a new issue on the GitHub Repository. On GitHub, navigate to the settings tab of your repository. Click the “add webhook” button. Paste your Webhook URL from MongoDB Realm into the input field that says “payload url”. Set content type to “application/json”. Click the option to “send me everything”, allowing GitHub to send all events, including the new issue event, to your MongoDB Realm application. Finally, click the green “add webhook” button to finish adding your webhook.

5

Confirm That Your Webhook Worked

Ensure that your GitHub Issue Tracker is functioning correctly so far by testing your webhook. To test if your webhook is working, open a new issue on your GitHub repository. You can use a different GitHub account if you want to simulate a real-life situation or use the account that you used to create your repository. Then check if your Realm app was prompted about the event, check your Realm application logs. Click the top-most result in the Logs Page to view the latest entry. It should be a log containing the text of your console.log statement, indicating that the webhook worked.

Note

If your console didn’t log, make sure you have clicked the blue “Review and Deploy” button at the top of the MongoDB Realm UI if it is visible.

6

Update Your Function To Add a MongoDB Document

The GitHub Issue Tracker should insert a MongoDB Document into your Atlas collection. Inserting a document when someone creates a new issue opens your application to add new features, such as executing logic upon document insertion. Navigate to the “Function Editor” of your service. Paste the following code into the function editor.

copy

 exports = async function(payload, response) {
  // parse the payload body from github
  const {arg1, arg2} = payload.query;
  const contentTypes = payload.headers["Content-Type"];
  const body = payload.body;

  // set githubAction as the type of GitHub event is sending
  const githubAction = JSON.parse(payload.body.text()).action;

  // if it is a new issue being opened, insert a document
  if(githubAction === "opened"){
    const issueDoc = {
      title: JSON.parse(payload.body.text()).issue.title,
      url: JSON.parse(payload.body.text()).issue.url,
      timestamp: new Date()
    }
    // insert a document into your collection
    const insertDoc = await context.services.get("mongodb-atlas").db("tracker").collection("githubIssues").insertOne(issueDoc);
    console.log(JSON.stringify(insertDoc, null, 2));
  }
};

Note

After pasting the code into your function editor, click the “Save” button. Click the “Review and Deploy Changes” option on the top of the screen.

7

Write a Comment When a Document Is Inserted

The GitHub Issue Tracker should write a helpful comment on newly opened GitHub Issues. You can do this by creating a Database Trigger that executes a function using the GitHub Issues API to write a comment to the GitHub Issue. In order to use the GitHub API a token is required. Click “Settings” on the top right corner of your GitHub Profile (not your repository settings).

Click the “Developer Settings” link on the bottom left. Then, click “Person access token”. This page allows you to generate a new token. Click the “Generate new token” to generate a token that will allow you to use the GitHub API. Click the “repo” and “admin:repo_hook” OAuth scope to grant read and write access to repository hooks, including the opening of new issues. Finally, click “Generate Token” to finish configuring your GitHub token. Copy the 40 digit token that GitHub has generated.

8

Create a MongoDB Realm Value With the GitHub Token

You can define a MongoDB Realm Secret to store your GitHub token securely. You can link this secret to a Value to be used within your Database Trigger Function. To begin, navigate to the Values & Secrets page and click the “Add a Secret” button. Specify a secret name and paste your 40 digit GitHub API Token into the “Secret Value” input and then click “Save”.

Next, click the “Values” tab and specify a value name (this value name will be used in our trigger function later). Set the “Value Type” as “Secret” and set the “Secret Name” as the secret you created in your previous step. Finally, click the save button. Saving your value will allow it to be accessible in any MongoDB Realm Function via the script context.values.get("myGithubTokenVal").

Note

In the screenshot below, a value is created called “myGithubTokenVal”. If you have created your value with an alternative name, access your value in a MongoDB Realm Function via the script context.values.get("<value-name>") and replace “<value-name>” with the name of your value.

9

Create a Database Trigger

You can create a Database Trigger to enable your Issue Tracking app to respond to a new issue document by executing function logic. You can use function logic to perform actions, such as utilizing the GitHub API. To create your database trigger, navigate to the Triggers page and click the “Add a trigger button”. Set your database and collection as the same database and collection that you insert documents related to GitHub issues into. Set the “operation type” to “Insert” for the trigger to fire upon document inserts in the collection.

Set the event type as “Function” and create a new function. This function will use the GitHub API to comment on the opened issue automatically.

10

Automatically Comment on GitHub Issues

You can add application logic to your Database trigger function to add a helpful comment on newly opened GitHub issues using the GitHub API. Paste the following code in your Database trigger function to post to GitHub when there is a new issue.

copy

exports = function (changeEvent) { // the changeEvent refers to the document inserted
  const githubToken = context.values.get("myGithubTokenVal"); // your GitHub access token

  const url = changeEvent.fullDocument.url; // the url of the issue

  const http = context.services.get("github"); // replace "github" with the name of your HTTP Service from Step 1, if you chose a different name

  const githubURL = `${url}/comments`;

  return http.post({
    url: githubURL,
    body: {
      body:
        "Hi this is the GitHub issue tracker bot for <github username>, thank you for leaving an issue. We will respond to your issue shortly. For now, check out  stackoverflow  for helpful tips: https://stackoverflow.com/questions/tagged/mongodb",
    },
    encodeBodyAsJSON: true,
    headers: {
      "Authorization": [`Token ${githubToken}`],
    },
  })
 .then(response => {
   // The response body is encoded as raw BSON.Binary. Parse it to JSON.
   const ejson_body = EJSON.parse(response.body.text());
   console.log(ejson_body);
   return ejson_body;
 })
 .catch(err => console.error(`An error has occurred with the DB Trigger: ${err}`));
};

11

Confirm That Your DB Trigger Function Worked

Testing that your Database Trigger Function worked is the next step in building your Task Tracker Application. Create a new issue on your GitHub repository. When there is a new issue, your webhook inserts a document into your collection, invoking the database trigger function. View the inserted document by navigating to the “Atlas” tab on the top of your MongoDB Realm UI. Click the Collections button for your cluster. Once you have navigated to your collections view, click the name of your collection in order to see your inserted document.

The database trigger function automatically comments on the GitHub issue with a helpful comment.

12

Create a Scheduled Trigger With Digest Info On The GitHub Issues

Create a scheduled to execute logic at a specific time. Your GitHub Task Tracker will utilize the scheduled trigger to log a weekly summary of the issues created. To create a scheduled trigger, navigate to the Triggers page and configure your trigger as a “Scheduled” trigger type. Then set the trigger to repeat once by the “Day of the Week” on “Sunday” to have the trigger fire every Sunday. You can choose an alternate day of the week, or switch the frequency of the scheduled trigger. Finally, set the event type as “Function” and paste the following code into your scheduled trigger function.

Note

In the code block below, a message is printed to the console. To further expand on your MongoDB Realm application, you could, for example, remove this message and hook MongoDB Realm to an automatic email service such as SendGrid to print the message.

copy

exports = async function() {
  const collection = context.services.get("mongodb-atlas").db("tracker").collection("githubIssues");
  const query = {
    timestamp: {
    $gte: new Date(new Date() - 7 * 60 * 60 * 24 * 1000)
    }
  };
  const projection = { "_id": 0, "title": 1 };
  return collection.find(query, projection)
    .toArray()
    .then(items => {

      // set all the issue titles as a string
      let issuesTitles = "";
      items.forEach((item) => {
        issuesTitles += `| ${item.title} |`
      })
      console.log(`Thanks for signing up for the weekly digest letter of our GitHub issues tracker app. This week you had ${items.length} issues submitted. The following  issues were created: ${issuesTitles}.`);
    });
};

Summary

• MongoDB Realm Functions allow you to execute server-side code for your application and can be called from other applications or other MongoDB Realm Functions.
• The MongoDB HTTP Service allows you to communicate with any other server through the HTTP protocol.
• MongoDB Realm Triggers allow you to execute server-side code in response to a database event or pre-defined schedule.

←   Task Tracker (Web) Create a Realm App (Realm UI)  →

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.