"
{
"message": "Rate limiting is not enabled.",
"documentation_url": "https://docs.github.com/enterprise/3.3/rest/reference/rate-limit#get-rate-limit-status-for-the-authenticated-user"
}
```
### Internal rate limits
See [Internal rate limits](/admin/code-hosts/rate-limits#internal-rate-limits).
## Repository permissions
Prerequisite for configuring repository permission syncing: [Add GitHub as an authentication provider](/admin/auth/#github).
> NOTE: If your GitHub organization enforces SAML SSO, consider configuring [`requiredSsoOrgs`](/admin/auth/#requiredssoOrgs) in your GitHub auth provider to ensure users properly authorize the OAuth application during sign-in. This helps prevent permissions syncing issues caused by tokens that lack SSO authorization.
Then, add or edit the GitHub connection as described above and include the `authorization` field:
```json
{
// ...
"authorization": {}
}
```
This needs to be done for every GitHub code host connection if there is more than one configured.
Repo-centric permission syncing is done by calling the [list repository collaborators GitHub API endpoint](https://docs.github.com/en/rest/collaborators/collaborators#list-repository-collaborators). To call this API endpoint correctly, we need a [GitHub access token](#github-api-access) with the required scopes and read and write access to all relevant repositories.
> IMPORTANT: We strongly recommend configuring both read and write access to associated repositories for permission syncing due to GitHub's token scope requirements. Without write access, there will be a conflict between [user-centric sync](/admin/permissions/syncing#troubleshooting) and repo-centric sync. In that case, [disable repo-centric permission sync](/admin/permissions/syncing#disable-repo-centric-permission-sync) (supported in Sourcegraph 5.0.4+).
> IMPORTANT: Optional, but strongly recommended - [continue with configuring webhooks for permissions](/admin/webhooks/incoming#user-permissions).
> NOTE: It can take some time to complete full cycle of repository permissions sync if you have a large number of users or repositories. [See sync duration time](/admin/permissions/syncing#sync-duration) for more information.
### Internal repositories
GitHub Enterprise has internal repositories in addition to the usual public and private repositories. Depending on how your organization structure is configured, you may want to make these internal repositories available to everyone on your Sourcegraph instance without relying on permission syncs. To mark all internal repositories as public, add the following field to the `authorization` field:
```json
{
// ...
"authorization": {
"markInternalReposAsPublic": true
}
}
```
If you would like internal repositories to remain private, but you're experiencing issues where user permission syncs aren't granting access to internal repositories, you can add the following field instead:
```json
{
// ...
"authorization": {
"syncInternalRepoPermissions": true
}
}
```
> NOTE: An explanation on repository visibility options in GitHub Enterprise. `public`- Only index public GitHub Enterprise repositories visible to all users. This excludes private and internal repos. `private` - Index both public and private GitHub Enterprise repositories. This allows accessing private repos the token has access to. `internal` - Include GitHub Enterprise internal repositories in addition to public/private repos. Internal repos are only visible to org members.
### Trigger permissions sync from GitHub webhooks
Follow the link to [configure webhooks for permissions for GitHub](/admin/webhooks/incoming#user-permissions)
### Teams and organizations permissions caching
> NOTE: This is an experimental feature.
> WARNING: The following section is experimental and might not work properly. Please prefer [configuring webhooks for permissions instead](/admin/webhooks/incoming#user-permissions)
GitHub code host can leverage caching mechanisms to reduce the number of API calls used when syncing permissions. This can significantly reduce the amount of time it takes to perform a full cycle of permissions sync due to reduced instances of being rate limited by the code host, and is useful for code hosts with very large numbers of users and repositories.
Sourcegraph can leverage caching of GitHub [team](https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/managing-team-access-to-an-organization-repository) and [organization](https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/repository-permission-levels-for-an-organization) permissions.
> NOTE: You should only try this if your GitHub setup makes extensive use of GitHub teams and organizations to distribute access to repositories and your number of `users * avg_repositories` is greater than 250,000 (which roughly corresponds to the scale at which [GitHub rate limits might become an issue](/admin/permissions/syncing#sync-duration)).
> {/* */}
This caching behaviour can be enabled via the `authorization.groupsCacheTTL` field:
```json
{
"url": "https://github.example.com",
"token": "$PERSONAL_ACCESS_TOKEN",
"authorization": {
"groupsCacheTTL": 72 // hours
}
}
```
In the corresponding [authorization provider](/admin/auth/#github) in [advanced configuration](/admin/config/site-config), the `allowGroupsPermissionsSync` field must be set as well for the correct auth scopes to be requested from users:
```json
{
// ...
"auth.providers": [
{
"type": "github",
"url": "https://github.example.com",
"allowGroupsPermissionsSync": true
}
]
}
```
A [token that has the required scopes](#github-api-access) and both read and write access to all relevant repositories and organizations is needed to fetch repository permissions and team memberships.
Read-only access will _not_ work with cached permissions sync, but will work with careful configuration for [regular GitHub permissions sync](#repository-permissions).
When enabling this feature, we currently recommend a default `groupsCacheTTL` of `72` (hours, or 3 days). A lower value can be set if your teams and organizations change frequently, though the chosen value must be at least several hours for the cache to be leveraged in the event of being rate-limited (which takes [an hour to recover from](https://docs.github.com/en/rest/overview/resources-in-the-rest-api#rate-limiting)).
Cache invalidation happens automatically on certain webhook events, so it is recommended to configure webhook support when using cached permissions sync.
Caches can also be [manually invalidated](#manually-invalidate-caches) if necessary.
#### Manually invalidate caches
To force a bypass of caches during a sync, you can manually queue users or repositories for sync with the `invalidateCaches` options via the Sourcegraph GraphQL API:
```gql
mutation {
scheduleUserPermissionsSync(
user: "userid"
options: {invalidateCaches: true}
) {
alwaysNil
}
}
```
## User authentication
To configure GitHub as an authentication provider (which will enable sign-in via GitHub), see the
[authentication documentation](/admin/auth/#github).
## Webhooks
Using the `webhooks` property on the external service has been deprecated.
Please consult [this page](/admin/webhooks/incoming) in order to configure webhooks.
## Configuration
GitHub connections support the following configuration options, which are specified in the JSON editor in the Administration "Manage code hosts" area.
{/* [View page on our docs](/admin/code-hosts/github) to see rendered content.
*/}
### admin/code_hosts/github.schema.json
{/* SCHEMA_SYNC_START: admin/code_hosts/github.schema.json */}
{/* WARNING: This section is auto-generated during releases. Do not edit manually. */}
```json
// Authentication alternatives: token OR gitHubAppDetails OR externalAccount OR useRandomExternalAccount
{
// If non-null, enforces GitHub repository permissions. This requires that there is an item in the [site configuration json](https://sourcegraph.com/docs/admin/config/site_config#auth-providers) `auth.providers` field, of type "github" with the same `url` field as specified in this `GitHubConnection`.
"authorization": {
"groupsCacheTTL": -1,
"markInternalReposAsPublic": false,
"syncInternalRepoPermissions": false
},
// ⚠️ DEPRECATED: DEPRECATED: Use the tls.external setting in site config
// DEPRECATED: Use the tls.external setting in site config
// Other example values:
// - "-----BEGIN CERTIFICATE-----\n..."
"certificate": null,
// A list of repository entries that define which repositories to never mirror from this GitHub instance. Takes precedence over "orgs", "repos", and "repositoryQuery" configuration.
// Each entry in the list can be either a name ({"name": "owner/name"}), an ID ({"id": "MDEwOlJlcG9zaXRvcnkxMTczMDM0Mg=="}), or a set of conditions like pattern, size, stars, etc. If multiple conditions are specified within a single entry, ALL of those conditions must be met for a repository to be excluded (AND). If multiple entries exist in the exclude list, a repository matching ANY of the entries (OR) will be excluded from syncing.
// Note: ID is the GitHub GraphQL ID, not the GitHub database ID. eg: "curl https://api.github.com/repos/vuejs/vue | jq .node_id"
// Other example values:
// - [
// {
// "forks": true
// }
// ]
// - [
// {
// "name": "owner/name"
// },
// {
// "id": "MDEwOlJlcG9zaXRvcnkxMTczMDM0Mg=="
// }
// ]
// - [
// {
// "name": "vuejs/vue"
// },
// {
// "name": "php/php-src"
// },
// {
// "pattern": "^topsecretorg/.*"
// }
// ]
// - [
// {
// "size": "\u003e= 1GB",
// "stars": "\u003c 100"
// }
// ]
"exclude": null,
// GitHub external account to use for authentication.
"externalAccount": {
"accountID": null,
"clientID": null
},
// If non-null, this is a GitHub App connection with some additional properties.
"gitHubAppDetails": {
"appID": 0,
"baseURL": null,
"cloneAllRepositories": false,
"installationID": 0
},
// SSH cipher to use when cloning via SSH. Must be a valid choice from `ssh -Q cipher`.
"gitSSHCipher": null,
// SSH keys to use when cloning Git repo.
"gitSSHCredential": null,
// The type of Git URLs to use for cloning and fetching Git repositories on this GitHub instance.
// If "http", Sourcegraph will access GitHub repositories using Git URLs of the form http(s)://github.com/myteam/myproject.git (using https: if the GitHub instance uses HTTPS).
// If "ssh", Sourcegraph will access GitHub repositories using Git URLs of the form git@github.com:myteam/myproject.git. See the documentation for how to provide SSH private keys and known_hosts: https://sourcegraph.com/docs/admin/repo/auth.
// Valid options: "http", "ssh"
"gitURLType": "http",
// The maximum number of repos that will be deleted per sync. A value of 0 or less indicates no maximum.
"maxDeletions": 0,
// An array of organization names identifying GitHub organizations whose repositories should be mirrored on Sourcegraph.
// Other example values:
// - [
// "name"
// ]
// - [
// "kubernetes",
// "golang",
// "facebook"
// ]
"orgs": null,
// Rate limit applied when making background API requests to GitHub.
"rateLimit": {
"enabled": true,
"requestsPerHour": 5000
},
// An array of repository "owner/name" strings specifying which GitHub or GitHub Enterprise repositories to mirror on Sourcegraph.
// Other example values:
// - [
// "owner/name"
// ]
// - [
// "kubernetes/kubernetes",
// "golang/go",
// "facebook/react"
// ]
"repos": null,
// The pattern used to generate the corresponding Sourcegraph repository name for a GitHub or GitHub Enterprise repository. In the pattern, the variable "{host}" is replaced with the GitHub host (such as github.example.com), and "{nameWithOwner}" is replaced with the GitHub repository's "owner/path" (such as "myorg/myrepo").
// For example, if your GitHub Enterprise URL is https://github.example.com and your Sourcegraph URL is https://src.example.com, then a repositoryPathPattern of "{host}/{nameWithOwner}" would mean that a GitHub repository at https://github.example.com/myorg/myrepo is available on Sourcegraph at https://src.example.com/github.example.com/myorg/myrepo.
// It is important that the Sourcegraph repository name generated with this pattern be unique to this code host. If different code hosts generate repository names that collide, Sourcegraph's behavior is undefined.
"repositoryPathPattern": "{host}/{nameWithOwner}",
// An array of strings specifying which GitHub or GitHub Enterprise repositories to mirror on Sourcegraph. The valid values are:
// - `public` mirrors all public repositories for GitHub Enterprise and is the equivalent of `none` for GitHub
// - `internal` mirrors all internal repositories for GitHub Enterprise and is the equivalent of `none` for GitHub
// - `affiliated` mirrors all repositories affiliated with the configured token's user:
// - Private repositories with read access
// - Public repositories owned by the user or their orgs
// - Public repositories with write access
// - `none` mirrors no repositories (except those specified in the `repos` configuration property or added manually)
// - All other values are executed as a GitHub advanced repository search as described at https://github.com/search/advanced. Example: to sync all repositories from the "sourcegraph" organization including forks the query would be "org:sourcegraph fork:true".
// If multiple values are provided, their results are unioned.
// If you need to narrow the set of mirrored repositories further (and don't want to enumerate it with a list or query set as above), create a new bot/machine user on GitHub or GitHub Enterprise that is only affiliated with the desired repositories.
"repositoryQuery": [
"none"
],
// A GitHub personal access token. Create one for GitHub.com at https://github.com/settings/tokens/new?description=Sourcegraph (for GitHub Enterprise, replace github.com with your instance's hostname). See https://sourcegraph.com/docs/admin/code_hosts/github#github-api-access for which scopes are required for which use cases.
"token": null,
// REQUIRED:
// URL of a GitHub instance, such as https://github.com or https://github-enterprise.example.com.
// Other example values:
// - "https://github.com"
// - "https://github-enterprise.example.com"
"url": null,
// Use a random user external account for authentication. When set, the code host connection will only be able to add public repositories.
"useRandomExternalAccount": false,
// ⚠️ DEPRECATED: DEPRECATED: See https://sourcegraph.com/docs/admin/config/webhooks/incoming#deprecation-notice
// An array of configurations defining existing GitHub webhooks that send updates back to Sourcegraph.
// Other example values:
// - [
// {
// "org": "yourorgname",
// "secret": "webhook-secret"
// }
// ]
"webhooks": null
}
```
{/* SCHEMA_SYNC_END: admin/code_hosts/github.schema.json */}