Custom repository metadata
Repositories tracked by Sourcegraph can be associated with user-provided key-value pairs. Once this metadata is added, it can be used to filter searches to the subset of matching repositories.
Metadata can be added either as key-value pairs or as tags. Key-value pairs can be searched with the filter repo:has.meta(mykey:myvalue)
. repo:has.meta(mykey)
can be used to search over repositories with a given key irrespective of its value. Tags are just key-value pairs with a null
value and can be searched with the filter repo:has.meta(mytag:)
.
Additionally, metadata can be searched with regex using slash-delimited regex literals like repo:has.meta(owner:/eng.(search|infra)/)
. This capability is particularly useful for searching against semi-structured metadata.
Examples
Repository owners
One way this feature might be used is to add the owning team of each repository as a key-value pair. For example, the repository github.com/sourcegraph/security-onboarding
repository is owned by the security team, so we could add owning-team:security
as a key-value pair on that repository.
Once those key-value pairs are added, they can be used to filter searches to only the code that is owned by a specific team with a search like repo:has.meta(owning-team:security) account creation
.
Maintenance status
Another way this could be used is to associate repos with a maintenance status. Do you have a library that is commonly used but is unmaintained, deprecated, or replaced by a better solution? You can associate these custom statuses with repository metadata. After adding this info to your repositories, you can do things like -repo:has.meta(status:deprecated)
to exclude all results from deprecated repos.
Adding metadata
There are three ways to add metadata to a repository: via web UI, Sourcegraph's GraphQL API, and the src-cli
command line tool.
NOTE: That user needs to have Repository metadata / Write
RBAC permission to be able to edit repo metadata.
Limitations
- There are no scale limits in terms of number of pairs per repo, or number of pairs globally.
- The size of a field is unbounded, but practically it's better to keep it small for performance reasons.
- There are no limits on special characters in the key-value pairs, but in practice we recommend not using special characters because the search query language doesn’t have full support for escaping arbitrary sequences, in particular
:
,(
and)
.
Web UI
Go to repository root page, hover over "Metadata" section and click on a gear icon, it will open a repository metadata editing page.
GraphQL
Metadata can be added with the addRepoMetadata
mutation, updated with the updateRepoMetadata
mutation, and deleted with the deleteRepoMetadata
mutation. You will need the GraphQL ID for the repository being targeted.
mutation AddSecurityOwner($repoID: ID!) { addRepoMetadata(repo: $repoID, key: "owning-team", value: "security") { alwaysNil } } mutation UpdateSecurityOwner($repoID: ID!) { updateRepoMetadata(repo: $repoID, key: "owning-team", value: "security++") { alwaysNil } } mutation DeleteSecurityOwner($repoID: ID!) { deleteRepoMetadata(repo: $repoID, key: "owning-team") { alwaysNil } }GRAPHQL
src-cli
Metadata can be added using src repos add-metadata
, updated using src repos update-metadata
, and deleted using src repos delete-metadata
. You will need the GraphQL ID for the repository being targeted.
$ src repos add-metadata -repo-name=repoName -key=owning-team -value=security Key-value pair 'owning-team:security' created. $ src repos update-metadata -repo-name=repoName -key=owning-team -value=security++ Value of key 'owning-team' updated to 'security++' $ src repos delete-metadata -repo-name=repoName -key=owning-team Key-value pair with key 'owning-team' deleted.TEXT