pipelines.go

Documentation: github.com/xanzy/go-gitlab

     1  //
     2  // Copyright 2021, Igor Varavko
     3  //
     4  // Licensed under the Apache License, Version 2.0 (the "License");
     5  // you may not use this file except in compliance with the License.
     6  // You may obtain a copy of the License at
     7  //
     8  //     http://www.apache.org/licenses/LICENSE-2.0
     9  //
    10  // Unless required by applicable law or agreed to in writing, software
    11  // distributed under the License is distributed on an "AS IS" BASIS,
    12  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13  // See the License for the specific language governing permissions and
    14  // limitations under the License.
    15  //
    16  
    17  package gitlab
    18  
    19  import (
    20  	"fmt"
    21  	"net/http"
    22  	"time"
    23  )
    24  
    25  // PipelinesService handles communication with the repositories related
    26  // methods of the GitLab API.
    27  //
    28  // GitLab API docs: https://docs.gitlab.com/ee/api/pipelines.html
    29  type PipelinesService struct {
    30  	client *Client
    31  }
    32  
    33  // PipelineVariable represents a pipeline variable.
    34  //
    35  // GitLab API docs: https://docs.gitlab.com/ee/api/pipelines.html
    36  type PipelineVariable struct {
    37  	Key          string `json:"key"`
    38  	Value        string `json:"value"`
    39  	VariableType string `json:"variable_type"`
    40  }
    41  
    42  // Pipeline represents a GitLab pipeline.
    43  //
    44  // GitLab API docs: https://docs.gitlab.com/ee/api/pipelines.html
    45  type Pipeline struct {
    46  	ID             int             `json:"id"`
    47  	IID            int             `json:"iid"`
    48  	ProjectID      int             `json:"project_id"`
    49  	Status         string          `json:"status"`
    50  	Source         string          `json:"source"`
    51  	Ref            string          `json:"ref"`
    52  	Name           string          `json:"name"`
    53  	SHA            string          `json:"sha"`
    54  	BeforeSHA      string          `json:"before_sha"`
    55  	Tag            bool            `json:"tag"`
    56  	YamlErrors     string          `json:"yaml_errors"`
    57  	User           *BasicUser      `json:"user"`
    58  	UpdatedAt      *time.Time      `json:"updated_at"`
    59  	CreatedAt      *time.Time      `json:"created_at"`
    60  	StartedAt      *time.Time      `json:"started_at"`
    61  	FinishedAt     *time.Time      `json:"finished_at"`
    62  	CommittedAt    *time.Time      `json:"committed_at"`
    63  	Duration       int             `json:"duration"`
    64  	QueuedDuration int             `json:"queued_duration"`
    65  	Coverage       string          `json:"coverage"`
    66  	WebURL         string          `json:"web_url"`
    67  	DetailedStatus *DetailedStatus `json:"detailed_status"`
    68  }
    69  
    70  // DetailedStatus contains detailed information about the status of a pipeline.
    71  type DetailedStatus struct {
    72  	Icon         string `json:"icon"`
    73  	Text         string `json:"text"`
    74  	Label        string `json:"label"`
    75  	Group        string `json:"group"`
    76  	Tooltip      string `json:"tooltip"`
    77  	HasDetails   bool   `json:"has_details"`
    78  	DetailsPath  string `json:"details_path"`
    79  	Illustration struct {
    80  		Image string `json:"image"`
    81  	} `json:"illustration"`
    82  	Favicon string `json:"favicon"`
    83  }
    84  
    85  func (p Pipeline) String() string {
    86  	return Stringify(p)
    87  }
    88  
    89  // PipelineTestReport contains a detailed report of a test run.
    90  type PipelineTestReport struct {
    91  	TotalTime    float64               `json:"total_time"`
    92  	TotalCount   int                   `json:"total_count"`
    93  	SuccessCount int                   `json:"success_count"`
    94  	FailedCount  int                   `json:"failed_count"`
    95  	SkippedCount int                   `json:"skipped_count"`
    96  	ErrorCount   int                   `json:"error_count"`
    97  	TestSuites   []*PipelineTestSuites `json:"test_suites"`
    98  }
    99  
   100  // PipelineTestSuites contains test suites results.
   101  type PipelineTestSuites struct {
   102  	Name         string               `json:"name"`
   103  	TotalTime    float64              `json:"total_time"`
   104  	TotalCount   int                  `json:"total_count"`
   105  	SuccessCount int                  `json:"success_count"`
   106  	FailedCount  int                  `json:"failed_count"`
   107  	SkippedCount int                  `json:"skipped_count"`
   108  	ErrorCount   int                  `json:"error_count"`
   109  	TestCases    []*PipelineTestCases `json:"test_cases"`
   110  }
   111  
   112  // PipelineTestCases contains test cases details.
   113  type PipelineTestCases struct {
   114  	Status         string          `json:"status"`
   115  	Name           string          `json:"name"`
   116  	Classname      string          `json:"classname"`
   117  	File           string          `json:"file"`
   118  	ExecutionTime  float64         `json:"execution_time"`
   119  	SystemOutput   interface{}     `json:"system_output"`
   120  	StackTrace     string          `json:"stack_trace"`
   121  	AttachmentURL  string          `json:"attachment_url"`
   122  	RecentFailures *RecentFailures `json:"recent_failures"`
   123  }
   124  
   125  // RecentFailures contains failures count for the project's default branch.
   126  type RecentFailures struct {
   127  	Count      int    `json:"count"`
   128  	BaseBranch string `json:"base_branch"`
   129  }
   130  
   131  func (p PipelineTestReport) String() string {
   132  	return Stringify(p)
   133  }
   134  
   135  // PipelineInfo shows the basic entities of a pipeline, mostly used as fields
   136  // on other assets, like Commit.
   137  type PipelineInfo struct {
   138  	ID        int        `json:"id"`
   139  	IID       int        `json:"iid"`
   140  	ProjectID int        `json:"project_id"`
   141  	Status    string     `json:"status"`
   142  	Source    string     `json:"source"`
   143  	Ref       string     `json:"ref"`
   144  	SHA       string     `json:"sha"`
   145  	WebURL    string     `json:"web_url"`
   146  	UpdatedAt *time.Time `json:"updated_at"`
   147  	CreatedAt *time.Time `json:"created_at"`
   148  }
   149  
   150  func (p PipelineInfo) String() string {
   151  	return Stringify(p)
   152  }
   153  
   154  // ListProjectPipelinesOptions represents the available ListProjectPipelines() options.
   155  //
   156  // GitLab API docs: https://docs.gitlab.com/ee/api/pipelines.html#list-project-pipelines
   157  type ListProjectPipelinesOptions struct {
   158  	ListOptions
   159  	Scope         *string          `url:"scope,omitempty" json:"scope,omitempty"`
   160  	Status        *BuildStateValue `url:"status,omitempty" json:"status,omitempty"`
   161  	Source        *string          `url:"source,omitempty" json:"source,omitempty"`
   162  	Ref           *string          `url:"ref,omitempty" json:"ref,omitempty"`
   163  	SHA           *string          `url:"sha,omitempty" json:"sha,omitempty"`
   164  	YamlErrors    *bool            `url:"yaml_errors,omitempty" json:"yaml_errors,omitempty"`
   165  	Name          *string          `url:"name,omitempty" json:"name,omitempty"`
   166  	Username      *string          `url:"username,omitempty" json:"username,omitempty"`
   167  	UpdatedAfter  *time.Time       `url:"updated_after,omitempty" json:"updated_after,omitempty"`
   168  	UpdatedBefore *time.Time       `url:"updated_before,omitempty" json:"updated_before,omitempty"`
   169  	OrderBy       *string          `url:"order_by,omitempty" json:"order_by,omitempty"`
   170  	Sort          *string          `url:"sort,omitempty" json:"sort,omitempty"`
   171  }
   172  
   173  // ListProjectPipelines gets a list of project piplines.
   174  //
   175  // GitLab API docs: https://docs.gitlab.com/ee/api/pipelines.html#list-project-pipelines
   176  func (s *PipelinesService) ListProjectPipelines(pid interface{}, opt *ListProjectPipelinesOptions, options ...RequestOptionFunc) ([]*PipelineInfo, *Response, error) {
   177  	project, err := parseID(pid)
   178  	if err != nil {
   179  		return nil, nil, err
   180  	}
   181  	u := fmt.Sprintf("projects/%s/pipelines", PathEscape(project))
   182  
   183  	req, err := s.client.NewRequest(http.MethodGet, u, opt, options)
   184  	if err != nil {
   185  		return nil, nil, err
   186  	}
   187  
   188  	var p []*PipelineInfo
   189  	resp, err := s.client.Do(req, &p)
   190  	if err != nil {
   191  		return nil, resp, err
   192  	}
   193  
   194  	return p, resp, nil
   195  }
   196  
   197  // GetPipeline gets a single project pipeline.
   198  //
   199  // GitLab API docs: https://docs.gitlab.com/ee/api/pipelines.html#get-a-single-pipeline
   200  func (s *PipelinesService) GetPipeline(pid interface{}, pipeline int, options ...RequestOptionFunc) (*Pipeline, *Response, error) {
   201  	project, err := parseID(pid)
   202  	if err != nil {
   203  		return nil, nil, err
   204  	}
   205  	u := fmt.Sprintf("projects/%s/pipelines/%d", PathEscape(project), pipeline)
   206  
   207  	req, err := s.client.NewRequest(http.MethodGet, u, nil, options)
   208  	if err != nil {
   209  		return nil, nil, err
   210  	}
   211  
   212  	p := new(Pipeline)
   213  	resp, err := s.client.Do(req, p)
   214  	if err != nil {
   215  		return nil, resp, err
   216  	}
   217  
   218  	return p, resp, nil
   219  }
   220  
   221  // GetPipelineVariables gets the variables of a single project pipeline.
   222  //
   223  // GitLab API docs: https://docs.gitlab.com/ee/api/pipelines.html#get-variables-of-a-pipeline
   224  func (s *PipelinesService) GetPipelineVariables(pid interface{}, pipeline int, options ...RequestOptionFunc) ([]*PipelineVariable, *Response, error) {
   225  	project, err := parseID(pid)
   226  	if err != nil {
   227  		return nil, nil, err
   228  	}
   229  	u := fmt.Sprintf("projects/%s/pipelines/%d/variables", PathEscape(project), pipeline)
   230  
   231  	req, err := s.client.NewRequest(http.MethodGet, u, nil, options)
   232  	if err != nil {
   233  		return nil, nil, err
   234  	}
   235  
   236  	var p []*PipelineVariable
   237  	resp, err := s.client.Do(req, &p)
   238  	if err != nil {
   239  		return nil, resp, err
   240  	}
   241  
   242  	return p, resp, nil
   243  }
   244  
   245  // GetPipelineTestReport gets the test report of a single project pipeline.
   246  //
   247  // GitLab API docs: https://docs.gitlab.com/ee/api/pipelines.html#get-a-pipelines-test-report
   248  func (s *PipelinesService) GetPipelineTestReport(pid interface{}, pipeline int, options ...RequestOptionFunc) (*PipelineTestReport, *Response, error) {
   249  	project, err := parseID(pid)
   250  	if err != nil {
   251  		return nil, nil, err
   252  	}
   253  	u := fmt.Sprintf("projects/%s/pipelines/%d/test_report", PathEscape(project), pipeline)
   254  
   255  	req, err := s.client.NewRequest(http.MethodGet, u, nil, options)
   256  	if err != nil {
   257  		return nil, nil, err
   258  	}
   259  
   260  	p := new(PipelineTestReport)
   261  	resp, err := s.client.Do(req, p)
   262  	if err != nil {
   263  		return nil, resp, err
   264  	}
   265  
   266  	return p, resp, nil
   267  }
   268  
   269  // GetLatestPipelineOptions represents the available GetLatestPipeline() options.
   270  //
   271  // GitLab API docs: https://docs.gitlab.com/ee/api/pipelines.html#get-the-latest-pipeline
   272  type GetLatestPipelineOptions struct {
   273  	Ref *string `url:"ref,omitempty" json:"ref,omitempty"`
   274  }
   275  
   276  // GetLatestPipeline gets the latest pipeline for a specific ref in a project.
   277  //
   278  // GitLab API docs: https://docs.gitlab.com/ee/api/pipelines.html#get-the-latest-pipeline
   279  func (s *PipelinesService) GetLatestPipeline(pid interface{}, opt *GetLatestPipelineOptions, options ...RequestOptionFunc) (*Pipeline, *Response, error) {
   280  	project, err := parseID(pid)
   281  	if err != nil {
   282  		return nil, nil, err
   283  	}
   284  	u := fmt.Sprintf("projects/%s/pipelines/latest", PathEscape(project))
   285  
   286  	req, err := s.client.NewRequest(http.MethodGet, u, opt, options)
   287  	if err != nil {
   288  		return nil, nil, err
   289  	}
   290  
   291  	p := new(Pipeline)
   292  	resp, err := s.client.Do(req, p)
   293  	if err != nil {
   294  		return nil, resp, err
   295  	}
   296  
   297  	return p, resp, nil
   298  }
   299  
   300  // CreatePipelineOptions represents the available CreatePipeline() options.
   301  //
   302  // GitLab API docs: https://docs.gitlab.com/ee/api/pipelines.html#create-a-new-pipeline
   303  type CreatePipelineOptions struct {
   304  	Ref       *string                     `url:"ref" json:"ref"`
   305  	Variables *[]*PipelineVariableOptions `url:"variables,omitempty" json:"variables,omitempty"`
   306  }
   307  
   308  // PipelineVariable represents a pipeline variable.
   309  //
   310  // GitLab API docs: https://docs.gitlab.com/ee/api/pipelines.html#create-a-new-pipeline
   311  type PipelineVariableOptions struct {
   312  	Key          *string `url:"key,omitempty" json:"key,omitempty"`
   313  	Value        *string `url:"value,omitempty" json:"value,omitempty"`
   314  	VariableType *string `url:"variable_type,omitempty" json:"variable_type,omitempty"`
   315  }
   316  
   317  // CreatePipeline creates a new project pipeline.
   318  //
   319  // GitLab API docs: https://docs.gitlab.com/ee/api/pipelines.html#create-a-new-pipeline
   320  func (s *PipelinesService) CreatePipeline(pid interface{}, opt *CreatePipelineOptions, options ...RequestOptionFunc) (*Pipeline, *Response, error) {
   321  	project, err := parseID(pid)
   322  	if err != nil {
   323  		return nil, nil, err
   324  	}
   325  	u := fmt.Sprintf("projects/%s/pipeline", PathEscape(project))
   326  
   327  	req, err := s.client.NewRequest(http.MethodPost, u, opt, options)
   328  	if err != nil {
   329  		return nil, nil, err
   330  	}
   331  
   332  	p := new(Pipeline)
   333  	resp, err := s.client.Do(req, p)
   334  	if err != nil {
   335  		return nil, resp, err
   336  	}
   337  
   338  	return p, resp, nil
   339  }
   340  
   341  // RetryPipelineBuild retries failed builds in a pipeline
   342  //
   343  // GitLab API docs:
   344  // https://docs.gitlab.com/ee/api/pipelines.html#retry-jobs-in-a-pipeline
   345  func (s *PipelinesService) RetryPipelineBuild(pid interface{}, pipeline int, options ...RequestOptionFunc) (*Pipeline, *Response, error) {
   346  	project, err := parseID(pid)
   347  	if err != nil {
   348  		return nil, nil, err
   349  	}
   350  	u := fmt.Sprintf("projects/%s/pipelines/%d/retry", PathEscape(project), pipeline)
   351  
   352  	req, err := s.client.NewRequest(http.MethodPost, u, nil, options)
   353  	if err != nil {
   354  		return nil, nil, err
   355  	}
   356  
   357  	p := new(Pipeline)
   358  	resp, err := s.client.Do(req, p)
   359  	if err != nil {
   360  		return nil, resp, err
   361  	}
   362  
   363  	return p, resp, nil
   364  }
   365  
   366  // CancelPipelineBuild cancels a pipeline builds
   367  //
   368  // GitLab API docs:
   369  // https://docs.gitlab.com/ee/api/pipelines.html#cancel-a-pipelines-jobs
   370  func (s *PipelinesService) CancelPipelineBuild(pid interface{}, pipeline int, options ...RequestOptionFunc) (*Pipeline, *Response, error) {
   371  	project, err := parseID(pid)
   372  	if err != nil {
   373  		return nil, nil, err
   374  	}
   375  	u := fmt.Sprintf("projects/%s/pipelines/%d/cancel", PathEscape(project), pipeline)
   376  
   377  	req, err := s.client.NewRequest(http.MethodPost, u, nil, options)
   378  	if err != nil {
   379  		return nil, nil, err
   380  	}
   381  
   382  	p := new(Pipeline)
   383  	resp, err := s.client.Do(req, p)
   384  	if err != nil {
   385  		return nil, resp, err
   386  	}
   387  
   388  	return p, resp, nil
   389  }
   390  
   391  // DeletePipeline deletes an existing pipeline.
   392  //
   393  // GitLab API docs:
   394  // https://docs.gitlab.com/ee/api/pipelines.html#delete-a-pipeline
   395  func (s *PipelinesService) DeletePipeline(pid interface{}, pipeline int, options ...RequestOptionFunc) (*Response, error) {
   396  	project, err := parseID(pid)
   397  	if err != nil {
   398  		return nil, err
   399  	}
   400  	u := fmt.Sprintf("projects/%s/pipelines/%d", PathEscape(project), pipeline)
   401  
   402  	req, err := s.client.NewRequest(http.MethodDelete, u, nil, options)
   403  	if err != nil {
   404  		return nil, err
   405  	}
   406  
   407  	return s.client.Do(req, nil)
   408  }
   409
View as plain text