repos_hooks.go

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

     1  // Copyright 2013 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  	"time"
    12  )
    13  
    14  // WebHookPayload represents the data that is received from GitHub when a push
    15  // event hook is triggered. The format of these payloads pre-date most of the
    16  // GitHub v3 API, so there are lots of minor incompatibilities with the types
    17  // defined in the rest of the API. Therefore, several types are duplicated
    18  // here to account for these differences.
    19  //
    20  // GitHub API docs: https://help.github.com/articles/post-receive-hooks
    21  type WebHookPayload struct {
    22  	After      *string          `json:"after,omitempty"`
    23  	Before     *string          `json:"before,omitempty"`
    24  	Commits    []*WebHookCommit `json:"commits,omitempty"`
    25  	Compare    *string          `json:"compare,omitempty"`
    26  	Created    *bool            `json:"created,omitempty"`
    27  	Deleted    *bool            `json:"deleted,omitempty"`
    28  	Forced     *bool            `json:"forced,omitempty"`
    29  	HeadCommit *WebHookCommit   `json:"head_commit,omitempty"`
    30  	Pusher     *User            `json:"pusher,omitempty"`
    31  	Ref        *string          `json:"ref,omitempty"`
    32  	Repo       *Repository      `json:"repository,omitempty"`
    33  	Sender     *User            `json:"sender,omitempty"`
    34  }
    35  
    36  func (w WebHookPayload) String() string {
    37  	return Stringify(w)
    38  }
    39  
    40  // WebHookCommit represents the commit variant we receive from GitHub in a
    41  // WebHookPayload.
    42  type WebHookCommit struct {
    43  	Added     []string       `json:"added,omitempty"`
    44  	Author    *WebHookAuthor `json:"author,omitempty"`
    45  	Committer *WebHookAuthor `json:"committer,omitempty"`
    46  	Distinct  *bool          `json:"distinct,omitempty"`
    47  	ID        *string        `json:"id,omitempty"`
    48  	Message   *string        `json:"message,omitempty"`
    49  	Modified  []string       `json:"modified,omitempty"`
    50  	Removed   []string       `json:"removed,omitempty"`
    51  	Timestamp *time.Time     `json:"timestamp,omitempty"`
    52  }
    53  
    54  func (w WebHookCommit) String() string {
    55  	return Stringify(w)
    56  }
    57  
    58  // WebHookAuthor represents the author or committer of a commit, as specified
    59  // in a WebHookCommit. The commit author may not correspond to a GitHub User.
    60  type WebHookAuthor struct {
    61  	Email    *string `json:"email,omitempty"`
    62  	Name     *string `json:"name,omitempty"`
    63  	Username *string `json:"username,omitempty"`
    64  }
    65  
    66  func (w WebHookAuthor) String() string {
    67  	return Stringify(w)
    68  }
    69  
    70  // Hook represents a GitHub (web and service) hook for a repository.
    71  type Hook struct {
    72  	CreatedAt *time.Time `json:"created_at,omitempty"`
    73  	UpdatedAt *time.Time `json:"updated_at,omitempty"`
    74  	URL       *string    `json:"url,omitempty"`
    75  	ID        *int64     `json:"id,omitempty"`
    76  
    77  	// Only the following fields are used when creating a hook.
    78  	// Config is required.
    79  	Config map[string]interface{} `json:"config,omitempty"`
    80  	Events []string               `json:"events,omitempty"`
    81  	Active *bool                  `json:"active,omitempty"`
    82  }
    83  
    84  func (h Hook) String() string {
    85  	return Stringify(h)
    86  }
    87  
    88  // createHookRequest is a subset of Hook and is used internally
    89  // by CreateHook to pass only the known fields for the endpoint.
    90  //
    91  // See https://github.com/google/go-github/issues/1015 for more
    92  // information.
    93  type createHookRequest struct {
    94  	// Config is required.
    95  	Name   string                 `json:"name"`
    96  	Config map[string]interface{} `json:"config,omitempty"`
    97  	Events []string               `json:"events,omitempty"`
    98  	Active *bool                  `json:"active,omitempty"`
    99  }
   100  
   101  // CreateHook creates a Hook for the specified repository.
   102  // Config is a required field.
   103  //
   104  // Note that only a subset of the hook fields are used and hook must
   105  // not be nil.
   106  //
   107  // GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/repos/#create-a-repository-webhook
   108  func (s *RepositoriesService) CreateHook(ctx context.Context, owner, repo string, hook *Hook) (*Hook, *Response, error) {
   109  	u := fmt.Sprintf("repos/%v/%v/hooks", owner, repo)
   110  
   111  	hookReq := &createHookRequest{
   112  		Name:   "web",
   113  		Events: hook.Events,
   114  		Active: hook.Active,
   115  		Config: hook.Config,
   116  	}
   117  
   118  	req, err := s.client.NewRequest("POST", u, hookReq)
   119  	if err != nil {
   120  		return nil, nil, err
   121  	}
   122  
   123  	h := new(Hook)
   124  	resp, err := s.client.Do(ctx, req, h)
   125  	if err != nil {
   126  		return nil, resp, err
   127  	}
   128  
   129  	return h, resp, nil
   130  }
   131  
   132  // ListHooks lists all Hooks for the specified repository.
   133  //
   134  // GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/repos/#list-repository-webhooks
   135  func (s *RepositoriesService) ListHooks(ctx context.Context, owner, repo string, opts *ListOptions) ([]*Hook, *Response, error) {
   136  	u := fmt.Sprintf("repos/%v/%v/hooks", owner, repo)
   137  	u, err := addOptions(u, opts)
   138  	if err != nil {
   139  		return nil, nil, err
   140  	}
   141  
   142  	req, err := s.client.NewRequest("GET", u, nil)
   143  	if err != nil {
   144  		return nil, nil, err
   145  	}
   146  
   147  	var hooks []*Hook
   148  	resp, err := s.client.Do(ctx, req, &hooks)
   149  	if err != nil {
   150  		return nil, resp, err
   151  	}
   152  
   153  	return hooks, resp, nil
   154  }
   155  
   156  // GetHook returns a single specified Hook.
   157  //
   158  // GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/repos/#get-a-repository-webhook
   159  func (s *RepositoriesService) GetHook(ctx context.Context, owner, repo string, id int64) (*Hook, *Response, error) {
   160  	u := fmt.Sprintf("repos/%v/%v/hooks/%d", owner, repo, id)
   161  	req, err := s.client.NewRequest("GET", u, nil)
   162  	if err != nil {
   163  		return nil, nil, err
   164  	}
   165  	h := new(Hook)
   166  	resp, err := s.client.Do(ctx, req, h)
   167  	if err != nil {
   168  		return nil, resp, err
   169  	}
   170  
   171  	return h, resp, nil
   172  }
   173  
   174  // EditHook updates a specified Hook.
   175  //
   176  // GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/repos/#update-a-repository-webhook
   177  func (s *RepositoriesService) EditHook(ctx context.Context, owner, repo string, id int64, hook *Hook) (*Hook, *Response, error) {
   178  	u := fmt.Sprintf("repos/%v/%v/hooks/%d", owner, repo, id)
   179  	req, err := s.client.NewRequest("PATCH", u, hook)
   180  	if err != nil {
   181  		return nil, nil, err
   182  	}
   183  	h := new(Hook)
   184  	resp, err := s.client.Do(ctx, req, h)
   185  	if err != nil {
   186  		return nil, resp, err
   187  	}
   188  
   189  	return h, resp, nil
   190  }
   191  
   192  // DeleteHook deletes a specified Hook.
   193  //
   194  // GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/repos/#delete-a-repository-webhook
   195  func (s *RepositoriesService) DeleteHook(ctx context.Context, owner, repo string, id int64) (*Response, error) {
   196  	u := fmt.Sprintf("repos/%v/%v/hooks/%d", owner, repo, id)
   197  	req, err := s.client.NewRequest("DELETE", u, nil)
   198  	if err != nil {
   199  		return nil, err
   200  	}
   201  	return s.client.Do(ctx, req, nil)
   202  }
   203  
   204  // PingHook triggers a 'ping' event to be sent to the Hook.
   205  //
   206  // GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/repos/#ping-a-repository-webhook
   207  func (s *RepositoriesService) PingHook(ctx context.Context, owner, repo string, id int64) (*Response, error) {
   208  	u := fmt.Sprintf("repos/%v/%v/hooks/%d/pings", owner, repo, id)
   209  	req, err := s.client.NewRequest("POST", u, nil)
   210  	if err != nil {
   211  		return nil, err
   212  	}
   213  	return s.client.Do(ctx, req, nil)
   214  }
   215  
   216  // TestHook triggers a test Hook by github.
   217  //
   218  // GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/repos/#test-the-push-repository-webhook
   219  func (s *RepositoriesService) TestHook(ctx context.Context, owner, repo string, id int64) (*Response, error) {
   220  	u := fmt.Sprintf("repos/%v/%v/hooks/%d/tests", owner, repo, id)
   221  	req, err := s.client.NewRequest("POST", u, nil)
   222  	if err != nil {
   223  		return nil, err
   224  	}
   225  	return s.client.Do(ctx, req, nil)
   226  }
   227
View as plain text