@loopstack/github-module 0.2.0 → 0.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +86 -5
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,16 +1,54 @@
|
|
|
1
1
|
# @loopstack/github-module
|
|
2
2
|
|
|
3
|
-
GitHub integration for the Loopstack automation framework.
|
|
3
|
+
> GitHub integration for the [Loopstack AI](https://loopstack.ai) automation framework.
|
|
4
|
+
|
|
5
|
+
This module provides a GitHub OAuth 2.0 provider implementation and 25 tools across 7 domains for interacting with GitHub APIs. It registers a GitHub OAuth provider with `@loopstack/oauth-module`, enabling GitHub authentication in any Loopstack workflow, and provides tools for repositories, issues, pull requests, content/git ops, actions, search, and users/orgs.
|
|
6
|
+
|
|
7
|
+
## Overview
|
|
8
|
+
|
|
9
|
+
The GitHub Module includes a **provider implementation** for `@loopstack/oauth-module`. It implements the `OAuthProviderInterface` and self-registers with the `OAuthProviderRegistry` on startup. Once registered, the generic OAuth workflow can handle `provider: 'github'` automatically.
|
|
10
|
+
|
|
11
|
+
By using this module, you'll be able to:
|
|
12
|
+
|
|
13
|
+
- Authenticate users with their GitHub account via OAuth 2.0
|
|
14
|
+
- Manage repositories, branches, issues, and pull requests programmatically
|
|
15
|
+
- Read and write file content, list directories, and inspect commits
|
|
16
|
+
- Trigger and monitor GitHub Actions workflow runs
|
|
17
|
+
- Search code, repositories, and issues across GitHub
|
|
18
|
+
- Access user profiles and organization memberships
|
|
4
19
|
|
|
5
20
|
## Installation
|
|
6
21
|
|
|
7
|
-
|
|
8
|
-
|
|
22
|
+
See [SETUP.md](./SETUP.md) for installation and setup instructions.
|
|
23
|
+
|
|
24
|
+
This module requires `@loopstack/oauth-module` as a peer dependency.
|
|
25
|
+
|
|
26
|
+
## How It Works
|
|
27
|
+
|
|
28
|
+
### Provider Registration
|
|
29
|
+
|
|
30
|
+
The `GitHubOAuthProvider` implements `OnModuleInit` and registers itself with the `OAuthProviderRegistry` at startup:
|
|
31
|
+
|
|
32
|
+
```typescript
|
|
33
|
+
onModuleInit(): void {
|
|
34
|
+
this.providerRegistry.register(this);
|
|
35
|
+
}
|
|
9
36
|
```
|
|
10
37
|
|
|
11
|
-
|
|
38
|
+
After registration, the generic `OAuthWorkflow` from `@loopstack/oauth-module` can handle authentication for `provider: 'github'`.
|
|
39
|
+
|
|
40
|
+
### Provider Details
|
|
41
|
+
|
|
42
|
+
| Property | Value |
|
|
43
|
+
| --------------- | --------------------------------------------- |
|
|
44
|
+
| `providerId` | `'github'` |
|
|
45
|
+
| `defaultScopes` | `repo`, `user`, `workflow`, `read:org` |
|
|
46
|
+
| Auth endpoint | `https://github.com/login/oauth/authorize` |
|
|
47
|
+
| Token endpoint | `https://github.com/login/oauth/access_token` |
|
|
12
48
|
|
|
13
|
-
|
|
49
|
+
> **Note:** GitHub OAuth tokens do not expire and do not support refresh. The `refreshToken()` method throws an error.
|
|
50
|
+
|
|
51
|
+
### Environment Variables
|
|
14
52
|
|
|
15
53
|
```env
|
|
16
54
|
GITHUB_CLIENT_ID=your_client_id
|
|
@@ -65,3 +103,46 @@ GITHUB_OAUTH_REDIRECT_URI=/oauth/callback
|
|
|
65
103
|
|
|
66
104
|
- **GitHubGetAuthenticatedUserTool** — Get authenticated user profile
|
|
67
105
|
- **GitHubListUserOrgsTool** — List user organizations
|
|
106
|
+
|
|
107
|
+
## Usage in Workflows
|
|
108
|
+
|
|
109
|
+
Once registered, any workflow can trigger GitHub authentication by launching the OAuth workflow with `provider: 'github'`:
|
|
110
|
+
|
|
111
|
+
```typescript
|
|
112
|
+
@InjectWorkflow() oAuth: OAuthWorkflow;
|
|
113
|
+
|
|
114
|
+
// In a transition method:
|
|
115
|
+
const result = await this.oAuth.run(
|
|
116
|
+
{ provider: 'github', scopes: ['repo', 'read:org', 'workflow'] },
|
|
117
|
+
{ alias: 'oAuth', callback: { transition: 'authCompleted' } },
|
|
118
|
+
);
|
|
119
|
+
|
|
120
|
+
await this.repository.save(
|
|
121
|
+
LinkDocument,
|
|
122
|
+
{
|
|
123
|
+
label: 'GitHub authentication required',
|
|
124
|
+
workflowId: result.workflowId,
|
|
125
|
+
embed: true,
|
|
126
|
+
expanded: true,
|
|
127
|
+
},
|
|
128
|
+
{ id: `link_${result.workflowId}` },
|
|
129
|
+
);
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
See `@loopstack/oauth-module` and `@loopstack/github-oauth-example` for complete usage examples.
|
|
133
|
+
|
|
134
|
+
## Dependencies
|
|
135
|
+
|
|
136
|
+
- `@loopstack/oauth-module` — Provides `OAuthProviderRegistry`, `OAuthProviderInterface`, and `OAuthTokenSet`
|
|
137
|
+
|
|
138
|
+
## About
|
|
139
|
+
|
|
140
|
+
Author: [Jakob Klippel](https://www.linkedin.com/in/jakob-klippel/)
|
|
141
|
+
|
|
142
|
+
License: Apache-2.0
|
|
143
|
+
|
|
144
|
+
### Additional Resources
|
|
145
|
+
|
|
146
|
+
- [Loopstack Documentation](https://loopstack.ai/docs)
|
|
147
|
+
- [Getting Started with Loopstack](https://loopstack.ai/docs/getting-started)
|
|
148
|
+
- For more examples see the [Loopstack Registry](https://loopstack.ai/registry)
|
package/package.json
CHANGED
|
@@ -9,7 +9,7 @@
|
|
|
9
9
|
"module",
|
|
10
10
|
"oauth"
|
|
11
11
|
],
|
|
12
|
-
"version": "0.2.
|
|
12
|
+
"version": "0.2.1",
|
|
13
13
|
"license": "Apache-2.0",
|
|
14
14
|
"author": {
|
|
15
15
|
"name": "Jakob Klippel",
|
|
@@ -30,7 +30,7 @@
|
|
|
30
30
|
"watch": "nest build --watch"
|
|
31
31
|
},
|
|
32
32
|
"dependencies": {
|
|
33
|
-
"@loopstack/oauth-module": "^0.2.
|
|
33
|
+
"@loopstack/oauth-module": "^0.2.1",
|
|
34
34
|
"zod": "^4.3.6"
|
|
35
35
|
},
|
|
36
36
|
"files": [
|