repos_pages.go

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

     1  // Copyright 2014 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  // Pages represents a GitHub Pages site configuration.
    14  type Pages struct {
    15  	URL              *string                `json:"url,omitempty"`
    16  	Status           *string                `json:"status,omitempty"`
    17  	CNAME            *string                `json:"cname,omitempty"`
    18  	Custom404        *bool                  `json:"custom_404,omitempty"`
    19  	HTMLURL          *string                `json:"html_url,omitempty"`
    20  	BuildType        *string                `json:"build_type,omitempty"`
    21  	Source           *PagesSource           `json:"source,omitempty"`
    22  	Public           *bool                  `json:"public,omitempty"`
    23  	HTTPSCertificate *PagesHTTPSCertificate `json:"https_certificate,omitempty"`
    24  	HTTPSEnforced    *bool                  `json:"https_enforced,omitempty"`
    25  }
    26  
    27  // PagesSource represents a GitHub page's source.
    28  type PagesSource struct {
    29  	Branch *string `json:"branch,omitempty"`
    30  	Path   *string `json:"path,omitempty"`
    31  }
    32  
    33  // PagesError represents a build error for a GitHub Pages site.
    34  type PagesError struct {
    35  	Message *string `json:"message,omitempty"`
    36  }
    37  
    38  // PagesBuild represents the build information for a GitHub Pages site.
    39  type PagesBuild struct {
    40  	URL       *string     `json:"url,omitempty"`
    41  	Status    *string     `json:"status,omitempty"`
    42  	Error     *PagesError `json:"error,omitempty"`
    43  	Pusher    *User       `json:"pusher,omitempty"`
    44  	Commit    *string     `json:"commit,omitempty"`
    45  	Duration  *int        `json:"duration,omitempty"`
    46  	CreatedAt *Timestamp  `json:"created_at,omitempty"`
    47  	UpdatedAt *Timestamp  `json:"updated_at,omitempty"`
    48  }
    49  
    50  // PagesDomain represents a domain associated with a GitHub Pages site.
    51  type PagesDomain struct {
    52  	Host                          *string `json:"host,omitempty"`
    53  	URI                           *string `json:"uri,omitempty"`
    54  	Nameservers                   *string `json:"nameservers,omitempty"`
    55  	DNSResolves                   *bool   `json:"dns_resolves,omitempty"`
    56  	IsProxied                     *bool   `json:"is_proxied,omitempty"`
    57  	IsCloudflareIP                *bool   `json:"is_cloudflare_ip,omitempty"`
    58  	IsFastlyIP                    *bool   `json:"is_fastly_ip,omitempty"`
    59  	IsOldIPAddress                *bool   `json:"is_old_ip_address,omitempty"`
    60  	IsARecord                     *bool   `json:"is_a_record,omitempty"`
    61  	HasCNAMERecord                *bool   `json:"has_cname_record,omitempty"`
    62  	HasMXRecordsPresent           *bool   `json:"has_mx_records_present,omitempty"`
    63  	IsValidDomain                 *bool   `json:"is_valid_domain,omitempty"`
    64  	IsApexDomain                  *bool   `json:"is_apex_domain,omitempty"`
    65  	ShouldBeARecord               *bool   `json:"should_be_a_record,omitempty"`
    66  	IsCNAMEToGithubUserDomain     *bool   `json:"is_cname_to_github_user_domain,omitempty"`
    67  	IsCNAMEToPagesDotGithubDotCom *bool   `json:"is_cname_to_pages_dot_github_dot_com,omitempty"`
    68  	IsCNAMEToFastly               *bool   `json:"is_cname_to_fastly,omitempty"`
    69  	IsPointedToGithubPagesIP      *bool   `json:"is_pointed_to_github_pages_ip,omitempty"`
    70  	IsNonGithubPagesIPPresent     *bool   `json:"is_non_github_pages_ip_present,omitempty"`
    71  	IsPagesDomain                 *bool   `json:"is_pages_domain,omitempty"`
    72  	IsServedByPages               *bool   `json:"is_served_by_pages,omitempty"`
    73  	IsValid                       *bool   `json:"is_valid,omitempty"`
    74  	Reason                        *string `json:"reason,omitempty"`
    75  	RespondsToHTTPS               *bool   `json:"responds_to_https,omitempty"`
    76  	EnforcesHTTPS                 *bool   `json:"enforces_https,omitempty"`
    77  	HTTPSError                    *string `json:"https_error,omitempty"`
    78  	IsHTTPSEligible               *bool   `json:"is_https_eligible,omitempty"`
    79  	CAAError                      *string `json:"caa_error,omitempty"`
    80  }
    81  
    82  // PagesHealthCheckResponse represents the response given for the health check of a GitHub Pages site.
    83  type PagesHealthCheckResponse struct {
    84  	Domain    *PagesDomain `json:"domain,omitempty"`
    85  	AltDomain *PagesDomain `json:"alt_domain,omitempty"`
    86  }
    87  
    88  // PagesHTTPSCertificate represents the HTTPS Certificate information for a GitHub Pages site.
    89  type PagesHTTPSCertificate struct {
    90  	State       *string  `json:"state,omitempty"`
    91  	Description *string  `json:"description,omitempty"`
    92  	Domains     []string `json:"domains,omitempty"`
    93  	// GitHub's API doesn't return a standard Timestamp, rather it returns a YYYY-MM-DD string.
    94  	ExpiresAt *string `json:"expires_at,omitempty"`
    95  }
    96  
    97  // createPagesRequest is a subset of Pages and is used internally
    98  // by EnablePages to pass only the known fields for the endpoint.
    99  type createPagesRequest struct {
   100  	BuildType *string      `json:"build_type,omitempty"`
   101  	Source    *PagesSource `json:"source,omitempty"`
   102  }
   103  
   104  // EnablePages enables GitHub Pages for the named repo.
   105  //
   106  // GitHub API docs: https://docs.github.com/en/rest/pages#create-a-github-pages-site
   107  func (s *RepositoriesService) EnablePages(ctx context.Context, owner, repo string, pages *Pages) (*Pages, *Response, error) {
   108  	u := fmt.Sprintf("repos/%v/%v/pages", owner, repo)
   109  
   110  	pagesReq := &createPagesRequest{
   111  		BuildType: pages.BuildType,
   112  		Source:    pages.Source,
   113  	}
   114  
   115  	req, err := s.client.NewRequest("POST", u, pagesReq)
   116  	if err != nil {
   117  		return nil, nil, err
   118  	}
   119  
   120  	req.Header.Set("Accept", mediaTypeEnablePagesAPIPreview)
   121  
   122  	enable := new(Pages)
   123  	resp, err := s.client.Do(ctx, req, enable)
   124  	if err != nil {
   125  		return nil, resp, err
   126  	}
   127  
   128  	return enable, resp, nil
   129  }
   130  
   131  // PagesUpdate sets up parameters needed to update a GitHub Pages site.
   132  type PagesUpdate struct {
   133  	// CNAME represents a custom domain for the repository.
   134  	// Leaving CNAME empty will remove the custom domain.
   135  	CNAME *string `json:"cname"`
   136  	// BuildType is optional and can either be "legacy" or "workflow".
   137  	// "workflow" - You are using a github workflow to build your pages.
   138  	// "legacy"   - You are deploying from a branch.
   139  	BuildType *string `json:"build_type,omitempty"`
   140  	// Source must include the branch name, and may optionally specify the subdirectory "/docs".
   141  	// Possible values for Source.Branch are usually "gh-pages", "main", and "master",
   142  	// or any other existing branch name.
   143  	// Possible values for Source.Path are: "/", and "/docs".
   144  	Source *PagesSource `json:"source,omitempty"`
   145  	// Public configures access controls for the site.
   146  	// If "true", the site will be accessible to anyone on the internet. If "false",
   147  	// the site will be accessible to anyone with read access to the repository that
   148  	// published the site.
   149  	Public *bool `json:"public,omitempty"`
   150  	// HTTPSEnforced specifies whether HTTPS should be enforced for the repository.
   151  	HTTPSEnforced *bool `json:"https_enforced,omitempty"`
   152  }
   153  
   154  // UpdatePages updates GitHub Pages for the named repo.
   155  //
   156  // GitHub API docs: https://docs.github.com/en/rest/pages#update-information-about-a-github-pages-site
   157  func (s *RepositoriesService) UpdatePages(ctx context.Context, owner, repo string, opts *PagesUpdate) (*Response, error) {
   158  	u := fmt.Sprintf("repos/%v/%v/pages", owner, repo)
   159  
   160  	req, err := s.client.NewRequest("PUT", u, opts)
   161  	if err != nil {
   162  		return nil, err
   163  	}
   164  
   165  	resp, err := s.client.Do(ctx, req, nil)
   166  	if err != nil {
   167  		return resp, err
   168  	}
   169  
   170  	return resp, nil
   171  }
   172  
   173  // DisablePages disables GitHub Pages for the named repo.
   174  //
   175  // GitHub API docs: https://docs.github.com/en/rest/pages#delete-a-github-pages-site
   176  func (s *RepositoriesService) DisablePages(ctx context.Context, owner, repo string) (*Response, error) {
   177  	u := fmt.Sprintf("repos/%v/%v/pages", owner, repo)
   178  	req, err := s.client.NewRequest("DELETE", u, nil)
   179  	if err != nil {
   180  		return nil, err
   181  	}
   182  
   183  	// TODO: remove custom Accept header when this API fully launches.
   184  	req.Header.Set("Accept", mediaTypeEnablePagesAPIPreview)
   185  
   186  	return s.client.Do(ctx, req, nil)
   187  }
   188  
   189  // GetPagesInfo fetches information about a GitHub Pages site.
   190  //
   191  // GitHub API docs: https://docs.github.com/en/rest/pages#get-a-github-pages-site
   192  func (s *RepositoriesService) GetPagesInfo(ctx context.Context, owner, repo string) (*Pages, *Response, error) {
   193  	u := fmt.Sprintf("repos/%v/%v/pages", owner, repo)
   194  	req, err := s.client.NewRequest("GET", u, nil)
   195  	if err != nil {
   196  		return nil, nil, err
   197  	}
   198  
   199  	site := new(Pages)
   200  	resp, err := s.client.Do(ctx, req, site)
   201  	if err != nil {
   202  		return nil, resp, err
   203  	}
   204  
   205  	return site, resp, nil
   206  }
   207  
   208  // ListPagesBuilds lists the builds for a GitHub Pages site.
   209  //
   210  // GitHub API docs: https://docs.github.com/en/rest/pages#list-github-pages-builds
   211  func (s *RepositoriesService) ListPagesBuilds(ctx context.Context, owner, repo string, opts *ListOptions) ([]*PagesBuild, *Response, error) {
   212  	u := fmt.Sprintf("repos/%v/%v/pages/builds", owner, repo)
   213  	u, err := addOptions(u, opts)
   214  	if err != nil {
   215  		return nil, nil, err
   216  	}
   217  
   218  	req, err := s.client.NewRequest("GET", u, nil)
   219  	if err != nil {
   220  		return nil, nil, err
   221  	}
   222  
   223  	var pages []*PagesBuild
   224  	resp, err := s.client.Do(ctx, req, &pages)
   225  	if err != nil {
   226  		return nil, resp, err
   227  	}
   228  
   229  	return pages, resp, nil
   230  }
   231  
   232  // GetLatestPagesBuild fetches the latest build information for a GitHub pages site.
   233  //
   234  // GitHub API docs: https://docs.github.com/en/rest/pages#get-latest-pages-build
   235  func (s *RepositoriesService) GetLatestPagesBuild(ctx context.Context, owner, repo string) (*PagesBuild, *Response, error) {
   236  	u := fmt.Sprintf("repos/%v/%v/pages/builds/latest", owner, repo)
   237  	req, err := s.client.NewRequest("GET", u, nil)
   238  	if err != nil {
   239  		return nil, nil, err
   240  	}
   241  
   242  	build := new(PagesBuild)
   243  	resp, err := s.client.Do(ctx, req, build)
   244  	if err != nil {
   245  		return nil, resp, err
   246  	}
   247  
   248  	return build, resp, nil
   249  }
   250  
   251  // GetPageBuild fetches the specific build information for a GitHub pages site.
   252  //
   253  // GitHub API docs: https://docs.github.com/en/rest/pages#get-github-pages-build
   254  func (s *RepositoriesService) GetPageBuild(ctx context.Context, owner, repo string, id int64) (*PagesBuild, *Response, error) {
   255  	u := fmt.Sprintf("repos/%v/%v/pages/builds/%v", owner, repo, id)
   256  	req, err := s.client.NewRequest("GET", u, nil)
   257  	if err != nil {
   258  		return nil, nil, err
   259  	}
   260  
   261  	build := new(PagesBuild)
   262  	resp, err := s.client.Do(ctx, req, build)
   263  	if err != nil {
   264  		return nil, resp, err
   265  	}
   266  
   267  	return build, resp, nil
   268  }
   269  
   270  // RequestPageBuild requests a build of a GitHub Pages site without needing to push new commit.
   271  //
   272  // GitHub API docs: https://docs.github.com/en/rest/pages#request-a-github-pages-build
   273  func (s *RepositoriesService) RequestPageBuild(ctx context.Context, owner, repo string) (*PagesBuild, *Response, error) {
   274  	u := fmt.Sprintf("repos/%v/%v/pages/builds", owner, repo)
   275  	req, err := s.client.NewRequest("POST", u, nil)
   276  	if err != nil {
   277  		return nil, nil, err
   278  	}
   279  
   280  	build := new(PagesBuild)
   281  	resp, err := s.client.Do(ctx, req, build)
   282  	if err != nil {
   283  		return nil, resp, err
   284  	}
   285  
   286  	return build, resp, nil
   287  }
   288  
   289  // GetPagesHealthCheck gets a DNS health check for the CNAME record configured for a repository's GitHub Pages.
   290  //
   291  // GitHub API docs: https://docs.github.com/en/rest/pages#get-a-dns-health-check-for-github-pages
   292  func (s *RepositoriesService) GetPageHealthCheck(ctx context.Context, owner, repo string) (*PagesHealthCheckResponse, *Response, error) {
   293  	u := fmt.Sprintf("repos/%v/%v/pages/health", owner, repo)
   294  	req, err := s.client.NewRequest("GET", u, nil)
   295  	if err != nil {
   296  		return nil, nil, err
   297  	}
   298  
   299  	healthCheckResponse := new(PagesHealthCheckResponse)
   300  	resp, err := s.client.Do(ctx, req, healthCheckResponse)
   301  	if err != nil {
   302  		return nil, resp, err
   303  	}
   304  
   305  	return healthCheckResponse, resp, nil
   306  }
   307
View as plain text