Skip to content

Commit a7cdf33

Browse files
committed
Fix GitHub, site config, settings, and GitLab schema format and section positioning
- Move configuration sections to after schema blocks - Restore original simplified schema content with comments - Keep MDX warning comments intact
1 parent 2235113 commit a7cdf33

4 files changed

Lines changed: 581 additions & 588 deletions

File tree

docs/admin/code_hosts/github.mdx

Lines changed: 155 additions & 93 deletions
Original file line numberDiff line numberDiff line change
@@ -397,6 +397,161 @@ Please consult [this page](/admin/config/webhooks/incoming) in order to configur
397397

398398
GitHub connections support the following configuration options, which are specified in the JSON editor in the site admin "Manage code hosts" area.
399399

400+
<details>
401+
<summary>JSON schema</summary>
402+
403+
{/* SCHEMA_SYNC_START: admin/code_hosts/github.schema.json */}
404+
{/* WARNING: This section is auto-generated during releases. Do not edit manually. */}
405+
{/* Last updated: 2024-12-20 */}
406+
407+
```json
408+
{
409+
// 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`.
410+
"authorization": null,
411+
412+
// TLS certificate of the GitHub Enterprise instance. This is only necessary if the certificate is self-signed or signed by an internal CA. To get the certificate run `openssl s_client -connect HOST:443 -showcerts < /dev/null 2> /dev/null | openssl x509 -outform PEM`. To escape the value into a JSON string, you may want to use a tool like https://json-escape-text.now.sh.
413+
"certificate": null,
414+
// Other example values:
415+
// - "-----BEGIN CERTIFICATE-----\n..."
416+
417+
// Only used to override the cloud_default column from a config file specified by EXTSVC_CONFIG_FILE
418+
"cloudDefault": false,
419+
420+
// When set to true, this external service will be chosen as our 'Global' GitHub service. Only valid on Sourcegraph.com. Only one service can have this flag set.
421+
"cloudGlobal": false,
422+
423+
// A list of repositories to never mirror from this GitHub instance. Takes precedence over "orgs", "repos", and "repositoryQuery" configuration.
424+
//
425+
// Supports excluding by name ({"name": "owner/name"}) or by ID ({"id": "MDEwOlJlcG9zaXRvcnkxMTczMDM0Mg=="}).
426+
//
427+
// Note: ID is the GitHub GraphQL ID, not the GitHub database ID. eg: "curl https://api.github.com/repos/vuejs/vue | jq .node_id"
428+
"exclude": null,
429+
// Other example values:
430+
// - [{"forks":true}]
431+
// - [
432+
// {
433+
// "name": "owner/name"
434+
// },
435+
// {
436+
// "id": "MDEwOlJlcG9zaXRvcnkxMTczMDM0Mg=="
437+
// }
438+
// ]
439+
// - [
440+
// {
441+
// "name": "vuejs/vue"
442+
// },
443+
// {
444+
// "name": "php/php-src"
445+
// },
446+
// {
447+
// "pattern": "^topsecretorg/.*"
448+
// }
449+
// ]
450+
// - [
451+
// {
452+
// "size": "\u003e= 1GB",
453+
// "stars": "\u003c 100"
454+
// }
455+
// ]
456+
457+
// If non-null, this is a GitHub App connection with some additional properties.
458+
"gitHubAppDetails": null,
459+
460+
// The type of Git URLs to use for cloning and fetching Git repositories on this GitHub instance.
461+
//
462+
// 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).
463+
//
464+
// 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#repositories-that-need-http-s-or-ssh-authentication.
465+
"gitURLType": "http",
466+
467+
// DEPRECATED: The installation ID of the GitHub App.
468+
"githubAppInstallationID": null,
469+
470+
// Deprecated and ignored field which will be removed entirely in the next release. GitHub repositories can no longer be enabled or disabled explicitly. Configure repositories to be mirrored via "repos", "exclude" and "repositoryQuery" instead.
471+
"initialRepositoryEnablement": null,
472+
473+
// An array of organization names identifying GitHub organizations whose repositories should be mirrored on Sourcegraph.
474+
"orgs": null,
475+
// Other example values:
476+
// - ["name"]
477+
// - [
478+
// "kubernetes",
479+
// "golang",
480+
// "facebook"
481+
// ]
482+
483+
// Whether the code host connection is in a pending state.
484+
"pending": false,
485+
486+
// Rate limit applied when making background API requests to GitHub.
487+
"rateLimit": {
488+
"enabled": true,
489+
"requestsPerHour": 5000
490+
},
491+
492+
// An array of repository "owner/name" strings specifying which GitHub or GitHub Enterprise repositories to mirror on Sourcegraph.
493+
"repos": null,
494+
// Other example values:
495+
// - ["owner/name"]
496+
// - [
497+
// "kubernetes/kubernetes",
498+
// "golang/go",
499+
// "facebook/react"
500+
// ]
501+
502+
// 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").
503+
//
504+
// 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.
505+
//
506+
// 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.
507+
"repositoryPathPattern": "{host}/{nameWithOwner}",
508+
509+
// An array of strings specifying which GitHub or GitHub Enterprise repositories to mirror on Sourcegraph. The valid values are:
510+
//
511+
// - `public` mirrors all public repositories for GitHub Enterprise and is the equivalent of `none` for GitHub
512+
//
513+
// - `internal` mirrors all internal repositories for GitHub Enterprise and is the equivalent of `none` for GitHub
514+
//
515+
// - `affiliated` mirrors all repositories affiliated with the configured token's user:
516+
// - Private repositories with read access
517+
// - Public repositories owned by the user or their orgs
518+
// - Public repositories with write access
519+
//
520+
// - `none` mirrors no repositories (except those specified in the `repos` configuration property or added manually)
521+
//
522+
// - 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".
523+
//
524+
// If multiple values are provided, their results are unioned.
525+
//
526+
// 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.
527+
"repositoryQuery": [
528+
"none"
529+
],
530+
531+
// 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_host_connection/github#github-api-token-and-access for which scopes are required for which use cases.
532+
"token": null,
533+
534+
// URL of a GitHub instance, such as https://github.com or https://github-enterprise.example.com.
535+
"url": null,
536+
// Other example values:
537+
// - "https://github.com"
538+
// - "https://github-enterprise.example.com"
539+
540+
// An array of configurations defining existing GitHub webhooks that send updates back to Sourcegraph.
541+
"webhooks": null
542+
// Other example values:
543+
// - [
544+
// {
545+
// "org": "yourorgname",
546+
// "secret": "webhook-secret"
547+
// }
548+
// ]
549+
}
550+
```
551+
{/* SCHEMA_SYNC_END: admin/code_hosts/github.schema.json */}
552+
553+
</details>
554+
400555
### Configuration Notes
401556

402557
#### Repository Selection Priority
@@ -506,99 +661,6 @@ Configure appropriate rate limits for your GitHub instance:
506661
}
507662
```
508663

509-
### JSON Schema
510-
511-
{/* SCHEMA_SYNC_START: admin/code_hosts/github.schema.json */}
512-
{/* WARNING: This section is auto-generated during releases. Do not edit manually. */}
513-
{/* Last updated: Manual setup - will be automated via sourcegraph/sourcegraph releases */}
514-
515-
```json
516-
{
517-
"type": "object",
518-
"title": "GitHub configuration",
519-
"description": "Configuration for GitHub code host connections",
520-
"properties": {
521-
"url": {
522-
"type": "string",
523-
"description": "URL of your GitHub instance (https://github.com for GitHub.com)",
524-
"examples": ["https://github.com", "https://github.example.com"]
525-
},
526-
"token": {
527-
"type": "string",
528-
"description": "GitHub personal access token or GitHub App installation access token"
529-
},
530-
"repos": {
531-
"type": "array",
532-
"description": "List of repositories to sync",
533-
"items": {
534-
"type": "string",
535-
"pattern": "^[^/]+/[^/]+$"
536-
},
537-
"examples": [["kubernetes/kubernetes", "golang/go"]]
538-
},
539-
"orgs": {
540-
"type": "array",
541-
"description": "List of organizations to sync all repositories from",
542-
"items": {
543-
"type": "string"
544-
},
545-
"examples": [["kubernetes", "golang"]]
546-
},
547-
"repositoryQuery": {
548-
"type": "array",
549-
"description": "List of search queries or special values to discover repositories",
550-
"items": {
551-
"type": "string"
552-
},
553-
"examples": [["public", "affiliated", "org:sourcegraph archived:false"]]
554-
},
555-
"exclude": {
556-
"type": "array",
557-
"description": "List of repository exclusion patterns",
558-
"items": {
559-
"type": "object",
560-
"properties": {
561-
"name": {
562-
"type": "string",
563-
"description": "Repository name pattern"
564-
},
565-
"id": {
566-
"type": "string",
567-
"description": "GitHub repository ID"
568-
},
569-
"pattern": {
570-
"type": "string",
571-
"description": "Regex pattern to match repository names"
572-
}
573-
}
574-
}
575-
},
576-
"authorization": {
577-
"type": "object",
578-
"description": "Repository permissions configuration"
579-
},
580-
"gitURLType": {
581-
"type": "string",
582-
"enum": ["http", "ssh"],
583-
"default": "http",
584-
"description": "Protocol to use for Git operations"
585-
},
586-
"certificate": {
587-
"type": "string",
588-
"description": "TLS certificate for GitHub Enterprise instances with custom certificates"
589-
},
590-
"repositoryPathPattern": {
591-
"type": "string",
592-
"description": "Template for repository names in Sourcegraph",
593-
"default": "{host}/{nameWithOwner}"
594-
}
595-
},
596-
"required": ["url"],
597-
"additionalProperties": true
598-
}
599-
```
600-
{/* SCHEMA_SYNC_END: admin/code_hosts/github.schema.json */}
601-
602664
## Default branch
603665

604666
Sourcegraph displays search results from the default branch of a repository when no `revision:` [parameter](/code-search/queries#repository-revisions) is specified. If you'd like the search results to be displayed from another branch by default, you may [change a repo's default branch on the github repo settings page](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/changing-the-default-branch). If this is not an option, consider using [search contexts](/code-search/working/search_contexts) instead.

0 commit comments

Comments
 (0)