@eng-automation/integrations

opstooling-integrations

Reusable third party integrations library

All integrations are unified under similar API, with following rules in mind:

• Setup/configuration is supported in two ways:
  • Automatic (static): all options are in environment variables, and setup is performed on first execution of any method.
  • Manual: use getInstance(opts) method from an integration, and pass the instance as a parameter to each method. This allows to have more than one instance of integration. One example why this is needed, are installation-authenticated instances of github in cla-bot-2021.
• Mocks are provided for each query, but fixtures are added when needed.
• All retry / rate-limiting logic should also be implemented in this module.

Using mocks and fixtures

// module.ts
import { github } from "opstooling-integrations";

export async function foo() {
  await github.createCommitStatus({...});
}

// module.spec.ts
import { describe, expect, it, jest } from "@jest/globals";
import { fixtures, github } from "opstooling-integrations";
import { foo } from ".";

jest.mock("opstooling-integrations");

describe("foo", () => {
  it("calls github.createCommitStatus", async () => {
  jest.mocked(github.createCommitStatus).mockResolvedValue(fixtures.github.createCommitStatusSuccessfulResponse());
    await foo();

    expect(github.createCommitStatus).toHaveBeenCalledWith({...});
  });
});

Integrations

GitHub

Configuration

Four auth types are supported: app, installation, and token.

app auth

Non-installation auth type for GitHub Apps. Using this means that org/repo permissions aren't accessible.
Requires appId and privateKey.

installation auth

This type is used to authorize requests for specific org/repo application installation. Requires installationId, which can be resolved using app auth. If app expected to have only one installation, then it can be configured through environment. Otherwise, use github.getInstance and pass the instance further.
Requires appId, privateKey and installationId.

token auth

Simplest of all, requires only token, works for personal tokens or oauth tokens.

Environment variable	Option for getInstance()	Description	Required?	Default value
GITHUB_AUTH_TYPE	authType	app, token, installation	no	token
GITHUB_APP_ID	appId	GitHub app ID	yes, if authType is app, or installation	-
GITHUB_PRIVATE_KEY or GITHUB_PRIVATE_KEY_BASE64	privateKey	GitHub app private key. Use GITHUB_PRIVATE_KEY_BASE64 to curcumvent newline issues	yes, if authType is app or installation	-
GITHUB_TOKEN	authToken	GitHub auth token. Can be personal, oauth, etc.	yes, if authType is token	-
GITHUB_INSTALLATION_ID	installationId	GitHub app installation id	if authType is installation	-
GITHUB_BASE_URL	baseUrl	API endpoint URL	no	https://api.github.com