Documentation
¶
Index ¶
- Constants
- func About(c *gin.Context)
- func AcknowledgeAction(c *gin.Context)
- func CreateAPIToken(c *gin.Context)
- func CreatePipelineReport(c *gin.Context)
- func DeleteAPIToken(c *gin.Context)
- func DeleteAPITokensBySubject(c *gin.Context)
- func DeleteConfigCondition(c *gin.Context)
- func DeleteConfigSource(c *gin.Context)
- func DeleteConfigTarget(c *gin.Context)
- func DeletePipelineReport(c *gin.Context)
- func GetPipelineReportByID(c *gin.Context)
- func Landing(c *gin.Context)
- func ListAPITokens(c *gin.Context)
- func ListConfigConditions(c *gin.Context)
- func ListConfigSources(c *gin.Context)
- func ListConfigTargets(c *gin.Context)
- func ListLabels(c *gin.Context)
- func ListPipelineReports(c *gin.Context)
- func ListSCMs(c *gin.Context)
- func Ping(c *gin.Context)
- func Ready(c *gin.Context)
- func SearchConfigConditions(c *gin.Context)
- func SearchConfigKinds(c *gin.Context)
- func SearchConfigSources(c *gin.Context)
- func SearchConfigTargets(c *gin.Context)
- func SearchLabels(c *gin.Context)
- func SearchOpenActions(c *gin.Context)
- func SearchPipelineReports(c *gin.Context)
- func SearchPipelineReportsSummary(c *gin.Context)
- func SearchSCMs(c *gin.Context)
- func UnacknowledgeAction(c *gin.Context)
- func UpdatePipelineReport(c *gin.Context)
- func Whoami(c *gin.Context)
- type AboutResponseModel
- type AuthOptions
- type ConditionConfigResponse
- type ConfigKindResponse
- type CreatePipelineReportResponse
- type CreateTokenRequest
- type CreateTokenResponse
- type CustomClaims
- type DefaultResponseModel
- type FindSCMSummaryResponse
- type GetPipelineReportByIDResponse
- type GetPipelineReportsResponse
- type Interceptor
- type ListLabelKeyOnlyResponse
- type ListLabelsResponse
- type ListSCMsResponse
- type OIDCOptions
- type Options
- type Permission
- type Principal
- type RoleResolver
- type RolesOptions
- type SearchLabelsRequest
- type SearchOpenActionsResponse
- type SearchPipelineReportsSummaryRequest
- type SearchPipelineReportsSummaryResponse
- type SearchSCMsRequest
- type Server
- type SourceConfigResponse
- type TargetConfigResponse
- type WhoamiResponse
- type ZitadelOptions
Constants ¶
const ( // ScopeReportsRead allows a token to read pipeline reports. ScopeReportsRead = "reports:read" // ScopeReportsWrite allows a token to publish pipeline reports. ScopeReportsWrite = "reports:write" )
const ( // VisibilityPublic indicates a public API VisibilityPublic string = "public" // VisibilityPrivate indicates a private API VisibilityPrivate string = "private" // visibilityDefault indicate Default visibility VisibilityDefault = VisibilityPublic // ModeZitadel indicates Zitadel authentication, validating tokens by introspection ModeZitadel = "zitadel" // ModeOIDC indicates generic OpenID Connect authentication, validating JWT // access tokens locally against the issuer signing keys ModeOIDC = "oidc" // ModeNone indicates no authentication ModeNone = "none" // DefaultRoleCacheTTL is how long a permission resolved from the identity // provider is reused before being looked up again. DefaultRoleCacheTTL = 60 * time.Second // ZitadelRolesClaim is the token claim Zitadel puts the project roles in. ZitadelRolesClaim = "urn:zitadel:iam:org:project:roles" // ResolverZitadel resolves the permission behind an Udash API token by asking // Zitadel for the current grants of the identity which created it. ResolverZitadel = "zitadel" // ResolverSnapshot trusts the permission recorded when the token was created. ResolverSnapshot = "snapshot" )
const ( // ErrInvalidPaginationParams is the error message returned when pagination parameters are invalid. ErrInvalidPaginationParams = "invalid pagination parameters" // ErrInvalidSummaryParam is the error message returned when the summary parameter is invalid. ErrInvalidSummaryParam = "invalid summary parameter" // ErrInvalidKeyOnlyParam is the error message returned when the keyonly parameter is invalid. ErrInvalidKeyOnlyParam = "invalid keyonly parameter" // ErrInvalidLatestParam is the error message returned when the latest parameter is invalid. ErrInvalidLatestParam = "invalid latest parameter" // ErrInvalidDaysParam is the error message returned when the days parameter is out of range. ErrInvalidDaysParam = "invalid days parameter" // ErrInvalidTimeRangeParams is the error message returned when only one of the time range boundaries is provided. ErrInvalidTimeRangeParams = "both start_time and end_time must be provided" // ErrInvalidMetricParam is the error message returned when the requested summary metric is not supported. ErrInvalidMetricParam = "invalid metric parameter" // ErrInvalidGranularityParam is the error message returned when the requested summary granularity is not supported. ErrInvalidGranularityParam = "invalid granularity parameter" // ErrTimeRangeTooWide is the error message returned when the requested time range spans more // than maxMonitoringDurationDays days. ErrTimeRangeTooWide = "requested time range exceeds the maximum allowed span" // ErrInvalidHoursParam is the error message returned when the hours parameter is out of range. ErrInvalidHoursParam = "invalid hours parameter" // ErrConflictingWindowParams is the error message returned when both days and hours are provided. ErrConflictingWindowParams = "days and hours cannot be combined" // ErrTooManyBuckets is the error message returned when the requested time range and granularity // would produce more than maxSummaryBuckets entries. ErrTooManyBuckets = "requested time range and granularity produce too many buckets" ErrInvalidJWT = "JWT is invalid" // ErrInternal is returned instead of the details of an error which the caller cannot // do anything about, and which may describe the database. ErrInternal = "internal server error" // ErrReportNotFound is returned when the requested pipeline report does not exist. ErrReportNotFound = "report not found" // ErrUnauthenticated is returned when a request carries no usable credential. ErrUnauthenticated = "authentication required" // ErrInsufficientPermission is returned when the caller is authenticated but not // privileged enough for the endpoint. ErrInsufficientPermission = "insufficient permission" // ErrInsufficientScope is returned when the token used is not allowed to perform // the requested action, even though the identity behind it would be. ErrInsufficientScope = "token is not allowed to perform this action" // ErrTokenCannotMintToken is returned when an API token is used to create another // one, which must require an identity provider login. ErrTokenCannotMintToken = "creating a token requires signing in, it cannot be done with a token" // ErrTokenNotFound is returned when the requested API token does not exist, or // belongs to somebody else. ErrTokenNotFound = "token not found" // ErrInvalidTokenRequest is returned when a token creation request is malformed. ErrInvalidTokenRequest = "invalid token request" )
const APIPrefix = "/api/v1beta1"
APIPrefix is where the versioned API is served.
const APITokenPrefix = "udash_pat_"
APITokenPrefix marks a bearer token as one Udash issued itself.
The prefix is what lets the middleware tell an Udash token from an identity provider one without having to try both, and lets secret scanners recognize one if it ever leaks into a public repository.
Variables ¶
This section is empty.
Functions ¶
func About ¶
About returns the version information of the API. @Summary About the API @Description Get version information of the API @Tags About @Success 200 {object} AboutResponseModel @Router /api/about [get]
func AcknowledgeAction ¶ added in v0.20.0
AcknowledgeAction hides an open action, such as a pull request somebody is handling @Summary Acknowledge an open action @Description Leave an open action out of the search for a number of days, or until the worst result of its pipelines is no longer the given one @Tags Pipeline Actions @Accept json @Produce json @Success 204 @Failure 400 {object} DefaultResponseModel @Failure 401 {object} DefaultResponseModel @Failure 403 {object} DefaultResponseModel @Failure 500 {object} DefaultResponseModel @Router /api/v1beta1/pipeline/actions/ack [put]
func CreateAPIToken ¶ added in v0.17.1
CreateAPIToken issues a new API token.
@Summary Create an API token @Description Issue a long lived token to authenticate against the Udash API. The token is returned once and cannot be recovered afterwards. @Tags Tokens @Accept json @Produce json @Param request body CreateTokenRequest true "token to create" @Success 201 {object} CreateTokenResponse @Failure 400 {object} DefaultResponseModel @Failure 401 {object} DefaultResponseModel @Failure 403 {object} DefaultResponseModel @Security BearerAuth @Router /api/v1beta1/tokens [post]
func CreatePipelineReport ¶
CreatePipelineReport insert a new report into the database @Summary Create a new pipeline report @Description Create a new pipeline report in the database @Tags Pipeline Reports @Accept json @Produce json @Success 201 {object} CreatePipelineReportResponse @Failure 400 {object} DefaultResponseModel @Failure 500 {object} DefaultResponseModel @Router /api/v1beta1/pipeline/reports [post]
func DeleteAPIToken ¶ added in v0.17.1
DeleteAPIToken revokes an API token.
@Summary Revoke an API token @Description Revoke one of the caller's API tokens. Administrators may revoke anybody's. @Tags Tokens @Produce json @Param id path string true "token id" @Success 200 {object} DefaultResponseModel @Failure 401 {object} DefaultResponseModel @Failure 404 {object} DefaultResponseModel @Security BearerAuth @Router /api/v1beta1/tokens/{id} [delete]
func DeleteAPITokensBySubject ¶ added in v0.17.1
DeleteAPITokensBySubject revokes every token of an identity.
@Summary Revoke every token of an identity @Description Revoke all API tokens created by a given identity, which is what offboarding somebody needs. Administrators only. @Tags Tokens @Produce json @Param subject query string true "identity provider subject" @Success 200 {object} DefaultResponseModel @Failure 400 {object} DefaultResponseModel @Failure 403 {object} DefaultResponseModel @Security BearerAuth @Router /api/v1beta1/tokens [delete]
func DeleteConfigCondition ¶ added in v0.9.0
DeleteConfigCondition deletes a resource configuration from the database.
func DeleteConfigSource ¶ added in v0.9.0
DeleteConfigSource deletes a resource configuration from the database.
func DeleteConfigTarget ¶ added in v0.9.0
DeleteConfigTarget deletes a resource configuration from the database.
func DeletePipelineReport ¶
DeletePipelineReport removes a pipeline report from the database @Summary Delete a pipeline report @Description Delete a pipeline report from the database @Tags Pipeline Reports @Param id path string true "Report ID" @Success 200 {object} DefaultResponseModel @Failure 500 {object} DefaultResponseModel @Router /api/v1beta1/pipeline/reports/{id} [delete]
func GetPipelineReportByID ¶ added in v0.9.0
GetPipelineReportByID returns the latest pipeline report for a specific ID @Summary Get a pipeline report by ID @Description Get the latest pipeline report for a specific ID @Tags Pipeline Reports @Param id path string true "Report ID" @Success 200 {object} GetPipelineReportByIDResponse @Failure 404 {object} DefaultResponseModel @Failure 500 {object} DefaultResponseModel @Router /api/v1beta1/pipeline/reports/{id} [get]
func Landing ¶
Landing is the landing page handler. @Summary Landing page @Description Landing page of the API @Tags Landing @Success 200 @Router /api [get]
func ListAPITokens ¶ added in v0.17.1
ListAPITokens returns the caller's API tokens.
@Summary List API tokens @Description List the caller's API tokens. Administrators may list everybody's with all=true. The tokens themselves are never returned. @Tags Tokens @Produce json @Param all query bool false "list every identity's tokens, administrators only" @Success 200 {array} model.APIToken @Failure 401 {object} DefaultResponseModel @Security BearerAuth @Router /api/v1beta1/tokens [get]
func ListConfigConditions ¶ added in v0.9.0
ListConfigConditions returns condition configurations from the database. @Summary List all configuration conditions @Description List all configuration conditions from the database @Tags Configuration Conditions @Param id query string false "ID of the configuration condition" @Param kind query string false "Kind of the configuration condition" @Param config query string false "Configuration of the condition" @Param limit query string false "Limit the number of reports returned, default is 100" @Param page query string false "Page number for pagination, default is 1" @Success 200 {object} ConditionConfigResponse @Failure 500 {object} DefaultResponseModel @Router /api/v1beta1/pipeline/config/conditions [get]
func ListConfigSources ¶ added in v0.9.0
ListConfigSources returns a resource configuration from the database. @Summary List all configuration sources @Description List all configuration sources from the database @Tags Configuration Sources @Param id query string false "ID of the configuration source" @Param kind query string false "Kind of the configuration source" @Param config query string false "Configuration of the source" @Param limit query string false "Limit the number of reports returned, default is 100" @Param page query string false "Page number for pagination, default is 1" @Success 200 {object} SourceConfigResponse @Failure 500 {object} DefaultResponseModel @Router /api/v1beta1/pipeline/config/sources [get]
func ListConfigTargets ¶ added in v0.9.0
ListConfigTargets returns target configurations from the database. @Summary List all target configurations. @Description List all configuration targets from the database @Tags Configuration Targets @Param id query string false "ID of the configuration target" @Param kind query string false "Kind of the configuration target" @Param config query string false "Configuration of the target" @Param limit query string false "Limit the number of reports returned, default is 100" @Param page query string false "Page number for pagination, default is 1" @Success 200 {object} TargetConfigResponse @Failure 500 {object} DefaultResponseModel @Router /api/v1beta1/pipeline/config/targets [get]
func ListLabels ¶ added in v0.14.0
ListLabels returns a list of labels from the database. @Summary List labels @Description List labels data from the database with optional filtering @Tags Labels @Param id query string false "Filter by label ID" @Param key query string false "Filter by label key" @Param value query string false "Filter by label value" @Param keyonly query string false "Return only unique label keys (true/false)" @Param limit query string false "Limit the number of labels returned, default is 100" @Param page query string false "Page number for pagination, default is 1" @Param start_time query string false "Start time for filtering labels (RFC3339 format)" @Param end_time query string false "End time for filtering labels (RFC3339 format)" @Success 200 {object} ListLabelsResponse @Failure 400 {object} DefaultResponseModel @Failure 500 {object} DefaultResponseModel @Router /api/v1beta1/pipeline/labels [get]
func ListPipelineReports ¶ added in v0.9.0
ListPipelineReports returns all pipeline reports from the database @Summary List all pipeline reports @Description List all pipeline reports from the database @Tags Pipeline Reports @Param scmid query string false "SCM ID" @Param limit query string false "Limit the number of reports returned, default is 100" @Param page query string false "Page number for pagination, default is 1" @Param start_time query string false "Start time for filtering reports (RFC3339 format)" @Param end_time query string false "End time for filtering reports (RFC3339 format)" @Param latest query string false "Only return the latest report per pipeline ID, default is true" @Accept json @Produce json @Success 200 {object} GetPipelineReportsResponse @Failure 400 {object} DefaultResponseModel @Failure 500 {object} DefaultResponseModel @Router /api/v1beta1/pipeline/reports [get]
func ListSCMs ¶ added in v0.9.0
ListSCMs returns a list of SCMs from the database. @Summary List SCMs @Description List SCMs data from the database @Tags SCMs @Param scmid query string false "ID of the SCM" @Param url query string false "URL of the SCM" @Param branch query string false "Branch of the SCM" @Param summary query bool false "Return a summary of the SCMs" @Param limit query string false "Limit the number of reports returned, default is 100" @Param page query string false "Page number for pagination, default is 1" @Param start_time query string false "Start time for filtering SCMs (RFC3339 format)" @Param end_time query string false "End time for filtering SCMs (RFC3339 format)" @Success 200 {object} ListSCMsResponse @Failure 400 {object} DefaultResponseModel @Failure 500 {object} DefaultResponseModel @Router /api/v1beta1/pipeline/scms [get]
func Ping ¶
Ping is a simple endpoint to check if the server is running. @Summary Ping the API @Description Ping the API to check if it's running @Tags Ping @Success 200 {object} DefaultResponseModel @Router /api/ping [get]
func Ready ¶ added in v0.21.0
Ready checks that the API can serve requests, which requires the database. @Summary Readiness of the API @Description Check that the API and its database are ready to serve requests @Tags Ping @Success 200 {object} DefaultResponseModel @Failure 503 {object} DefaultResponseModel @Router /api/ready [get]
func SearchConfigConditions ¶ added in v0.9.0
SearchConfigConditions returns condition configurations from the database. @Summary Search configuration conditions @Description Search for configuration conditions in the database @Tags Configuration Conditions @Accept json @Produce json @Success 200 {object} ConditionConfigResponse @Failure 400 {object} DefaultResponseModel @Failure 500 {object} DefaultResponseModel @Router /api/v1beta1/pipeline/config/conditions/search [post]
func SearchConfigKinds ¶ added in v0.9.0
SearchConfigKinds returns a resource configuration from the database. @Summary Search configuration by kind @Description Search for configuration by kind in the database @Tags Configuration @Accept json @Produce json @Success 200 {object} ConfigKindResponse @Failure 400 {object} DefaultResponseModel @Failure 500 {object} DefaultResponseModel @Router /api/v1beta1/pipeline/config/kinds [get]
func SearchConfigSources ¶ added in v0.9.0
SearchConfigSources returns a resource configuration from the database. @Summary Search configuration sources @Description Search for configuration sources in the database @Tags Configuration Sources @Accept json @Produce json @Success 200 {object} SourceConfigResponse @Failure 400 {object} DefaultResponseModel @Failure 500 {object} DefaultResponseModel @Router /api/v1beta1/pipeline/config/sources/search [post]
func SearchConfigTargets ¶ added in v0.9.0
SearchConfigTargets returns target configurations from the database. @Summary Search configuration targets @Description Search for configuration targets in the database @Tags Configuration Targets @Accept json @Produce json @Success 200 {object} TargetConfigResponse @Failure 400 {object} DefaultResponseModel @Failure 500 {object} DefaultResponseModel @Router /api/v1beta1/pipeline/config/targets/search [post]
func SearchLabels ¶ added in v0.14.0
SearchLabels searches labels from the database using advanced filtering @Summary Search labels @Description Search labels in the database using advanced filtering @Param body body SearchLabelsRequest true "Search parameters" @Tags Labels @Accept json @Produce json @Success 200 {object} ListLabelsResponse @Failure 400 {object} DefaultResponseModel @Failure 500 {object} DefaultResponseModel @Router /api/v1beta1/pipeline/labels/search [post]
func SearchOpenActions ¶ added in v0.19.0
SearchOpenActions returns the actions left open, such as pull requests waiting to be merged @Summary Search open actions @Description Search the actions left open by the latest report of every pipeline, one entry per action URL along with the pipelines feeding it @Tags Pipeline Actions @Accept json @Produce json @Success 200 {object} SearchOpenActionsResponse @Failure 400 {object} DefaultResponseModel @Failure 500 {object} DefaultResponseModel @Router /api/v1beta1/pipeline/actions/search [post]
func SearchPipelineReports ¶ added in v0.9.0
SearchPipelineReports returns all pipeline reports from the database using advanced filtering @Summary Search pipeline reports @Description Search pipeline reports in the database using advanced filtering @Param limit query string false "Limit the number of reports returned, default is 100" @Param page query string false "Page number for pagination, default is 1" @Tags Pipeline Reports @Accept json @Produce json @Success 200 {object} GetPipelineReportsResponse @Failure 400 {object} DefaultResponseModel @Failure 500 {object} DefaultResponseModel @Router /api/v1beta1/pipeline/reports/search [post]
func SearchPipelineReportsSummary ¶ added in v0.16.0
SearchPipelineReportsSummary returns the number of pipeline reports per result, per time bucket. @Summary Summarize pipeline reports @Description Return the number of pipeline reports per result for each time bucket of the requested time range. @Description Buckets are UTC hours, UTC calendar days, ISO weeks or calendar months depending on the @Description granularity, and the date of an entry is the start of its bucket, formatted as RFC3339. @Description Every report is counted, including several reports of the same pipeline, and buckets without @Description any report are returned with a zeroed entry. @Tags Pipeline Reports @Accept json @Produce json @Param body body SearchPipelineReportsSummaryRequest true "Summary filters" @Success 200 {object} SearchPipelineReportsSummaryResponse @Failure 400 {object} DefaultResponseModel @Failure 500 {object} DefaultResponseModel @Router /api/v1beta1/pipeline/reports/summary [post]
func SearchSCMs ¶ added in v0.14.0
SearchSCMs searches SCMs using JSON filters. @Summary Search SCMs @Description Search SCM data using JSON filters. When summary is true, the response contains SCM summary data for all matching SCMs. @Tags SCMs @Accept json @Produce json @Param body body SearchSCMsRequest true "SCM search filters" @Success 200 {object} ListSCMsResponse @Failure 400 {object} DefaultResponseModel @Failure 500 {object} DefaultResponseModel @Router /api/v1beta1/pipeline/scms/search [post]
func UnacknowledgeAction ¶ added in v0.20.0
UnacknowledgeAction removes the acknowledgement of an open action @Summary Unacknowledge an open action @Description Bring an acknowledged open action back in the search @Tags Pipeline Actions @Produce json @Param url query string true "Link of the action" @Success 204 @Failure 400 {object} DefaultResponseModel @Failure 401 {object} DefaultResponseModel @Failure 403 {object} DefaultResponseModel @Failure 500 {object} DefaultResponseModel @Router /api/v1beta1/pipeline/actions/ack [delete]
func UpdatePipelineReport ¶
UpdatePipelineReport updates a pipeline report in the database Note: This endpoint is not supported yet. @Summary Update a pipeline report @Description Update a pipeline report in the database. Please note that this endpoint is not supported yet. @Tags Pipeline Reports @Param id path string true "Report ID" @Accept json @Produce json @Success 200 {object} DefaultResponseModel @Router /api/v1beta1/pipeline/reports/{id} [put]
func Whoami ¶ added in v0.17.1
Whoami describes the identity behind the credential used.
@Summary Describe the current identity @Description Return the identity, permission and token scopes behind the credential used. Updatecli calls it to validate a token at login time. @Tags Tokens @Produce json @Success 200 {object} WhoamiResponse @Failure 401 {object} DefaultResponseModel @Security BearerAuth @Router /api/v1beta1/whoami [get]
Types ¶
type AboutResponseModel ¶ added in v0.9.0
type AuthOptions ¶
type AuthOptions struct {
// Mode selects how incoming tokens are validated.
// Accepted values are: "oidc", "zitadel", "none"
// Default to "none"
Mode string
// Zitadel holds Zitadel specific options
Zitadel ZitadelOptions
// OIDC holds generic OpenID Connect options
OIDC OIDCOptions
// Roles maps identity provider roles onto Udash permissions
Roles RolesOptions
// Visibility defines the visibility of the API
// Accepted values are: "public", "private"
// Default to "public"
Visibility string
}
AuthOptions holds every authentication and authorization setting.
func (*AuthOptions) Init ¶
func (a *AuthOptions) Init() error
Init fills in the defaults and the environment variable fallbacks, and reports what it cannot make sense of.
An error here must stop the server: carrying on with an unusable configuration leaves the API unauthenticated, which is the opposite of what was asked for.
type ConditionConfigResponse ¶ added in v0.9.0
type ConditionConfigResponse struct {
// Configs is a list of configuration conditions.
Configs []model.ConfigCondition `json:"configs"`
// TotalCount is the total number of conditions for pagination.
TotalCount int `json:"total_count"`
}
ConditionConfigResponse represents a response containing configuration conditions.
type ConfigKindResponse ¶ added in v0.9.0
type ConfigKindResponse struct {
Data []string `json:"data"`
}
ConfigKindResponse represents a response containing configuration kinds.
type CreatePipelineReportResponse ¶ added in v0.9.0
type CreateTokenRequest ¶ added in v0.17.1
type CreateTokenRequest struct {
// Name is what the token is for, shown back in the token list.
Name string `json:"name" binding:"required"`
// Scopes is what the token may do. It defaults to publishing reports, and may
// never exceed what the identity creating it is allowed to do.
Scopes []string `json:"scopes,omitempty"`
// ExpiresAt is when the token stops working. Leave it out for a token which
// never expires, which is what an unattended pipeline needs.
ExpiresAt *time.Time `json:"expires_at,omitempty"`
}
CreateTokenRequest is the body of a token creation request.
type CreateTokenResponse ¶ added in v0.17.1
type CreateTokenResponse struct {
model.APIToken
// Token is the credential itself. It is returned here once and never again:
// only its hash is stored.
Token string `json:"token"`
}
CreateTokenResponse carries the newly created token.
type CustomClaims ¶
type CustomClaims struct {
Name string `json:"name"`
Username string `json:"username"`
ShouldReject bool `json:"shouldReject,omitempty"`
// All keeps every claim of the token, including the ones above.
//
// Which claim carries the identity provider roles is configuration, not
// something that can be named in a struct tag: Zitadel, Keycloak and Auth0
// each use a different one. See RolesOptions.Claim.
All map[string]interface{} `json:"-"`
}
CustomClaims contains custom data we want from the jwt token.
func (*CustomClaims) UnmarshalJSON ¶ added in v0.17.1
func (c *CustomClaims) UnmarshalJSON(data []byte) error
UnmarshalJSON decodes the named claims and keeps the raw ones alongside.
type DefaultResponseModel ¶ added in v0.9.0
type FindSCMSummaryResponse ¶ added in v0.9.0
type FindSCMSummaryResponse struct {
TotalCount int `json:"total_count"`
Data map[string]database.SCMBranchDataset `json:"data"`
}
FindSCMSummaryResponse represents the response for the FindSCMSummary endpoint.
type GetPipelineReportByIDResponse ¶ added in v0.9.0
type GetPipelineReportByIDResponse struct {
Message string `json:"message"`
Data model.PipelineReport `json:"data"`
NBReportsByID int `json:"nbReportsByID"`
LatestReportByID model.PipelineReport `json:"latestReportByID"`
}
type GetPipelineReportsResponse ¶ added in v0.9.0
type GetPipelineReportsResponse struct {
Data []database.SearchLatestReportData `json:"data"`
TotalCount int `json:"total_count"`
}
type Interceptor ¶ added in v0.12.0
type Interceptor[T authorization.Ctx] struct { // contains filtered or unexported fields }
func NewZitadelGin ¶ added in v0.12.0
func NewZitadelGin[T authorization.Ctx](authorizer *authorization.Authorizer[T], roles RolesOptions) *Interceptor[T]
func (*Interceptor[T]) Context ¶ added in v0.12.0
func (i *Interceptor[T]) Context(ctx context.Context) T
func (*Interceptor[T]) RequireAuthorization ¶ added in v0.12.0
func (i *Interceptor[T]) RequireAuthorization(options ...authorization.CheckOption) gin.HandlerFunc
type ListLabelKeyOnlyResponse ¶ added in v0.14.0
type ListLabelKeyOnlyResponse struct {
// Labels is a list of labels.
Labels []string `json:"labels"`
// TotalCount is the total number of labels matching the query.
TotalCount int `json:"total_count"`
}
ListLabelKeyOnlyResponse represents the response for listing all available labels
type ListLabelsResponse ¶ added in v0.14.0
type ListLabelsResponse struct {
// Labels is a list of labels.
Labels []model.Label `json:"labels"`
// TotalCount is the total number of labels matching the query.
TotalCount int `json:"total_count"`
}
ListLabelsResponse represents the response for the ListLabels endpoint.
type ListSCMsResponse ¶ added in v0.9.0
type ListSCMsResponse struct {
// SCMs is a list of SCMs.
SCMs []model.SCM `json:"scms"`
// TotalCount is the total number of SCMs matching the query.
TotalCount int `json:"total_count"`
}
ListSCMsResponse represents the response for the ListSCMs endpoint.
type OIDCOptions ¶ added in v0.17.1
type OIDCOptions struct {
// The issuer of our token.
Issuer string
// The audience of our token.
Audience []string
}
OIDCOptions defines the settings of the generic OpenID Connect mode. It works with any provider issuing JWT access tokens, Zitadel included.
type Permission ¶ added in v0.17.1
type Permission string
Permission is what an identity is allowed to do in Udash.
const ( // PermissionNone is granted to an unauthenticated request. PermissionNone Permission = "" // PermissionViewer may read pipeline reports. PermissionViewer Permission = "viewer" // PermissionPublisher may publish pipeline reports and create API tokens. PermissionPublisher Permission = "publisher" // PermissionAdmin may do anything, including managing other identities' tokens. PermissionAdmin Permission = "admin" )
func ParsePermission ¶ added in v0.17.1
func ParsePermission(s string) Permission
ParsePermission turns a configured string into a Permission. An unknown value yields PermissionNone, which IsValid rejects.
func (Permission) AtLeast ¶ added in v0.17.1
func (p Permission) AtLeast(other Permission) bool
AtLeast reports whether p grants everything other does.
func (Permission) IsValid ¶ added in v0.17.1
func (p Permission) IsValid() bool
IsValid reports whether the permission is one Udash knows about.
func (Permission) Scopes ¶ added in v0.17.1
func (p Permission) Scopes() []string
Scopes returns the token scopes this permission is allowed to hand out. A token can never be granted more than the identity which created it, and never gets to manage tokens: a token must not be able to mint another one.
type Principal ¶ added in v0.17.1
type Principal struct {
// Subject is the identity provider subject.
Subject string
// Name is a human readable name for that identity, when the provider gives one.
Name string
// Permission is what that identity may do, after intersecting the identity
// provider roles with the scopes of the token in use.
Permission Permission
// TokenID is set only when the request authenticated with an Udash API token.
TokenID *uuid.UUID
// TokenName is the name of that token.
TokenName string
// Scopes is what that token may do. It is nil for an identity provider token,
// which is bounded by its Permission alone.
Scopes []string
}
Principal is the identity behind a request.
type RoleResolver ¶ added in v0.17.1
type RoleResolver interface {
// Resolve returns the current permission of the given subject. The recorded
// permission is what was granted when the token was created, and is what a
// resolver returns when it cannot do better.
Resolve(ctx context.Context, subject string, recorded Permission) (Permission, error)
}
RoleResolver reports what an identity may currently do, given only its subject.
It exists for requests authenticating with an Udash API token: those carry no identity provider token, so there are no claims to read the roles from.
type RolesOptions ¶ added in v0.17.1
type RolesOptions struct {
// Claim is the token claim holding the identity provider roles. Providers
// disagree both on the name and on the shape: Zitadel uses an object keyed by
// role name, Keycloak and Auth0 use an array of strings. Both are accepted.
Claim string
// Mapping lists, per Udash permission, the identity provider roles granting it.
Mapping map[string][]string
// Default is the permission granted to an authenticated identity matching no
// role at all. It deliberately defaults to the least privileged one.
Default string
// Resolver decides how the permission behind an Udash API token is resolved,
// since such a request carries no identity provider token to read roles from.
Resolver string
// CacheTTL is how long a resolved permission is reused before being looked up
// again. Without it a publish heavy pipeline would query the identity provider
// on every single report.
CacheTTL time.Duration
}
RolesOptions describes how the roles carried by a token become Udash permissions.
type SearchLabelsRequest ¶ added in v0.16.0
type SearchLabelsRequest struct {
// Id is the unique identifier of the label.
Id string `json:"id"`
// Key is the key of the label.
Key string `json:"key"`
// Value is the value of the label.
Value string `json:"value"`
// Limit is the maximum number of labels to return
// This is optional and can be used to limit the number of labels returned
Limit int `json:"limit"`
// Page is the page number for pagination
// This is optional and can be used to paginate the results
Page int `json:"page"`
// StartTime is the start time for the time range filter
// This is optional and can be used to filter labels by a specific start time
// Time format is RFC3339: 2006-01-02T15:04:05Z07:00
StartTime string `json:"start_time"`
// EndTime is the end time for the time range filter
// This is optional and can be used to filter labels by a specific end time
// Time format is RFC3339: 2006-01-02T15:04:05Z07:00
EndTime string `json:"end_time"`
// KeyOnly specifies if we only need to retrieve a list of uniq Label keys
KeyOnly bool `json:"key_only"`
}
SearchLabelsRequest represents the filters used to search labels.
type SearchOpenActionsResponse ¶ added in v0.19.0
type SearchOpenActionsResponse struct {
Data []database.OpenActionData `json:"data"`
// TotalCount counts the actions matching the request, across every page.
TotalCount int `json:"total_count"`
// AcknowledgedCount counts the acknowledged actions, whatever the request asked for.
AcknowledgedCount int `json:"acknowledged_count"`
}
type SearchPipelineReportsSummaryRequest ¶ added in v0.16.0
type SearchPipelineReportsSummaryRequest struct {
// Metric is what the reports are counted by. It defaults to "result", which is
// the only value supported so far.
Metric string `json:"metric,omitempty"`
// Granularity is the size of the time buckets, one of "hour", "day", "week" or
// "month". It defaults to "day".
Granularity string `json:"granularity,omitempty"`
// Days is the number of days to summarize, today included.
// It defaults to 7 and is ignored when hours, or start_time and end_time, are provided.
Days int `json:"days,omitempty"`
// Hours is the number of hours to summarize, the current hour included.
// It cannot be combined with days and is ignored when start_time and end_time are provided.
Hours int `json:"hours,omitempty"`
// ScmID is the ID of the SCM to filter reports by.
// Use "none" to only count the reports which are not attached to any SCM.
ScmID string `json:"scmid,omitempty"`
// Labels is a map of labels to filter reports by.
Labels map[string]string `json:"labels,omitempty"`
// Results is a list of pipeline results to filter reports by, such as
// "✔", "✗", "⚠" or "-". A report is counted when its result is any of them.
// An empty list does not filter anything out.
Results []string `json:"results,omitempty"`
// OpenAction filters reports by whether they carry an action left open, such as a
// pull request still waiting to be merged. This is optional: unset does not filter
// anything out, true only counts the reports with an open action and false only the
// ones without.
//
// The same breakdown is reported without filtering anything out under the open_actions
// key of every bucket.
OpenAction *bool `json:"open_action,omitempty"`
// StartTime is the start time for the time range filter.
// Time format is: 2006-01-02 15:04:05Z07:00
StartTime string `json:"start_time,omitempty"`
// EndTime is the end time for the time range filter.
// Time format is: 2006-01-02 15:04:05Z07:00
EndTime string `json:"end_time,omitempty"`
}
SearchPipelineReportsSummaryRequest represents the filters used to summarize pipeline reports.
type SearchPipelineReportsSummaryResponse ¶ added in v0.16.0
type SearchPipelineReportsSummaryResponse struct {
// Metric is the metric the reports were counted by.
Metric string `json:"metric"`
// Granularity is the size of the time buckets of the entries.
Granularity string `json:"granularity"`
// Data contains one entry per time bucket, ordered from the oldest to the most recent one.
Data []database.ReportResultSummaryEntry `json:"data"`
// TotalCount is the total number of reports matching the query.
TotalCount int `json:"total_count"`
}
SearchPipelineReportsSummaryResponse represents the response for the SearchPipelineReportsSummary endpoint.
type SearchSCMsRequest ¶ added in v0.14.0
type SearchSCMsRequest struct {
// ScmID is the ID of the SCM to filter by.
ScmID string `json:"scmid"`
// StartTime is the start time for the time range filter.
// Time format is RFC3339: 2006-01-02T15:04:05Z07:00
StartTime string `json:"start_time"`
// EndTime is the end time for the time range filter.
// Time format is RFC3339: 2006-01-02T15:04:05Z07:00
EndTime string `json:"end_time"`
// Labels filters SCM summaries by report labels.
Labels map[string]string `json:"labels,omitempty"`
// Results filters SCM summaries by pipeline result, such as "✔", "✗", "⚠" or
// "-". An empty list does not filter anything out.
Results []string `json:"results,omitempty"`
// OpenAction filters SCM summaries by whether a pipeline carries an action left open,
// such as a pull request still waiting to be merged. This is optional: unset does not
// filter anything out, true only keeps the pipelines with an open action and false only
// the ones without.
OpenAction *bool `json:"open_action,omitempty"`
// URL is the SCM URL to filter by.
URL string `json:"url,omitempty"`
// Branch is the SCM branch to filter by.
Branch string `json:"branch,omitempty"`
// Summary indicates if the response should contain SCM summary data.
Summary bool `json:"summary,omitempty"`
// Limit is the maximum number of SCMs to return.
Limit int `json:"limit,omitempty"`
// Page is the page number for pagination.
Page int `json:"page,omitempty"`
}
SearchSCMsRequest represents the filters used to search SCM records.
type Server ¶
type Server struct {
Options Options
}
func (*Server) Run ¶
@title Udash API @version v1beta1 @description API for managing Updatecli pipeline reports. @securityDefinitions.apikey BearerAuth @in header @name Authorization @description Either an Udash API token, created from the tokens page and prefixed with "udash_pat_", or an access token from the configured identity provider. Send it as "Bearer <token>".
type SourceConfigResponse ¶ added in v0.9.0
type SourceConfigResponse struct {
// Configs is a list of configuration sources.
Configs []model.ConfigSource `json:"configs"`
// TotalCount is the total number of sources for pagination.
TotalCount int `json:"total_count"`
}
SourceConfigResponse represents a response containing configuration sources.
type TargetConfigResponse ¶ added in v0.9.0
type TargetConfigResponse struct {
// Configs is a list of configuration targets.
Configs []model.ConfigTarget `json:"configs"`
// TotalCount is the total number of targets for pagination.
TotalCount int `json:"total_count"`
}
TargetConfigResponse represents a response containing configuration targets.
type WhoamiResponse ¶ added in v0.17.1
type WhoamiResponse struct {
Subject string `json:"subject,omitempty"`
Name string `json:"name,omitempty"`
Permission string `json:"permission,omitempty"`
TokenName string `json:"tokenName,omitempty"`
Scopes []string `json:"scopes,omitempty"`
}
WhoamiResponse describes the identity behind the credential used.
type ZitadelOptions ¶ added in v0.12.0
type ZitadelOptions struct {
// Domain is the Zitadel domain
// example: xxx.region.zitadel.cloud
Domain string
// KeyFile is the path to the service account key file
// example: /path/to/key.json
KeyFile string
}
ZitadelOptions defines Zitadel specific options for authentication