api

package
v0.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 17, 2026 License: Apache-2.0 Imports: 25 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	MinMajorVersion = 2020
	MinMinorVersion = 1
)

Minimum supported TeamCity version

Variables

View Source 
var (
	// ReadRetry is the default for idempotent read operations (GET).
	// Retries on network errors and 5xx responses.
	ReadRetry = RetryConfig{MaxRetries: 3, Interval: 200 * time.Millisecond}

	// NoRetry disables retries. Use for non-idempotent operations (POST to queue, etc.).
	NoRetry = RetryConfig{MaxRetries: 0}

	// LongRetry is for operations that may need more time to succeed
	// (e.g., waiting for resources to propagate).
	LongRetry = RetryConfig{MaxRetries: 3, Interval: 1 * time.Second}
)

Predefined retry configurations for different operation types.

View Source 
var AgentFields = FieldSpec{
	Available: []string{"id", "name", "typeId", "connected", "enabled", "authorized", "href", "webUrl", "pool.id", "pool.name"},
	Default:   []string{"id", "name", "connected", "enabled", "authorized", "href", "webUrl", "pool.id", "pool.name"},
}
View Source 
var BuildFields = FieldSpec{
	Available: []string{
		"id", "number", "status", "state", "href", "webUrl", "branchName", "defaultBranch",
		"buildTypeId", "statusText", "queuedDate", "startDate", "finishDate", "percentageComplete",
		"pinned", "tags.tag.name",
		"buildType.id", "buildType.name", "buildType.projectName", "buildType.projectId", "buildType.href", "buildType.webUrl",
		"triggered.type", "triggered.date", "triggered.user.name", "triggered.user.username",
		"agent.id", "agent.name", "agent.href", "agent.webUrl",
	},
	Default: []string{
		"id", "number", "status", "state", "branchName", "buildTypeId",
		"buildType.id", "buildType.name", "buildType.projectName",
		"triggered.type", "triggered.user.name", "triggered.user.username",
		"startDate", "finishDate", "queuedDate", "agent.name",
	},
}

BuildFields field specifications

View Source 
var BuildTypeFields = FieldSpec{
	Available: []string{"id", "name", "projectName", "projectId", "href", "webUrl", "paused"},
	Default:   []string{"id", "name", "projectName", "projectId", "href", "webUrl", "paused"},
}
View Source 
var PoolFields = FieldSpec{
	Available: []string{"id", "name", "maxAgents", "href"},
	Default:   []string{"id", "name", "maxAgents"},
}
View Source 
var ProjectFields = FieldSpec{
	Available: []string{"id", "name", "description", "parentProjectId", "href", "webUrl"},
	Default:   []string{"id", "name", "description", "parentProjectId", "href", "webUrl"},
}
View Source 
var QueuedBuildFields = FieldSpec{
	Available: []string{
		"id", "buildTypeId", "state", "branchName", "href", "webUrl", "queuedDate",
		"buildType.id", "buildType.name", "buildType.projectName",
		"triggered.type", "triggered.date", "triggered.user.name", "triggered.user.username",
	},
	Default: []string{
		"id", "buildTypeId", "state", "branchName", "href", "webUrl", "queuedDate",
		"buildType.id", "buildType.name", "buildType.projectName",
		"triggered.type", "triggered.user.name", "triggered.user.username",
	},
}

Functions

func FormatTeamCityTime 

func FormatTeamCityTime(t time.Time) string

FormatTeamCityTime formats time to TeamCity's date format.

func ParseTeamCityTime 

func ParseTeamCityTime(s string) (time.Time, error)

ParseTeamCityTime parses TeamCity's time format (20250710T080607+0000)

func ParseUserDate 

func ParseUserDate(input string) (string, error)

ParseUserDate converts user input to TeamCity date format. Supports: "24h" (relative), "2026-01-21" (absolute), or TeamCity format.

func ToAPIFields 

func ToAPIFields(fields []string) string

ToAPIFields converts dot-notation fields to TeamCity API fields parameter. Example: ["id", "buildType.name", "buildType.projectId"] -> "id,buildType(name,projectId)"

func ToAPIFieldsEncoded 

func ToAPIFieldsEncoded(fields []string) string

ToAPIFieldsEncoded returns URL-encoded TeamCity API fields parameter

Types

type APIError 

type APIError struct {
	Message string `json:"message"`
}

APIError represents an error from TeamCity's REST API

type APIErrorResponse 

type APIErrorResponse struct {
	Errors []APIError `json:"errors"`
}

APIErrorResponse represents TeamCity's error response format

type Agent 

type Agent struct {
	ID         int    `json:"id,omitempty"`
	Name       string `json:"name,omitempty"`
	TypeID     int    `json:"typeId,omitempty"`
	Connected  bool   `json:"connected,omitempty"`
	Enabled    bool   `json:"enabled,omitempty"`
	Authorized bool   `json:"authorized,omitempty"`
	Href       string `json:"href,omitempty"`
	WebURL     string `json:"webUrl,omitempty"`
	Pool       *Pool  `json:"pool,omitempty"`
	Build      *Build `json:"build,omitempty"`
}

Agent represents a build agent

type AgentList 

type AgentList struct {
	Count    int     `json:"count"`
	Href     string  `json:"href"`
	NextHref string  `json:"nextHref,omitempty"`
	Agents   []Agent `json:"agent"`
}

AgentList represents a list of agents

type AgentRef 

type AgentRef struct {
	ID   int    `json:"id,omitempty"`
	Name string `json:"name,omitempty"`
}

AgentRef is a reference to an agent

type AgentsOptions 

type AgentsOptions struct {
	Authorized bool   // Filter by authorization status
	Connected  bool   // Filter by connection status
	Enabled    bool   // Filter by enabled status
	Pool       string // Filter by pool name
	Limit      int
	Fields     []string // Fields to return (uses AgentFields.Default if empty)
}

AgentsOptions represents options for listing agents

type ApprovalInfo 

type ApprovalInfo struct {
	Status                     string `json:"status"`
	ConfigurationValid         bool   `json:"configurationValid"`
	CanBeApprovedByCurrentUser bool   `json:"canBeApprovedByCurrentUser"`
}

ApprovalInfo represents approval information for a queued build

type Artifact 

type Artifact struct {
	Name     string     `json:"name"`
	Size     int64      `json:"size,omitempty"`
	ModTime  string     `json:"modificationTime,omitempty"`
	Href     string     `json:"href,omitempty"`
	Children *Artifacts `json:"children,omitempty"`
	Content  *Content   `json:"content,omitempty"`
}

Artifact represents a build artifact

type Artifacts 

type Artifacts struct {
	Count int        `json:"count"`
	File  []Artifact `json:"file"`
}

Artifacts represents a list of artifacts

type Build 

type Build struct {
	ID                 int         `json:"id"`
	BuildTypeID        string      `json:"buildTypeId,omitempty"`
	Number             string      `json:"number,omitempty"`
	Status             string      `json:"status,omitempty"`
	State              string      `json:"state,omitempty"`
	Personal           bool        `json:"personal,omitempty"`
	BranchName         string      `json:"branchName,omitempty"`
	DefaultBranch      bool        `json:"defaultBranch,omitempty"`
	Href               string      `json:"href,omitempty"`
	WebURL             string      `json:"webUrl,omitempty"`
	StatusText         string      `json:"statusText,omitempty"`
	QueuedDate         string      `json:"queuedDate,omitempty"`
	StartDate          string      `json:"startDate,omitempty"`
	FinishDate         string      `json:"finishDate,omitempty"`
	BuildType          *BuildType  `json:"buildType,omitempty"`
	Triggered          *Triggered  `json:"triggered,omitempty"`
	Agent              *Agent      `json:"agent,omitempty"`
	PercentageComplete int         `json:"percentageComplete,omitempty"`
	Pinned             bool        `json:"pinned,omitempty"`
	Tags               *TagList    `json:"tags,omitempty"`
	LastChanges        *ChangeList `json:"lastChanges,omitempty"`
}

Build represents a TeamCity build

type BuildComment 

type BuildComment struct {
	Text string `json:"text"`
}

BuildComment represents a comment on a build

type BuildList 

type BuildList struct {
	Count    int     `json:"count"`
	Href     string  `json:"href"`
	NextHref string  `json:"nextHref,omitempty"`
	Builds   []Build `json:"build"`
}

BuildList represents a list of builds

type BuildQueue 

type BuildQueue struct {
	Count  int           `json:"count"`
	Href   string        `json:"href"`
	Builds []QueuedBuild `json:"build"`
}

BuildQueue represents the build queue

type BuildStep 

type BuildStep struct {
	ID         string       `json:"id,omitempty"`
	Name       string       `json:"name"`
	Type       string       `json:"type"`
	Properties PropertyList `json:"properties,omitempty"`
}

BuildStep represents a build step configuration

type BuildType 

type BuildType struct {
	ID          string   `json:"id"`
	Name        string   `json:"name,omitempty"`
	ProjectName string   `json:"projectName,omitempty"`
	ProjectID   string   `json:"projectId,omitempty"`
	Href        string   `json:"href,omitempty"`
	WebURL      string   `json:"webUrl,omitempty"`
	Paused      bool     `json:"paused,omitempty"`
	Project     *Project `json:"project,omitempty"`
}

BuildType represents a build configuration

type BuildTypeList 

type BuildTypeList struct {
	Count      int         `json:"count"`
	BuildTypes []BuildType `json:"buildType"`
}

BuildTypeList represents a list of build configurations

type BuildTypeRef 

type BuildTypeRef struct {
	ID string `json:"id"`
}

BuildTypeRef is a reference to a build type

type BuildTypesOptions 

type BuildTypesOptions struct {
	Project string
	Limit   int
	Fields  []string
}

BuildTypesOptions represents options for listing build configurations

type BuildsOptions 

type BuildsOptions struct {
	BuildTypeID string
	Branch      string
	Status      string
	State       string
	User        string
	Project     string
	Number      string
	Limit       int
	SinceDate   string
	UntilDate   string
	Fields      []string
}

BuildsOptions represents options for listing builds

type Change 

type Change struct {
	ID       int    `json:"id,omitempty"`
	Version  string `json:"version,omitempty"` // commit SHA
	Username string `json:"username,omitempty"`
	Date     string `json:"date,omitempty"`
	Comment  string `json:"comment,omitempty"`
	WebURL   string `json:"webUrl,omitempty"`
	Files    *Files `json:"files,omitempty"`
}

type ChangeList 

type ChangeList struct {
	Count  int      `json:"count"`
	Change []Change `json:"change"`
}

type Client 

type Client struct {
	BaseURL    string
	Token      string
	APIVersion string // Optional: pin to a specific API version (e.g., "2020.1")
	HTTPClient *http.Client
	// contains filtered or unexported fields
}

Client represents a TeamCity API client

func NewClient 

func NewClient(baseURL, token string, opts ...ClientOption) *Client

NewClient creates a new TeamCity API client with Bearer token authentication

func NewClientWithBasicAuth 

func NewClientWithBasicAuth(baseURL, username, password string, opts ...ClientOption) *Client

NewClientWithBasicAuth creates a new TeamCity API client with Basic authentication. Use empty username with superuser token, or username/password for regular users.

func (*Client) AddBuildTags 

func (c *Client) AddBuildTags(buildID string, tags []string) error

AddBuildTags adds tags to a build (accepts ID or #number)

func (*Client) AddProjectToPool added in v0.2.0 

func (c *Client) AddProjectToPool(poolID int, projectID string) error

AddProjectToPool assigns a project to an agent pool

func (*Client) ApproveQueuedBuild 

func (c *Client) ApproveQueuedBuild(buildID string) error

ApproveQueuedBuild approves a queued build that requires approval

func (*Client) AuthorizeAgent 

func (c *Client) AuthorizeAgent(id int, authorized bool) error

AuthorizeAgent sets the authorized status of an agent

func (*Client) BuildTypeExists 

func (c *Client) BuildTypeExists(id string) bool

BuildTypeExists checks if a build configuration exists

func (*Client) CancelBuild 

func (c *Client) CancelBuild(buildID string, comment string) error

CancelBuild cancels a running or queued build (accepts ID or #number)

func (*Client) CheckVersion 

func (c *Client) CheckVersion() error

CheckVersion verifies the server meets minimum version requirements

func (*Client) CreateAPIToken 

func (c *Client) CreateAPIToken(name string) (*Token, error)

CreateAPIToken creates an API token for the current user

func (*Client) CreateBuildStep 

func (c *Client) CreateBuildStep(buildTypeID string, step BuildStep) error

CreateBuildStep adds a build step to a build configuration

func (*Client) CreateBuildType 

func (c *Client) CreateBuildType(projectID string, req CreateBuildTypeRequest) (*BuildType, error)

CreateBuildType creates a new build configuration in a project

func (*Client) CreateProject 

func (c *Client) CreateProject(req CreateProjectRequest) (*Project, error)

CreateProject creates a new project

func (*Client) CreateSecureToken 

func (c *Client) CreateSecureToken(projectID, value string) (string, error)

CreateSecureToken creates a new secure token for the given value in a project. Returns the scrambled token that can be used in configuration files as credentialsJSON:<token>. Requires EDIT_PROJECT permission.

func (*Client) CreateUser 

func (c *Client) CreateUser(req CreateUserRequest) (*User, error)

CreateUser creates a new user

func (*Client) DeleteAPIToken 

func (c *Client) DeleteAPIToken(name string) error

DeleteAPIToken deletes an API token for the current user

func (*Client) DeleteBuildComment 

func (c *Client) DeleteBuildComment(buildID string) error

DeleteBuildComment removes the comment from a build (accepts ID or #number)

func (*Client) DeleteBuildTypeParameter 

func (c *Client) DeleteBuildTypeParameter(buildTypeID, name string) error

DeleteBuildTypeParameter deletes a parameter from a build configuration

func (*Client) DeleteProjectParameter 

func (c *Client) DeleteProjectParameter(projectID, name string) error

DeleteProjectParameter deletes a parameter from a project

func (*Client) DownloadArtifact 

func (c *Client) DownloadArtifact(buildID, artifactPath string) ([]byte, error)

DownloadArtifact downloads an artifact and returns its content (accepts ID or #number)

func (*Client) DownloadArtifactTo added in v0.4.0 

func (c *Client) DownloadArtifactTo(ctx context.Context, buildID, artifactPath string, w io.Writer) (int64, error)

DownloadArtifactTo streams an artifact to a writer (accepts ID or #number)

func (*Client) EnableAgent added in v0.2.0 

func (c *Client) EnableAgent(id int, enabled bool) error

EnableAgent sets the enabled status of an agent

func (*Client) ExportProjectSettings added in v0.3.0 

func (c *Client) ExportProjectSettings(projectID, format string, useRelativeIds bool) ([]byte, error)

ExportProjectSettings exports project settings as a ZIP archive in the specified format. Format can be "kotlin" or "xml". Returns the raw ZIP file bytes.

func (*Client) GetAgent added in v0.2.0 

func (c *Client) GetAgent(id int) (*Agent, error)

GetAgent returns details for a single agent

func (*Client) GetAgentByName added in v0.4.0 

func (c *Client) GetAgentByName(name string) (*Agent, error)

GetAgentByName returns details for an agent by name. PathEscape is sufficient here: TeamCity prohibits colons and commas in agent names (they conflict with locator syntax), so we only need to escape path-unsafe characters.

func (*Client) GetAgentCompatibleBuildTypes added in v0.2.0 

func (c *Client) GetAgentCompatibleBuildTypes(id int) (*BuildTypeList, error)

GetAgentCompatibleBuildTypes returns build types compatible with an agent

func (*Client) GetAgentIncompatibleBuildTypes added in v0.2.0 

func (c *Client) GetAgentIncompatibleBuildTypes(id int) (*CompatibilityList, error)

GetAgentIncompatibleBuildTypes returns build types incompatible with an agent and reasons

func (*Client) GetAgentPool added in v0.2.0 

func (c *Client) GetAgentPool(id int) (*Pool, error)

GetAgentPool returns details for a single pool

func (*Client) GetAgentPools added in v0.2.0 

func (c *Client) GetAgentPools(requestedFields []string) (*PoolList, error)

GetAgentPools returns all agent pools

func (*Client) GetAgents 

func (c *Client) GetAgents(opts AgentsOptions) (*AgentList, error)

GetAgents returns a list of agents

func (*Client) GetArtifacts 

func (c *Client) GetArtifacts(buildID string) (*Artifacts, error)

GetArtifacts returns the artifacts for a build (accepts ID or #number)

func (*Client) GetBuild 

func (c *Client) GetBuild(ref string) (*Build, error)

GetBuild returns a single build by ID or #number

func (*Client) GetBuildChanges 

func (c *Client) GetBuildChanges(buildID string) (*ChangeList, error)

func (*Client) GetBuildComment 

func (c *Client) GetBuildComment(buildID string) (string, error)

GetBuildComment returns the comment for a build (accepts ID or #number)

func (*Client) GetBuildLog 

func (c *Client) GetBuildLog(buildID string) (string, error)

GetBuildLog returns the build log (accepts ID or #number)

func (*Client) GetBuildProblems added in v0.4.0 

func (c *Client) GetBuildProblems(buildID string) (*ProblemOccurrences, error)

func (*Client) GetBuildQueue 

func (c *Client) GetBuildQueue(opts QueueOptions) (*BuildQueue, error)

GetBuildQueue returns the build queue

func (*Client) GetBuildTags 

func (c *Client) GetBuildTags(buildID string) (*TagList, error)

GetBuildTags returns the tags for a build (accepts ID or #number)

func (*Client) GetBuildTests 

func (c *Client) GetBuildTests(buildID string, failedOnly bool, limit int) (*TestOccurrences, error)

func (*Client) GetBuildType 

func (c *Client) GetBuildType(id string) (*BuildType, error)

GetBuildType returns a single build configuration by ID

func (*Client) GetBuildTypeParameter 

func (c *Client) GetBuildTypeParameter(buildTypeID, name string) (*Parameter, error)

GetBuildTypeParameter returns a specific parameter for a build configuration

func (*Client) GetBuildTypeParameters 

func (c *Client) GetBuildTypeParameters(buildTypeID string) (*ParameterList, error)

GetBuildTypeParameters returns parameters for a build configuration

func (*Client) GetBuildTypes 

func (c *Client) GetBuildTypes(opts BuildTypesOptions) (*BuildTypeList, error)

GetBuildTypes returns a list of build configurations

func (*Client) GetBuilds 

func (c *Client) GetBuilds(opts BuildsOptions) (*BuildList, error)

GetBuilds returns a list of builds

func (*Client) GetCurrentUser 

func (c *Client) GetCurrentUser() (*User, error)

GetCurrentUser returns the authenticated user

func (*Client) GetParameterValue 

func (c *Client) GetParameterValue(path string) (string, error)

GetParameterValue returns just the raw value of a parameter

func (*Client) GetProject 

func (c *Client) GetProject(id string) (*Project, error)

GetProject returns a single project by ID

func (*Client) GetProjectParameter 

func (c *Client) GetProjectParameter(projectID, name string) (*Parameter, error)

GetProjectParameter returns a specific parameter for a project

func (*Client) GetProjectParameters 

func (c *Client) GetProjectParameters(projectID string) (*ParameterList, error)

GetProjectParameters returns parameters for a project

func (*Client) GetProjects 

func (c *Client) GetProjects(opts ProjectsOptions) (*ProjectList, error)

GetProjects returns a list of projects

func (*Client) GetQueuedBuildApprovalInfo 

func (c *Client) GetQueuedBuildApprovalInfo(buildID string) (*ApprovalInfo, error)

GetQueuedBuildApprovalInfo returns approval information for a queued build

func (*Client) GetSecureValue 

func (c *Client) GetSecureValue(projectID, token string) (string, error)

GetSecureValue retrieves the original value for a secure token. Requires CHANGE_SERVER_SETTINGS permission (System Administrator only).

func (*Client) GetServer 

func (c *Client) GetServer() (*Server, error)

GetServer returns server information

func (*Client) GetUser 

func (c *Client) GetUser(username string) (*User, error)

GetUser returns a user by username

func (*Client) GetVcsRootEntries added in v0.5.0 

func (c *Client) GetVcsRootEntries(buildTypeID string) (*VcsRootEntries, error)

GetVcsRootEntries returns the VCS root entries attached to a build configuration

func (*Client) GetVersionedSettingsConfig added in v0.3.0 

func (c *Client) GetVersionedSettingsConfig(projectID string) (*VersionedSettingsConfig, error)

GetVersionedSettingsConfig returns the versioned settings configuration for a project.

func (*Client) GetVersionedSettingsStatus added in v0.3.0 

func (c *Client) GetVersionedSettingsStatus(projectID string) (*VersionedSettingsStatus, error)

GetVersionedSettingsStatus returns the sync status of versioned settings for a project.

func (*Client) MoveQueuedBuildToTop 

func (c *Client) MoveQueuedBuildToTop(buildID string) error

MoveQueuedBuildToTop moves a queued build to the top of the queue

func (*Client) PinBuild 

func (c *Client) PinBuild(buildID string, comment string) error

PinBuild pins a build to prevent it from being cleaned up (accepts ID or #number)

func (*Client) ProjectExists 

func (c *Client) ProjectExists(id string) bool

ProjectExists checks if a project exists

func (*Client) RawRequest 

func (c *Client) RawRequest(method, path string, body io.Reader, headers map[string]string) (*RawResponse, error)

RawRequest performs a raw HTTP request and returns the response without parsing

func (*Client) RebootAgent added in v0.4.0 

func (c *Client) RebootAgent(ctx context.Context, id int, afterBuild bool) error

RebootAgent requests a reboot of the specified agent. If afterBuild is true, the agent will reboot after the current build finishes. This uses the web UI endpoint as there is no REST API for agent reboot.

func (*Client) RemoveBuildTag 

func (c *Client) RemoveBuildTag(buildID string, tag string) error

RemoveBuildTag removes a specific tag from a build (accepts ID or #number)

func (*Client) RemoveFromQueue 

func (c *Client) RemoveFromQueue(id string) error

RemoveFromQueue removes a build from the queue

func (*Client) RemoveProjectFromPool added in v0.2.0 

func (c *Client) RemoveProjectFromPool(poolID int, projectID string) error

RemoveProjectFromPool removes a project from an agent pool

func (*Client) ResolveBuildID 

func (c *Client) ResolveBuildID(ref string) (string, error)

ResolveBuildID resolves a build reference to an ID. If ref starts with #, it's treated as a build number and looked up. Otherwise it's used as-is (assumed to be an ID).

func (*Client) RunBuild 

func (c *Client) RunBuild(buildTypeID string, opts RunBuildOptions) (*Build, error)

RunBuild runs a new build with full options

func (*Client) ServerVersion 

func (c *Client) ServerVersion() (*Server, error)

ServerVersion returns cached server version info

func (*Client) SetAgentPool added in v0.2.0 

func (c *Client) SetAgentPool(agentID int, poolID int) error

SetAgentPool moves an agent to a different pool

func (*Client) SetBuildComment 

func (c *Client) SetBuildComment(buildID string, comment string) error

SetBuildComment sets or updates the comment on a build (accepts ID or #number)

func (*Client) SetBuildTypeParameter 

func (c *Client) SetBuildTypeParameter(buildTypeID, name, value string, secure bool) error

SetBuildTypeParameter sets a parameter for a build configuration

func (*Client) SetBuildTypePaused 

func (c *Client) SetBuildTypePaused(id string, paused bool) error

SetBuildTypePaused sets the paused state of a build configuration

func (*Client) SetBuildTypeSetting 

func (c *Client) SetBuildTypeSetting(buildTypeID, setting, value string) error

SetBuildTypeSetting sets a build configuration setting

func (*Client) SetProjectParameter 

func (c *Client) SetProjectParameter(projectID, name, value string, secure bool) error

SetProjectParameter sets a parameter for a project

func (*Client) SetQueuedBuildPosition 

func (c *Client) SetQueuedBuildPosition(buildID string, position int) error

SetQueuedBuildPosition moves a queued build to a specific position in the queue

func (*Client) SupportsFeature 

func (c *Client) SupportsFeature(feature string) bool

SupportsFeature checks if the server supports a specific feature

func (*Client) UnpinBuild 

func (c *Client) UnpinBuild(buildID string) error

UnpinBuild removes the pin from a build (accepts ID or #number)

func (*Client) UploadDiffChanges added in v0.2.0 

func (c *Client) UploadDiffChanges(patch []byte, description string) (string, error)

func (*Client) UserExists 

func (c *Client) UserExists(username string) bool

UserExists checks if a user exists

type ClientInterface 

type ClientInterface interface {
	// Server
	GetServer() (*Server, error)
	ServerVersion() (*Server, error)
	CheckVersion() error
	SupportsFeature(feature string) bool

	// Users
	GetCurrentUser() (*User, error)
	GetUser(username string) (*User, error)
	UserExists(username string) bool
	CreateUser(req CreateUserRequest) (*User, error)
	CreateAPIToken(name string) (*Token, error)
	DeleteAPIToken(name string) error

	// Projects
	GetProjects(opts ProjectsOptions) (*ProjectList, error)
	GetProject(id string) (*Project, error)
	CreateProject(req CreateProjectRequest) (*Project, error)
	ProjectExists(id string) bool
	CreateSecureToken(projectID, value string) (string, error)
	GetSecureValue(projectID, token string) (string, error)
	GetVersionedSettingsStatus(projectID string) (*VersionedSettingsStatus, error)
	GetVersionedSettingsConfig(projectID string) (*VersionedSettingsConfig, error)
	ExportProjectSettings(projectID, format string, useRelativeIds bool) ([]byte, error)

	// Build Types (Jobs)
	GetBuildTypes(opts BuildTypesOptions) (*BuildTypeList, error)
	GetBuildType(id string) (*BuildType, error)
	SetBuildTypePaused(id string, paused bool) error
	CreateBuildType(projectID string, req CreateBuildTypeRequest) (*BuildType, error)
	BuildTypeExists(id string) bool
	CreateBuildStep(buildTypeID string, step BuildStep) error
	GetVcsRootEntries(buildTypeID string) (*VcsRootEntries, error)
	SetBuildTypeSetting(buildTypeID, setting, value string) error

	// Builds (Runs)
	GetBuilds(opts BuildsOptions) (*BuildList, error)
	GetBuild(ref string) (*Build, error)
	ResolveBuildID(ref string) (string, error)
	RunBuild(buildTypeID string, opts RunBuildOptions) (*Build, error)
	CancelBuild(buildID string, comment string) error
	GetBuildLog(buildID string) (string, error)
	PinBuild(buildID string, comment string) error
	UnpinBuild(buildID string) error
	AddBuildTags(buildID string, tags []string) error
	GetBuildTags(buildID string) (*TagList, error)
	RemoveBuildTag(buildID string, tag string) error
	SetBuildComment(buildID string, comment string) error
	GetBuildComment(buildID string) (string, error)
	DeleteBuildComment(buildID string) error
	GetBuildChanges(buildID string) (*ChangeList, error)
	GetBuildTests(buildID string, failedOnly bool, limit int) (*TestOccurrences, error)
	GetBuildProblems(buildID string) (*ProblemOccurrences, error)
	UploadDiffChanges(patch []byte, description string) (string, error)

	// Artifacts
	GetArtifacts(buildID string) (*Artifacts, error)
	DownloadArtifact(buildID, artifactPath string) ([]byte, error)
	DownloadArtifactTo(ctx context.Context, buildID, artifactPath string, w io.Writer) (int64, error)

	// Build Queue
	GetBuildQueue(opts QueueOptions) (*BuildQueue, error)
	RemoveFromQueue(id string) error
	SetQueuedBuildPosition(buildID string, position int) error
	MoveQueuedBuildToTop(buildID string) error
	ApproveQueuedBuild(buildID string) error
	GetQueuedBuildApprovalInfo(buildID string) (*ApprovalInfo, error)

	// Parameters
	GetProjectParameters(projectID string) (*ParameterList, error)
	GetProjectParameter(projectID, name string) (*Parameter, error)
	SetProjectParameter(projectID, name, value string, secure bool) error
	DeleteProjectParameter(projectID, name string) error
	GetBuildTypeParameters(buildTypeID string) (*ParameterList, error)
	GetBuildTypeParameter(buildTypeID, name string) (*Parameter, error)
	SetBuildTypeParameter(buildTypeID, name, value string, secure bool) error
	DeleteBuildTypeParameter(buildTypeID, name string) error
	GetParameterValue(path string) (string, error)

	// Agents
	GetAgents(opts AgentsOptions) (*AgentList, error)
	GetAgent(id int) (*Agent, error)
	GetAgentByName(name string) (*Agent, error)
	AuthorizeAgent(id int, authorized bool) error
	EnableAgent(id int, enabled bool) error
	RebootAgent(ctx context.Context, id int, afterBuild bool) error
	GetAgentCompatibleBuildTypes(id int) (*BuildTypeList, error)
	GetAgentIncompatibleBuildTypes(id int) (*CompatibilityList, error)

	// Agent Pools
	GetAgentPools(fields []string) (*PoolList, error)
	GetAgentPool(id int) (*Pool, error)
	AddProjectToPool(poolID int, projectID string) error
	RemoveProjectFromPool(poolID int, projectID string) error
	SetAgentPool(agentID int, poolID int) error

	// Raw API access
	RawRequest(method, path string, body io.Reader, headers map[string]string) (*RawResponse, error)
}

ClientInterface defines the TeamCity API client interface. Cmd package uses this interface for dependency injection in tests.

type ClientOption 

type ClientOption func(*Client)

ClientOption allows configuring the client

func WithAPIVersion 

func WithAPIVersion(version string) ClientOption

WithAPIVersion pins the client to a specific API version

func WithTimeout 

func WithTimeout(timeout time.Duration) ClientOption

WithTimeout sets a custom HTTP timeout

type Compatibility added in v0.2.0 

type Compatibility struct {
	Compatible bool                 `json:"compatible"`
	BuildType  *BuildType           `json:"buildType,omitempty"`
	Agent      *Agent               `json:"agent,omitempty"`
	Reasons    *IncompatibleReasons `json:"incompatibleReasons,omitempty"`
}

Compatibility represents build type compatibility info

type CompatibilityList added in v0.2.0 

type CompatibilityList struct {
	Count         int             `json:"count"`
	Compatibility []Compatibility `json:"compatibility"`
}

CompatibilityList represents a list of compatibility entries

type Content 

type Content struct {
	Href string `json:"href"`
}

Content represents artifact content reference

type CreateBuildTypeRequest 

type CreateBuildTypeRequest struct {
	ID   string `json:"id,omitempty"`
	Name string `json:"name"`
}

CreateBuildTypeRequest represents a request to create a build configuration

type CreateProjectRequest 

type CreateProjectRequest struct {
	ID              string `json:"id,omitempty"`
	Name            string `json:"name"`
	ParentProjectID string `json:"parentProject,omitempty"`
}

CreateProjectRequest represents a request to create a project

type CreateUserRequest 

type CreateUserRequest struct {
	Username string   `json:"username"`
	Password string   `json:"password"`
	Name     string   `json:"name,omitempty"`
	Email    string   `json:"email,omitempty"`
	Roles    RoleList `json:"roles,omitempty"`
}

CreateUserRequest represents a request to create a user

type FieldSpec 

type FieldSpec struct {
	Available []string
	Default   []string
}

FieldSpec defines available and default fields for a resource type

func (*FieldSpec) Help 

func (fs *FieldSpec) Help() string

Help returns help text

func (*FieldSpec) ParseFields 

func (fs *FieldSpec) ParseFields(input string) ([]string, error)

ParseFields parses comma-separated fields, validates them, returns defaults if empty

type FileChange 

type FileChange struct {
	File       string `json:"file"`
	ChangeType string `json:"changeType"` // added, edited, removed
}

type Files 

type Files struct {
	File []FileChange `json:"file"`
}

type IncompatibleReasons added in v0.2.0 

type IncompatibleReasons struct {
	Reasons []string `json:"reason,omitempty"`
}

IncompatibleReasons contains reasons why an agent can't run a build type

type LastChanges added in v0.2.0 

type LastChanges struct {
	Change []PersonalChange `json:"change"`
}

LastChanges represents the changes to include in a build

type Locator 

type Locator struct {
	// contains filtered or unexported fields
}

func NewLocator 

func NewLocator() *Locator

func (*Locator) Add 

func (l *Locator) Add(key, value string) *Locator

func (*Locator) AddInt 

func (l *Locator) AddInt(key string, value int) *Locator

func (*Locator) AddIntDefault 

func (l *Locator) AddIntDefault(key string, value, defaultVal int) *Locator

func (*Locator) AddRaw added in v0.4.0 

func (l *Locator) AddRaw(key, value string) *Locator

AddRaw adds a key:value pair without escaping the value. Use for values that are already valid locator syntax (e.g. sub-locators).

func (*Locator) AddUpper 

func (l *Locator) AddUpper(key, value string) *Locator

func (*Locator) Encode 

func (l *Locator) Encode() string

func (*Locator) IsEmpty 

func (l *Locator) IsEmpty() bool

func (*Locator) String 

func (l *Locator) String() string

type Parameter 

type Parameter struct {
	Name  string         `json:"name"`
	Value string         `json:"value"`
	Type  *ParameterType `json:"type,omitempty"`
}

Parameter represents a TeamCity parameter

type ParameterList 

type ParameterList struct {
	Count    int         `json:"count"`
	Property []Parameter `json:"property"`
}

ParameterList represents a list of parameters

type ParameterType 

type ParameterType struct {
	RawValue string `json:"rawValue,omitempty"`
}

ParameterType represents parameter type info

type PersonalChange added in v0.2.0 

type PersonalChange struct {
	ID       string `json:"id"`
	Personal bool   `json:"personal,omitempty"`
}

PersonalChange represents a personal change (uploaded diff) reference

type Pool 

type Pool struct {
	ID        int          `json:"id,omitempty"`
	Name      string       `json:"name,omitempty"`
	Href      string       `json:"href,omitempty"`
	MaxAgents int          `json:"maxAgents,omitempty"`
	Projects  *ProjectList `json:"projects,omitempty"`
	Agents    *AgentList   `json:"agents,omitempty"`
}

Pool represents an agent pool

type PoolList added in v0.2.0 

type PoolList struct {
	Count int    `json:"count"`
	Pools []Pool `json:"agentPool"`
}

PoolList represents a list of agent pools

type ProblemOccurrence added in v0.4.0 

type ProblemOccurrence struct {
	ID       string `json:"id"`
	Type     string `json:"type"`
	Identity string `json:"identity"`
	Details  string `json:"details"`
}

type ProblemOccurrences added in v0.4.0 

type ProblemOccurrences struct {
	Count             int                 `json:"count"`
	ProblemOccurrence []ProblemOccurrence `json:"problemOccurrence"`
}

type Project 

type Project struct {
	ID              string `json:"id"`
	Name            string `json:"name,omitempty"`
	Description     string `json:"description,omitempty"`
	ParentProjectID string `json:"parentProjectId,omitempty"`
	Href            string `json:"href,omitempty"`
	WebURL          string `json:"webUrl,omitempty"`
}

Project represents a TeamCity project

type ProjectList 

type ProjectList struct {
	Count    int       `json:"count"`
	Projects []Project `json:"project"`
}

ProjectList represents a list of projects

type ProjectsOptions 

type ProjectsOptions struct {
	Parent string
	Limit  int
	Fields []string
}

ProjectsOptions represents options for listing projects

type Property 

type Property struct {
	Name  string `json:"name"`
	Value string `json:"value"`
}

Property represents a build property

type PropertyList 

type PropertyList struct {
	Property []Property `json:"property"`
}

PropertyList represents a list of properties

type QueueOptions 

type QueueOptions struct {
	BuildTypeID string
	Limit       int
	Fields      []string
}

QueueOptions represents options for listing queued builds

type QueuedBuild 

type QueuedBuild struct {
	ID          int        `json:"id"`
	BuildTypeID string     `json:"buildTypeId,omitempty"`
	State       string     `json:"state,omitempty"`
	BranchName  string     `json:"branchName,omitempty"`
	Href        string     `json:"href,omitempty"`
	WebURL      string     `json:"webUrl,omitempty"`
	BuildType   *BuildType `json:"buildType,omitempty"`
	Triggered   *Triggered `json:"triggered,omitempty"`
	QueuedDate  string     `json:"queuedDate,omitempty"`
}

QueuedBuild represents a build in the queue

type RawResponse 

type RawResponse struct {
	StatusCode int
	Headers    http.Header
	Body       []byte
}

RawResponse represents the response from a raw API request

type RetryConfig 

type RetryConfig struct {
	MaxRetries uint64
	Interval   time.Duration
}

RetryConfig defines retry behavior for API operations.

type Revision added in v0.2.0 

type Revision struct {
	Version         string              `json:"version"`
	VcsBranchName   string              `json:"vcsBranchName,omitempty"`
	VcsRootInstance *VcsRootInstanceRef `json:"vcs-root-instance,omitempty"`
}

type Revisions added in v0.2.0 

type Revisions struct {
	Revision []Revision `json:"revision"`
}

type Role 

type Role struct {
	RoleID string `json:"roleId"`
	Scope  string `json:"scope"` // "g" for global, "p:ProjectID" for project
}

Role represents a TeamCity role assignment

type RoleList 

type RoleList struct {
	Role []Role `json:"role"`
}

RoleList represents a list of role assignments

type RunBuildOptions 

type RunBuildOptions struct {
	Branch                    string
	Params                    map[string]string // Configuration parameters
	SystemProps               map[string]string // System properties (system.*)
	EnvVars                   map[string]string // Environment variables (env.*)
	Comment                   string
	Personal                  bool
	CleanSources              bool
	RebuildDependencies       bool
	QueueAtTop                bool
	RebuildFailedDependencies bool
	AgentID                   int
	Tags                      []string
	PersonalChangeID          string
	Revision                  string
}

RunBuildOptions represents options for running a build

type Server 

type Server struct {
	Version      string `json:"version"`
	VersionMajor int    `json:"versionMajor"`
	VersionMinor int    `json:"versionMinor"`
	BuildNumber  string `json:"buildNumber"`
	WebURL       string `json:"webUrl"`
}

Server represents TeamCity server info

type Tag 

type Tag struct {
	Name string `json:"name"`
}

Tag represents a build tag

type TagList 

type TagList struct {
	Tag []Tag `json:"tag"`
}

TagList represents a list of tags

type TerminalClient added in v0.3.0 

type TerminalClient struct {
	// contains filtered or unexported fields
}

func NewTerminalClient added in v0.3.0 

func NewTerminalClient(baseURL, username, token string) *TerminalClient

func (*TerminalClient) Connect added in v0.3.0 

func (c *TerminalClient) Connect(session *TerminalSession, cols, rows int) (*TerminalConn, error)

func (*TerminalClient) OpenSession added in v0.3.0 

func (c *TerminalClient) OpenSession(agentID int) (*TerminalSession, error)

type TerminalConn added in v0.3.0 

type TerminalConn struct {
	// contains filtered or unexported fields
}

func (*TerminalConn) Close added in v0.3.0 

func (tc *TerminalConn) Close()

func (*TerminalConn) Exec added in v0.3.0 

func (tc *TerminalConn) Exec(ctx context.Context, command string) error

func (*TerminalConn) RunInteractive added in v0.3.0 

func (tc *TerminalConn) RunInteractive(ctx context.Context) error

type TerminalSession added in v0.3.0 

type TerminalSession struct {
	Token  string `json:"token"`
	NodeID string `json:"nodeId"`
}

TerminalSession holds the session token and node ID from TeamCity's agent terminal plugin

type TestOccurrence 

type TestOccurrence struct {
	ID       string `json:"id"`
	Name     string `json:"name"`
	Status   string `json:"status"` // SUCCESS, FAILURE, IGNORED
	Duration int    `json:"duration,omitempty"`
	Details  string `json:"details,omitempty"`
	Ignored  bool   `json:"ignored,omitempty"`
	Href     string `json:"href,omitempty"`
}

type TestOccurrences 

type TestOccurrences struct {
	Count          int              `json:"count"`
	Passed         int              `json:"passed,omitempty"`
	Failed         int              `json:"failed,omitempty"`
	Ignored        int              `json:"ignored,omitempty"`
	TestOccurrence []TestOccurrence `json:"testOccurrence"`
}

type Token 

type Token struct {
	Name  string `json:"name"`
	Value string `json:"value,omitempty"`
}

Token represents an API token

type TriggerBuildRequest 

type TriggerBuildRequest struct {
	BuildType         BuildTypeRef       `json:"buildType"`
	BranchName        string             `json:"branchName,omitempty"`
	Properties        *PropertyList      `json:"properties,omitempty"`
	Comment           *BuildComment      `json:"comment,omitempty"`
	Personal          bool               `json:"personal,omitempty"`
	TriggeringOptions *TriggeringOptions `json:"triggeringOptions,omitempty"`
	Agent             *AgentRef          `json:"agent,omitempty"`
	Tags              *TagList           `json:"tags,omitempty"`
	LastChanges       *LastChanges       `json:"lastChanges,omitempty"`
	Revisions         *Revisions         `json:"revisions,omitempty"`
}

TriggerBuildRequest represents a request to trigger a build

type Triggered 

type Triggered struct {
	Type string `json:"type,omitempty"`
	Date string `json:"date,omitempty"`
	User *User  `json:"user,omitempty"`
}

Triggered represents who/what triggered a build

type TriggeringOptions 

type TriggeringOptions struct {
	CleanSources              bool `json:"cleanSources,omitempty"`
	RebuildAllDependencies    bool `json:"rebuildAllDependencies,omitempty"`
	QueueAtTop                bool `json:"queueAtTop,omitempty"`
	RebuildFailedOrIncomplete bool `json:"rebuildFailedOrIncompleteDependencies,omitempty"`
}

TriggeringOptions represents options for triggering a build

type User 

type User struct {
	ID       int    `json:"id,omitempty"`
	Username string `json:"username,omitempty"`
	Name     string `json:"name,omitempty"`
	Email    string `json:"email,omitempty"`
	Href     string `json:"href,omitempty"`
}

User represents a TeamCity user

type VcsRootEntries added in v0.5.0 

type VcsRootEntries struct {
	Count        int            `json:"count"`
	VcsRootEntry []VcsRootEntry `json:"vcs-root-entry"`
}

type VcsRootEntry added in v0.5.0 

type VcsRootEntry struct {
	ID      string      `json:"id,omitempty"`
	VcsRoot *VcsRootRef `json:"vcs-root,omitempty"`
}

type VcsRootInstanceRef added in v0.5.0 

type VcsRootInstanceRef struct {
	VcsRootID string `json:"vcs-root-id"`
}

type VcsRootRef added in v0.5.0 

type VcsRootRef struct {
	ID   string `json:"id"`
	Name string `json:"name,omitempty"`
}

type VersionedSettingsConfig added in v0.3.0 

type VersionedSettingsConfig struct {
	SynchronizationMode string `json:"synchronizationMode,omitempty"` // enabled, disabled
	Format              string `json:"format,omitempty"`              // kotlin, xml
	BuildSettingsMode   string `json:"buildSettingsMode,omitempty"`   // useFromVCS, useCurrentByDefault
	VcsRootID           string `json:"vcsRootId,omitempty"`
	SettingsPath        string `json:"settingsPath,omitempty"`
	AllowUIEditing      bool   `json:"allowUIEditing,omitempty"`
	ShowSettingsChanges bool   `json:"showSettingsChanges,omitempty"`
}

VersionedSettingsConfig represents the configuration of versioned settings

type VersionedSettingsStatus added in v0.3.0 

type VersionedSettingsStatus struct {
	Type        string `json:"type,omitempty"`        // info, warning, error
	Message     string `json:"message,omitempty"`     // Human-readable status message
	Timestamp   string `json:"timestamp,omitempty"`   // When the status was recorded
	DslOutdated bool   `json:"dslOutdated,omitempty"` // DSL scripts need regeneration
}

VersionedSettingsStatus represents the sync status of versioned settings

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.