adopr

Documentation

Overview

Package adopr fetches the lockfile changes of an Azure DevOps pull request (or comparison / commit) via the REST API, so it can be vetted without cloning the repository. dev.azure.com, *.visualstudio.com and self-hosted Azure DevOps Server instances all work — the /_git/ URL shape is unique to Azure DevOps, so any host is recognised.

Index

• Variables
• func Fetch(ref Ref, isLockfile func(path string) bool) (*ghpr.Result, error)
• func FetchCompare(ref CmpRef, isLockfile func(path string) bool) (*ghpr.Result, error)
• func HasToken() bool
• func ParseCommit(s string) (instance, project, repo, sha string, ok bool)
• func PostComment(ref Ref, body string) (commentURL string, updated bool, err error)
• type CmpRef
  • func ParseCompare(s string) (CmpRef, bool)
  • func ResolveCommit(instance, project, repo, sha string) (CmpRef, error)
  • func (r CmpRef) String() string
• type QueueItem
  • func ListQueue(instance, project, repo string, authors []string, limit int) ([]QueueItem, string, error)
• type Ref
  • func Parse(s string) (Ref, bool)
  • func (r Ref) String() string

Variables

var DefaultQueueAuthors = []string{"dependabot", "renovate"}

DefaultQueueAuthors are the bot identities looked for when the user doesn't pass -author. Azure DevOps has no canonical bot account — the Dependabot extension and self-hosted Renovate post as whatever identity they're given — so author specs match display names loosely: "renovate" finds "Renovate Bot".

Functions

func Fetch

func Fetch(ref Ref, isLockfile func(path string) bool) (*ghpr.Result, error)

Fetch downloads the PR metadata and the before/after contents of every changed file isLockfile accepts. It authenticates with AZURE_DEVOPS_TOKEN / AZURE_DEVOPS_EXT_PAT (a personal access token) or SYSTEM_ACCESSTOKEN (Azure Pipelines) when set, and works unauthenticated on public projects.

func FetchCompare

func FetchCompare(ref CmpRef, isLockfile func(path string) bool) (*ghpr.Result, error)

FetchCompare downloads the file changes between two revisions (merge-base semantics, like a PR diff) and returns the before/after contents of every changed file isLockfile accepts.

func HasToken

func HasToken() bool

HasToken reports whether an Azure DevOps token is configured in the environment.

func ParseCommit

func ParseCommit(s string) (instance, project, repo, sha string, ok bool)

ParseCommit recognises an Azure DevOps commit URL:

https://dev.azure.com/ORG/PROJECT/_git/REPO/commit/SHA

func PostComment

func PostComment(ref Ref, body string) (commentURL string, updated bool, err error)

PostComment creates — or, if a lockvet comment already exists, updates — the report comment thread on a pull request. The thread is created with status "closed" so branch policies that require comment resolution are never blocked by a report. Returns the PR's web URL and whether an existing comment was updated. Requires a token that can contribute to pull requests (AZURE_DEVOPS_TOKEN with Code: Read & Write, or Azure Pipelines' SYSTEM_ACCESSTOKEN).

Types

type CmpRef

type CmpRef struct {
	Instance string
	Project  string
	Repo     string
	Base     string
	BaseType string
	Head     string
	HeadType string
}

CmpRef identifies a comparison between two revisions of an Azure DevOps repository. Base and Head follow lockvet's usual meaning: the diff explains how Head differs from Base (merge-base semantics, like a PR). BaseType / HeadType are "branch", "commit" or "tag".

func ParseCompare

func ParseCompare(s string) (CmpRef, bool)

ParseCompare recognises an Azure DevOps branch-compare URL:

https://dev.azure.com/ORG/PROJECT/_git/REPO/branchCompare?baseVersion=GBmain&targetVersion=GBfeature

The GB / GC / GT prefixes Azure DevOps puts on the two versions select branch, commit and tag respectively.

func ResolveCommit

func ResolveCommit(instance, project, repo, sha string) (CmpRef, error)

ResolveCommit turns a commit URL's parts into the CmpRef parent...sha, so a single commit can be vetted with FetchCompare.

func (CmpRef) String

func (r CmpRef) String() string

type QueueItem

type QueueItem struct {
	Ref     Ref
	Title   string
	Author  string
	URL     string // web link
	Updated time.Time
}

QueueItem is one open dependency-update pull request found by ListQueue.

func ListQueue

func ListQueue(instance, project, repo string, authors []string, limit int) ([]QueueItem, string, error)

ListQueue finds open (active) pull requests by the given authors in an Azure DevOps project, or a single repository of it when repo is non-empty (both URL path segments, possibly percent-encoded). Authors may be empty to match every open PR. Results are newest first (Azure DevOps orders by creation date and PR objects carry no update time), capped at limit. The returned string describes the scope for display.

type Ref

type Ref struct {
	Instance string // e.g. "https://dev.azure.com/fabrikam" (org URL, no trailing slash)
	Project  string // URL path segment, may be percent-encoded
	Repo     string // URL path segment, may be percent-encoded
	ID       int
}

Ref identifies an Azure DevOps pull request.

func Parse

func Parse(s string) (Ref, bool)

Parse recognises an Azure DevOps pull request URL:

https://dev.azure.com/ORG/PROJECT/_git/REPO/pullrequest/123

*.visualstudio.com and self-hosted Azure DevOps Server URLs (with collection prefixes) are recognised too — the /_git/…/pullrequest/N shape is unique to Azure DevOps.

func (Ref) String

func (r Ref) String() string