@rawdash/connector-github 0.15.0 → 0.17.0

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.
Files changed (5) hide show
  1. package/README.md +48 -64
  2. package/dist/index.d.ts +606 -4
  3. package/dist/index.js +372 -96
  4. package/dist/index.js.map +1 -1
  5. package/package.json +5 -4
package/README.md CHANGED
@@ -1,13 +1,11 @@
1
+ <!-- This file is generated from connector metadata by scripts/generate-connector-docs.ts. Do not edit by hand. -->
2
+
1
3
  # @rawdash/connector-github
2
4
 
3
5
  [![npm version](https://img.shields.io/npm/v/@rawdash/connector-github)](https://www.npmjs.com/package/@rawdash/connector-github)
4
6
  [![license](https://img.shields.io/npm/l/@rawdash/connector-github)](https://github.com/rawdash/rawdash/blob/main/LICENSE)
5
7
 
6
- GitHub connector for rawdash — sync pull requests, issues, deployments, releases, and CI runs into your dashboard.
7
-
8
- ## What it is
9
-
10
- `@rawdash/connector-github` is a rawdash connector that pulls data from the GitHub REST API. It syncs workflow runs, pull requests, issues, deployments, releases, and contributor activity into the rawdash storage engine, where they become available to widgets defined in your `rawdash.config.ts`.
8
+ Sync pull requests, issues, deployments, releases, CI runs, and contributor activity from a GitHub repository.
11
9
 
12
10
  ## Install
13
11
 
@@ -15,10 +13,44 @@ GitHub connector for rawdash — sync pull requests, issues, deployments, releas
15
13
  npm install @rawdash/connector-github
16
14
  ```
17
15
 
18
- ## Quick example
16
+ ## Authentication
17
+
18
+ A personal access token is optional for public repositories but required for private repos and to avoid the low unauthenticated rate limit.
19
+
20
+ 1. Open GitHub → Settings → Developer settings → Personal access tokens.
21
+ 2. Generate a token with the `repo` scope (read access is sufficient).
22
+ 3. Store it as a secret and reference it from the connector config as `token: secret("GITHUB_TOKEN")`.
23
+
24
+ ## Configuration
25
+
26
+ | Field | Type | Required | Description |
27
+ | ------- | ------ | -------- | ------------------------------------- |
28
+ | `owner` | string | Yes | GitHub username or organization name. |
29
+ | `repo` | string | Yes | Repository name. |
30
+ | `token` | secret | No | GitHub PAT with `repo` scope. |
31
+
32
+ ## Resources
33
+
34
+ - **`repo`** _(entity)_ - Top-level repository stats (stars, forks, and watchers) as a single entity.
35
+ - Endpoint: `GET /repos/{owner}/{repo}`
36
+ - **`workflow_run`** _(event)_ - GitHub Actions CI pipeline executions.
37
+ - Endpoint: `GET /repos/{owner}/{repo}/actions/runs`
38
+ - **`pull_request`** _(entity)_ - Open and closed pull requests, including draft state, author, and review state.
39
+ - Endpoint: `GET /repos/{owner}/{repo}/pulls`
40
+ - Review state is folded in from GET /repos/{owner}/{repo}/pulls/{number}/reviews per PR.
41
+ - **`issue`** _(entity)_ - Open and closed issues with labels, assignees, and author (pull requests excluded).
42
+ - Endpoint: `GET /repos/{owner}/{repo}/issues`
43
+ - **`deployment`** _(entity)_ - Deployments with their latest status, keyed by environment and ref.
44
+ - Endpoint: `GET /repos/{owner}/{repo}/deployments`
45
+ - The latest status is folded in from GET /repos/{owner}/{repo}/deployments/{id}/statuses.
46
+ - **`release`** _(entity)_ - Published, draft, and prerelease GitHub releases.
47
+ - Endpoint: `GET /repos/{owner}/{repo}/releases`
48
+ - **`contributor`** _(entity)_ - Per-author commit activity (commits, additions, deletions) for the repository.
49
+ - Endpoint: `GET /repos/{owner}/{repo}/stats/contributors`
50
+
51
+ ## Example
19
52
 
20
53
  ```ts
21
- import { GitHubConnector } from '@rawdash/connector-github';
22
54
  import {
23
55
  defineConfig,
24
56
  defineDashboard,
@@ -32,7 +64,7 @@ const github = {
32
64
  config: {
33
65
  owner: 'my-org',
34
66
  repo: 'my-repo',
35
- token: secret('GITHUB_TOKEN'), // optional for public repos
67
+ token: secret('GITHUB_TOKEN'),
36
68
  },
37
69
  };
38
70
 
@@ -47,79 +79,31 @@ export default defineConfig({
47
79
  metric: defineMetric({
48
80
  connector: github,
49
81
  shape: 'entity',
50
- field: 'id',
82
+ entityType: 'pull_request',
51
83
  fn: 'count',
52
84
  filter: [{ field: 'state', op: 'eq', value: 'open' }],
53
85
  }),
54
86
  },
55
- ci_status: {
56
- kind: 'status',
57
- title: 'CI',
58
- source: `${github.name}:workflow_runs`,
59
- },
60
87
  },
61
88
  }),
62
89
  },
63
90
  });
64
-
65
- // Wire the registry separately when mounting:
66
- // mountEngine(config, { connectorRegistry: { 'github-actions': GitHubConnector } });
67
91
  ```
68
92
 
69
- ## Configuration
70
-
71
- | Field | Type | Required | Description |
72
- | ------- | -------- | -------- | --------------------------------------------------------------------------------- |
73
- | `owner` | `string` | Yes | GitHub username or organization name |
74
- | `repo` | `string` | Yes | Repository name |
75
- | `token` | `Secret` | No | GitHub PAT with `repo` scope. Required for private repos and to avoid rate limits |
76
-
77
- ## Data synced
78
-
79
- - **Workflow runs** — CI pipeline executions (shape: `event`)
80
- - **Pull requests** — open and closed PRs with review state (shape: `entity`)
81
- - **Issues** — open and closed issues with labels and assignees (shape: `entity`)
82
- - **Deployments** — deployment events and statuses (shape: `event`)
83
- - **Releases** — published GitHub releases (shape: `event`)
84
- - **Contributors** — commit activity per author (shape: `metric`)
85
-
86
- ## Schemas
87
-
88
- `GitHubConnector.schemas` declares the Zod schema for each resource's raw API response. The cloud shape-drift pipeline reads these at deploy time to populate `connector_baselines`, and the package's property tests fuzz against them.
89
-
90
- | Resource | Represents |
91
- | ---------------------- | ----------------------------------------------------- |
92
- | `repo` | `GET /repos/{owner}/{repo}` — top-level repo stats |
93
- | `workflow_runs` | `GET /repos/{owner}/{repo}/actions/runs` page |
94
- | `pull_requests` | `GET /repos/{owner}/{repo}/pulls` page |
95
- | `pull_request_reviews` | `GET /repos/{owner}/{repo}/pulls/{n}/reviews` |
96
- | `issues` | `GET /repos/{owner}/{repo}/issues` page |
97
- | `deployments` | `GET /repos/{owner}/{repo}/deployments` page |
98
- | `deployment_statuses` | `GET /repos/{owner}/{repo}/deployments/{id}/statuses` |
99
- | `releases` | `GET /repos/{owner}/{repo}/releases` page |
100
- | `contributors` | `GET /repos/{owner}/{repo}/stats/contributors` |
101
-
102
- ## Duplicate handling
103
-
104
- The GitHub REST API can return the same item more than once within a single sync — for example when cursor pagination overlaps as the underlying collection mutates mid-fetch, when a retried request re-introduces items already seen, or when the same entity appears via more than one endpoint.
105
-
106
- Per resource (`workflow_runs`, `pull_requests`, `issues`, `deployments`, `releases`, `contributors`), the connector dedupes by stable id before writing to storage. The strategy is **keep last**: when two copies share an id, the later copy in the API response wins. `workflow_runs` additionally tracks ids across paginated pages within a single sync so the same run can't be written as two separate events. When duplicates are dropped, the connector emits a `console.warn` with the count so the behavior is observable. `repo_stats` is a single-document resource so dedupe doesn't apply.
107
-
108
- ## Property tests
93
+ ## Rate limits
109
94
 
110
- Every resource in this connector has a fast-check property test under `src/property.test.ts` that:
95
+ Unauthenticated requests share GitHub’s low 60 requests/hour limit; an authenticated token raises it to 5,000 requests/hour.
111
96
 
112
- 1. Generates N≥100 synthetic API payloads from a Zod schema mirroring the GitHub API response.
113
- 2. Pipes them through `connector.sync()` against an `InMemoryStorage` instance.
114
- 3. Asserts universal invariants — non-empty entity ids, finite event timestamps, no `undefined` leaking into storage, no thrown errors on any valid input — plus per-resource counts.
97
+ ## Limitations
115
98
 
116
- The helper lives in `@rawdash/connector-test-utils`. When extending the connector with a new resource, add a Zod schema for its payload and a test wired up via `runPropertySyncTest`.
99
+ - The GitHub REST API can return the same item more than once within a sync (cursor pagination overlapping a mutating collection, retried requests, or an item surfaced via multiple endpoints). Each resource dedupes by stable id before writing, keeping the last copy seen.
100
+ - Public repositories without a token are subject to GitHub’s low unauthenticated rate limit.
117
101
 
118
102
  ## Links
119
103
 
120
- - [rawdash docs](https://rawdash.dev)
104
+ - [Rawdash docs](https://rawdash.dev/docs/connectors/)
105
+ - [GitHub API docs](https://docs.github.com/rest)
121
106
  - [GitHub](https://github.com/rawdash/rawdash)
122
- - [Issues](https://github.com/rawdash/rawdash/issues)
123
107
 
124
108
  ## License
125
109