Skip to content

docs: Update code host setup steps for guided setup #2079

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
federubinstein merged 2 commits into from
Oct 13, 2026
Merged

docs: Update code host setup steps for guided setup #2079

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a168979
docs: Update code host setup steps for guided setup
federubinstein Oct 8, 2026
3a89223
Merge branch 'main' into fede/code-host-wizards
federubinstein Oct 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 16 additions & 17 deletions docs/admin/code-hosts/bitbucket-cloud.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,8 @@ To connect Bitbucket Cloud to Sourcegraph:

1. Go to **Administration > Code host connections > Add connection**.
2. Select **Bitbucket.org**.
3. Configure the connection to Bitbucket Cloud using the action buttons above the text field. Additional fields can be added using <kbd>Cmd/Ctrl+Space</kbd> for auto-completion. See the [configuration documentation below](#configuration).
4. Press **Add connection**.
3. Follow the guided setup to connect your credentials, choose repositories, and set any optional settings. For options it doesn't cover, use the **JSON config editor**. See the [configuration documentation below](#configuration).
4. Press **Create connection**.

## Repository syncing

Expand All @@ -27,24 +27,23 @@ In addition, there is one more field for configuring which repositories are mirr

## Configuration options

Bitbucket Cloud code host connections can be configured with either a username and app password combination, or with workspace access tokens.
Bitbucket Cloud code host connections can be configured with either a user API token, or with workspace access tokens.

### Username and app password
### User API token

1. Visit your [Bitbucket account settings page](https://bitbucket.org/account/settings).
2. Navigate to **App passwords**.
3. Select **Create app password**.
4. Give your app password a label.
5. Select the `Projects: Read` permission. `Repositories: Read` should automatically be selected.
6. Press **Create**.
1. Visit your [Atlassian account API tokens page](https://id.atlassian.com/manage-profile/security/api-tokens).
2. Select **Create API token with scopes**.
3. Give your API token a name and choose **Bitbucket** as the app.
4. Select the `read:user:bitbucket`, `read:workspace:bitbucket`, and `read:repository:bitbucket` scopes.
5. Press **Create**.

Use the newly created app password and your username to configure the Bitbucket Cloud connection:
Use the newly created API token and your Atlassian account email to configure the Bitbucket Cloud connection:

```json
{
"url": "https://bitbucket.org",
"username": "USERNAME",
"appPassword": "<PASSWORD>"
"username": "<ATLASSIAN_ACCOUNT_EMAIL>",
"apiToken": "<API_TOKEN>"
// ... other settings
}
```
Expand All @@ -70,7 +69,7 @@ Use the newly created access token to configure the Bitbucket Cloud connection:

### HTTPS cloning

Sourcegraph clones repositories from your Bitbucket Cloud via HTTP(S), using the [`username`](/admin/code-hosts/bitbucket-cloud#configuration) and [`appPassword`](/admin/code-hosts/bitbucket-cloud#configuration) required fields you provide in the configuration.
Sourcegraph clones repositories from your Bitbucket Cloud via HTTP(S), using the credentials you provide in the configuration.

## Rate limits

Expand All @@ -96,9 +95,9 @@ Then, add or edit a Bitbucket Cloud connection as described above and include th
```json
{
// The URL used to set up the Bitbucket Cloud authentication provider must match this URL.
"url": "https://bitbucket.com",
"username": "horsten",
"appPassword": "$APP_PASSWORD",
"url": "https://bitbucket.org",
"username": "<ATLASSIAN_ACCOUNT_EMAIL>",
"apiToken": "$API_TOKEN",
// ...
"authorization": {}
}
Expand Down
8 changes: 4 additions & 4 deletions docs/admin/code-hosts/bitbucket-server.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,10 +9,10 @@ Administrators can sync Git repositories hosted on [Bitbucket Server](https://ww

To connect Bitbucket Server / Bitbucket Data Center to Sourcegraph:

1. Go to **Administration > Manage code hosts > Add repositories**
1. Select **Bitbucket Server / Bitbucket Data Center**.
1. Configure the connection to Bitbucket Server / Bitbucket Data Center using the action buttons above the text field, and additional fields can be added using <kbd>Cmd/Ctrl+Space</kbd> for auto-completion. See the [configuration documentation below](#configuration).
1. Press **Add repositories**.
1. Go to **Administration > Code host connections > Add connection**.
1. Select **Bitbucket Server**.
1. Follow the guided setup to connect your credentials, choose repositories, and set any optional settings. For options it doesn't cover, use the **JSON config editor**. See the [configuration documentation below](#configuration).
1. Press **Create connection**.

Also consider installing the [Sourcegraph Bitbucket Server plugin](/integration/bitbucket-server#sourcegraph-bitbucket-server-plugin) which enables native code navigation for every Bitbucket user when browsing code and reviewing pull requests, allows for faster permission syncing between Sourcegraph and Bitbucket Server / Bitbucket Data Center and adds support for webhooks to Bitbucket Server / Bitbucket Data Center.

Expand Down
8 changes: 4 additions & 4 deletions docs/admin/code-hosts/github.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -208,10 +208,10 @@ in the **Advanced configuration** with your certificate(s).

To connect GitHub to Sourcegraph with an access token:

1. Go to **Administration > Manage code hosts**
2. Select **GitHub**.
3. Configure the connection to GitHub using the action buttons above the text field, and additional fields can be added using <kbd>Cmd/Ctrl+Space</kbd> for auto-completion. See the [configuration documentation below](#configuration).
4. Press **Add repositories**.
1. Go to **Administration > Code host connections > Add connection**.
2. Select **GitHub with a personal access token**.
3. Follow the guided setup to connect your token, choose repositories, and set any optional settings. For options it doesn't cover, use the **JSON config editor**. See the [configuration documentation below](#configuration).
4. Press **Create connection**.

In this example, the kubernetes public repository on GitHub is added by selecting **Add a single repository** and replacing `<owner>/<repository>` with `kubernetes/kubernetes`:

Expand Down
14 changes: 7 additions & 7 deletions docs/admin/code-hosts/gitlab.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,13 +9,13 @@ Administrators can sync Git repositories hosted on [GitLab](https://gitlab.com)

To connect GitLab to Sourcegraph:

1. Go to **Administration > Manage code hosts > Add code host**
2. Select **GitLab** (for GitLab.com) or **GitLab Self-Managed**.
3. Set **url** to the URL of your GitLab instance, such as https://gitlab.example.com or https://gitlab.com (for GitLab.com).
1. Go to **Administration > Code host connections > Add connection**.
2. Select **GitLab**.
3. Choose GitLab.com, or enter the URL of your self-managed GitLab instance, such as https://gitlab.example.com.
4. Create a GitLab access token using these [instructions](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#creating-a-personal-access-token) with the `read_api` and `read_repository` scopes, and set it to be the value of the token.
5. Use the [Repository syncing documentation below](#repository-syncing) to select and add your preferred projects/repos to the configuration.
6. You can use the action buttons above the text field to add the fields, and additional fields can be added using `Cmd/Ctrl+Space` for auto-completion. See the [configuration documentation below](#configuration) for additional fields.
7. Click **Add repositories**.
5. Choose the projects to sync. See the [Repository syncing documentation below](#repository-syncing).
6. For options the guided setup doesn't cover, use the **JSON config editor**. See the [configuration documentation below](#configuration).
7. Click **Create connection**.

Example config:

Expand Down Expand Up @@ -318,7 +318,7 @@ The Sourcegraph instance's administrator must [update the `corsOrigin` advanced

## Access token scopes

Sourcegraph requires an access token with `api` permissions (and `sudo`, if you are using the `username` identity provider type). These permissions are required for the following reasons:
Sourcegraph requires an access token with the `read_api` and `read_repository` scopes (or `api` and `sudo` from a GitLab administrator, if you are using the `username` identity provider type). These permissions are required for the following reasons:

| Request Type | Required GitLab scope | Sourcegraph usage |
| ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
Expand Down
Loading