tags.go

Documentation: github.com/xanzy/go-gitlab

     1  //
     2  // Copyright 2021, Sander van Harmelen
     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  	"net/url"
    23  )
    24  
    25  // TagsService handles communication with the tags related methods
    26  // of the GitLab API.
    27  //
    28  // GitLab API docs: https://docs.gitlab.com/ee/api/tags.html
    29  type TagsService struct {
    30  	client *Client
    31  }
    32  
    33  // Tag represents a GitLab tag.
    34  //
    35  // GitLab API docs: https://docs.gitlab.com/ee/api/tags.html
    36  type Tag struct {
    37  	Commit    *Commit      `json:"commit"`
    38  	Release   *ReleaseNote `json:"release"`
    39  	Name      string       `json:"name"`
    40  	Message   string       `json:"message"`
    41  	Protected bool         `json:"protected"`
    42  	Target    string       `json:"target"`
    43  }
    44  
    45  // ReleaseNote represents a GitLab version release.
    46  //
    47  // GitLab API docs: https://docs.gitlab.com/ee/api/tags.html
    48  type ReleaseNote struct {
    49  	TagName     string `json:"tag_name"`
    50  	Description string `json:"description"`
    51  }
    52  
    53  func (t Tag) String() string {
    54  	return Stringify(t)
    55  }
    56  
    57  // ListTagsOptions represents the available ListTags() options.
    58  //
    59  // GitLab API docs:
    60  // https://docs.gitlab.com/ee/api/tags.html#list-project-repository-tags
    61  type ListTagsOptions struct {
    62  	ListOptions
    63  	OrderBy *string `url:"order_by,omitempty" json:"order_by,omitempty"`
    64  	Search  *string `url:"search,omitempty" json:"search,omitempty"`
    65  	Sort    *string `url:"sort,omitempty" json:"sort,omitempty"`
    66  }
    67  
    68  // ListTags gets a list of tags from a project, sorted by name in reverse
    69  // alphabetical order.
    70  //
    71  // GitLab API docs:
    72  // https://docs.gitlab.com/ee/api/tags.html#list-project-repository-tags
    73  func (s *TagsService) ListTags(pid interface{}, opt *ListTagsOptions, options ...RequestOptionFunc) ([]*Tag, *Response, error) {
    74  	project, err := parseID(pid)
    75  	if err != nil {
    76  		return nil, nil, err
    77  	}
    78  	u := fmt.Sprintf("projects/%s/repository/tags", PathEscape(project))
    79  
    80  	req, err := s.client.NewRequest(http.MethodGet, u, opt, options)
    81  	if err != nil {
    82  		return nil, nil, err
    83  	}
    84  
    85  	var t []*Tag
    86  	resp, err := s.client.Do(req, &t)
    87  	if err != nil {
    88  		return nil, resp, err
    89  	}
    90  
    91  	return t, resp, nil
    92  }
    93  
    94  // GetTag a specific repository tag determined by its name. It returns 200 together
    95  // with the tag information if the tag exists. It returns 404 if the tag does not exist.
    96  //
    97  // GitLab API docs:
    98  // https://docs.gitlab.com/ee/api/tags.html#get-a-single-repository-tag
    99  func (s *TagsService) GetTag(pid interface{}, tag string, options ...RequestOptionFunc) (*Tag, *Response, error) {
   100  	project, err := parseID(pid)
   101  	if err != nil {
   102  		return nil, nil, err
   103  	}
   104  	u := fmt.Sprintf("projects/%s/repository/tags/%s", PathEscape(project), url.PathEscape(tag))
   105  
   106  	req, err := s.client.NewRequest(http.MethodGet, u, nil, options)
   107  	if err != nil {
   108  		return nil, nil, err
   109  	}
   110  
   111  	var t *Tag
   112  	resp, err := s.client.Do(req, &t)
   113  	if err != nil {
   114  		return nil, resp, err
   115  	}
   116  
   117  	return t, resp, nil
   118  }
   119  
   120  // CreateTagOptions represents the available CreateTag() options.
   121  //
   122  // GitLab API docs:
   123  // https://docs.gitlab.com/ee/api/tags.html#create-a-new-tag
   124  type CreateTagOptions struct {
   125  	TagName *string `url:"tag_name,omitempty" json:"tag_name,omitempty"`
   126  	Ref     *string `url:"ref,omitempty" json:"ref,omitempty"`
   127  	Message *string `url:"message,omitempty" json:"message,omitempty"`
   128  
   129  	// Deprecated: Use the Releases API instead. (Deprecated in GitLab 11.7)
   130  	ReleaseDescription *string `url:"release_description:omitempty" json:"release_description,omitempty"`
   131  }
   132  
   133  // CreateTag creates a new tag in the repository that points to the supplied ref.
   134  //
   135  // GitLab API docs:
   136  // https://docs.gitlab.com/ee/api/tags.html#create-a-new-tag
   137  func (s *TagsService) CreateTag(pid interface{}, opt *CreateTagOptions, options ...RequestOptionFunc) (*Tag, *Response, error) {
   138  	project, err := parseID(pid)
   139  	if err != nil {
   140  		return nil, nil, err
   141  	}
   142  	u := fmt.Sprintf("projects/%s/repository/tags", PathEscape(project))
   143  
   144  	req, err := s.client.NewRequest(http.MethodPost, u, opt, options)
   145  	if err != nil {
   146  		return nil, nil, err
   147  	}
   148  
   149  	t := new(Tag)
   150  	resp, err := s.client.Do(req, t)
   151  	if err != nil {
   152  		return nil, resp, err
   153  	}
   154  
   155  	return t, resp, nil
   156  }
   157  
   158  // DeleteTag deletes a tag of a repository with given name.
   159  //
   160  // GitLab API docs:
   161  // https://docs.gitlab.com/ee/api/tags.html#delete-a-tag
   162  func (s *TagsService) DeleteTag(pid interface{}, tag string, options ...RequestOptionFunc) (*Response, error) {
   163  	project, err := parseID(pid)
   164  	if err != nil {
   165  		return nil, err
   166  	}
   167  	u := fmt.Sprintf("projects/%s/repository/tags/%s", PathEscape(project), url.PathEscape(tag))
   168  
   169  	req, err := s.client.NewRequest(http.MethodDelete, u, nil, options)
   170  	if err != nil {
   171  		return nil, err
   172  	}
   173  
   174  	return s.client.Do(req, nil)
   175  }
   176  
   177  // CreateReleaseNoteOptions represents the available CreateReleaseNote() options.
   178  //
   179  // Deprecated: This feature was deprecated in GitLab 11.7.
   180  //
   181  // GitLab API docs:
   182  // https://docs.gitlab.com/ee/api/tags.html#create-a-new-release
   183  type CreateReleaseNoteOptions struct {
   184  	Description *string `url:"description:omitempty" json:"description,omitempty"`
   185  }
   186  
   187  // CreateReleaseNote Add release notes to the existing git tag.
   188  // If there already exists a release for the given tag, status code 409 is returned.
   189  //
   190  // Deprecated: This feature was deprecated in GitLab 11.7.
   191  //
   192  // GitLab API docs:
   193  // https://docs.gitlab.com/ee/api/tags.html#create-a-new-release
   194  func (s *TagsService) CreateReleaseNote(pid interface{}, tag string, opt *CreateReleaseNoteOptions, options ...RequestOptionFunc) (*ReleaseNote, *Response, error) {
   195  	project, err := parseID(pid)
   196  	if err != nil {
   197  		return nil, nil, err
   198  	}
   199  	u := fmt.Sprintf("projects/%s/repository/tags/%s/release", PathEscape(project), url.PathEscape(tag))
   200  
   201  	req, err := s.client.NewRequest(http.MethodPost, u, opt, options)
   202  	if err != nil {
   203  		return nil, nil, err
   204  	}
   205  
   206  	r := new(ReleaseNote)
   207  	resp, err := s.client.Do(req, r)
   208  	if err != nil {
   209  		return nil, resp, err
   210  	}
   211  
   212  	return r, resp, nil
   213  }
   214  
   215  // UpdateReleaseNoteOptions represents the available UpdateReleaseNote() options.
   216  //
   217  // GitLab API docs:
   218  // https://docs.gitlab.com/ee/api/tags.html#update-a-release
   219  type UpdateReleaseNoteOptions struct {
   220  	Description *string `url:"description:omitempty" json:"description,omitempty"`
   221  }
   222  
   223  // UpdateReleaseNote Updates the release notes of a given release.
   224  //
   225  // Deprecated: This feature was deprecated in GitLab 11.7.
   226  //
   227  // GitLab API docs:
   228  // https://docs.gitlab.com/ee/api/tags.html#update-a-release
   229  func (s *TagsService) UpdateReleaseNote(pid interface{}, tag string, opt *UpdateReleaseNoteOptions, options ...RequestOptionFunc) (*ReleaseNote, *Response, error) {
   230  	project, err := parseID(pid)
   231  	if err != nil {
   232  		return nil, nil, err
   233  	}
   234  	u := fmt.Sprintf("projects/%s/repository/tags/%s/release", PathEscape(project), url.PathEscape(tag))
   235  
   236  	req, err := s.client.NewRequest(http.MethodPut, u, opt, options)
   237  	if err != nil {
   238  		return nil, nil, err
   239  	}
   240  
   241  	r := new(ReleaseNote)
   242  	resp, err := s.client.Do(req, r)
   243  	if err != nil {
   244  		return nil, resp, err
   245  	}
   246  
   247  	return r, resp, nil
   248  }
   249
View as plain text