@assemblyline-agents/github 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenEve contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,19 @@
+# @assemblyline-agents/github
+
+Official Assembly Line GitHub connection plugin.
+
+`defineGitHubConnection` and `defineGitHubMcpConnection` give agents authenticated GitHub access, and the bundled skill under `skills/` covers repository, issue, pull-request, and workflow tasks. GitHub is intentionally a tool connection rather than an inbound Assembly Line communication channel.
+
+## Install
+
+```sh
+npm install @assemblyline-agents/github
+```
+
+## Part of Assembly Line
+
+This package is part of [Assembly Line](https://github.com/jasonbadeaux/openeve), a vendor-neutral, filesystem-first framework for durable AI agents. See the developer documentation in [docs/developers/](https://github.com/jasonbadeaux/openeve/tree/main/docs/developers) for setup, agent authoring, and deployment guides.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+import { type ConnectionDefinition, type McpPluginConnectionOptions } from "@assemblyline-agents/core";
+export declare const GITHUB_APP_REQUIRED_ENV: readonly ["GITHUB_APP_ID", "GITHUB_PRIVATE_KEY"];
+export interface GitHubConnectionOptions {
+    name?: string;
+    description?: string;
+    scopes?: string[];
+    capabilities?: string[];
+    required?: boolean;
+}
+export interface GitHubAppEnvironment {
+    GITHUB_APP_ID?: string;
+    GITHUB_PRIVATE_KEY?: string;
+    GITHUB_API_URL?: string;
+    GITHUB_TOKEN?: string;
+}
+/** GitHub App installation connection for authenticated repository tooling. */
+export declare function defineGitHubConnection(options?: GitHubConnectionOptions): ConnectionDefinition;
+export type GitHubMcpConnectionOptions = McpPluginConnectionOptions;
+export declare function defineGitHubMcpConnection(options: GitHubMcpConnectionOptions): import("@assemblyline-agents/core").McpHttpClientConnectionDefinition;
+export declare const openevePlugin: import("@assemblyline-agents/core").PluginModule;
+export declare function createGitHubInstallationToken(options: {
+    env: GitHubAppEnvironment;
+    installationId: number;
+    fetch?: typeof fetch;
+}): Promise<{
+    token: string;
+    expiresAt?: string;
+}>;
+export declare function createGitHubAppJwt(env: GitHubAppEnvironment, nowSeconds?: number): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAML,KAAK,oBAAoB,EAEzB,KAAK,0BAA0B,EAChC,MAAM,2BAA2B,CAAC;AAGnC,eAAO,MAAM,uBAAuB,kDAAmD,CAAC;AAExF,MAAM,WAAW,uBAAuB;IACtC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,+EAA+E;AAC/E,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,uBAA4B,GAAG,oBAAoB,CAclG;AAID,MAAM,MAAM,0BAA0B,GAAG,0BAA0B,CAAC;AAEpE,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,0BAA0B,yEAE5E;AAED,eAAO,MAAM,aAAa,kDAAqD,CAAC;AAEhF,wBAAsB,6BAA6B,CAAC,OAAO,EAAE;IAC3D,GAAG,EAAE,oBAAoB,CAAC;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB,GAAG,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAgBjD;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,oBAAoB,EAAE,UAAU,SAAgC,GAAG,MAAM,CAahH"}

package/dist/index.js

@@ -0,0 +1,92 @@
+import { createSign } from "node:crypto";
+import { adapter, connectionPluginMetadata, defineConnection, defineMcpPluginConnection, definePlugin } from "@assemblyline-agents/core";
+import { fetchWithPolicy } from "@assemblyline-agents/runtime";
+export const GITHUB_APP_REQUIRED_ENV = ["GITHUB_APP_ID", "GITHUB_PRIVATE_KEY"];
+/** GitHub App installation connection for authenticated repository tooling. */
+export function defineGitHubConnection(options = {}) {
+    return defineConnection({
+        description: options.description ?? "GitHub App installation connection for repository, issue, pull request, and workflow capabilities.",
+        provider: "github",
+        binding: adapter("github-app"),
+        scopes: options.scopes ?? ["issues:write", "pull_requests:write", "contents:read"],
+        capabilities: options.capabilities ?? ["issues", "pull_requests", "repository"],
+        subject: "installation",
+        required: options.required ?? false,
+        metadata: {
+            appAuth: "installation-token",
+            ...(options.name ? { name: options.name } : {})
+        }
+    });
+}
+const GITHUB_MCP_PLUGIN = connectionPluginMetadata("github");
+export function defineGitHubMcpConnection(options) {
+    return defineMcpPluginConnection(GITHUB_MCP_PLUGIN, options);
+}
+export const openevePlugin = definePlugin({ connections: [GITHUB_MCP_PLUGIN] });
+export async function createGitHubInstallationToken(options) {
+    const apiUrl = options.env.GITHUB_API_URL ?? "https://api.github.com";
+    const jwt = createGitHubAppJwt(options.env);
+    const response = await fetchWithPolicy(options.fetch ?? fetch, `${apiUrl}/app/installations/${options.installationId}/access_tokens`, {
+        method: "POST",
+        headers: githubHeaders(jwt)
+    });
+    const parsed = await parseJson(response);
+    if (!response.ok)
+        throw new Error(`GitHub installation token request failed: ${response.status} ${JSON.stringify(parsed)}`);
+    const record = recordValue(parsed);
+    const token = stringValue(record?.token);
+    if (!token)
+        throw new Error("GitHub installation token response did not include a token.");
+    const out = { token };
+    const expiresAt = stringValue(record?.expires_at);
+    if (expiresAt)
+        out.expiresAt = expiresAt;
+    return out;
+}
+export function createGitHubAppJwt(env, nowSeconds = Math.floor(Date.now() / 1000)) {
+    const appId = env.GITHUB_APP_ID;
+    const privateKey = env.GITHUB_PRIVATE_KEY?.replace(/\\n/g, "\n");
+    if (!appId || !privateKey)
+        throw new Error("GitHub App auth requires GITHUB_APP_ID and GITHUB_PRIVATE_KEY.");
+    const header = base64Url(JSON.stringify({ alg: "RS256", typ: "JWT" }));
+    const payload = base64Url(JSON.stringify({
+        iat: nowSeconds - 60,
+        exp: nowSeconds + 9 * 60,
+        iss: appId
+    }));
+    const signingInput = `${header}.${payload}`;
+    const signature = createSign("RSA-SHA256").update(signingInput).sign(privateKey);
+    return `${signingInput}.${base64Url(signature)}`;
+}
+function githubHeaders(token) {
+    return {
+        accept: "application/vnd.github+json",
+        authorization: `Bearer ${token}`,
+        "content-type": "application/json",
+        "user-agent": "openeve-github-adapter",
+        "x-github-api-version": "2022-11-28"
+    };
+}
+function base64Url(value) {
+    return Buffer.from(value).toString("base64url");
+}
+function stringValue(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function recordValue(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value))
+        ? value
+        : undefined;
+}
+async function parseJson(response) {
+    const text = await response.text();
+    if (!text)
+        return {};
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { text };
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@assemblyline-agents/github",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@assemblyline-agents/runtime": "0.1.0",
+    "@assemblyline-agents/core": "0.1.0"
+  },
+  "description": "Official OpenEve GitHub connection plugin.",
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jasonbadeaux/openeve.git",
+    "directory": "packages/github"
+  },
+  "bugs": {
+    "url": "https://github.com/jasonbadeaux/openeve/issues"
+  },
+  "homepage": "https://github.com/jasonbadeaux/openeve#readme",
+  "author": "OpenEve contributors",
+  "keywords": [
+    "openeve",
+    "ai",
+    "agents",
+    "github",
+    "connection",
+    "plugin"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit"
+  }
+}

package/skills/github/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: github
+description: Use configured GitHub MCP tools for repositories, issues, pull requests, and Actions.
+---
+# GitHub
+Resolve the owner and repository before searching. Read the current issue, pull request, review, or workflow state before proposing a change.
+
+The deployment owner configures the GitHub OAuth application or token. The scaffold is read-only; issue, pull request, repository, and workflow mutations require writes to be enabled with the configured approval gate.