@probelabs/visor 0.1.137 → 0.1.138-ee
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/dist/cli-main.d.ts.map +1 -1
- package/dist/cli.d.ts.map +1 -1
- package/dist/docs/action-reference.md +14 -0
- package/dist/docs/ci-cli-mode.md +51 -2
- package/dist/docs/commands.md +8 -0
- package/dist/docs/github-auth.md +326 -0
- package/dist/docs/github-ops.md +6 -2
- package/dist/docs/index.md +1 -0
- package/dist/docs/security.md +11 -1
- package/dist/github-auth.d.ts +61 -0
- package/dist/github-auth.d.ts.map +1 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +2312 -298
- package/dist/sdk/{check-provider-registry-SA2WHPLO.mjs → check-provider-registry-B5X3AL4Z.mjs} +6 -6
- package/dist/sdk/{check-provider-registry-SCL4KP55.mjs → check-provider-registry-XRD3J74K.mjs} +5 -5
- package/dist/sdk/{chunk-F4K5WFSM.mjs → chunk-3CREE2RR.mjs} +14 -14
- package/dist/sdk/{chunk-UMFEBYCN.mjs → chunk-G3W5KQL7.mjs} +3 -3
- package/dist/sdk/{chunk-BRD36I43.mjs → chunk-GIPTKOXT.mjs} +2 -2
- package/dist/sdk/{chunk-QUEWQWDX.mjs → chunk-RR2KJCQS.mjs} +2 -2
- package/dist/sdk/{chunk-QUEWQWDX.mjs.map → chunk-RR2KJCQS.mjs.map} +1 -1
- package/dist/sdk/{chunk-DFKP7LY6.mjs → chunk-SUZCXRJ4.mjs} +19 -19
- package/dist/sdk/{chunk-J6F5K5EG.mjs.map → chunk-SUZCXRJ4.mjs.map} +1 -1
- package/dist/sdk/{failure-condition-evaluator-B5JJFYKU.mjs → failure-condition-evaluator-D5XXOVV2.mjs} +3 -3
- package/dist/sdk/{github-frontend-VAWVSCNX.mjs → github-frontend-LGS6PO5Y.mjs} +3 -3
- package/dist/sdk/{host-LOQWBHWT.mjs → host-RF2UEKMG.mjs} +2 -2
- package/dist/sdk/{host-TEQ7HKKH.mjs → host-YDQC5HZQ.mjs} +2 -2
- package/dist/sdk/knex-store-HPXJILBL.mjs +411 -0
- package/dist/sdk/knex-store-HPXJILBL.mjs.map +1 -0
- package/dist/sdk/loader-ZC5G3JGJ.mjs +89 -0
- package/dist/sdk/loader-ZC5G3JGJ.mjs.map +1 -0
- package/dist/sdk/opa-policy-engine-S2S2ULEI.mjs +655 -0
- package/dist/sdk/opa-policy-engine-S2S2ULEI.mjs.map +1 -0
- package/dist/sdk/{routing-HR6N43RQ.mjs → routing-6YONAZI2.mjs} +4 -4
- package/dist/sdk/{schedule-tool-handler-OXGTPLST.mjs → schedule-tool-handler-47KJUUJH.mjs} +6 -6
- package/dist/sdk/{schedule-tool-handler-Y2UABBXN.mjs → schedule-tool-handler-WHB5AGLT.mjs} +5 -5
- package/dist/sdk/sdk.js +1533 -275
- package/dist/sdk/sdk.js.map +1 -1
- package/dist/sdk/sdk.mjs +5 -5
- package/dist/sdk/{trace-helpers-FAAGLXBI.mjs → trace-helpers-LSOZHDYF.mjs} +2 -2
- package/dist/sdk/validator-XTZJZZJH.mjs +134 -0
- package/dist/sdk/validator-XTZJZZJH.mjs.map +1 -0
- package/dist/sdk/{workflow-check-provider-L2ZUOMJR.mjs → workflow-check-provider-D375GDQS.mjs} +6 -6
- package/dist/sdk/{workflow-check-provider-WLA7LO56.mjs → workflow-check-provider-MIFPOENL.mjs} +5 -5
- package/dist/types/cli.d.ts +8 -0
- package/dist/types/cli.d.ts.map +1 -1
- package/package.json +2 -2
- package/dist/output/traces/run-2026-02-23T08-59-32-321Z.ndjson +0 -138
- package/dist/output/traces/run-2026-02-23T09-00-20-148Z.ndjson +0 -1442
- package/dist/sdk/check-provider-registry-BCGP62RY.mjs +0 -29
- package/dist/sdk/chunk-ALB3N4ZQ.mjs +0 -443
- package/dist/sdk/chunk-ALB3N4ZQ.mjs.map +0 -1
- package/dist/sdk/chunk-DFKP7LY6.mjs.map +0 -1
- package/dist/sdk/chunk-E2N3U5HU.mjs +0 -1502
- package/dist/sdk/chunk-J6F5K5EG.mjs +0 -40235
- package/dist/sdk/chunk-UMFEBYCN.mjs.map +0 -1
- package/dist/sdk/chunk-YTAGJZHN.mjs +0 -739
- package/dist/sdk/chunk-YTAGJZHN.mjs.map +0 -1
- package/dist/sdk/failure-condition-evaluator-3B3G5NYW.mjs +0 -17
- package/dist/sdk/github-frontend-ZOVXPPHQ.mjs +0 -1356
- package/dist/sdk/github-frontend-ZOVXPPHQ.mjs.map +0 -1
- package/dist/sdk/routing-SEQYM4N6.mjs +0 -25
- package/dist/sdk/schedule-tool-handler-5BDMLHS5.mjs +0 -39
- package/dist/sdk/schedule-tool-handler-Y2UABBXN.mjs.map +0 -1
- package/dist/sdk/trace-helpers-FAAGLXBI.mjs.map +0 -1
- package/dist/sdk/trace-helpers-IGMH7ZPP.mjs +0 -25
- package/dist/sdk/trace-helpers-IGMH7ZPP.mjs.map +0 -1
- package/dist/sdk/workflow-check-provider-7SR7ZWSV.mjs +0 -29
- package/dist/sdk/workflow-check-provider-7SR7ZWSV.mjs.map +0 -1
- package/dist/sdk/workflow-check-provider-L2ZUOMJR.mjs.map +0 -1
- package/dist/sdk/workflow-check-provider-WLA7LO56.mjs.map +0 -1
- package/dist/traces/run-2026-02-23T08-59-32-321Z.ndjson +0 -138
- package/dist/traces/run-2026-02-23T09-00-20-148Z.ndjson +0 -1442
- /package/dist/sdk/{check-provider-registry-BCGP62RY.mjs.map → check-provider-registry-B5X3AL4Z.mjs.map} +0 -0
- /package/dist/sdk/{check-provider-registry-SA2WHPLO.mjs.map → check-provider-registry-XRD3J74K.mjs.map} +0 -0
- /package/dist/sdk/{chunk-F4K5WFSM.mjs.map → chunk-3CREE2RR.mjs.map} +0 -0
- /package/dist/sdk/{chunk-E2N3U5HU.mjs.map → chunk-G3W5KQL7.mjs.map} +0 -0
- /package/dist/sdk/{chunk-BRD36I43.mjs.map → chunk-GIPTKOXT.mjs.map} +0 -0
- /package/dist/sdk/{check-provider-registry-SCL4KP55.mjs.map → failure-condition-evaluator-D5XXOVV2.mjs.map} +0 -0
- /package/dist/sdk/{github-frontend-VAWVSCNX.mjs.map → github-frontend-LGS6PO5Y.mjs.map} +0 -0
- /package/dist/sdk/{host-LOQWBHWT.mjs.map → host-RF2UEKMG.mjs.map} +0 -0
- /package/dist/sdk/{host-TEQ7HKKH.mjs.map → host-YDQC5HZQ.mjs.map} +0 -0
- /package/dist/sdk/{failure-condition-evaluator-3B3G5NYW.mjs.map → routing-6YONAZI2.mjs.map} +0 -0
- /package/dist/sdk/{failure-condition-evaluator-B5JJFYKU.mjs.map → schedule-tool-handler-47KJUUJH.mjs.map} +0 -0
- /package/dist/sdk/{routing-HR6N43RQ.mjs.map → schedule-tool-handler-WHB5AGLT.mjs.map} +0 -0
- /package/dist/sdk/{routing-SEQYM4N6.mjs.map → trace-helpers-LSOZHDYF.mjs.map} +0 -0
- /package/dist/sdk/{schedule-tool-handler-5BDMLHS5.mjs.map → workflow-check-provider-D375GDQS.mjs.map} +0 -0
- /package/dist/sdk/{schedule-tool-handler-OXGTPLST.mjs.map → workflow-check-provider-MIFPOENL.mjs.map} +0 -0
package/dist/cli-main.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"","sourceRoot":"","sources":["file:///home/runner/work/visor/visor/src/cli-main.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"","sourceRoot":"","sources":["file:///home/runner/work/visor/visor/src/cli-main.ts"],"names":[],"mappings":"AAyyBA;;GAEG;AACH,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CA27C1C"}
|
package/dist/cli.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"","sourceRoot":"","sources":["file:///home/runner/work/visor/visor/src/cli.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAA2B,MAAM,aAAa,CAAC;AAQlE;;GAEG;AACH,qBAAa,GAAG;IACd,OAAO,CAAC,OAAO,CAAU;IACzB,OAAO,CAAC,YAAY,CAA0D;IAG9E,OAAO,CAAC,WAAW,CAGR;;IAOX;;OAEG;IACH,OAAO,CAAC,YAAY;
|
|
1
|
+
{"version":3,"file":"","sourceRoot":"","sources":["file:///home/runner/work/visor/visor/src/cli.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAA2B,MAAM,aAAa,CAAC;AAQlE;;GAEG;AACH,qBAAa,GAAG;IACd,OAAO,CAAC,OAAO,CAAU;IACzB,OAAO,CAAC,YAAY,CAA0D;IAG9E,OAAO,CAAC,WAAW,CAGR;;IAOX;;OAEG;IACH,OAAO,CAAC,YAAY;IAoFpB;;OAEG;IACH,OAAO,CAAC,aAAa,CAEnB;IAEF;;OAEG;IACI,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU;IAmM5C;;OAEG;IACH,OAAO,CAAC,eAAe;IAyCvB;;OAEG;IACI,WAAW,IAAI,MAAM;IAkE5B;;OAEG;IACI,UAAU,IAAI,MAAM;IAoC3B;;OAEG;IACI,eAAe,IAAI,MAAM;IAkBhC;;OAEG;IACI,QAAQ,IAAI,IAAI;IAIvB;;OAEG;IACI,WAAW,IAAI,IAAI;CAG3B"}
|
|
@@ -63,9 +63,23 @@ jobs:
|
|
|
63
63
|
github-token: ${{ secrets.GITHUB_TOKEN }}
|
|
64
64
|
```
|
|
65
65
|
|
|
66
|
+
### Credential Propagation
|
|
67
|
+
|
|
68
|
+
When running as a GitHub Action, Visor automatically propagates the authenticated token to all child processes. This means:
|
|
69
|
+
|
|
70
|
+
- **Command checks** using `gh` CLI or `git` against private repos work out of the box
|
|
71
|
+
- **AI agents** (Claude Code) can use `gh` and `git` in bash steps
|
|
72
|
+
- **MCP servers** (stdio) inherit the GitHub credentials
|
|
73
|
+
- **Git operations** (clone, push, fetch) authenticate automatically via `GIT_CONFIG_*` env vars
|
|
74
|
+
|
|
75
|
+
No additional configuration is needed — authentication is set up once and flows everywhere.
|
|
76
|
+
|
|
77
|
+
For CLI mode authentication and detailed setup, see [GitHub Authentication](github-auth.md).
|
|
78
|
+
|
|
66
79
|
### Related Documentation
|
|
67
80
|
|
|
68
81
|
- [AI Configuration](ai-configuration.md) - Configure AI providers and models
|
|
82
|
+
- [GitHub Authentication](github-auth.md) - Token and GitHub App auth setup
|
|
69
83
|
- [GitHub Checks](GITHUB_CHECKS.md) - GitHub Check runs integration
|
|
70
84
|
- [Tag Filtering](tag-filtering.md) - Filter checks by tags
|
|
71
85
|
- [Configuration](configuration.md) - Full configuration reference
|
package/dist/docs/ci-cli-mode.md
CHANGED
|
@@ -70,6 +70,51 @@ jobs:
|
|
|
70
70
|
sarif_file: results.sarif
|
|
71
71
|
```
|
|
72
72
|
|
|
73
|
+
## GitHub Authentication
|
|
74
|
+
|
|
75
|
+
Visor supports GitHub authentication in CLI mode via flags or environment variables. When configured, credentials are automatically propagated to all child processes — command checks, AI agents, MCP servers, and git operations work out of the box.
|
|
76
|
+
|
|
77
|
+
### Token Auth
|
|
78
|
+
|
|
79
|
+
```yaml
|
|
80
|
+
jobs:
|
|
81
|
+
visor-cli:
|
|
82
|
+
runs-on: ubuntu-latest
|
|
83
|
+
steps:
|
|
84
|
+
- uses: actions/checkout@v4
|
|
85
|
+
- run: npx -y @probelabs/visor@latest --config .visor.yaml --output json
|
|
86
|
+
env:
|
|
87
|
+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
|
88
|
+
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
### GitHub App Auth
|
|
92
|
+
|
|
93
|
+
```yaml
|
|
94
|
+
jobs:
|
|
95
|
+
visor-cli:
|
|
96
|
+
runs-on: ubuntu-latest
|
|
97
|
+
steps:
|
|
98
|
+
- uses: actions/checkout@v4
|
|
99
|
+
- run: |
|
|
100
|
+
npx -y @probelabs/visor@latest --config .visor.yaml \
|
|
101
|
+
--github-app-id "$GITHUB_APP_ID" \
|
|
102
|
+
--github-private-key "$GITHUB_APP_PRIVATE_KEY"
|
|
103
|
+
env:
|
|
104
|
+
GITHUB_APP_ID: ${{ secrets.VISOR_APP_ID }}
|
|
105
|
+
GITHUB_APP_PRIVATE_KEY: ${{ secrets.VISOR_PRIVATE_KEY }}
|
|
106
|
+
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
| Option | Environment Variable | Description |
|
|
110
|
+
|--------|---------------------|-------------|
|
|
111
|
+
| `--github-token <token>` | `GITHUB_TOKEN` / `GH_TOKEN` | Personal access token |
|
|
112
|
+
| `--github-app-id <id>` | `GITHUB_APP_ID` | GitHub App ID |
|
|
113
|
+
| `--github-private-key <key>` | `GITHUB_APP_PRIVATE_KEY` | App private key (PEM content or file path) |
|
|
114
|
+
| `--github-installation-id <id>` | `GITHUB_APP_INSTALLATION_ID` | Installation ID (auto-detected if omitted) |
|
|
115
|
+
|
|
116
|
+
This enables `gh` CLI commands and `git` operations against private repos inside command checks and AI agent steps. See [GitHub Authentication](./github-auth.md) for full details.
|
|
117
|
+
|
|
73
118
|
## Environment Variables
|
|
74
119
|
|
|
75
120
|
### AI Provider Keys
|
|
@@ -88,7 +133,11 @@ Set one of the following based on your AI provider:
|
|
|
88
133
|
|
|
89
134
|
| Variable | Description |
|
|
90
135
|
|----------|-------------|
|
|
91
|
-
| `GITHUB_TOKEN` |
|
|
136
|
+
| `GITHUB_TOKEN` | GitHub token for API access and child process propagation |
|
|
137
|
+
| `GH_TOKEN` | Alternative to `GITHUB_TOKEN` (both are set when auth is configured) |
|
|
138
|
+
| `GITHUB_APP_ID` | GitHub App ID (for App authentication) |
|
|
139
|
+
| `GITHUB_APP_PRIVATE_KEY` | GitHub App private key, PEM content or file path |
|
|
140
|
+
| `GITHUB_APP_INSTALLATION_ID` | GitHub App installation ID (optional, auto-detected) |
|
|
92
141
|
|
|
93
142
|
## Exit Codes
|
|
94
143
|
|
|
@@ -128,7 +177,7 @@ jobs:
|
|
|
128
177
|
|
|
129
178
|
## Notes
|
|
130
179
|
|
|
131
|
-
-
|
|
180
|
+
- GitHub credentials are optional in CLI mode. Provide them when your workflow uses `gh` CLI, accesses private repos, or uses the `github` provider.
|
|
132
181
|
- If you want PR comments/checks, use `--mode github-actions` with `GITHUB_TOKEN`.
|
|
133
182
|
- Use `--output-file` for reliable file output instead of shell redirection (`> file`).
|
|
134
183
|
- The `--fail-fast` flag is useful in CI to stop early when issues are found.
|
package/dist/docs/commands.md
CHANGED
|
@@ -167,6 +167,14 @@ See [Tag Filtering](tag-filtering.md) for detailed tag filtering documentation.
|
|
|
167
167
|
#### Config Reloading
|
|
168
168
|
- `--watch` - Watch config file for changes and reload automatically (requires `--config`). Also reloads on `SIGUSR2` signal (non-Windows). Intended for long-running modes like `--slack`.
|
|
169
169
|
|
|
170
|
+
#### GitHub Authentication
|
|
171
|
+
- `--github-token <token>` - GitHub token for API operations (env: `GITHUB_TOKEN`)
|
|
172
|
+
- `--github-app-id <id>` - GitHub App ID (env: `GITHUB_APP_ID`)
|
|
173
|
+
- `--github-private-key <key>` - GitHub App private key, PEM content or file path (env: `GITHUB_APP_PRIVATE_KEY`)
|
|
174
|
+
- `--github-installation-id <id>` - GitHub App installation ID, auto-detected if omitted
|
|
175
|
+
|
|
176
|
+
See [GitHub Authentication](github-auth.md) for setup guide and details.
|
|
177
|
+
|
|
170
178
|
#### Other Options
|
|
171
179
|
- `--slack` - Enable Slack Socket Mode runner
|
|
172
180
|
- `--mode <mode>` - Run mode: `cli` (default) or `github-actions`
|
|
@@ -0,0 +1,326 @@
|
|
|
1
|
+
# GitHub Authentication
|
|
2
|
+
|
|
3
|
+
Visor supports two authentication methods for GitHub: **Personal Access Tokens (PAT)** and **GitHub App** installations. Authentication is optional in CLI mode but required for workflows that interact with GitHub (labels, comments, PR data, private repo access).
|
|
4
|
+
|
|
5
|
+
When configured, Visor automatically propagates credentials to all child processes — command checks, AI agents, MCP servers, and git operations work out of the box regardless of local git configuration.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Quick Start
|
|
10
|
+
|
|
11
|
+
### Token Authentication
|
|
12
|
+
|
|
13
|
+
The simplest setup. Use a Personal Access Token or the default `GITHUB_TOKEN` in Actions.
|
|
14
|
+
|
|
15
|
+
**CLI:**
|
|
16
|
+
```bash
|
|
17
|
+
# Via environment variable (recommended)
|
|
18
|
+
GITHUB_TOKEN=ghp_xxx visor --config .visor.yaml
|
|
19
|
+
|
|
20
|
+
# Via CLI flag
|
|
21
|
+
visor --github-token ghp_xxx --config .visor.yaml
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
**GitHub Actions:**
|
|
25
|
+
```yaml
|
|
26
|
+
- uses: probelabs/visor@v1
|
|
27
|
+
with:
|
|
28
|
+
github-token: ${{ secrets.GITHUB_TOKEN }}
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
### GitHub App Authentication
|
|
32
|
+
|
|
33
|
+
Recommended for organizations. Provides granular permissions, bot identity, and audit logging.
|
|
34
|
+
|
|
35
|
+
**CLI:**
|
|
36
|
+
```bash
|
|
37
|
+
# Via environment variables
|
|
38
|
+
GITHUB_APP_ID=12345 \
|
|
39
|
+
GITHUB_APP_PRIVATE_KEY="$(cat key.pem)" \
|
|
40
|
+
visor --config .visor.yaml
|
|
41
|
+
|
|
42
|
+
# Via CLI flags
|
|
43
|
+
visor --github-app-id 12345 \
|
|
44
|
+
--github-private-key ./key.pem \
|
|
45
|
+
--config .visor.yaml
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
**GitHub Actions:**
|
|
49
|
+
```yaml
|
|
50
|
+
- uses: probelabs/visor@v1
|
|
51
|
+
with:
|
|
52
|
+
app-id: ${{ secrets.VISOR_APP_ID }}
|
|
53
|
+
private-key: ${{ secrets.VISOR_PRIVATE_KEY }}
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
---
|
|
57
|
+
|
|
58
|
+
## CLI Options
|
|
59
|
+
|
|
60
|
+
| Option | Environment Variable | Description |
|
|
61
|
+
|--------|---------------------|-------------|
|
|
62
|
+
| `--github-token <token>` | `GITHUB_TOKEN` or `GH_TOKEN` | Personal access token or fine-grained token |
|
|
63
|
+
| `--github-app-id <id>` | `GITHUB_APP_ID` | GitHub App ID |
|
|
64
|
+
| `--github-private-key <key>` | `GITHUB_APP_PRIVATE_KEY` | App private key (PEM content or file path) |
|
|
65
|
+
| `--github-installation-id <id>` | `GITHUB_APP_INSTALLATION_ID` | Installation ID (auto-detected if omitted) |
|
|
66
|
+
|
|
67
|
+
**Resolution order:** CLI flags take precedence over environment variables.
|
|
68
|
+
|
|
69
|
+
---
|
|
70
|
+
|
|
71
|
+
## How It Works
|
|
72
|
+
|
|
73
|
+
When Visor authenticates with GitHub, it does three things:
|
|
74
|
+
|
|
75
|
+
### 1. Creates an Authenticated Octokit Instance
|
|
76
|
+
|
|
77
|
+
Used internally for GitHub API calls — posting PR comments, adding labels, creating check runs.
|
|
78
|
+
|
|
79
|
+
### 2. Sets Token Environment Variables
|
|
80
|
+
|
|
81
|
+
```
|
|
82
|
+
GITHUB_TOKEN=<token>
|
|
83
|
+
GH_TOKEN=<token>
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
These are inherited by all child processes, enabling:
|
|
87
|
+
- `gh` CLI commands in command checks
|
|
88
|
+
- `gh api` calls in AI agent bash steps
|
|
89
|
+
- Any tool that reads `GITHUB_TOKEN` from the environment
|
|
90
|
+
|
|
91
|
+
### 3. Configures Git HTTPS Credentials
|
|
92
|
+
|
|
93
|
+
```
|
|
94
|
+
GIT_CONFIG_COUNT=2
|
|
95
|
+
GIT_CONFIG_KEY_0=url.https://x-access-token:<token>@github.com/.insteadOf
|
|
96
|
+
GIT_CONFIG_VALUE_0=https://github.com/
|
|
97
|
+
GIT_CONFIG_KEY_1=url.https://x-access-token:<token>@github.com/.insteadOf
|
|
98
|
+
GIT_CONFIG_VALUE_1=git@github.com:
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
This uses git's `GIT_CONFIG_COUNT` mechanism (git 2.31+) to:
|
|
102
|
+
- Rewrite `https://github.com/` URLs to include the access token
|
|
103
|
+
- Rewrite `git@github.com:` SSH-style URLs to authenticated HTTPS
|
|
104
|
+
- Work on any machine regardless of local git configuration
|
|
105
|
+
- Require no temp files or global config changes
|
|
106
|
+
- Propagate automatically to all child processes
|
|
107
|
+
|
|
108
|
+
**Result:** `git clone`, `git push`, `git fetch`, and `git ls-remote` against github.com private repositories work automatically in command checks, AI agents, and MCP tools.
|
|
109
|
+
|
|
110
|
+
---
|
|
111
|
+
|
|
112
|
+
## GitHub App Setup
|
|
113
|
+
|
|
114
|
+
### 1. Create a GitHub App
|
|
115
|
+
|
|
116
|
+
1. Go to **Settings > Developer settings > GitHub Apps > New GitHub App**
|
|
117
|
+
2. Set a name (e.g., "Visor Bot")
|
|
118
|
+
3. Set the homepage URL (can be your repo URL)
|
|
119
|
+
4. Uncheck **Webhook > Active** (Visor doesn't need webhooks from the App)
|
|
120
|
+
5. Set permissions:
|
|
121
|
+
- **Repository permissions:**
|
|
122
|
+
- Contents: Read (for code access)
|
|
123
|
+
- Pull requests: Read & Write (for comments, labels)
|
|
124
|
+
- Checks: Read & Write (for check runs)
|
|
125
|
+
- Issues: Read & Write (for issue operations)
|
|
126
|
+
- Metadata: Read (required)
|
|
127
|
+
- **Organization permissions:** None required
|
|
128
|
+
6. Click **Create GitHub App**
|
|
129
|
+
|
|
130
|
+
### 2. Generate a Private Key
|
|
131
|
+
|
|
132
|
+
1. On the App settings page, scroll to **Private keys**
|
|
133
|
+
2. Click **Generate a private key**
|
|
134
|
+
3. Save the downloaded `.pem` file securely
|
|
135
|
+
|
|
136
|
+
### 3. Install the App
|
|
137
|
+
|
|
138
|
+
1. Go to **Install App** in the sidebar
|
|
139
|
+
2. Select the organization or account
|
|
140
|
+
3. Choose **All repositories** or select specific repos
|
|
141
|
+
4. Click **Install**
|
|
142
|
+
|
|
143
|
+
### 4. Note the IDs
|
|
144
|
+
|
|
145
|
+
- **App ID**: Shown at the top of the App settings page
|
|
146
|
+
- **Installation ID**: Visible in the URL after installation (`/installations/<id>`)
|
|
147
|
+
- Visor auto-detects this if you don't provide it
|
|
148
|
+
|
|
149
|
+
### 5. Store Secrets
|
|
150
|
+
|
|
151
|
+
**GitHub Actions:**
|
|
152
|
+
```bash
|
|
153
|
+
# Store as repository or organization secrets
|
|
154
|
+
gh secret set VISOR_APP_ID --body "12345"
|
|
155
|
+
gh secret set VISOR_PRIVATE_KEY < key.pem
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
**Local / CI:**
|
|
159
|
+
```bash
|
|
160
|
+
# Environment variables
|
|
161
|
+
export GITHUB_APP_ID=12345
|
|
162
|
+
export GITHUB_APP_PRIVATE_KEY="$(cat key.pem)"
|
|
163
|
+
|
|
164
|
+
# Or pass as file path
|
|
165
|
+
export GITHUB_APP_PRIVATE_KEY=./path/to/key.pem
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
---
|
|
169
|
+
|
|
170
|
+
## Token Permissions
|
|
171
|
+
|
|
172
|
+
### Personal Access Token (Classic)
|
|
173
|
+
|
|
174
|
+
Required scopes:
|
|
175
|
+
- `repo` — Full repository access (for private repos)
|
|
176
|
+
- `write:discussion` — Optional, for PR comments
|
|
177
|
+
|
|
178
|
+
### Fine-Grained Token
|
|
179
|
+
|
|
180
|
+
Required permissions:
|
|
181
|
+
- **Contents**: Read
|
|
182
|
+
- **Pull requests**: Read and Write
|
|
183
|
+
- **Issues**: Read and Write (if using label/comment operations)
|
|
184
|
+
- **Checks**: Read and Write (if using GitHub Checks API)
|
|
185
|
+
|
|
186
|
+
### Default `GITHUB_TOKEN` in Actions
|
|
187
|
+
|
|
188
|
+
The `${{ secrets.GITHUB_TOKEN }}` or `${{ github.token }}` works for most use cases. Limitations:
|
|
189
|
+
- Cannot trigger other workflows
|
|
190
|
+
- Cannot access other repositories
|
|
191
|
+
- Scoped to the current repository only
|
|
192
|
+
|
|
193
|
+
---
|
|
194
|
+
|
|
195
|
+
## Child Process Propagation
|
|
196
|
+
|
|
197
|
+
Visor's credential injection ensures authentication works across all provider types:
|
|
198
|
+
|
|
199
|
+
| Provider | What Works |
|
|
200
|
+
|----------|-----------|
|
|
201
|
+
| **command** | `gh pr list`, `git clone https://github.com/org/private-repo`, any tool reading `GITHUB_TOKEN` |
|
|
202
|
+
| **ai** (Claude Code) | Agent bash steps using `gh`, `git`, or any GitHub-aware CLI tool |
|
|
203
|
+
| **mcp** (stdio) | MCP server processes inherit all credentials |
|
|
204
|
+
| **github** (native) | Labels, comments, check runs via Octokit API |
|
|
205
|
+
| **git-checkout** | Cloning private repositories in worktrees |
|
|
206
|
+
|
|
207
|
+
### Example: Command Check with `gh`
|
|
208
|
+
|
|
209
|
+
```yaml
|
|
210
|
+
steps:
|
|
211
|
+
list-prs:
|
|
212
|
+
type: command
|
|
213
|
+
exec: gh pr list --repo myorg/myrepo --json number,title
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
This works automatically when Visor has GitHub auth configured — no additional environment setup needed in the check definition.
|
|
217
|
+
|
|
218
|
+
### Example: AI Agent Accessing Private Repos
|
|
219
|
+
|
|
220
|
+
```yaml
|
|
221
|
+
steps:
|
|
222
|
+
code-explorer:
|
|
223
|
+
type: ai
|
|
224
|
+
provider: claude-code
|
|
225
|
+
prompt: |
|
|
226
|
+
Clone the shared library from https://github.com/myorg/shared-lib
|
|
227
|
+
and analyze its API surface.
|
|
228
|
+
ai:
|
|
229
|
+
allowBash: true
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
The agent's `git clone` command succeeds because the git credentials are in the environment.
|
|
233
|
+
|
|
234
|
+
---
|
|
235
|
+
|
|
236
|
+
## Without Authentication
|
|
237
|
+
|
|
238
|
+
When no GitHub credentials are provided:
|
|
239
|
+
|
|
240
|
+
- Visor runs normally — auth is optional in CLI mode
|
|
241
|
+
- GitHub provider checks (`type: github`) will return `github/missing_octokit` errors
|
|
242
|
+
- `gh` CLI commands will fail with auth errors
|
|
243
|
+
- `git` operations against private repos will fail
|
|
244
|
+
- Public repository operations still work
|
|
245
|
+
|
|
246
|
+
A warning is logged if auth is attempted but fails:
|
|
247
|
+
|
|
248
|
+
```
|
|
249
|
+
[warn] GitHub auth failed: <error message>
|
|
250
|
+
[warn] Continuing without GitHub API access
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
---
|
|
254
|
+
|
|
255
|
+
## Troubleshooting
|
|
256
|
+
|
|
257
|
+
### "No authenticated Octokit instance available"
|
|
258
|
+
|
|
259
|
+
The `github/missing_octokit` error means no credentials reached the GitHub provider.
|
|
260
|
+
|
|
261
|
+
**Fix:** Set `GITHUB_TOKEN` or configure App auth before running Visor.
|
|
262
|
+
|
|
263
|
+
### gh CLI shows "not logged in"
|
|
264
|
+
|
|
265
|
+
The `gh` CLI reads `GITHUB_TOKEN` or `GH_TOKEN` from the environment.
|
|
266
|
+
|
|
267
|
+
**Check:** Run `visor --debug` and look for `GitHub auth: token` or `GitHub auth: github-app` in the output.
|
|
268
|
+
|
|
269
|
+
### git clone fails for private repos
|
|
270
|
+
|
|
271
|
+
Git needs credentials configured. Visor sets `GIT_CONFIG_*` env vars automatically.
|
|
272
|
+
|
|
273
|
+
**Check:**
|
|
274
|
+
1. Verify auth is working: look for the auth log line
|
|
275
|
+
2. Verify git version is 2.31+ (`git --version`)
|
|
276
|
+
3. For SSH URLs (`git@github.com:...`), Visor rewrites them to HTTPS automatically
|
|
277
|
+
|
|
278
|
+
### GitHub App installation ID not found
|
|
279
|
+
|
|
280
|
+
If auto-detection fails:
|
|
281
|
+
```
|
|
282
|
+
GitHub App installation ID could not be auto-detected
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
**Fix:** Provide the installation ID explicitly:
|
|
286
|
+
```bash
|
|
287
|
+
visor --github-installation-id 12345678
|
|
288
|
+
# or
|
|
289
|
+
export GITHUB_APP_INSTALLATION_ID=12345678
|
|
290
|
+
```
|
|
291
|
+
|
|
292
|
+
### Token not propagating to child processes
|
|
293
|
+
|
|
294
|
+
**Check:** Add a debug command check to verify:
|
|
295
|
+
```yaml
|
|
296
|
+
steps:
|
|
297
|
+
debug-auth:
|
|
298
|
+
type: command
|
|
299
|
+
exec: |
|
|
300
|
+
echo "GITHUB_TOKEN set: $([ -n "$GITHUB_TOKEN" ] && echo yes || echo no)"
|
|
301
|
+
echo "GIT_CONFIG_COUNT: $GIT_CONFIG_COUNT"
|
|
302
|
+
gh auth status 2>&1 || true
|
|
303
|
+
```
|
|
304
|
+
|
|
305
|
+
---
|
|
306
|
+
|
|
307
|
+
## Security Considerations
|
|
308
|
+
|
|
309
|
+
- Tokens are stored only in `process.env` — no files are written to disk
|
|
310
|
+
- Git credentials use `GIT_CONFIG_COUNT` env vars, not `.gitconfig` or credential helpers
|
|
311
|
+
- All credentials are scoped to the Visor process and its children
|
|
312
|
+
- When the process exits, no persistent state remains
|
|
313
|
+
- For GitHub Apps, Visor extracts a short-lived installation token (~1 hour expiry)
|
|
314
|
+
|
|
315
|
+
See [Security](./security.md) for broader security guidance.
|
|
316
|
+
|
|
317
|
+
---
|
|
318
|
+
|
|
319
|
+
## Related Documentation
|
|
320
|
+
|
|
321
|
+
- [Security](./security.md) - Security best practices and authentication overview
|
|
322
|
+
- [Action Reference](./action-reference.md) - GitHub Action inputs and outputs
|
|
323
|
+
- [CI/CLI Mode](./ci-cli-mode.md) - Running Visor in CI pipelines
|
|
324
|
+
- [GitHub Provider](./github-ops.md) - Native GitHub operations (labels, comments)
|
|
325
|
+
- [Command Provider](./command-provider.md) - Running shell commands
|
|
326
|
+
- [Claude Code](./claude-code.md) - AI agent integration
|
package/dist/docs/github-ops.md
CHANGED
|
@@ -8,8 +8,12 @@ The `github` provider performs safe, native GitHub operations via Octokit — no
|
|
|
8
8
|
|
|
9
9
|
## Requirements
|
|
10
10
|
|
|
11
|
-
-
|
|
12
|
-
- `
|
|
11
|
+
- An authenticated Octokit instance must be available. Provided automatically when:
|
|
12
|
+
- Running as a GitHub Action with `github-token` or `app-id`/`private-key` inputs
|
|
13
|
+
- Running in CLI mode with `--github-token`, `--github-app-id`/`--github-private-key`, or `GITHUB_TOKEN` env var
|
|
14
|
+
- `GITHUB_REPOSITORY` is auto-set in Actions. In CLI mode, set it if needed.
|
|
15
|
+
|
|
16
|
+
See [GitHub Authentication](./github-auth.md) for setup details.
|
|
13
17
|
|
|
14
18
|
## Configuration
|
|
15
19
|
|
package/dist/docs/index.md
CHANGED
|
@@ -12,6 +12,7 @@ Visor is an AI-powered workflow orchestration tool for code review, automation,
|
|
|
12
12
|
| [Configuration](./configuration.md) | Core configuration reference for `.visor.yaml` files |
|
|
13
13
|
| [Commands](./commands.md) | CLI commands and PR comment commands reference |
|
|
14
14
|
| [Action Reference](./action-reference.md) | GitHub Action inputs, outputs, and usage examples |
|
|
15
|
+
| [GitHub Authentication](./github-auth.md) | Token and GitHub App auth setup for CLI, CI, and child processes |
|
|
15
16
|
| [CI/CLI Mode](./ci-cli-mode.md) | Running Visor in CI pipelines and CLI mode |
|
|
16
17
|
|
|
17
18
|
---
|
package/dist/docs/security.md
CHANGED
|
@@ -46,7 +46,16 @@ Visor supports two authentication methods for GitHub integration:
|
|
|
46
46
|
- Organization-wide installations
|
|
47
47
|
- Audit logging and traceability
|
|
48
48
|
|
|
49
|
-
|
|
49
|
+
### Credential Propagation
|
|
50
|
+
|
|
51
|
+
When Visor authenticates, it automatically injects credentials into `process.env` so that all child processes (command checks, AI agents, MCP servers, git operations) inherit them. This includes:
|
|
52
|
+
|
|
53
|
+
- `GITHUB_TOKEN` and `GH_TOKEN` for the `gh` CLI
|
|
54
|
+
- `GIT_CONFIG_COUNT`/`GIT_CONFIG_KEY_*`/`GIT_CONFIG_VALUE_*` for authenticated git HTTPS access
|
|
55
|
+
|
|
56
|
+
No temp files are written, no global git config is modified, and credentials are scoped to the Visor process tree.
|
|
57
|
+
|
|
58
|
+
See [GitHub Authentication](./github-auth.md) for complete setup guide including CLI options, GitHub App creation steps, and troubleshooting.
|
|
50
59
|
|
|
51
60
|
---
|
|
52
61
|
|
|
@@ -456,6 +465,7 @@ See [Configuration](./configuration.md) for complete extends documentation.
|
|
|
456
465
|
|
|
457
466
|
## Related Documentation
|
|
458
467
|
|
|
468
|
+
- [GitHub Authentication](./github-auth.md) - Token and GitHub App auth setup, credential propagation
|
|
459
469
|
- [AI Configuration](./ai-configuration.md) - AI provider security options
|
|
460
470
|
- [HTTP Integration](./http.md) - HTTP authentication and TLS
|
|
461
471
|
- [Command Provider](./command-provider.md) - Command injection prevention
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
import { Octokit } from '@octokit/rest';
|
|
2
|
+
/**
|
|
3
|
+
* Options for GitHub authentication.
|
|
4
|
+
* Supports both personal access token and GitHub App authentication.
|
|
5
|
+
*/
|
|
6
|
+
export interface GitHubAuthOptions {
|
|
7
|
+
/** Personal access token or fine-grained token */
|
|
8
|
+
token?: string;
|
|
9
|
+
/** GitHub App ID */
|
|
10
|
+
appId?: string;
|
|
11
|
+
/** GitHub App private key (PEM content or file path) */
|
|
12
|
+
privateKey?: string;
|
|
13
|
+
/** GitHub App installation ID (auto-detected if omitted) */
|
|
14
|
+
installationId?: string;
|
|
15
|
+
/** Repository owner (for auto-detecting installation ID) */
|
|
16
|
+
owner?: string;
|
|
17
|
+
/** Repository name (for auto-detecting installation ID) */
|
|
18
|
+
repo?: string;
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* Result of successful GitHub authentication.
|
|
22
|
+
*/
|
|
23
|
+
export interface GitHubAuthResult {
|
|
24
|
+
/** Authenticated Octokit instance */
|
|
25
|
+
octokit: Octokit;
|
|
26
|
+
/** Authentication method used */
|
|
27
|
+
authType: 'github-app' | 'token';
|
|
28
|
+
/** Raw token string for environment propagation */
|
|
29
|
+
token: string;
|
|
30
|
+
}
|
|
31
|
+
/**
|
|
32
|
+
* Create an authenticated Octokit instance.
|
|
33
|
+
* Returns undefined if no credentials are provided (auth is optional in CLI mode).
|
|
34
|
+
*
|
|
35
|
+
* For token auth: uses the token directly.
|
|
36
|
+
* For GitHub App auth: creates JWT-authenticated client, resolves installation ID,
|
|
37
|
+
* then extracts an installation access token for environment propagation.
|
|
38
|
+
*/
|
|
39
|
+
export declare function createAuthenticatedOctokit(options: GitHubAuthOptions): Promise<GitHubAuthResult | undefined>;
|
|
40
|
+
/**
|
|
41
|
+
* Resolve GitHub auth options from environment variables.
|
|
42
|
+
* Used as fallback when no explicit CLI arguments are provided.
|
|
43
|
+
*/
|
|
44
|
+
export declare function resolveAuthFromEnvironment(): GitHubAuthOptions;
|
|
45
|
+
/**
|
|
46
|
+
* Resolve private key — supports both inline PEM content and file paths.
|
|
47
|
+
*/
|
|
48
|
+
export declare function resolvePrivateKey(keyOrPath: string): string;
|
|
49
|
+
/**
|
|
50
|
+
* Inject GitHub credentials into process.env for child processes.
|
|
51
|
+
*
|
|
52
|
+
* Sets GITHUB_TOKEN/GH_TOKEN for gh CLI, and configures git HTTPS auth
|
|
53
|
+
* via GIT_CONFIG_COUNT/KEY/VALUE env vars so `git clone`, `git push`, etc.
|
|
54
|
+
* work automatically against github.com without any local git config.
|
|
55
|
+
*
|
|
56
|
+
* Uses git's GIT_CONFIG_COUNT mechanism (git 2.31+, March 2021):
|
|
57
|
+
* - No temp files or global config mutation
|
|
58
|
+
* - Inherited by all child processes automatically
|
|
59
|
+
* - Works regardless of local git configuration
|
|
60
|
+
*/
|
|
61
|
+
export declare function injectGitHubCredentials(token: string): void;
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"","sourceRoot":"","sources":["file:///home/runner/work/visor/visor/src/github-auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAIxC;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oBAAoB;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4DAA4D;IAC5D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2DAA2D;IAC3D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,qCAAqC;IACrC,OAAO,EAAE,OAAO,CAAC;IACjB,iCAAiC;IACjC,QAAQ,EAAE,YAAY,GAAG,OAAO,CAAC;IACjC,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;GAOG;AACH,wBAAsB,0BAA0B,CAC9C,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CA2EvC;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,IAAI,iBAAiB,CAS9D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAU3D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAmB3D"}
|
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"","sourceRoot":"","sources":["file:///home/runner/work/visor/visor/src/index.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"","sourceRoot":"","sources":["file:///home/runner/work/visor/visor/src/index.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAuD9D,wBAAsB,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CA8OzC;AAID,OAAO,EAAE,wBAAwB,EAAE,CAAC"}
|