checks.go

Documentation: github.com/google/go-github/v45/github

     1  // Copyright 2018 The go-github AUTHORS. All rights reserved.
     2  //
     3  // Use of this source code is governed by a BSD-style
     4  // license that can be found in the LICENSE file.
     5  
     6  package github
     7  
     8  import (
     9  	"context"
    10  	"fmt"
    11  )
    12  
    13  // ChecksService provides access to the Checks API in the
    14  // GitHub API.
    15  //
    16  // GitHub API docs: https://docs.github.com/en/rest/checks/
    17  type ChecksService service
    18  
    19  // CheckRun represents a GitHub check run on a repository associated with a GitHub app.
    20  type CheckRun struct {
    21  	ID           *int64          `json:"id,omitempty"`
    22  	NodeID       *string         `json:"node_id,omitempty"`
    23  	HeadSHA      *string         `json:"head_sha,omitempty"`
    24  	ExternalID   *string         `json:"external_id,omitempty"`
    25  	URL          *string         `json:"url,omitempty"`
    26  	HTMLURL      *string         `json:"html_url,omitempty"`
    27  	DetailsURL   *string         `json:"details_url,omitempty"`
    28  	Status       *string         `json:"status,omitempty"`
    29  	Conclusion   *string         `json:"conclusion,omitempty"`
    30  	StartedAt    *Timestamp      `json:"started_at,omitempty"`
    31  	CompletedAt  *Timestamp      `json:"completed_at,omitempty"`
    32  	Output       *CheckRunOutput `json:"output,omitempty"`
    33  	Name         *string         `json:"name,omitempty"`
    34  	CheckSuite   *CheckSuite     `json:"check_suite,omitempty"`
    35  	App          *App            `json:"app,omitempty"`
    36  	PullRequests []*PullRequest  `json:"pull_requests,omitempty"`
    37  }
    38  
    39  // CheckRunOutput represents the output of a CheckRun.
    40  type CheckRunOutput struct {
    41  	Title            *string               `json:"title,omitempty"`
    42  	Summary          *string               `json:"summary,omitempty"`
    43  	Text             *string               `json:"text,omitempty"`
    44  	AnnotationsCount *int                  `json:"annotations_count,omitempty"`
    45  	AnnotationsURL   *string               `json:"annotations_url,omitempty"`
    46  	Annotations      []*CheckRunAnnotation `json:"annotations,omitempty"`
    47  	Images           []*CheckRunImage      `json:"images,omitempty"`
    48  }
    49  
    50  // CheckRunAnnotation represents an annotation object for a CheckRun output.
    51  type CheckRunAnnotation struct {
    52  	Path            *string `json:"path,omitempty"`
    53  	StartLine       *int    `json:"start_line,omitempty"`
    54  	EndLine         *int    `json:"end_line,omitempty"`
    55  	StartColumn     *int    `json:"start_column,omitempty"`
    56  	EndColumn       *int    `json:"end_column,omitempty"`
    57  	AnnotationLevel *string `json:"annotation_level,omitempty"`
    58  	Message         *string `json:"message,omitempty"`
    59  	Title           *string `json:"title,omitempty"`
    60  	RawDetails      *string `json:"raw_details,omitempty"`
    61  }
    62  
    63  // CheckRunImage represents an image object for a CheckRun output.
    64  type CheckRunImage struct {
    65  	Alt      *string `json:"alt,omitempty"`
    66  	ImageURL *string `json:"image_url,omitempty"`
    67  	Caption  *string `json:"caption,omitempty"`
    68  }
    69  
    70  // CheckSuite represents a suite of check runs.
    71  type CheckSuite struct {
    72  	ID           *int64         `json:"id,omitempty"`
    73  	NodeID       *string        `json:"node_id,omitempty"`
    74  	HeadBranch   *string        `json:"head_branch,omitempty"`
    75  	HeadSHA      *string        `json:"head_sha,omitempty"`
    76  	URL          *string        `json:"url,omitempty"`
    77  	BeforeSHA    *string        `json:"before,omitempty"`
    78  	AfterSHA     *string        `json:"after,omitempty"`
    79  	Status       *string        `json:"status,omitempty"`
    80  	Conclusion   *string        `json:"conclusion,omitempty"`
    81  	CreatedAt    *Timestamp     `json:"created_at,omitempty"`
    82  	UpdatedAt    *Timestamp     `json:"updated_at,omitempty"`
    83  	App          *App           `json:"app,omitempty"`
    84  	Repository   *Repository    `json:"repository,omitempty"`
    85  	PullRequests []*PullRequest `json:"pull_requests,omitempty"`
    86  
    87  	// The following fields are only populated by Webhook events.
    88  	HeadCommit *Commit `json:"head_commit,omitempty"`
    89  }
    90  
    91  func (c CheckRun) String() string {
    92  	return Stringify(c)
    93  }
    94  
    95  func (c CheckSuite) String() string {
    96  	return Stringify(c)
    97  }
    98  
    99  // GetCheckRun gets a check-run for a repository.
   100  //
   101  // GitHub API docs: https://docs.github.com/en/rest/checks/runs#get-a-check-run
   102  func (s *ChecksService) GetCheckRun(ctx context.Context, owner, repo string, checkRunID int64) (*CheckRun, *Response, error) {
   103  	u := fmt.Sprintf("repos/%v/%v/check-runs/%v", owner, repo, checkRunID)
   104  	req, err := s.client.NewRequest("GET", u, nil)
   105  	if err != nil {
   106  		return nil, nil, err
   107  	}
   108  
   109  	req.Header.Set("Accept", mediaTypeCheckRunsPreview)
   110  
   111  	checkRun := new(CheckRun)
   112  	resp, err := s.client.Do(ctx, req, checkRun)
   113  	if err != nil {
   114  		return nil, resp, err
   115  	}
   116  
   117  	return checkRun, resp, nil
   118  }
   119  
   120  // GetCheckSuite gets a single check suite.
   121  //
   122  // GitHub API docs: https://docs.github.com/en/rest/checks/suites#get-a-check-suite
   123  func (s *ChecksService) GetCheckSuite(ctx context.Context, owner, repo string, checkSuiteID int64) (*CheckSuite, *Response, error) {
   124  	u := fmt.Sprintf("repos/%v/%v/check-suites/%v", owner, repo, checkSuiteID)
   125  	req, err := s.client.NewRequest("GET", u, nil)
   126  	if err != nil {
   127  		return nil, nil, err
   128  	}
   129  
   130  	req.Header.Set("Accept", mediaTypeCheckRunsPreview)
   131  
   132  	checkSuite := new(CheckSuite)
   133  	resp, err := s.client.Do(ctx, req, checkSuite)
   134  	if err != nil {
   135  		return nil, resp, err
   136  	}
   137  
   138  	return checkSuite, resp, nil
   139  }
   140  
   141  // CreateCheckRunOptions sets up parameters needed to create a CheckRun.
   142  type CreateCheckRunOptions struct {
   143  	Name        string            `json:"name"`                   // The name of the check (e.g., "code-coverage"). (Required.)
   144  	HeadSHA     string            `json:"head_sha"`               // The SHA of the commit. (Required.)
   145  	DetailsURL  *string           `json:"details_url,omitempty"`  // The URL of the integrator's site that has the full details of the check. (Optional.)
   146  	ExternalID  *string           `json:"external_id,omitempty"`  // A reference for the run on the integrator's system. (Optional.)
   147  	Status      *string           `json:"status,omitempty"`       // The current status. Can be one of "queued", "in_progress", or "completed". Default: "queued". (Optional.)
   148  	Conclusion  *string           `json:"conclusion,omitempty"`   // Can be one of "success", "failure", "neutral", "cancelled", "skipped", "timed_out", or "action_required". (Optional. Required if you provide a status of "completed".)
   149  	StartedAt   *Timestamp        `json:"started_at,omitempty"`   // The time that the check run began. (Optional.)
   150  	CompletedAt *Timestamp        `json:"completed_at,omitempty"` // The time the check completed. (Optional. Required if you provide conclusion.)
   151  	Output      *CheckRunOutput   `json:"output,omitempty"`       // Provide descriptive details about the run. (Optional)
   152  	Actions     []*CheckRunAction `json:"actions,omitempty"`      // Possible further actions the integrator can perform, which a user may trigger. (Optional.)
   153  }
   154  
   155  // CheckRunAction exposes further actions the integrator can perform, which a user may trigger.
   156  type CheckRunAction struct {
   157  	Label       string `json:"label"`       // The text to be displayed on a button in the web UI. The maximum size is 20 characters. (Required.)
   158  	Description string `json:"description"` // A short explanation of what this action would do. The maximum size is 40 characters. (Required.)
   159  	Identifier  string `json:"identifier"`  // A reference for the action on the integrator's system. The maximum size is 20 characters. (Required.)
   160  }
   161  
   162  // CreateCheckRun creates a check run for repository.
   163  //
   164  // GitHub API docs: https://docs.github.com/en/rest/checks/runs#create-a-check-run
   165  func (s *ChecksService) CreateCheckRun(ctx context.Context, owner, repo string, opts CreateCheckRunOptions) (*CheckRun, *Response, error) {
   166  	u := fmt.Sprintf("repos/%v/%v/check-runs", owner, repo)
   167  	req, err := s.client.NewRequest("POST", u, opts)
   168  	if err != nil {
   169  		return nil, nil, err
   170  	}
   171  
   172  	req.Header.Set("Accept", mediaTypeCheckRunsPreview)
   173  
   174  	checkRun := new(CheckRun)
   175  	resp, err := s.client.Do(ctx, req, checkRun)
   176  	if err != nil {
   177  		return nil, resp, err
   178  	}
   179  
   180  	return checkRun, resp, nil
   181  }
   182  
   183  // UpdateCheckRunOptions sets up parameters needed to update a CheckRun.
   184  type UpdateCheckRunOptions struct {
   185  	Name        string            `json:"name"`                   // The name of the check (e.g., "code-coverage"). (Required.)
   186  	DetailsURL  *string           `json:"details_url,omitempty"`  // The URL of the integrator's site that has the full details of the check. (Optional.)
   187  	ExternalID  *string           `json:"external_id,omitempty"`  // A reference for the run on the integrator's system. (Optional.)
   188  	Status      *string           `json:"status,omitempty"`       // The current status. Can be one of "queued", "in_progress", or "completed". Default: "queued". (Optional.)
   189  	Conclusion  *string           `json:"conclusion,omitempty"`   // Can be one of "success", "failure", "neutral", "cancelled", "skipped", "timed_out", or "action_required". (Optional. Required if you provide a status of "completed".)
   190  	CompletedAt *Timestamp        `json:"completed_at,omitempty"` // The time the check completed. (Optional. Required if you provide conclusion.)
   191  	Output      *CheckRunOutput   `json:"output,omitempty"`       // Provide descriptive details about the run. (Optional)
   192  	Actions     []*CheckRunAction `json:"actions,omitempty"`      // Possible further actions the integrator can perform, which a user may trigger. (Optional.)
   193  }
   194  
   195  // UpdateCheckRun updates a check run for a specific commit in a repository.
   196  //
   197  // GitHub API docs: https://docs.github.com/en/rest/checks/runs#update-a-check-run
   198  func (s *ChecksService) UpdateCheckRun(ctx context.Context, owner, repo string, checkRunID int64, opts UpdateCheckRunOptions) (*CheckRun, *Response, error) {
   199  	u := fmt.Sprintf("repos/%v/%v/check-runs/%v", owner, repo, checkRunID)
   200  	req, err := s.client.NewRequest("PATCH", u, opts)
   201  	if err != nil {
   202  		return nil, nil, err
   203  	}
   204  
   205  	req.Header.Set("Accept", mediaTypeCheckRunsPreview)
   206  
   207  	checkRun := new(CheckRun)
   208  	resp, err := s.client.Do(ctx, req, checkRun)
   209  	if err != nil {
   210  		return nil, resp, err
   211  	}
   212  
   213  	return checkRun, resp, nil
   214  }
   215  
   216  // ListCheckRunAnnotations lists the annotations for a check run.
   217  //
   218  // GitHub API docs: https://docs.github.com/en/rest/checks/runs#list-check-run-annotations
   219  func (s *ChecksService) ListCheckRunAnnotations(ctx context.Context, owner, repo string, checkRunID int64, opts *ListOptions) ([]*CheckRunAnnotation, *Response, error) {
   220  	u := fmt.Sprintf("repos/%v/%v/check-runs/%v/annotations", owner, repo, checkRunID)
   221  	u, err := addOptions(u, opts)
   222  	if err != nil {
   223  		return nil, nil, err
   224  	}
   225  
   226  	req, err := s.client.NewRequest("GET", u, nil)
   227  	if err != nil {
   228  		return nil, nil, err
   229  	}
   230  
   231  	req.Header.Set("Accept", mediaTypeCheckRunsPreview)
   232  
   233  	var checkRunAnnotations []*CheckRunAnnotation
   234  	resp, err := s.client.Do(ctx, req, &checkRunAnnotations)
   235  	if err != nil {
   236  		return nil, resp, err
   237  	}
   238  
   239  	return checkRunAnnotations, resp, nil
   240  }
   241  
   242  // ListCheckRunsOptions represents parameters to list check runs.
   243  type ListCheckRunsOptions struct {
   244  	CheckName *string `url:"check_name,omitempty"` // Returns check runs with the specified name.
   245  	Status    *string `url:"status,omitempty"`     // Returns check runs with the specified status. Can be one of "queued", "in_progress", or "completed".
   246  	Filter    *string `url:"filter,omitempty"`     // Filters check runs by their completed_at timestamp. Can be one of "latest" (returning the most recent check runs) or "all". Default: "latest"
   247  	AppID     *int64  `url:"app_id,omitempty"`     // Filters check runs by GitHub App ID.
   248  
   249  	ListOptions
   250  }
   251  
   252  // ListCheckRunsResults represents the result of a check run list.
   253  type ListCheckRunsResults struct {
   254  	Total     *int        `json:"total_count,omitempty"`
   255  	CheckRuns []*CheckRun `json:"check_runs,omitempty"`
   256  }
   257  
   258  // ListCheckRunsForRef lists check runs for a specific ref.
   259  //
   260  // GitHub API docs: https://docs.github.com/en/rest/checks/runs#list-check-runs-for-a-git-reference
   261  func (s *ChecksService) ListCheckRunsForRef(ctx context.Context, owner, repo, ref string, opts *ListCheckRunsOptions) (*ListCheckRunsResults, *Response, error) {
   262  	u := fmt.Sprintf("repos/%v/%v/commits/%v/check-runs", owner, repo, refURLEscape(ref))
   263  	u, err := addOptions(u, opts)
   264  	if err != nil {
   265  		return nil, nil, err
   266  	}
   267  
   268  	req, err := s.client.NewRequest("GET", u, nil)
   269  	if err != nil {
   270  		return nil, nil, err
   271  	}
   272  
   273  	req.Header.Set("Accept", mediaTypeCheckRunsPreview)
   274  
   275  	var checkRunResults *ListCheckRunsResults
   276  	resp, err := s.client.Do(ctx, req, &checkRunResults)
   277  	if err != nil {
   278  		return nil, resp, err
   279  	}
   280  
   281  	return checkRunResults, resp, nil
   282  }
   283  
   284  // ListCheckRunsCheckSuite lists check runs for a check suite.
   285  //
   286  // GitHub API docs: https://docs.github.com/en/rest/checks/runs#list-check-runs-in-a-check-suite
   287  func (s *ChecksService) ListCheckRunsCheckSuite(ctx context.Context, owner, repo string, checkSuiteID int64, opts *ListCheckRunsOptions) (*ListCheckRunsResults, *Response, error) {
   288  	u := fmt.Sprintf("repos/%v/%v/check-suites/%v/check-runs", owner, repo, checkSuiteID)
   289  	u, err := addOptions(u, opts)
   290  	if err != nil {
   291  		return nil, nil, err
   292  	}
   293  
   294  	req, err := s.client.NewRequest("GET", u, nil)
   295  	if err != nil {
   296  		return nil, nil, err
   297  	}
   298  
   299  	req.Header.Set("Accept", mediaTypeCheckRunsPreview)
   300  
   301  	var checkRunResults *ListCheckRunsResults
   302  	resp, err := s.client.Do(ctx, req, &checkRunResults)
   303  	if err != nil {
   304  		return nil, resp, err
   305  	}
   306  
   307  	return checkRunResults, resp, nil
   308  }
   309  
   310  // ReRequestCheckRun triggers GitHub to rerequest an existing check run.
   311  //
   312  // GitHub API docs: https://docs.github.com/en/rest/checks/runs#rerequest-a-check-run
   313  func (s *ChecksService) ReRequestCheckRun(ctx context.Context, owner, repo string, checkRunID int64) (*Response, error) {
   314  	u := fmt.Sprintf("repos/%v/%v/check-runs/%v/rerequest", owner, repo, checkRunID)
   315  
   316  	req, err := s.client.NewRequest("POST", u, nil)
   317  	if err != nil {
   318  		return nil, err
   319  	}
   320  
   321  	req.Header.Set("Accept", mediaTypeCheckRunsPreview)
   322  
   323  	return s.client.Do(ctx, req, nil)
   324  }
   325  
   326  // ListCheckSuiteOptions represents parameters to list check suites.
   327  type ListCheckSuiteOptions struct {
   328  	CheckName *string `url:"check_name,omitempty"` // Filters checks suites by the name of the check run.
   329  	AppID     *int    `url:"app_id,omitempty"`     // Filters check suites by GitHub App id.
   330  
   331  	ListOptions
   332  }
   333  
   334  // ListCheckSuiteResults represents the result of a check run list.
   335  type ListCheckSuiteResults struct {
   336  	Total       *int          `json:"total_count,omitempty"`
   337  	CheckSuites []*CheckSuite `json:"check_suites,omitempty"`
   338  }
   339  
   340  // ListCheckSuitesForRef lists check suite for a specific ref.
   341  //
   342  // GitHub API docs: https://docs.github.com/en/rest/checks/suites#list-check-suites-for-a-git-reference
   343  func (s *ChecksService) ListCheckSuitesForRef(ctx context.Context, owner, repo, ref string, opts *ListCheckSuiteOptions) (*ListCheckSuiteResults, *Response, error) {
   344  	u := fmt.Sprintf("repos/%v/%v/commits/%v/check-suites", owner, repo, refURLEscape(ref))
   345  	u, err := addOptions(u, opts)
   346  	if err != nil {
   347  		return nil, nil, err
   348  	}
   349  
   350  	req, err := s.client.NewRequest("GET", u, nil)
   351  	if err != nil {
   352  		return nil, nil, err
   353  	}
   354  
   355  	req.Header.Set("Accept", mediaTypeCheckRunsPreview)
   356  
   357  	var checkSuiteResults *ListCheckSuiteResults
   358  	resp, err := s.client.Do(ctx, req, &checkSuiteResults)
   359  	if err != nil {
   360  		return nil, resp, err
   361  	}
   362  
   363  	return checkSuiteResults, resp, nil
   364  }
   365  
   366  // AutoTriggerCheck enables or disables automatic creation of CheckSuite events upon pushes to the repository.
   367  type AutoTriggerCheck struct {
   368  	AppID   *int64 `json:"app_id,omitempty"`  // The id of the GitHub App. (Required.)
   369  	Setting *bool  `json:"setting,omitempty"` // Set to "true" to enable automatic creation of CheckSuite events upon pushes to the repository, or "false" to disable them. Default: "true" (Required.)
   370  }
   371  
   372  // CheckSuitePreferenceOptions set options for check suite preferences for a repository.
   373  type CheckSuitePreferenceOptions struct {
   374  	AutoTriggerChecks []*AutoTriggerCheck `json:"auto_trigger_checks,omitempty"` // A slice of auto trigger checks that can be set for a check suite in a repository.
   375  }
   376  
   377  // CheckSuitePreferenceResults represents the results of the preference set operation.
   378  type CheckSuitePreferenceResults struct {
   379  	Preferences *PreferenceList `json:"preferences,omitempty"`
   380  	Repository  *Repository     `json:"repository,omitempty"`
   381  }
   382  
   383  // PreferenceList represents a list of auto trigger checks for repository
   384  type PreferenceList struct {
   385  	AutoTriggerChecks []*AutoTriggerCheck `json:"auto_trigger_checks,omitempty"` // A slice of auto trigger checks that can be set for a check suite in a repository.
   386  }
   387  
   388  // SetCheckSuitePreferences changes the default automatic flow when creating check suites.
   389  //
   390  // GitHub API docs: https://docs.github.com/en/rest/checks/suites#update-repository-preferences-for-check-suites
   391  func (s *ChecksService) SetCheckSuitePreferences(ctx context.Context, owner, repo string, opts CheckSuitePreferenceOptions) (*CheckSuitePreferenceResults, *Response, error) {
   392  	u := fmt.Sprintf("repos/%v/%v/check-suites/preferences", owner, repo)
   393  	req, err := s.client.NewRequest("PATCH", u, opts)
   394  	if err != nil {
   395  		return nil, nil, err
   396  	}
   397  
   398  	req.Header.Set("Accept", mediaTypeCheckRunsPreview)
   399  
   400  	var checkSuitePrefResults *CheckSuitePreferenceResults
   401  	resp, err := s.client.Do(ctx, req, &checkSuitePrefResults)
   402  	if err != nil {
   403  		return nil, resp, err
   404  	}
   405  
   406  	return checkSuitePrefResults, resp, nil
   407  }
   408  
   409  // CreateCheckSuiteOptions sets up parameters to manually create a check suites
   410  type CreateCheckSuiteOptions struct {
   411  	HeadSHA    string  `json:"head_sha"`              // The sha of the head commit. (Required.)
   412  	HeadBranch *string `json:"head_branch,omitempty"` // The name of the head branch where the code changes are implemented.
   413  }
   414  
   415  // CreateCheckSuite manually creates a check suite for a repository.
   416  //
   417  // GitHub API docs: https://docs.github.com/en/rest/checks/suites#create-a-check-suite
   418  func (s *ChecksService) CreateCheckSuite(ctx context.Context, owner, repo string, opts CreateCheckSuiteOptions) (*CheckSuite, *Response, error) {
   419  	u := fmt.Sprintf("repos/%v/%v/check-suites", owner, repo)
   420  	req, err := s.client.NewRequest("POST", u, opts)
   421  	if err != nil {
   422  		return nil, nil, err
   423  	}
   424  
   425  	req.Header.Set("Accept", mediaTypeCheckRunsPreview)
   426  
   427  	checkSuite := new(CheckSuite)
   428  	resp, err := s.client.Do(ctx, req, checkSuite)
   429  	if err != nil {
   430  		return nil, resp, err
   431  	}
   432  
   433  	return checkSuite, resp, nil
   434  }
   435  
   436  // ReRequestCheckSuite triggers GitHub to rerequest an existing check suite, without pushing new code to a repository.
   437  //
   438  // GitHub API docs: https://docs.github.com/en/rest/checks/suites#rerequest-a-check-suite
   439  func (s *ChecksService) ReRequestCheckSuite(ctx context.Context, owner, repo string, checkSuiteID int64) (*Response, error) {
   440  	u := fmt.Sprintf("repos/%v/%v/check-suites/%v/rerequest", owner, repo, checkSuiteID)
   441  
   442  	req, err := s.client.NewRequest("POST", u, nil)
   443  	if err != nil {
   444  		return nil, err
   445  	}
   446  
   447  	req.Header.Set("Accept", mediaTypeCheckRunsPreview)
   448  
   449  	resp, err := s.client.Do(ctx, req, nil)
   450  	return resp, err
   451  }
   452
View as plain text