Edit

Share via

resources.repositories.repository definition

  • Article

The repository keyword lets you specify an external repository. Use a repository resource to reference an additional repository in your pipeline.

repositories:
- repository: string # Required as first property. Alias for the repository.
  endpoint: string # ID of the service endpoint connecting to this repository.
  trigger: none | trigger | [ string ] # CI trigger for this repository, no CI trigger if skipped (only works for Azure Repos).
  name: string # repository name (format depends on 'type'; does not accept variables).
  ref: string # ref name to checkout; defaults to 'refs/heads/main'. The branch checked out by default whenever the resource trigger fires.
  type: string # Type of repository: git, github, githubenterprise, and bitbucket.

repositories:
- repository: string # Required as first property. Alias for the repository.
  endpoint: string # ID of the service endpoint connecting to this repository.
  trigger: none | trigger | [ string ] # CI trigger for this repository, no CI trigger if skipped (only works for Azure Repos).
  name: string # repository name (format depends on 'type'; does not accept variables).
  type: string # Type of repository: git, github, githubenterprise, and bitbucket.
  ref: string # ref name to checkout; defaults to 'refs/heads/main'. The branch checked out by default whenever the resource trigger fires. Does not accept variables.

repositories:
- repository: string # Required as first property. Alias for the repository.
  endpoint: string # ID of the service endpoint connecting to this repository.
  name: string # repository name (format depends on 'type'; does not accept variables).
  type: string # Type of repository: git, github, githubenterprise, and bitbucket.
  ref: string # ref name to checkout; defaults to 'refs/heads/main'. The branch checked out by default whenever the resource trigger fires. Does not accept variables.

Definitions that reference this definition: resources.repositories

Properties

repository string. Required as first property.
Alias for the specified repository. Acceptable values: [-_A-Za-z0-9]*.

endpoint string.
ID of the service endpoint connecting to this repository.

trigger trigger.
CI trigger for this repository, no CI trigger if omitted.

Important

  • Repository resource triggers are supported only for Azure Repos Git repositories.
  • Repository resource triggers don't support batch.

name string.
Repository name. Format depends on 'type'; does not accept variables.

ref string.
ref name to checkout; defaults to 'refs/heads/main'. The branch checked out by default whenever the resource trigger fires. Template expressions are supported.

ref string.
ref name to checkout; defaults to 'refs/heads/main'. The branch checked out by default whenever the resource trigger fires. Does not accept variables.

type string.
Type of repository: git, github, githubenterprise, and bitbucket.

Remarks

Important

Repository resource does not allow pipeline variables in name and ref. Wildcards are supported in triggers.

Template expressions are supported for the ref property (but not the name property). Wildcards are supported in triggers.

Important

Repository resource triggers are supported for Azure Repos Git repositories only. For more information on trigger syntax, including wildcard support for branches and tags, see trigger definition and Build Azure Repos Git or TFS Git repositories.

Important

batch is not supported in repository resource triggers.

If your pipeline has templates in another repository, you must let the system know about that repository.

If your pipeline has templates in another repository, or if you want to use multi-repo checkout with a repository that requires a service connection, you must let the system know about that repository.

Types

Pipelines support the following values for the repository type: git, github, and bitbucket. The git type refers to Azure Repos Git repos.

  • If you specify type: git, the name value refers to the name of an Azure Repos Git repository.

    • If your pipeline is in the same Azure DevOps project as the repository, for example a repository named tools, you reference it using name: tools.
    • If your pipeline is in the same Azure DevOps organization as the repository, but in a different Azure DevOps project, for example a project named ToolsProject, you must qualify the repository name with the project name: name: ToolsProject/tools.

  • If you specify type: github, the name value is the full name of the GitHub repo and includes the user or organization. An example is name: Microsoft/vscode. GitHub repos require a GitHub service connection for authorization.

  • If you specify type: bitbucket, the name value is the full name of the Bitbucket Cloud repo and includes the user or organization. An example is name: MyBitbucket/vscode. Bitbucket Cloud repos require a Bitbucket Cloud service connection for authorization.

For more information about these types, see Check out multiple repositories in your pipeline - Repository resource definition.

Variables

In each run, the metadata for a repository resource is available to all jobs in the form of runtime variables. The <Alias> is the identifier that you gave for your repository resource.

resources.repositories.<Alias>.name
resources.repositories.<Alias>.ref
resources.repositories.<Alias>.type
resources.repositories.<Alias>.id
resources.repositories.<Alias>.url
resources.repositories.<Alias>.version

The following example has a repository resource with an alias of common, and the repository resource variables are accessed using resources.repositories.common.*.

resources:
  repositories:
    - repository: common
      type: git
      ref: main
      name: Repo

variables:
  ref: $[ resources.repositories.common.ref ]
  name: $[ resources.repositories.common.name ]
  id: $[ resources.repositories.common.id ]
  type: $[ resources.repositories.common.type ]
  url: $[ resources.repositories.common.url ]
  version: $[ resources.repositories.common.version ]

steps:
- bash: |
    echo "name = $(name)"
    echo "ref = $(ref)"
    echo "id = $(id)"
    echo "type = $(type)"
    echo "url = $(url)"
    echo "version = $(version)"

Variables

In each run, the metadata for a repository resource is available to all jobs in the form of runtime variables. The <Alias> is the identifier that you gave for your repository resource.

resources.repositories.<Alias>.name
resources.repositories.<Alias>.ref
resources.repositories.<Alias>.type
resources.repositories.<Alias>.id
resources.repositories.<Alias>.url

The following example has a repository resource with an alias of common, and the repository resource variables are accessed using resources.repositories.common.*.

resources:
  repositories:
    - repository: common
      type: git
      ref: main
      name: Repo

variables:
  ref: $[ resources.repositories.common.ref ]
  name: $[ resources.repositories.common.name ]
  id: $[ resources.repositories.common.id ]
  type: $[ resources.repositories.common.type ]
  url: $[ resources.repositories.common.url ]

steps:
- bash: |
    echo "name = $(name)"
    echo "ref = $(ref)"
    echo "id = $(id)"
    echo "type = $(type)"
    echo "url = $(url)"

Examples

resources:
  repositories:
  - repository: common
    type: github
    name: Contoso/CommonTools
    endpoint: MyContosoServiceConnection

See also