@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.
Files changed (87) hide show
  1. package/dist/cli-main.d.ts.map +1 -1
  2. package/dist/cli.d.ts.map +1 -1
  3. package/dist/docs/action-reference.md +14 -0
  4. package/dist/docs/ci-cli-mode.md +51 -2
  5. package/dist/docs/commands.md +8 -0
  6. package/dist/docs/github-auth.md +326 -0
  7. package/dist/docs/github-ops.md +6 -2
  8. package/dist/docs/index.md +1 -0
  9. package/dist/docs/security.md +11 -1
  10. package/dist/github-auth.d.ts +61 -0
  11. package/dist/github-auth.d.ts.map +1 -0
  12. package/dist/index.d.ts.map +1 -1
  13. package/dist/index.js +2312 -298
  14. package/dist/sdk/{check-provider-registry-SA2WHPLO.mjs → check-provider-registry-B5X3AL4Z.mjs} +6 -6
  15. package/dist/sdk/{check-provider-registry-SCL4KP55.mjs → check-provider-registry-XRD3J74K.mjs} +5 -5
  16. package/dist/sdk/{chunk-F4K5WFSM.mjs → chunk-3CREE2RR.mjs} +14 -14
  17. package/dist/sdk/{chunk-UMFEBYCN.mjs → chunk-G3W5KQL7.mjs} +3 -3
  18. package/dist/sdk/{chunk-BRD36I43.mjs → chunk-GIPTKOXT.mjs} +2 -2
  19. package/dist/sdk/{chunk-QUEWQWDX.mjs → chunk-RR2KJCQS.mjs} +2 -2
  20. package/dist/sdk/{chunk-QUEWQWDX.mjs.map → chunk-RR2KJCQS.mjs.map} +1 -1
  21. package/dist/sdk/{chunk-DFKP7LY6.mjs → chunk-SUZCXRJ4.mjs} +19 -19
  22. package/dist/sdk/{chunk-J6F5K5EG.mjs.map → chunk-SUZCXRJ4.mjs.map} +1 -1
  23. package/dist/sdk/{failure-condition-evaluator-B5JJFYKU.mjs → failure-condition-evaluator-D5XXOVV2.mjs} +3 -3
  24. package/dist/sdk/{github-frontend-VAWVSCNX.mjs → github-frontend-LGS6PO5Y.mjs} +3 -3
  25. package/dist/sdk/{host-LOQWBHWT.mjs → host-RF2UEKMG.mjs} +2 -2
  26. package/dist/sdk/{host-TEQ7HKKH.mjs → host-YDQC5HZQ.mjs} +2 -2
  27. package/dist/sdk/knex-store-HPXJILBL.mjs +411 -0
  28. package/dist/sdk/knex-store-HPXJILBL.mjs.map +1 -0
  29. package/dist/sdk/loader-ZC5G3JGJ.mjs +89 -0
  30. package/dist/sdk/loader-ZC5G3JGJ.mjs.map +1 -0
  31. package/dist/sdk/opa-policy-engine-S2S2ULEI.mjs +655 -0
  32. package/dist/sdk/opa-policy-engine-S2S2ULEI.mjs.map +1 -0
  33. package/dist/sdk/{routing-HR6N43RQ.mjs → routing-6YONAZI2.mjs} +4 -4
  34. package/dist/sdk/{schedule-tool-handler-OXGTPLST.mjs → schedule-tool-handler-47KJUUJH.mjs} +6 -6
  35. package/dist/sdk/{schedule-tool-handler-Y2UABBXN.mjs → schedule-tool-handler-WHB5AGLT.mjs} +5 -5
  36. package/dist/sdk/sdk.js +1533 -275
  37. package/dist/sdk/sdk.js.map +1 -1
  38. package/dist/sdk/sdk.mjs +5 -5
  39. package/dist/sdk/{trace-helpers-FAAGLXBI.mjs → trace-helpers-LSOZHDYF.mjs} +2 -2
  40. package/dist/sdk/validator-XTZJZZJH.mjs +134 -0
  41. package/dist/sdk/validator-XTZJZZJH.mjs.map +1 -0
  42. package/dist/sdk/{workflow-check-provider-L2ZUOMJR.mjs → workflow-check-provider-D375GDQS.mjs} +6 -6
  43. package/dist/sdk/{workflow-check-provider-WLA7LO56.mjs → workflow-check-provider-MIFPOENL.mjs} +5 -5
  44. package/dist/types/cli.d.ts +8 -0
  45. package/dist/types/cli.d.ts.map +1 -1
  46. package/package.json +2 -2
  47. package/dist/output/traces/run-2026-02-23T08-59-32-321Z.ndjson +0 -138
  48. package/dist/output/traces/run-2026-02-23T09-00-20-148Z.ndjson +0 -1442
  49. package/dist/sdk/check-provider-registry-BCGP62RY.mjs +0 -29
  50. package/dist/sdk/chunk-ALB3N4ZQ.mjs +0 -443
  51. package/dist/sdk/chunk-ALB3N4ZQ.mjs.map +0 -1
  52. package/dist/sdk/chunk-DFKP7LY6.mjs.map +0 -1
  53. package/dist/sdk/chunk-E2N3U5HU.mjs +0 -1502
  54. package/dist/sdk/chunk-J6F5K5EG.mjs +0 -40235
  55. package/dist/sdk/chunk-UMFEBYCN.mjs.map +0 -1
  56. package/dist/sdk/chunk-YTAGJZHN.mjs +0 -739
  57. package/dist/sdk/chunk-YTAGJZHN.mjs.map +0 -1
  58. package/dist/sdk/failure-condition-evaluator-3B3G5NYW.mjs +0 -17
  59. package/dist/sdk/github-frontend-ZOVXPPHQ.mjs +0 -1356
  60. package/dist/sdk/github-frontend-ZOVXPPHQ.mjs.map +0 -1
  61. package/dist/sdk/routing-SEQYM4N6.mjs +0 -25
  62. package/dist/sdk/schedule-tool-handler-5BDMLHS5.mjs +0 -39
  63. package/dist/sdk/schedule-tool-handler-Y2UABBXN.mjs.map +0 -1
  64. package/dist/sdk/trace-helpers-FAAGLXBI.mjs.map +0 -1
  65. package/dist/sdk/trace-helpers-IGMH7ZPP.mjs +0 -25
  66. package/dist/sdk/trace-helpers-IGMH7ZPP.mjs.map +0 -1
  67. package/dist/sdk/workflow-check-provider-7SR7ZWSV.mjs +0 -29
  68. package/dist/sdk/workflow-check-provider-7SR7ZWSV.mjs.map +0 -1
  69. package/dist/sdk/workflow-check-provider-L2ZUOMJR.mjs.map +0 -1
  70. package/dist/sdk/workflow-check-provider-WLA7LO56.mjs.map +0 -1
  71. package/dist/traces/run-2026-02-23T08-59-32-321Z.ndjson +0 -138
  72. package/dist/traces/run-2026-02-23T09-00-20-148Z.ndjson +0 -1442
  73. /package/dist/sdk/{check-provider-registry-BCGP62RY.mjs.map → check-provider-registry-B5X3AL4Z.mjs.map} +0 -0
  74. /package/dist/sdk/{check-provider-registry-SA2WHPLO.mjs.map → check-provider-registry-XRD3J74K.mjs.map} +0 -0
  75. /package/dist/sdk/{chunk-F4K5WFSM.mjs.map → chunk-3CREE2RR.mjs.map} +0 -0
  76. /package/dist/sdk/{chunk-E2N3U5HU.mjs.map → chunk-G3W5KQL7.mjs.map} +0 -0
  77. /package/dist/sdk/{chunk-BRD36I43.mjs.map → chunk-GIPTKOXT.mjs.map} +0 -0
  78. /package/dist/sdk/{check-provider-registry-SCL4KP55.mjs.map → failure-condition-evaluator-D5XXOVV2.mjs.map} +0 -0
  79. /package/dist/sdk/{github-frontend-VAWVSCNX.mjs.map → github-frontend-LGS6PO5Y.mjs.map} +0 -0
  80. /package/dist/sdk/{host-LOQWBHWT.mjs.map → host-RF2UEKMG.mjs.map} +0 -0
  81. /package/dist/sdk/{host-TEQ7HKKH.mjs.map → host-YDQC5HZQ.mjs.map} +0 -0
  82. /package/dist/sdk/{failure-condition-evaluator-3B3G5NYW.mjs.map → routing-6YONAZI2.mjs.map} +0 -0
  83. /package/dist/sdk/{failure-condition-evaluator-B5JJFYKU.mjs.map → schedule-tool-handler-47KJUUJH.mjs.map} +0 -0
  84. /package/dist/sdk/{routing-HR6N43RQ.mjs.map → schedule-tool-handler-WHB5AGLT.mjs.map} +0 -0
  85. /package/dist/sdk/{routing-SEQYM4N6.mjs.map → trace-helpers-LSOZHDYF.mjs.map} +0 -0
  86. /package/dist/sdk/{schedule-tool-handler-5BDMLHS5.mjs.map → workflow-check-provider-D375GDQS.mjs.map} +0 -0
  87. /package/dist/sdk/{schedule-tool-handler-OXGTPLST.mjs.map → workflow-check-provider-MIFPOENL.mjs.map} +0 -0
@@ -1 +1 @@
1
- {"version":3,"file":"","sourceRoot":"","sources":["file:///home/runner/work/visor/visor/src/cli-main.ts"],"names":[],"mappings":"AAmyBA;;GAEG;AACH,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAy5C1C"}
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;IA0EpB;;OAEG;IACH,OAAO,CAAC,aAAa,CAEnB;IAEF;;OAEG;IACI,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU;IAqL5C;;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"}
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
@@ -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` | Required for `--mode github-actions` |
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
- - In CLI mode, GitHub credentials are not required. Provide your AI provider keys as environment variables.
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.
@@ -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
@@ -8,8 +8,12 @@ The `github` provider performs safe, native GitHub operations via Octokit — no
8
8
 
9
9
  ## Requirements
10
10
 
11
- - `GITHUB_TOKEN` (or the Action input `github-token`) must be present.
12
- - `GITHUB_REPOSITORY` is auto‑set in Actions.
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
 
@@ -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
  ---
@@ -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
- See [GitHub Checks](./GITHUB_CHECKS.md) and [Action Reference](./action-reference.md) for complete authentication setup.
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"}
@@ -1 +1 @@
1
- {"version":3,"file":"","sourceRoot":"","sources":["file:///home/runner/work/visor/visor/src/index.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAkG9D,wBAAsB,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CA8OzC;AAID,OAAO,EAAE,wBAAwB,EAAE,CAAC"}
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"}