You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CHANGELOG.md
+1Lines changed: 1 addition & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
9
9
10
10
### Changed
11
11
- Remove references to demo from docs. [#734](https://github.com/sourcebot-dev/sourcebot/pull/734)
12
+
- Add docs for GitHub App connection auth. #[735](https://github.com/sourcebot-dev/sourcebot/pull/735)
12
13
13
14
### Fixed
14
15
- Fixed issue where 403 errors were being raised during a user driven permission sync against a self-hosted code host. [#729](https://github.com/sourcebot-dev/sourcebot/pull/729)
A GitHub connection can be used for either [authentication](/docs/configuration/auth) or [permission syncing](/docs/features/permission-syncing). This is controlled using the `purpose` field
54
+
A GitHub connection can be used for [authentication](/docs/configuration/auth)and/or [permission syncing](/docs/features/permission-syncing). This is controlled using the `purpose` field
55
55
in the GitHub identity provider config.
56
56
57
57
<Accordiontitle="instructions">
@@ -115,7 +115,7 @@ in the GitHub identity provider config.
A GitLab connection can be used for either [authentication](/docs/configuration/auth) or [permission syncing](/docs/features/permission-syncing). This is controlled using the `purpose` field
118
+
A GitLab connection can be used for [authentication](/docs/configuration/auth)and/or [permission syncing](/docs/features/permission-syncing). This is controlled using the `purpose` field
Sourcebot can sync code from GitHub.com, GitHub Enterprise Server, and GitHub Enterprise Cloud.
10
11
@@ -106,56 +107,114 @@ If you're not familiar with Sourcebot [connections](/docs/connections/overview),
106
107
107
108
## Authenticating with GitHub
108
109
109
-
In order to index private repositories, you'll need to generate a access token and provide it to Sourcebot. GitHub provides [two types](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#types-of-personal-access-tokens) of access tokens:
110
+
In order to index private repositories, you'll need to authenticate with GitHub. Sourcebot supports the following mechanisms of authenticating a GitHub connection:
110
111
111
112
112
113
<AccordionGroup>
113
-
<Accordiontitle="Fine-grained personal access tokens"defaultOpen>
114
-
Create a new fine-grained PAT [here](https://github.com/settings/personal-access-tokens/new). First, select the resource owner and the repositories that you want Sourcebot to have access to.
115
-
116
-
Next, under "Repository permissions", select permissions `Contents` and `Metadata` with access `Read-only`. The permissions should look like the following:
117
-
118
-
Register a new [GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app#registering-a-github-app) and provide it with the following permissions:
119
+
- “Contents” repository permissions (read)
120
+
- “Metadata” repository permissions (read)
121
+
- “Members” organization permissions (read)
122
+
- “Email addresses” account permissions (read)
123
+
124
+
This can be the same GitHub App you've registered and configured as an [external identity provider](/docs/configuration/idp#github)
125
+
</Step>
126
+
<Steptitle="Install the GitHub App">
127
+
Install the GitHub App into the GitHub orgs that you want Sourcebot to be aware of. **Sourcebot will only be able to index repos from orgs with the GitHub App installed.**
128
+
</Step>
129
+
<Steptitle="Create a private key for the GitHub App">
130
+
Create a [private key](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps) for the GitHub App.
131
+
</Step>
132
+
<Steptitle="Define the GitHub App config in Sourcebot">
133
+
Create a new `apps` object in the Sourcebot [config file](/docs/configuration/config-file). The private key you created in the previous
134
+
step must be passed in as a [token](/docs/configuration/config-file#tokens).
135
+
```json wrap icon="code"
136
+
"apps": [
137
+
{
138
+
"type": "github", // must be github
139
+
"id": "1234567", // Your GitHub App ID
140
+
"privateKey": {
141
+
"env": "GITHUB_APP_PRIVATE_KEY"// Token which contains your Github App private key
142
+
}
143
+
}
144
+
]
145
+
```
146
+
</Step>
147
+
<Steptitle="You're done!">
148
+
That's it! Sourcebot will now use this GitHub App to authenticate when pulling repos for this connection.
149
+
</Step>
150
+
</Steps>
151
+
</Accordion>
152
+
<Accordiontitle="Fine-grained personal access tokens">
153
+
<Steps>
154
+
<Steptitle="Create PAT">
155
+
Create a new fine-grained PAT [here](https://github.com/settings/personal-access-tokens/new). Select the resource owner and the repositories that you want Sourcebot to have access to.
156
+
157
+
Next, under "Repository permissions", select permissions `Contents` and `Metadata` with access `Read-only`. The permissions should look like the following:
158
+
159
+
Next, provide the PAT via a [token](/docs/configuration/config-file#tokens) which is referenced in the `token` field in the [connection](/docs/connections/overview) config object.
165
+
166
+
The most common mechanism of doing this is defining an environment variable that holds the PAT:
167
+
168
+
```json
169
+
{
170
+
"type": "github",
171
+
"token": {
172
+
// note: this env var can be named anything. It
173
+
// doesn't need to be `GITHUB_TOKEN`.
174
+
"env": "GITHUB_TOKEN"
175
+
}
176
+
// .. rest of config ..
177
+
}
178
+
```
179
+
</Step>
180
+
<Steptitle="You're done!">
181
+
That's it! Sourcebot will now use this PAT to authenticate when pulling repos for this connection.
Next, provide the PAT via a [token](/docs/configuration/config-file#tokens) which is referenced in the `token` field in the [connection](/docs/connections/overview) config object.
196
+
197
+
The most common mechanism of doing this is defining an environment variable that holds the PAT:
198
+
199
+
```json
200
+
{
201
+
"type": "github",
202
+
"token": {
203
+
// note: this env var can be named anything. It
204
+
// doesn't need to be `GITHUB_TOKEN`.
205
+
"env": "GITHUB_TOKEN"
206
+
}
207
+
// .. rest of config ..
208
+
}
209
+
```
210
+
</Step>
211
+
<Steptitle="You're done!">
212
+
That's it! Sourcebot will now use this PAT to authenticate when pulling repos for this connection.
213
+
</Step>
214
+
</Steps>
128
215
</Accordion>
129
216
</AccordionGroup>
130
217
131
-
Next, provide the access token via an environment variable [token](/docs/configuration/config-file#tokens) which is referenced in the `token` property:
132
-
133
-
<Tabs>
134
-
<Tabtitle="Environment Variable">
135
-
136
-
1. Add the `token` property to your connection config:
137
-
```json
138
-
{
139
-
"type": "github",
140
-
"token": {
141
-
// note: this env var can be named anything. It
142
-
// doesn't need to be `GITHUB_TOKEN`.
143
-
"env": "GITHUB_TOKEN"
144
-
}
145
-
// .. rest of config ..
146
-
}
147
-
```
148
-
149
-
2. Pass this environment variable each time you run Sourcebot:
150
-
```bash
151
-
docker run \
152
-
-e GITHUB_TOKEN=<PAT> \
153
-
/* additional args */ \
154
-
ghcr.io/sourcebot-dev/sourcebot:latest
155
-
```
156
-
</Tab>
157
-
</Tabs>
158
-
159
218
## Connecting to a custom GitHub host
160
219
161
220
To connect to a GitHub host other than `github.com`, provide the `url` property to your config:
0 commit comments