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 Linear's GraphQL API for cloud-hosted instances from your application. Fusebit's multi-tenant approach makes it easy for you to manage multiple Linear 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.

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 Linear 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 Linear GraphQL API

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

const linearClient = await integration.tenant.getSdkByTenant(ctx, 'linearConnector', ctx.params.tenantId);

// List all the Linear issues assigned to me.
const me = await linearClient.viewer;
const issues = await me.assignedIssues();
if (!issues.nodes.length) {
  ctx.body = {
    message: 'You have no issues!',
  };
  return;
} else {
  ctx.body = {
    message: 'You have issues:',
  };
  issues.nodes.map((issue) => {
    ctx.body.message += `\n > ${issue.title}`;
  });
  return;
}

The linearClient object provided by Fusebit is an instance of the @linear/sdk npm package. The full reference documentation for the package is available here.

Fusebit ensures the above SDK object is already bootstrapped with the Linear 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 Linear App

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

To create your own Linear App:

  1. In the Fusebit Management Portal, find the Integration you would like to connect to the new Linear App you just created. 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

πŸ“˜

If more than one Integration is linked to that same Connector, they will all use the new Linear App you are about to configure.

  1. Select Enable Production Credentials in the Connector Configuration and note the OAuth Redirect URL under the 'Linear Configuration' section. You will need this information to successfully create your app in Linear.
  1. In your Linear Workspace, navigate to Settings > Account > API > Your Applications and select 'Create New'. Alternatively, you can click on this link to go there directly.

    On this screen, in addition to the required fields, you will need to paste the OAuth Redirect URL retrieved from from the previous step into the Callback URL field.

  1. Once you have filled out all the fields and selected 'Create', Linear will display the Client ID and Client Secret to you, make sure to save these as you will need to configure these in the connector in the Fusebit Management Portal.
  1. Back in the portal, under 'Fusebit Connector Configuration', paste in the Client ID and Client Secret you obtained earlier from the Linear App you created.

    Additionally, If the method(s) you want to invoke against the Linear API require certain permissions see here, add them under 'Space separated scopes to request from the OAuth server'.

    The following permissions are necessary to run the example provided: read

🚧

When switching a Connector to a different Linear App, all IdentityIdentity - An identity is a unique relationship one of your customers has with a service. An identity can be used by multiple integrations to act on that service on behalf of your customer. objects associated with that Connector will be deleted. Your users will need to re-authenticate against Linear after you make the change.

πŸ‘

Good Job!

Any time a new user installs your Integration, you should now see your Linear App information displayed during the authorization step.

Also, now that you've configured your own app, you can also leverage our Webhooks SDK to receive events from Linear!

Receiving events from Linear (Webhooks support)

With this Linear App configuration, your Fusebit Integration will be able to read and write new issues and comments (or on behalf of users if you configured that functionality). But you will likely also want to get notified when users respond to your issues/comments OR when they post certain keywords or commands. We can achieve that by configuring your app with Linear Webhooks

  1. Make sure you are using your own Linear App and have configured your Connector with that app's secrets.
  2. In your Connector, copy the Webhook URL you find under 'Linear Configuration'
  1. In your Linear App, enable the Webhooks toggle and paste the Webhook URL into the box. Here, you will also want to select all the event notifications you want to receive for your app.

Once you have configured Webhooks in your App, you can receive events in your Integration. The Connector will route all events from the workspace (team) that your Integration was authorized for when it was created.

  1. At the bottom of integration.js edit the following handler, which will log an messages received from Linear.
integration.event.on('/:componentName/webhook/:eventtype', async (ctx) => {

  const new_value = ctx.req.body.data.data.body;
  console.log ('There is a new update in Linear! Issue:' new_value)
// Insert your code here and invoke your backend to perform an action using this information!
});

🚧

Configuring Webhooks for an existing app?

If this app is already in production and you are adding webhooks functionality to it, your users will need to have their tenants re-authenticate with the app to work.

They will need to do this by:

  • Deleting all existing installations of the integration from the Fusebit Management Portal

  • Asking tenants to revoke access to the app from Settings > Applications > Authorized Applications and selecting 'Revoke Access' for the app. Alternatively, they can click on this link to go there directly


Did this page help you?