This IntegrationIntegration - An integration is the place the you write your code to get things done! Written in NodeJS, an integration runs in Fusebit's secure and scalable environment to translate between the needs of your backend application and the remote service or services you're connecting to. allows full access to the GitHub API, allowing you to build rich integrations. Fusebit's multi-tenant approach makes it easy for you to manage multiple GitHub connections on behalf of your app's users. Our Node.js-based programming model and lightweight deployment story make it easy to customize the Integration with any necessary business logic.

GitHub offers two application models: GitHub Apps and OAuth Apps. While GitHub Apps are the officially-recommended way to integrate with GitHub due to their security and other advantages, Fusebit offers support for both models. For a rundown of the differences, here are some good) resources.

In this tutorial, we walk you through building a GitHub App with Fusebit, but the process is similar for OAuth Apps, as you can see here.

Getting Started

  1. Use the Fusebit Management PortalFusebit Management Portal - The Fusebit Management Portal enables you to easily setup and manage all your integrations in one place. Link: https://manage.fusebit.io to create an account and log in.
  2. Create a new Integration using one of our GitHub templates
  1. You will then be able to run the Integration, download it's code, modify it, and deploy your changes. Detailed instructions on how to get started with an Integration are available here.

Invoking the GitHub API

The Integration template comes pre-configured with some example calls that invoke GitHub's API, for example:

// Get information about the current user
const data = await githubapp.rest.users.getAuthenticated();

The githubapp object provided by Fusebit is an instance of the @octokit/rest npm package. The full reference documentation for the package is available here.

Fusebit ensures the above SDK object is already bootstrapped with the GitHub credentials of the user invoking the Integration. You do not need to worry about obtaining an access token or refresh token -- Fusebit does that for you automatically.

Creating your own GitHub App

Out of the box, Fusebit's GitHub Integration uses our own demonstration application in the GitHub Marketplace. This is to make it easier to get started, however you will likely need to register your own GitHub App in case:

  • the GitHub method you are executing via the SDK requires more advanced permissions
  • you want to receive inbound messages via webhooks
  • you want to deploy your Integration in production and you want end-users to see your own branding instead of Fusebit branding

To create your own GitHub App:

  1. Go to https://github.com/settings/apps/new if you are creating the app under your account, or navigate to your organization page, select Developer settings > GitHub Apps > New GitHub App. If you are building an OAuth App instead, follow the steps here
  1. Fill out the required fields:
  • Uncheck Active in the Webhooks section
  • When asked Where can this GitHub App be installed?, select Any account
  1. On the About screen, note the Client ID and generate and copy a Client secret
  1. If the method(s) you want to invoke against the GitHub API require certain permissions see here, add the appropriate access under Permissions & events.

The sample code used below, does not require any additional permissions, so you can skip this step.

Configure your Connector

Back in the Fusebit Portal, find the Integration you would like to connect to the new GitHub App you just created.

  1. Select the ConnectorConnector - A connector is the package from Fusebit that manages the relationship between one or more integrations and a specific service. One of the most common types of connector is an OAuth connector, which takes care of the OAuth negotiation between your customers and the service you're integrating, so that you don't have to! tied to that integration.
  1. Select Enable Production Credentials in the Connector Configuration and then paste in the Client ID and Client Secret you obtained earlier from the GitHub App you created.

If you granted additional permissions to your app, make sure you list the corresponding scopes as a space-separated list. A full list of the available scopes is available here.

  1. Under Advanced Fusebit Options, paste the following under Override the OAuth2 Authorization URL, replacing fusebit-demo with the name of your app: https://github.com/apps/fusebit-demo/installations/new. Make sure you hit Save in the Portal.
  2. Navigate back to your GitHub App and over to Identifying and authorizing users and paste the URL provided by Fusebit in the GitHub Configuration section under OAuth2 Redirect URL
  1. Ensure the Request user authorization (OAuth) during installation checkbox is checked.
  1. Go back to the Installs tab of your Integration and delete any existing Installs. Now, any time a new user installs your Integration, you should now see your HubSpot App information displayed during the authorization step.

🚧

Existing users will need to re-authenticate once you complete this step.

  1. You can now hit Run in the Editor again, and you should be prompted to sign into your own HubSpot App.

Good job! Now that you've configured your own app, you can also leverage our Webhooks SDK to receive events from GitHub!

Receiving events from GitHub

With this app configuration, your Fusebit Integration will be able to request data from GitHub. But you will likely also want to have your application respond to events from GitHub without needing to poll for changes.

We can achieve that by configuring your GitHub App and leveraging their Webhooks API and connecting it to Fusebit.

  1. Make sure you are using your own GitHub App and have configured your Connector with that app's secrets. In your Connector, note the Webhook URL as you will need it in the next step.
  1. In your GitHub App configuration screen, go to Webhook, check the Active box, and in the Webhook URL field, paste the URL you copied from Fusebit in the previous step.

Be sure to select Save changes.

  1. It is a best practice to secure your webhooks. Follow the instructions provided here to generate a high-entropy secret, and paste it in the Webhook secret field in the GitHub portal. Hold on to the value, as you will also need it in a subsequent step.

  2. To receive events for various actions in GitHub, you will need to request certain permissions and subscribe. In the following example, we will subscribe to notifications about Issues. In your GitHub App configuration, go to Permissions & events and select Access: Read-only next to Issues. Scroll further down the page, and check the box next to Issues in the Subscribe to events section. Don't forget to hit Save changes at the bottom of the page.

  1. Back in the Fusebit Portal, paste the same secret value from step 3 in the Webhook Secret field and hit Save.

  2. Add any new scopes to the appropriate field as well. For the purposes of this example, add the issues scope to the ones already present.

  3. Navigate back to your Integration and go to the Installs tab. Delete any existing Installs. This will force Fusebit to repeat the authentication process and request the new scopes you just added.

  4. Hit Edit to see your Integration code and note the following function at the bottom of the template. This is the piece of code that will run when a GitHub event is received.

integration.event.on('/:componentName/webhook/(issues.*)', async (ctx) => {
  const { data } = ctx.req.body.data;
  console.log('captured webhook', data);
});
  1. Hit Run in the Editor to repeat the authentication flow. You should now see a GitHub consent screen reflecting the requested permission to work with Issues. Select a repository here where you can create or modify an Issue for testing purposes.

  2. Once the Integration is installed successfully, go and create or make changes to an Issue in the repository from the previous step.

  3. In the Editor console window, you should see the event sent by GitHub.


Did this page help you?