@Singleton public class

CommitInsightResource

extends AbstractInsightResource
java.lang.Object
   ↳ com.atlassian.bitbucket.rest.RestResource
     ↳ com.atlassian.bitbucket.internal.codeinsights.rest.AbstractInsightResource
       ↳ com.atlassian.bitbucket.internal.codeinsights.rest.commit.CommitInsightResource

Summary

[Expand]
Inherited Constants
From class com.atlassian.bitbucket.internal.codeinsights.rest.AbstractInsightResource
[Expand]
Inherited Fields
From class com.atlassian.bitbucket.rest.RestResource
Public Constructors
CommitInsightResource(I18nService i18nService, InsightReportService insightReportService, InsightAnnotationService insightAnnotationService, Validator validator)
Public Methods
@EscalateAnonymous2LO Response addAnnotations(Repository repository, String commitId, String reportKey, RestBulkAddInsightAnnotationRequest request, String projectKey, String repoSlug)
Add annotations to the given report.
@EscalateAnonymous2LO Response delete(Repository repository, String commitId, String key, String projectKey, String repoSlug)
Delete a report for the given commit.
@EscalateAnonymous2LO Response deleteAnnotations(Repository repository, String commitId, String reportKey, Set<String> externalIds, String projectKey, String repoSlug)
Delete annotations for a given report that match the given external IDs, or all annotations if no external IDs are provided.
@EscalateAnonymous2LO Response get(Repository repository, String commitId, String key, String projectKey, String repoSlug)
Retrieve the specified report.
@EscalateAnonymous2LO Response getAnnotations(Repository repository, String commitId, List<String> externalIds, List<String> keys, List<String> paths, List<AnnotationSeverity> severities, List<AnnotationType> type, String projectKey, String repoSlug)
Get annotations for the given commit ID, filtered by any query parameters given.
@EscalateAnonymous2LO Response getAnnotations(Repository repository, String commitId, String key, String projectKey, String repoSlug)
Retrieve the specified report's annotations.
@EscalateAnonymous2LO Response getReports(Repository repository, String commitId, PageRequest pageRequest, String projectKey, String repoSlug)
Retrieve all reports for the given commit.
@EscalateAnonymous2LO Response set(Repository repository, String commitId, String key, RestSetInsightReportRequest request, String projectKey, String repoSlug)

Create a new insight report, or replace the existing one if a report already exists for the given repository, commit, and report key.

@EscalateAnonymous2LO Response setAnnotation(Repository repository, String commitId, String reportKey, String externalId, RestSingleAddInsightAnnotationRequest request, String projectKey, String repoSlug)
Create an annotation with the given external ID, or replace it if it already exists.
[Expand]
Inherited Methods
From class com.atlassian.bitbucket.internal.codeinsights.rest.AbstractInsightResource
From class com.atlassian.bitbucket.rest.RestResource
From class java.lang.Object

Public Constructors

public CommitInsightResource (I18nService i18nService, InsightReportService insightReportService, InsightAnnotationService insightAnnotationService, Validator validator)

Public Methods

@EscalateAnonymous2LO public Response addAnnotations (Repository repository, String commitId, String reportKey, RestBulkAddInsightAnnotationRequest request, String projectKey, String repoSlug)

Add annotations to the given report. The request should be a JSON object mapping the string "annotations" to an array of maps containing the annotation data, as described below. See also the example request.
A few things to note:

  • Annotations are an extension of a report, so a report must first exist in order to post annotations. Annotations are posted separately from the report, and can be posted in bulk using this endpoint.
  • Only the annotations that are on lines changed in the unified diff will be displayed. This means it is likely not all annotations posted will be displayed on the pull request It also means that if the user is viewing a side-by-side diff, commit diff or iterative review diff they will not be able to view the annotations.
  • A report cannot have more than 1000 annotations by default, however this property is congurable at an instance level. If the request would result in more than the maximum number of annotations being stored then the entire request is rejected and no new annotations are stored.
  • There is no de-duplication of annotations on Bitbucket so be sure that reruns of builds will first delete the report and annotations before creating them.
Annotation parameters
Parameter Description Required? Restrictions Type
path The path of the file on which this annotation should be placed. This is the path of the file relative to the git repository Yes String
line The line number that the annotation should belong to. For file-level annotations, the line number should be 0 Yes Non-negative integer Integer
message The message to display to users Yes The maximum length accepted is 2000 characters, however the user interface may truncate this value for display purposes. We recommend that the message is short and succinct, with further details available to the user if needed on the page linked to by the the annotation link. String
severity The severity of the annotation Yes One of: LOW, MEDIUM, HIGH String
link An http or https URL representing the location of the annotation in the external tool No String
type The type of annotation posted No One of: VULNERABILITY, CODE_SMELL, BUG String
externalId If the caller requires a link to get or modify this annotation, then an ID must be provided. It is not used or required by Bitbucket, but only by the annotation creator for updating or deleting this specific annotation. No A string value shorter than 450 characters String

Parameters
commitId The commit ID on which to record the annotation. This must be a full 40 character commit hash
reportKey The key of the report to which this annotation belongs
projectKey The project key
repoSlug The repository slug

@EscalateAnonymous2LO public Response delete (Repository repository, String commitId, String key, String projectKey, String repoSlug)

Delete a report for the given commit. Also deletes any annotations associated with this report.

Parameters
commitId The commit ID on which the report belongs. This must be a full 40 character commit hash
key The report key
projectKey The project key
repoSlug The repository slug

@EscalateAnonymous2LO public Response deleteAnnotations (Repository repository, String commitId, String reportKey, Set<String> externalIds, String projectKey, String repoSlug)

Delete annotations for a given report that match the given external IDs, or all annotations if no external IDs are provided.

Parameters
commitId The commit ID on which the report is recorded. This must be a full 40 character commit hash
reportKey The key of the report to which this annotation belongs
externalIds The external IDs for the annotations that are to be deleted. Can be specified more than once to delete by more than one external ID, or can be unspecified to delete all annotations
projectKey The project key
repoSlug The repository slug

@EscalateAnonymous2LO public Response get (Repository repository, String commitId, String key, String projectKey, String repoSlug)

Retrieve the specified report.

Parameters
commitId The commit ID on which the report is recorded. This must be a full 40 character commit hash
key The report key
projectKey The project key
repoSlug The repository slug

@EscalateAnonymous2LO public Response getAnnotations (Repository repository, String commitId, List<String> externalIds, List<String> keys, List<String> paths, List<AnnotationSeverity> severities, List<AnnotationType> type, String projectKey, String repoSlug)

Get annotations for the given commit ID, filtered by any query parameters given.

Parameters
commitId The commit ID on which the report is recorded. This must be a full 40 character commit hash
externalIds Return only annotations that have one of the provided external IDs. Can be specified more than once to filter by more than one external ID
keys Return only annotations that belong to one of the provided report keys. Can be specified more than once to filter by more than one report
paths Return only annotations that appear on one of the provided paths. Can be specified more than once to filter by more than one path
severities Return only annotations that have one of the given severities. Can be specified more than once to filter by more than one severity. Valid severities are LOW, MEDIUM and HIGH
type Return only annotations that have one of the given types. Can be specified more than once to filter by multiple types. Valid types are BUG, CODE_SMELL, and VULNERABILITY
projectKey The project key
repoSlug The repository slug
Returns
  • The annotations matching the given parameters

@EscalateAnonymous2LO public Response getAnnotations (Repository repository, String commitId, String key, String projectKey, String repoSlug)

Retrieve the specified report's annotations.

Parameters
commitId The commit ID on which the report is recorded. This must be a full 40 character commit hash
key The report key
projectKey The project key
repoSlug The repository slug

@EscalateAnonymous2LO public Response getReports (Repository repository, String commitId, PageRequest pageRequest, String projectKey, String repoSlug)

Retrieve all reports for the given commit.

Parameters
commitId The commit ID on which the report is recorded. This must be a full 40 character commit hash
projectKey The project key
repoSlug The repository slug
Returns
  • The reports for the given commit

@EscalateAnonymous2LO public Response set (Repository repository, String commitId, String key, RestSetInsightReportRequest request, String projectKey, String repoSlug)

Create a new insight report, or replace the existing one if a report already exists for the given repository, commit, and report key. A request to replace an existing report will be rejected if the authenticated user was not the creator of the specified report.

The report key should be a unique string chosen by the reporter and should be unique enough not to potentially clash with report keys from other reporters. We recommend using reverse DNS namespacing or a similar standard to ensure that collision is avoided.

Report parameters
Parameter Description Required? Restrictions Type
title A short string representing the name of the report Yes Max length: 450 characters (but we recommend that it is shorter so that the display is nicer) String
details A string to describe the purpose of the report. This string may contain escaped newlines and if it does it will display the content accordingly. No Max length: 2000 characters String
result Indicates whether the report is in a passed or failed state No One of: PASS, FAIL String
data An array of data fields (described below) to display information on the report No Maximum 6 data fields Array
reporter A string to describe the tool or company who created the report No Max length: 450 characters String
link A URL linking to the results of the report in an external tool. No Must be a valid http or https URL String
logoUrl A URL to the report logo. If none is provided, the default insights logo will be used. No Must be a valid http or https URL String
Data parameters

The data field on the report is an array with at most 6 data fields (JSON maps) containing information that is to be displayed on the report (see the request example).

Parameter Description Type
title A string describing what this data field represents String
type The type of data contained in the value field. If not provided, then the value will be detected as a boolean, number or string. One of: BOOLEAN, DATE, DURATION, LINK, NUMBER, PERCENTAGE, TEXT String
value A value based on the type provided. Either a raw value (string, number or boolean) or a map. See below.
Type Field Value Field Type Value Field Display
None/Omitted Number, String or Boolean (not an array or object) Plain text
BOOLEAN Boolean The value will be read as a JSON boolean and displayed as 'Yes' or 'No'.
DATE Number The value will be read as a JSON number in the form of a Unix timestamp (milliseconds) and will be displayed as a relative date if the date is less than one week ago, otherwise it will be displayed as an absolute date.
DURATION Number The value will be read as a JSON number in milliseconds and will be displayed in a human readable duration format.
LINK Object: {"linktext": "Link text here", "href": "https://link.to.annotation/in/external/tool"} The value will be read as a JSON object containing the fields "linktext" and "href" and will be displayed as a clickable link on the report.
NUMBER Number The value will be read as a JSON number and large numbers will be displayed in a human readable format (e.g. 14.3k).
PERCENTAGE Number (between 0 and 100) The value will be read as a JSON number between 0 and 100 and will be displayed with a percentage sign.
TEXT String The value will be read as a JSON string and will be displayed as-is

Parameters
commitId The commit ID on which the report is recorded. This must be a full 40 character commit hash
key A unique string representing the report as chosen by the reporter. This should be unique enough to not clash with other report's keys. To do this, we recommend namespacing the key using reverse DNS
request The request object containing the details of the report to create (see example)
projectKey The project key
repoSlug The repository slug
Returns
  • The newly created report

@EscalateAnonymous2LO public Response setAnnotation (Repository repository, String commitId, String reportKey, String externalId, RestSingleAddInsightAnnotationRequest request, String projectKey, String repoSlug)

Create an annotation with the given external ID, or replace it if it already exists. A request to replace an existing annotation will be rejected if the authenticated user was not the creator of the specified report.

Parameters
commitId The commit ID on which the annotation belongs. This must be a full 40 character commit hash
reportKey The key of the report to which this annotation belongs
externalId The external ID of the annotation that is to be updated or created
projectKey The project key
repoSlug The repository slug