repos_hooks.go

Documentation: github.com/google/go-github/v45/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  //
    22  // Deprecated: Please use PushEvent instead.
    23  type WebHookPayload = PushEvent
    24  
    25  // WebHookCommit represents the commit variant we receive from GitHub in a
    26  // WebHookPayload.
    27  //
    28  // Deprecated: Please use HeadCommit instead.
    29  type WebHookCommit = HeadCommit
    30  
    31  // WebHookAuthor represents the author or committer of a commit, as specified
    32  // in a WebHookCommit. The commit author may not correspond to a GitHub User.
    33  //
    34  // Deprecated: Please use CommitAuthor instead.
    35  // NOTE Breaking API change: the `Username` field is now called `Login`.
    36  type WebHookAuthor = CommitAuthor
    37  
    38  // Hook represents a GitHub (web and service) hook for a repository.
    39  type Hook struct {
    40  	CreatedAt    *time.Time             `json:"created_at,omitempty"`
    41  	UpdatedAt    *time.Time             `json:"updated_at,omitempty"`
    42  	URL          *string                `json:"url,omitempty"`
    43  	ID           *int64                 `json:"id,omitempty"`
    44  	Type         *string                `json:"type,omitempty"`
    45  	Name         *string                `json:"name,omitempty"`
    46  	TestURL      *string                `json:"test_url,omitempty"`
    47  	PingURL      *string                `json:"ping_url,omitempty"`
    48  	LastResponse map[string]interface{} `json:"last_response,omitempty"`
    49  
    50  	// Only the following fields are used when creating a hook.
    51  	// Config is required.
    52  	Config map[string]interface{} `json:"config,omitempty"`
    53  	Events []string               `json:"events,omitempty"`
    54  	Active *bool                  `json:"active,omitempty"`
    55  }
    56  
    57  func (h Hook) String() string {
    58  	return Stringify(h)
    59  }
    60  
    61  // createHookRequest is a subset of Hook and is used internally
    62  // by CreateHook to pass only the known fields for the endpoint.
    63  //
    64  // See https://github.com/google/go-github/issues/1015 for more
    65  // information.
    66  type createHookRequest struct {
    67  	// Config is required.
    68  	Name   string                 `json:"name"`
    69  	Config map[string]interface{} `json:"config,omitempty"`
    70  	Events []string               `json:"events,omitempty"`
    71  	Active *bool                  `json:"active,omitempty"`
    72  }
    73  
    74  // CreateHook creates a Hook for the specified repository.
    75  // Config is a required field.
    76  //
    77  // Note that only a subset of the hook fields are used and hook must
    78  // not be nil.
    79  //
    80  // GitHub API docs: https://docs.github.com/en/rest/webhooks/repos#create-a-repository-webhook
    81  func (s *RepositoriesService) CreateHook(ctx context.Context, owner, repo string, hook *Hook) (*Hook, *Response, error) {
    82  	u := fmt.Sprintf("repos/%v/%v/hooks", owner, repo)
    83  
    84  	hookReq := &createHookRequest{
    85  		Name:   "web",
    86  		Events: hook.Events,
    87  		Active: hook.Active,
    88  		Config: hook.Config,
    89  	}
    90  
    91  	req, err := s.client.NewRequest("POST", u, hookReq)
    92  	if err != nil {
    93  		return nil, nil, err
    94  	}
    95  
    96  	h := new(Hook)
    97  	resp, err := s.client.Do(ctx, req, h)
    98  	if err != nil {
    99  		return nil, resp, err
   100  	}
   101  
   102  	return h, resp, nil
   103  }
   104  
   105  // ListHooks lists all Hooks for the specified repository.
   106  //
   107  // GitHub API docs: https://docs.github.com/en/rest/webhooks/repos#list-repository-webhooks
   108  func (s *RepositoriesService) ListHooks(ctx context.Context, owner, repo string, opts *ListOptions) ([]*Hook, *Response, error) {
   109  	u := fmt.Sprintf("repos/%v/%v/hooks", owner, repo)
   110  	u, err := addOptions(u, opts)
   111  	if err != nil {
   112  		return nil, nil, err
   113  	}
   114  
   115  	req, err := s.client.NewRequest("GET", u, nil)
   116  	if err != nil {
   117  		return nil, nil, err
   118  	}
   119  
   120  	var hooks []*Hook
   121  	resp, err := s.client.Do(ctx, req, &hooks)
   122  	if err != nil {
   123  		return nil, resp, err
   124  	}
   125  
   126  	return hooks, resp, nil
   127  }
   128  
   129  // GetHook returns a single specified Hook.
   130  //
   131  // GitHub API docs: https://docs.github.com/en/rest/webhooks/repos#get-a-repository-webhook
   132  func (s *RepositoriesService) GetHook(ctx context.Context, owner, repo string, id int64) (*Hook, *Response, error) {
   133  	u := fmt.Sprintf("repos/%v/%v/hooks/%d", owner, repo, id)
   134  	req, err := s.client.NewRequest("GET", u, nil)
   135  	if err != nil {
   136  		return nil, nil, err
   137  	}
   138  	h := new(Hook)
   139  	resp, err := s.client.Do(ctx, req, h)
   140  	if err != nil {
   141  		return nil, resp, err
   142  	}
   143  
   144  	return h, resp, nil
   145  }
   146  
   147  // EditHook updates a specified Hook.
   148  //
   149  // GitHub API docs: https://docs.github.com/en/rest/webhooks/repos#update-a-repository-webhook
   150  func (s *RepositoriesService) EditHook(ctx context.Context, owner, repo string, id int64, hook *Hook) (*Hook, *Response, error) {
   151  	u := fmt.Sprintf("repos/%v/%v/hooks/%d", owner, repo, id)
   152  	req, err := s.client.NewRequest("PATCH", u, hook)
   153  	if err != nil {
   154  		return nil, nil, err
   155  	}
   156  	h := new(Hook)
   157  	resp, err := s.client.Do(ctx, req, h)
   158  	if err != nil {
   159  		return nil, resp, err
   160  	}
   161  
   162  	return h, resp, nil
   163  }
   164  
   165  // DeleteHook deletes a specified Hook.
   166  //
   167  // GitHub API docs: https://docs.github.com/en/rest/webhooks/repos#delete-a-repository-webhook
   168  func (s *RepositoriesService) DeleteHook(ctx context.Context, owner, repo string, id int64) (*Response, error) {
   169  	u := fmt.Sprintf("repos/%v/%v/hooks/%d", owner, repo, id)
   170  	req, err := s.client.NewRequest("DELETE", u, nil)
   171  	if err != nil {
   172  		return nil, err
   173  	}
   174  	return s.client.Do(ctx, req, nil)
   175  }
   176  
   177  // PingHook triggers a 'ping' event to be sent to the Hook.
   178  //
   179  // GitHub API docs: https://docs.github.com/en/rest/webhooks/repos#ping-a-repository-webhook
   180  func (s *RepositoriesService) PingHook(ctx context.Context, owner, repo string, id int64) (*Response, error) {
   181  	u := fmt.Sprintf("repos/%v/%v/hooks/%d/pings", owner, repo, id)
   182  	req, err := s.client.NewRequest("POST", u, nil)
   183  	if err != nil {
   184  		return nil, err
   185  	}
   186  	return s.client.Do(ctx, req, nil)
   187  }
   188  
   189  // TestHook triggers a test Hook by github.
   190  //
   191  // GitHub API docs: https://docs.github.com/en/rest/webhooks/repos#test-the-push-repository-webhook
   192  func (s *RepositoriesService) TestHook(ctx context.Context, owner, repo string, id int64) (*Response, error) {
   193  	u := fmt.Sprintf("repos/%v/%v/hooks/%d/tests", owner, repo, id)
   194  	req, err := s.client.NewRequest("POST", u, nil)
   195  	if err != nil {
   196  		return nil, err
   197  	}
   198  	return s.client.Do(ctx, req, nil)
   199  }
   200
View as plain text