@slates-integrations/github 0.2.0-rc.2

package/README.md

@@ -0,0 +1,109 @@
+# <img src="https://provider-logos.metorial-cdn.com/github.png" height="20"> Github
+
+Manage repositories, issues, and pull requests. Create and configure branches, star repositories, review code, and merge changes. Automate CI/CD workflows with GitHub Actions, manage workflow runs, secrets, and artifacts. Track issues with labels, milestones, and assignees. Search across code, repositories, issues, and users. Manage organizations, teams, and memberships. Create and manage projects, gists, packages, deployments, and environments. Access security alerts including code scanning, secret scanning, and Dependabot alerts. Read and write file contents in repositories. Manage webhooks, notifications, and codespaces.
+
+## Tools
+
+### Comment on Issue
+
+Add a comment to an existing issue or pull request. Both issues and pull requests share the same comment API.
+
+### Create Commit Status
+
+Create a status check on a specific commit. Useful for integrating CI/CD results, deployment status, or other external checks. Also supports reading the combined status of all checks for a given ref.
+
+### Create Release
+
+Create a new release for a GitHub repository with a tag, name, release notes, and draft/pre-release options. Can automatically generate release notes from commits since the last release.
+
+### Create Repository
+
+Create a new GitHub repository for the authenticated user or within an organization. Supports initializing with a README, gitignore template, and license.
+
+### Get Issue
+
+Retrieve detailed information about a specific issue, including its body, comments count, labels, assignees, and milestone.
+
+### Get Repository
+
+Retrieve detailed information about a GitHub repository including its settings, statistics, and metadata. Use this to inspect a repository's configuration, check its visibility, default branch, language, star/fork counts, and more.
+
+### Get User
+
+Retrieve a GitHub user's profile. Provide a username to look up any user, or omit it to get the authenticated user's profile.
+
+### Star Repository
+
+Star or unstar a GitHub repository for the authenticated user.
+
+### List Branches
+
+List branches in a GitHub repository with optional filtering for protected branches.
+
+### List Commits
+
+List commits on a repository branch with filtering by SHA, path, author, or date range.
+
+### List Issues
+
+List issues in a GitHub repository with filtering and sorting options. Filter by state, labels, assignee, milestone, and since date. Note: GitHub's API returns pull requests alongside issues — this tool filters them out.
+
+### List Pull Requests
+
+List pull requests in a GitHub repository with filtering by state, head/base branch, and sorting options.
+
+### List Repositories
+
+List repositories for the authenticated user or a specific organization. Supports filtering by type, sorting, and pagination.
+
+### Manage Collaborators
+
+List, add, or remove collaborators on a GitHub repository. Control access permissions for individual users.
+
+### Manage File Content
+
+Read, create, update, or delete a file in a GitHub repository. - **read**: Retrieve file contents (decoded from Base64). - **write**: Create or update a file. Provide Base64-encoded content and a commit message. - **delete**: Delete a file. Requires the file's current SHA and a commit message.
+
+### Manage Gist
+
+Create, read, update, or delete GitHub Gists (code snippets). - **create**: Create a new gist with one or more files. - **get**: Retrieve a gist by ID. - **update**: Update a gist's description or files. - **delete**: Delete a gist. - **list**: List gists for the authenticated user.
+
+### Manage Issue
+
+Create a new issue or update an existing one in a GitHub repository. When creating: provide title and optionally body, labels, assignees, and milestone. When updating: provide the issue number along with fields to change (title, body, state, labels, assignees).
+
+### Manage Labels
+
+List existing labels or create a new label in a GitHub repository. Labels can be applied to issues and pull requests for categorization.
+
+### Manage Pull Request
+
+Create a new pull request or update an existing one. When creating: provide head branch, base branch, and title. When updating: provide the pull request number along with fields to change.
+
+### Manage Workflow
+
+Interact with GitHub Actions workflows: list workflows, list runs, trigger a workflow dispatch, cancel or rerun a workflow run, and view run jobs.
+
+### Merge Pull Request
+
+Merge a pull request using the specified merge method (merge commit, squash, or rebase).
+
+### Review Pull Request
+
+Submit a review on a pull request with an approve, request changes, or comment action. Optionally include inline comments on specific files and lines. Can also request reviewers.
+
+### Search GitHub
+
+Search across GitHub for repositories, code, issues/pull requests, or users using GitHub's search syntax. Supports qualifiers for filtering (e.g., "language:python stars:>100" for repositories).
+
+### Update Repository
+
+Update settings of an existing GitHub repository. Modify name, description, visibility, feature toggles (issues, wiki, projects), default branch, and archive status.
+
+## License
+
+This integration is licensed under the [FSL-1.1](https://github.com/metorial/metorial-platform/blob/dev/LICENSE).
+
+<div align="center">
+  <sub>Built with ❤️ by <a href="https://metorial.com">Metorial</a></sub>
+</div>

package/docs/SPEC.md

@@ -0,0 +1,215 @@
+Now I have enough information to write the specification. Let me compile everything.
+
+# Slates Specification for GitHub
+
+## Overview
+
+GitHub is a cloud-based platform for version control and collaboration using Git. It provides hosting for software repositories along with features for issue tracking, code review, project management, CI/CD (GitHub Actions), and package hosting. GitHub offers both REST and GraphQL APIs for programmatic access to its platform resources.
+
+## Authentication
+
+GitHub supports several authentication methods for API access:
+
+### 1. Personal Access Tokens (PATs)
+
+Personal Access Tokens are preferred over passwords and provide granular control over permissions, enabling developers to create tokens that allow only specific actions. There are two types:
+
+- **Fine-grained PATs** (recommended): Allow selecting specific repositories and precise permissions. Generated under **Settings > Developer settings > Personal access tokens > Fine-grained tokens**.
+- **Classic PATs**: Use OAuth scopes for permission control. Generated under **Settings > Developer settings > Personal access tokens > Tokens (classic)**.
+
+Tokens are passed via the `Authorization` header:
+
+```
+Authorization: Bearer <YOUR-TOKEN>
+```
+
+### 2. OAuth 2.0 (OAuth Apps)
+
+Every registered OAuth app is assigned a unique Client ID and Client Secret. The client secret is used to get an access token for the signed-in user.
+
+- **Authorization endpoint:** `https://github.com/login/oauth/authorize`
+- **Token endpoint:** `https://github.com/login/oauth/access_token`
+- **Flow:** Standard OAuth 2.0 Authorization Code flow. After a successful app authentication, GitHub provides a temporary code value, which must be POSTed back to GitHub with the client secret in exchange for an access token.
+
+**Available OAuth Scopes:**
+
+| Scope                                                  | Description                                                                 |
+| ------------------------------------------------------ | --------------------------------------------------------------------------- |
+| `(no scope)`                                           | Read-only access to public information                                      |
+| `repo`                                                 | Full access to public and private repositories                              |
+| `repo:status`                                          | Read/write access to commit statuses                                        |
+| `public_repo`                                          | Access to public repositories only                                          |
+| `admin:org`                                            | Full management of organizations and teams                                  |
+| `write:org` / `read:org`                               | Write or read access to organization membership                             |
+| `admin:repo_hook`                                      | Full access to repository webhooks                                          |
+| `admin:org_hook`                                       | Full access to organization webhooks                                        |
+| `user`                                                 | Read/write access to user profile (includes `user:email` and `user:follow`) |
+| `user:email`                                           | Read access to email addresses                                              |
+| `gist`                                                 | Write access to gists                                                       |
+| `notifications`                                        | Access to notifications                                                     |
+| `workflow`                                             | Manage GitHub Actions workflow files                                        |
+| `write:packages` / `read:packages` / `delete:packages` | Manage GitHub Packages                                                      |
+| `project` / `read:project`                             | Access to user and organization projects                                    |
+| `delete_repo`                                          | Delete repositories                                                         |
+| `codespace`                                            | Create and manage codespaces                                                |
+| `security_events`                                      | Access to code scanning API                                                 |
+| `read:audit_log`                                       | Read audit log data                                                         |
+
+### 3. GitHub Apps
+
+GitHub Apps authentication allows third-party applications to act on behalf of a user or organization, involving creating a GitHub App, installing it on a user or organization's account, and authenticating requests using a private key.
+
+- **Authentication as the app:** Generate a JSON Web Token (JWT) signed with the app's private key, then use it to obtain an installation access token.
+- **Authentication on behalf of a user:** Uses an OAuth-like flow to obtain a user access token.
+- GitHub Apps use fine-grained permissions instead of scopes, which give you more control over what your app can do.
+
+### Base URL
+
+All API requests are made to `https://api.github.com`.
+
+## Features
+
+### Repository Management
+
+Create, read, update, and delete repositories. Manage repository settings including visibility (public/private), branch protection rules, collaborator access, deploy keys, and repository topics. Also supports forking, transferring ownership, and managing repository templates.
+
+### Issues and Issue Tracking
+
+Create and manage issues within repositories. Supports labels, milestones, assignees, and comments. Issues can be searched and filtered across repositories using a powerful search syntax.
+
+### Pull Requests and Code Review
+
+Create and manage pull requests including requesting reviewers, managing review comments, and merging. Supports diff and patch formats. Allows managing pull request reviews with approve, request-changes, and comment actions.
+
+### Git Data
+
+Low-level access to Git objects including blobs, trees, commits, refs, and tags. Allows reading and writing raw Git data in a repository.
+
+### GitHub Actions and Workflows
+
+Manage workflows, workflow runs, and artifacts. Trigger workflows, view run logs, and manage workflow secrets and variables. Also supports managing self-hosted runners.
+
+### Organizations and Teams
+
+Manage organization settings, memberships, teams, and team memberships. Control organization-level permissions, invitations, and outside collaborator access.
+
+### Users and Profiles
+
+Access and update user profile information, email addresses, SSH keys, GPG keys, and social accounts. View followers and following relationships.
+
+### Projects
+
+Create and manage GitHub Projects (the project board feature). Supports managing columns and cards for organizing issues and pull requests.
+
+### Gists
+
+Create, update, delete, and list gists (code snippets). Supports forking, starring, and commenting on gists.
+
+### GitHub Packages
+
+Publish, install, and manage packages. Supports multiple package ecosystems including npm, Maven, Docker, NuGet, and RubyGems.
+
+### Code Search and Repository Search
+
+Search across code, repositories, issues, pull requests, users, topics, and commits using GitHub's search syntax. Supports qualifiers for filtering results.
+
+### Deployments and Environments
+
+Using the Deployments REST API, you can build custom tooling that interacts with your server and a third-party app. Manage deployment statuses and environments for repositories.
+
+### Checks and Commit Statuses
+
+You can use the REST API to build GitHub Apps that run powerful checks against code changes in a repository. Create and manage check runs, check suites, and commit statuses for CI/CD integration.
+
+### Content Management
+
+Use the REST API to create, modify, and delete Base64 encoded content in a repository. Read and write files, directories, and symlinks within repositories.
+
+### Notifications
+
+Access and manage notification threads for watched repositories and subscriptions.
+
+### Security and Code Scanning
+
+Access code scanning alerts, secret scanning alerts, Dependabot alerts, and security advisories. Manage repository vulnerability settings.
+
+### Codespaces
+
+Create, manage, and delete cloud development environments. Configure machine types and manage secrets for codespaces.
+
+### GraphQL API
+
+In addition to the REST API, GitHub provides a GraphQL API (v4) that allows more flexible, efficient queries with the ability to request exactly the data needed in a single request.
+
+## Events
+
+Webhooks provide a way for notifications to be delivered to an external web server whenever certain events occur on GitHub. Webhooks let you subscribe to events happening in a software system and automatically receive a delivery of data to your server whenever those events occur.
+
+You can create webhooks in a repository to subscribe to events that occur in that repository. You can create webhooks to subscribe to events that occur in a specific repository, organization, GitHub Marketplace account, GitHub Sponsors account, or GitHub App.
+
+Webhooks are configured with a payload URL, content type (JSON or form), and an optional secret for signature verification. The webhook signature header is the HMAC hex digest of the request body, generated using the SHA-256 hash function and the secret as the HMAC key.
+
+### Code & Repository Events
+
+- **Push:** Triggered when commits are pushed to a branch or tag.
+- **Create / Delete:** Triggered when a branch or tag is created or deleted.
+- **Repository:** Triggered when a repository is created, deleted, archived, made public/private, or transferred.
+- **Fork:** Triggered when a repository is forked.
+- **Release:** Triggered when a release is published, edited, or deleted (including pre-releases).
+- **Commit Comment:** Triggered when a comment is made on a commit.
+
+### Pull Request Events
+
+- **Pull Request:** Triggered for activity on pull requests (opened, closed, merged, assigned, labeled, review requested, etc.). Configurable by action type.
+- **Pull Request Review:** Triggered when a review is submitted, edited, or dismissed.
+- **Pull Request Review Comment:** Triggered for comments on a pull request diff.
+- **Pull Request Review Thread:** Triggered when a comment thread on a pull request is resolved or unresolved.
+
+### Issue Events
+
+- **Issues:** Triggered for issue activity (opened, edited, closed, assigned, labeled, etc.).
+- **Issue Comment:** Triggered when a comment is created, edited, or deleted on an issue or pull request.
+- **Label:** Triggered when a label is created, edited, or deleted.
+- **Milestone:** Triggered when a milestone is created, closed, edited, or deleted.
+
+### CI/CD and Checks Events
+
+- **Check Run / Check Suite:** Triggered for check run and check suite lifecycle events (created, completed, rerequested).
+- **Workflow Job:** Triggered when a GitHub Actions workflow job is queued, in progress, or completed.
+- **Workflow Run:** Triggered when a workflow run is requested, completed, or in progress.
+- **Deployment / Deployment Status:** Triggered when a deployment is created or its status changes.
+- **Status:** Triggered when the status of a commit changes.
+
+### Organization and Team Events
+
+- **Organization:** Triggered for organization-level events (member added/removed, renamed, etc.).
+- **Team:** Triggered when a team is created, deleted, edited, or has members/repos added/removed.
+- **Membership:** Triggered when a user is added to or removed from a team.
+- **Member:** Triggered when a collaborator is added to a repository.
+
+### Security Events
+
+- **Code Scanning Alert:** Triggered when a code scanning alert is created, fixed, or dismissed.
+- **Secret Scanning Alert:** Triggered when a secret scanning alert is created, resolved, or reopened.
+- **Dependabot Alert:** Triggered for Dependabot vulnerability alert activity.
+- **Repository Vulnerability Alert:** Triggered when a security vulnerability is detected.
+
+### Discussion Events
+
+- **Discussion:** Triggered for GitHub Discussions activity (created, edited, answered, etc.).
+- **Discussion Comment:** Triggered when a comment on a discussion is created, edited, or deleted.
+
+### Project Events
+
+- **Projects V2 Item:** Triggered when an item in a GitHub Project is created, edited, or deleted.
+
+### Other Events
+
+- **Star:** Triggered when a repository is starred or unstarred.
+- **Watch:** Triggered when a user watches a repository.
+- **Wiki (Gollum):** Triggered when a wiki page is created or updated.
+- **Page Build:** Triggered when a GitHub Pages site is built.
+- **Package:** Triggered when a package is published or updated in GitHub Packages.
+- **Sponsorship:** Triggered for GitHub Sponsors activity.
+- **Marketplace Purchase:** Triggered for GitHub Marketplace purchase activity.
+- **Ping:** A special event sent when a webhook is first created to verify the connection.

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@slates-integrations/github",
+  "main": "src/index.ts",
+  "type": "module",
+  "scripts": {
+    "build": "bunx @vercel/ncc build src/index.ts -o dist -m -s",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@types/node": "^20",
+    "slates": "1.0.0-rc.9",
+    "zod": "^4.2"
+  },
+  "devDependencies": {
+    "typescript": "^5"
+  },
+  "version": "0.2.0-rc.2"
+}

package/slate.json

@@ -0,0 +1,22 @@
+{
+  "name": "@github/github",
+  "description": "Manage repositories, issues, and pull requests. Create and configure branches, star repositories, review code, and merge changes. Automate CI/CD workflows with GitHub Actions, manage workflow runs, secrets, and artifacts. Track issues with labels, milestones, and assignees. Search across code, repositories, issues, and users. Manage organizations, teams, and memberships. Create and manage projects, gists, packages, deployments, and environments. Access security alerts including code scanning, secret scanning, and Dependabot alerts. Read and write file contents in repositories. Manage webhooks, notifications, and codespaces.",
+  "categories": [
+    "apis-and-http-requests",
+    "task-and-project-management"
+  ],
+  "skills": [
+    "manage repositories",
+    "star repositories",
+    "create pull requests",
+    "track issues",
+    "review and merge code",
+    "automate CI/CD workflows",
+    "search code and repositories",
+    "manage organizations and teams",
+    "read and write file contents",
+    "manage security alerts",
+    "configure webhooks"
+  ],
+  "logoUrl": "https://provider-logos.metorial-cdn.com/github.png"
+}

package/src/auth.ts

@@ -0,0 +1,257 @@
+import { SlateAuth, createAxios } from 'slates';
+import { z } from 'zod';
+
+export let auth = SlateAuth.create()
+  .output(
+    z.object({
+      token: z.string(),
+      refreshToken: z.string().optional()
+    })
+  )
+  .addOauth({
+    type: 'auth.oauth',
+    name: 'OAuth',
+    key: 'oauth',
+
+    scopes: [
+      {
+        title: 'Repository',
+        description: 'Full access to public and private repositories',
+        scope: 'repo'
+      },
+      {
+        title: 'Repository Status',
+        description: 'Read/write access to commit statuses',
+        scope: 'repo:status'
+      },
+      {
+        title: 'Public Repository',
+        description: 'Access to public repositories only',
+        scope: 'public_repo'
+      },
+      {
+        title: 'Admin: Organization',
+        description: 'Full management of organizations and teams',
+        scope: 'admin:org'
+      },
+      {
+        title: 'Write Organization',
+        description: 'Write access to organization membership',
+        scope: 'write:org'
+      },
+      {
+        title: 'Read Organization',
+        description: 'Read access to organization membership',
+        scope: 'read:org'
+      },
+      {
+        title: 'Admin: Repo Hook',
+        description: 'Full access to repository webhooks',
+        scope: 'admin:repo_hook'
+      },
+      {
+        title: 'Admin: Org Hook',
+        description: 'Full access to organization webhooks',
+        scope: 'admin:org_hook'
+      },
+      {
+        title: 'User',
+        description: 'Read/write access to user profile, email, and follow',
+        scope: 'user'
+      },
+      {
+        title: 'User Email',
+        description: 'Read access to email addresses',
+        scope: 'user:email'
+      },
+      {
+        title: 'Gist',
+        description: 'Write access to gists',
+        scope: 'gist'
+      },
+      {
+        title: 'Notifications',
+        description: 'Access to notifications',
+        scope: 'notifications'
+      },
+      {
+        title: 'Workflow',
+        description: 'Manage GitHub Actions workflow files',
+        scope: 'workflow'
+      },
+      {
+        title: 'Write Packages',
+        description: 'Upload packages to GitHub Packages',
+        scope: 'write:packages'
+      },
+      {
+        title: 'Read Packages',
+        description: 'Download packages from GitHub Packages',
+        scope: 'read:packages'
+      },
+      {
+        title: 'Delete Packages',
+        description: 'Delete packages from GitHub Packages',
+        scope: 'delete:packages'
+      },
+      {
+        title: 'Project',
+        description: 'Full access to user and organization projects',
+        scope: 'project'
+      },
+      {
+        title: 'Read Project',
+        description: 'Read-only access to user and organization projects',
+        scope: 'read:project'
+      },
+      {
+        title: 'Delete Repository',
+        description: 'Delete repositories',
+        scope: 'delete_repo'
+      },
+      {
+        title: 'Security Events',
+        description: 'Access to code scanning API',
+        scope: 'security_events'
+      },
+      {
+        title: 'Read Audit Log',
+        description: 'Read audit log data',
+        scope: 'read:audit_log'
+      }
+    ],
+
+    getAuthorizationUrl: async ctx => {
+      let params = new URLSearchParams({
+        client_id: ctx.clientId,
+        redirect_uri: ctx.redirectUri,
+        state: ctx.state,
+        scope: ctx.scopes.join(' ')
+      });
+
+      return {
+        url: `https://github.com/login/oauth/authorize?${params.toString()}`
+      };
+    },
+
+    handleCallback: async ctx => {
+      let http = createAxios();
+
+      let response = await http.post(
+        'https://github.com/login/oauth/access_token',
+        {
+          client_id: ctx.clientId,
+          client_secret: ctx.clientSecret,
+          code: ctx.code,
+          redirect_uri: ctx.redirectUri
+        },
+        {
+          headers: {
+            Accept: 'application/json'
+          }
+        }
+      );
+
+      let data = response.data;
+
+      return {
+        output: {
+          token: data.access_token,
+          refreshToken: data.refresh_token
+        }
+      };
+    },
+
+    handleTokenRefresh: async ctx => {
+      if (!ctx.output.refreshToken) {
+        return { output: ctx.output };
+      }
+
+      let http = createAxios();
+
+      let response = await http.post(
+        'https://github.com/login/oauth/access_token',
+        {
+          client_id: ctx.clientId,
+          client_secret: ctx.clientSecret,
+          grant_type: 'refresh_token',
+          refresh_token: ctx.output.refreshToken
+        },
+        {
+          headers: {
+            Accept: 'application/json'
+          }
+        }
+      );
+
+      let data = response.data;
+
+      return {
+        output: {
+          token: data.access_token,
+          refreshToken: data.refresh_token ?? ctx.output.refreshToken
+        }
+      };
+    },
+
+    getProfile: async (ctx: any) => {
+      let http = createAxios({
+        baseURL: 'https://api.github.com',
+        headers: {
+          Authorization: `Bearer ${ctx.output.token}`,
+          Accept: 'application/vnd.github+json'
+        }
+      });
+
+      let response = await http.get('/user');
+      let user = response.data;
+
+      return {
+        profile: {
+          id: String(user.id),
+          email: user.email ?? undefined,
+          name: user.name ?? user.login,
+          imageUrl: user.avatar_url
+        }
+      };
+    }
+  })
+  .addTokenAuth({
+    type: 'auth.token',
+    name: 'Personal Access Token',
+    key: 'personal_access_token',
+
+    inputSchema: z.object({
+      token: z.string().describe('GitHub Personal Access Token (classic or fine-grained)')
+    }),
+
+    getOutput: async ctx => {
+      return {
+        output: {
+          token: ctx.input.token
+        }
+      };
+    },
+
+    getProfile: async (ctx: any) => {
+      let http = createAxios({
+        baseURL: 'https://api.github.com',
+        headers: {
+          Authorization: `Bearer ${ctx.output.token}`,
+          Accept: 'application/vnd.github+json'
+        }
+      });
+
+      let response = await http.get('/user');
+      let user = response.data;
+
+      return {
+        profile: {
+          id: String(user.id),
+          email: user.email ?? undefined,
+          name: user.name ?? user.login,
+          imageUrl: user.avatar_url
+        }
+      };
+    }
+  });

package/src/config.ts

@@ -0,0 +1,4 @@
+import { SlateConfig } from 'slates';
+import { z } from 'zod';
+
+export let config = SlateConfig.create(z.object({}));