sourcebot/schemas/v2/index.json

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "title": "Sourcebot configuration schema",
    "description": "A Sourcebot configuration file outlines which repositories Sourcebot should sync and index.",
    "definitions": {
        "Token": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "object",
                    "properties": {
                        "env": {
                            "type": "string",
                            "description": "The name of the environment variable that contains the token."
                        }
                    },
                    "required": [
                        "env"
                    ],
                    "additionalProperties": false
                }
            ]
        },
        "GitRevisions": {
            "type": "object",
            "description": "The revisions (branches, tags) that should be included when indexing. The default branch (HEAD) is always indexed.",
            "properties": {
                "branches": {
                    "type": "array",
                    "description": "List of branches to include when indexing. For a given repo, only the branches that exist on the repo's remote *and* match at least one of the provided `branches` will be indexed. The default branch (HEAD) is always indexed. Glob patterns are supported.",
                    "items": {
                        "type": "string"
                    },
                    "examples": [
                        [
                            "main",
                            "release/*"
                        ],
                        [
                            "**"
                        ]
                    ],
                    "default": []
                },
                "tags": {
                    "type": "array",
                    "description": "List of tags to include when indexing. For a given repo, only the tags that exist on the repo's remote *and* match at least one of the provided `tags` will be indexed. Glob patterns are supported.",
                    "items": {
                        "type": "string"
                    },
                    "examples": [
                        [
                            "latest",
                            "v2.*.*"
                        ],
                        [
                            "**"
                        ]
                    ],
                    "default": []
                }
            },
            "additionalProperties": false
        },
        "GitHubConfig": {
            "type": "object",
            "properties": {
                "type": {
                    "const": "github",
                    "description": "GitHub Configuration"
                },
                "token": {
                    "$ref": "#/definitions/Token",
                    "description": "A Personal Access Token (PAT).",
                    "examples": [
                        "secret-token",
                        { "env": "ENV_VAR_CONTAINING_TOKEN" }
                    ]
                },
                "url": {
                    "type": "string",
                    "format": "url",
                    "default": "https://github.com",
                    "description": "The URL of the GitHub host. Defaults to https://github.com",
                    "examples": [
                        "https://github.com",
                        "https://github.example.com"
                    ],
                    "pattern": "^https?:\\/\\/[^\\s/$.?#].[^\\s]*$"
                },
                "users": {
                    "type": "array",
                    "items": {
                        "type": "string",
                        "pattern": "^[\\w.-]+$"
                    },
                    "examples": [
                        [
                            "torvalds",
                            "DHH"
                        ]
                    ],
                    "description": "List of users to sync with. All repositories that the user owns will be synced, unless explicitly defined in the `exclude` property."
                },
                "orgs": {
                    "type": "array",
                    "items": {
                        "type": "string",
                        "pattern": "^[\\w.-]+$"
                    },
                    "examples": [
                        [
                            "my-org-name"
                        ],
                        [
                            "sourcebot-dev",
                            "commaai"
                        ]
                    ],
                    "description": "List of organizations to sync with. All repositories in the organization visible to the provided `token` (if any) will be synced, unless explicitly defined in the `exclude` property."
                },
                "repos": {
                    "type": "array",
                    "items": {
                        "type": "string",
                        "pattern": "^[\\w.-]+\\/[\\w.-]+$"
                    },
                    "description": "List of individual repositories to sync with. Expected to be formatted as '{orgName}/{repoName}' or '{userName}/{repoName}'."
                },
                "exclude": {
                    "type": "object",
                    "properties": {
                        "forks": {
                            "type": "boolean",
                            "default": false,
                            "description": "Exlcude forked repositories from syncing."
                        },
                        "archived": {
                            "type": "boolean",
                            "default": false,
                            "description": "Exlcude archived repositories from syncing."
                        },
                        "repos": {
                            "type": "array",
                            "items": {
                                "type": "string",
                                "pattern": "^[\\w.-]+\\/[\\w.-]+$"
                            },
                            "default": [],
                            "description": "List of individual repositories to exclude from syncing. Expected to be formatted as '{orgName}/{repoName}' or '{userName}/{repoName}'."
                        }
                    },
                    "additionalProperties": false
                },
                "revisions": {
                    "$ref": "#/definitions/GitRevisions"
                }
            },
            "required": [
                "type"
            ],
            "additionalProperties": false
        },
        "GitLabConfig": {
            "type": "object",
            "properties": {
                "type": {
                    "const": "gitlab",
                    "description": "GitLab Configuration"
                },
                "token": {
                    "$ref": "#/definitions/Token",
                    "description": "An authentication token.",
                    "examples": [
                        "secret-token",
                        { "env": "ENV_VAR_CONTAINING_TOKEN" }
                    ]
                },
                "url": {
                    "type": "string",
                    "format": "url",
                    "default": "https://gitlab.com",
                    "description": "The URL of the GitLab host. Defaults to https://gitlab.com",
                    "examples": [
                        "https://gitlab.com",
                        "https://gitlab.example.com"
                    ],
                    "pattern": "^https?:\\/\\/[^\\s/$.?#].[^\\s]*$"
                },
                "users": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "description": "List of users to sync with. All projects owned by the user and visible to the provided `token` (if any) will be synced, unless explicitly defined in the `exclude` property."
                },
                "groups": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "examples": [
                        ["my-group"],
                        [
                            "my-group/sub-group-a",
                            "my-group/sub-group-b"
                        ]
                    ],
                    "description": "List of groups to sync with. All projects in the group (and recursive subgroups) visible to the provided `token` (if any) will be synced, unless explicitly defined in the `exclude` property. Subgroups can be specified by providing the path to the subgroup (e.g. `my-group/sub-group-a`)."
                },
                "projects": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "examples": [
                        ["my-group/my-project"],
                        ["my-group/my-sub-group/my-project"]
                    ],
                    "description": "List of individual projects to sync with. The project's namespace must be specified. See: https://docs.gitlab.com/ee/user/namespace/"
                },
                "exclude": {
                    "type": "object",
                    "properties": {
                        "forks": {
                            "type": "boolean",
                            "default": false,
                            "description": "Exlcude forked projects from syncing."
                        },
                        "archived": {
                            "type": "boolean",
                            "default": false,
                            "description": "Exlcude archived projects from syncing."
                        },
                        "projects": {
                            "type": "array",
                            "items": {
                                "type": "string",
                                "pattern": "^[\\w.-]+\\/[\\w.-]+$"
                            },
                            "default": [],
                            "examples": [
                                [
                                    "my-group/my-project"
                                ]
                            ],
                            "description": "List of individual projects to exclude from syncing. The project's namespace must be specified. See: https://docs.gitlab.com/ee/user/namespace/"
                        }
                    },
                    "additionalProperties": false
                },
                "revisions": {
                    "$ref": "#/definitions/GitRevisions"
                }
            },
            "required": [
                "type"
            ],
            "additionalProperties": false
        },
        "GiteaConfig": {
            "type": "object",
            "properties": {
                "type": {
                    "const": "gitea",
                    "description": "Gitea Configuration"
                },
                "token": {
                    "$ref": "#/definitions/Token",
                    "description": "An access token.",
                    "examples": [
                        "secret-token",
                        { "env": "ENV_VAR_CONTAINING_TOKEN" }
                    ]
                },
                "url": {
                    "type": "string",
                    "format": "url",
                    "default": "https://gitea.com",
                    "description": "The URL of the Gitea host. Defaults to https://gitea.com",
                    "examples": [
                        "https://gitea.com",
                        "https://gitea.example.com"
                    ],
                    "pattern": "^https?:\\/\\/[^\\s/$.?#].[^\\s]*$"
                },
                "orgs": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "examples": [
                        [
                            "my-org-name"
                        ]
                    ],
                    "description": "List of organizations to sync with. All repositories in the organization visible to the provided `token` (if any) will be synced, unless explicitly defined in the `exclude` property. If a `token` is provided, it must have the read:organization scope."
                },
                "repos": {
                    "type": "array",
                    "items": {
                        "type": "string",
                        "pattern": "^[\\w.-]+\\/[\\w.-]+$"
                    },
                    "description": "List of individual repositories to sync with. Expected to be formatted as '{orgName}/{repoName}' or '{userName}/{repoName}'."
                },
                "users": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "examples": [
                        [
                            "username-1",
                            "username-2"
                        ]
                    ],
                    "description": "List of users to sync with. All repositories that the user owns will be synced, unless explicitly defined in the `exclude` property. If a `token` is provided, it must have the read:user scope."
                },
                "exclude": {
                    "type": "object",
                    "properties": {
                        "forks": {
                            "type": "boolean",
                            "default": false,
                            "description": "Exlcude forked repositories from syncing."
                        },
                        "archived": {
                            "type": "boolean",
                            "default": false,
                            "description": "Exlcude archived repositories from syncing."
                        },
                        "repos": {
                            "type": "array",
                            "items": {
                                "type": "string",
                                "pattern": "^[\\w.-]+\\/[\\w.-]+$"
                            },
                            "default": [],
                            "description": "List of individual repositories to exclude from syncing. Expected to be formatted as '{orgName}/{repoName}' or '{userName}/{repoName}'."
                        }
                    },
                    "additionalProperties": false
                },
                "revisions": {
                    "$ref": "#/definitions/GitRevisions"
                }
            },
            "required": [
                "type"
            ],
            "additionalProperties": false
        },
        "LocalConfig": {
            "type": "object",
            "properties": {
                "type": {
                    "const": "local",
                    "description": "Local Configuration"
                },
                "path": {
                    "type": "string",
                    "description": "Path to the local directory to sync with. Relative paths are relative to the configuration file's directory.",
                    "pattern": ".+"
                },
                "watch": {
                    "type": "boolean",
                    "default": true,
                    "description": "Enables a file watcher that will automatically re-sync when changes are made within `path` (recursively). Defaults to true."
                },
                "exclude": {
                    "type": "object",
                    "properties": {
                        "paths": {
                            "type": "array",
                            "items": {
                                "type": "string",
                                "pattern": ".+"
                            },
                            "description": "List of paths relative to the provided `path` to exclude from the index. .git, .hg, and .svn are always exluded.",
                            "default": [],
                            "examples": [
                                [
                                    "node_modules",
                                    "bin",
                                    "dist",
                                    "build",
                                    "out"
                                ]
                            ]
                        }
                    },
                    "additionalProperties": false
                }
            },
            "required": [
                "type",
                "path"
            ],
            "additionalProperties": false
        },
        "Repos": {
            "anyOf": [
                {
                    "$ref": "#/definitions/GitHubConfig"
                },
                {
                    "$ref": "#/definitions/GitLabConfig"
                },
                {
                    "$ref": "#/definitions/GiteaConfig"
                },
                {
                    "$ref": "#/definitions/LocalConfig"
                }
            ]
        }
    },
    "properties": {
        "$schema": {
            "type": "string"
        },
        "repos": {
            "type": "array",
            "description": "Defines a collection of repositories from varying code hosts that Sourcebot should sync with.",
            "items": {
                "$ref": "#/definitions/Repos"
            }
        }
    },
    "additionalProperties": false
}