Linking code from Azure Devops Server

If you’re not familiar with Sourcebot connections, please read that overview first.

Examples

Enable TFS path support

This is required if you’re using an older version of ADO Server which has /tfs in the repo paths.

{
    "type": "azuredevops",
    "useTfsPath": true
    "repos": [
        "organizationName/projectName/repoName",
        "organizationName/projectName/repoName2
    ]
}   

Sync individual repos

{
    "type": "azuredevops",
    "repos": [
        "organizationName/projectName/repoName",
        "organizationName/projectName/repoName2
    ]
}

Sync all repos in a collection

{
    "type": "azuredevops",
    "orgs": [
        "collectionName",
        "collectionName2"
    ]
}

Sync all repos in a project

{
    "type": "azuredevops",
    "projects": [
        "collectionName/projectName",
        "collectionName/projectName2"
    ]
}

Exclude repos from syncing

{
    "type": "azuredevops",
    // Include all repos in my-org...
    "orgs": [
        "my-org"
    ],
    // ...except:
    "exclude": {
        // repos that are disabled 
        "disabled": true,
        // repos that match these glob patterns
        "repos": [
            "reposToExclude*"
        ],
        // projects that match these glob patterns
        "projects": [
            "projectstoExclude*"
        ]
        // repos less than the defined min OR larger than the defined max
        "size": {
            // repos that are less than 1MB (in bytes)...
            "min": 1048576,
            // or repos greater than 100MB (in bytes)
            "max": 104857600 
        }
    }
}

Authenticating with Azure Devops Server

Azure Devops Server requires you to provide a PAT in order to index your repositories. To learn how to create PAT, check out the Azure Devops docs. Sourcebot needs the Read access for the Code scope in order to find and clone your repos.

Next, provide the access token via the token property, either as an environment variable or a secret:

Environment Variable

1. Add the token property to your connection config:

{
    "type": "azuredevops",
    "token": {
        // note: this env var can be named anything. It
        // doesn't need to be `ADO_TOKEN`.
        "env": "ADO_TOKEN"
    }
    // .. rest of config ..
}

2. Pass this environment variable each time you run Sourcebot:

docker run \
    -e ADO_TOKEN=<PAT> \
    /* additional args */ \
    ghcr.io/sourcebot-dev/sourcebot:latest

Schema reference

Reference

schemas/v3/azuredevops.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "title": "AzureDevOpsConnectionConfig",
  "properties": {
    "type": {
      "const": "azuredevops",
      "description": "Azure DevOps Configuration"
    },
    "token": {
      "description": "A Personal Access Token (PAT).",
      "examples": [
        {
          "secret": "SECRET_KEY"
        }
      ],
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "secret": {
              "type": "string",
              "description": "The name of the secret that contains the token."
            }
          },
          "required": [
            "secret"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "env": {
              "type": "string",
              "description": "The name of the environment variable that contains the token. Only supported in declarative connection configs."
            }
          },
          "required": [
            "env"
          ],
          "additionalProperties": false
        }
      ]
    },
    "url": {
      "type": "string",
      "format": "url",
      "default": "https://dev.azure.com",
      "description": "The URL of the Azure DevOps host. For Azure DevOps Cloud, use https://dev.azure.com. For Azure DevOps Server, use your server URL.",
      "examples": [
        "https://dev.azure.com",
        "https://azuredevops.example.com"
      ],
      "pattern": "^https?:\\/\\/[^\\s/$.?#].[^\\s]*$"
    },
    "deploymentType": {
      "type": "string",
      "enum": [
        "cloud",
        "server"
      ],
      "default": "cloud",
      "description": "The type of Azure DevOps deployment"
    },
    "useTfsPath": {
      "type": "boolean",
      "default": false,
      "description": "Use legacy TFS path format (/tfs) in API URLs. Required for older TFS installations (TFS 2018 and earlier). When true, API URLs will include /tfs in the path (e.g., https://server/tfs/collection/_apis/...)."
    },
    "orgs": {
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[\\w.-]+$"
      },
      "default": [],
      "examples": [
        [
          "my-org"
        ]
      ],
      "description": "List of organizations to sync with. For Cloud, this is the organization name. For Server, this is the collection name. All projects and repositories visible to the provided `token` will be synced, unless explicitly defined in the `exclude` property."
    },
    "projects": {
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[\\w.-]+\\/[\\w.-]+$"
      },
      "default": [],
      "examples": [
        [
          "my-org/my-project",
          "my-collection/my-project"
        ]
      ],
      "description": "List of specific projects to sync with. Expected to be formatted as '{orgName}/{projectName}' for Cloud or '{collectionName}/{projectName}' for Server."
    },
    "repos": {
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[\\w.-]+\\/[\\w.-]+\\/[\\w.-]+$"
      },
      "default": [],
      "examples": [
        [
          "my-org/my-project/my-repo"
        ]
      ],
      "description": "List of individual repositories to sync with. Expected to be formatted as '{orgName}/{projectName}/{repoName}'."
    },
    "exclude": {
      "type": "object",
      "properties": {
        "disabled": {
          "type": "boolean",
          "default": false,
          "description": "Exclude disabled repositories from syncing."
        },
        "repos": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "default": [],
          "description": "List of repositories to exclude from syncing. Glob patterns are supported."
        },
        "projects": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "default": [],
          "description": "List of projects to exclude from syncing. Glob patterns are supported."
        },
        "size": {
          "type": "object",
          "description": "Exclude repositories based on their size.",
          "properties": {
            "min": {
              "type": "integer",
              "description": "Minimum repository size (in bytes) to sync (inclusive). Repositories less than this size will be excluded from syncing."
            },
            "max": {
              "type": "integer",
              "description": "Maximum repository size (in bytes) to sync (inclusive). Repositories greater than this size will be excluded from syncing."
            }
          },
          "additionalProperties": false
        }
      },
      "additionalProperties": false
    },
    "revisions": {
      "type": "object",
      "description": "The revisions (branches, tags) that should be included when indexing. The default branch (HEAD) is always indexed. A maximum of 64 revisions can be indexed, with any additional revisions being ignored.",
      "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. A maximum of 64 branches can be indexed, with any additional branches being ignored.",
          "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. A maximum of 64 tags can be indexed, with any additional tags being ignored.",
          "items": {
            "type": "string"
          },
          "examples": [
            [
              "latest",
              "v2.*.*"
            ],
            [
              "**"
            ]
          ],
          "default": []
        }
      },
      "additionalProperties": false
    }
  },
  "required": [
    "type",
    "token"
  ],
  "additionalProperties": false
}