codespaces.go

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

     1  // Copyright 2023 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  // CodespacesService handles communication with the Codespaces related
    14  // methods of the GitHub API.
    15  //
    16  // GitHub API docs: https://docs.github.com/en/rest/codespaces/
    17  type CodespacesService service
    18  
    19  // Codespace represents a codespace.
    20  //
    21  // GitHub API docs: https://docs.github.com/en/rest/codespaces
    22  type Codespace struct {
    23  	ID                             *int64                        `json:"id,omitempty"`
    24  	Name                           *string                       `json:"name,omitempty"`
    25  	DisplayName                    *string                       `json:"display_name,omitempty"`
    26  	EnvironmentID                  *string                       `json:"environment_id,omitempty"`
    27  	Owner                          *User                         `json:"owner,omitempty"`
    28  	BillableOwner                  *User                         `json:"billable_owner,omitempty"`
    29  	Repository                     *Repository                   `json:"repository,omitempty"`
    30  	Machine                        *CodespacesMachine            `json:"machine,omitempty"`
    31  	DevcontainerPath               *string                       `json:"devcontainer_path,omitempty"`
    32  	Prebuild                       *bool                         `json:"prebuild,omitempty"`
    33  	CreatedAt                      *Timestamp                    `json:"created_at,omitempty"`
    34  	UpdatedAt                      *Timestamp                    `json:"updated_at,omitempty"`
    35  	LastUsedAt                     *Timestamp                    `json:"last_used_at,omitempty"`
    36  	State                          *string                       `json:"state,omitempty"`
    37  	URL                            *string                       `json:"url,omitempty"`
    38  	GitStatus                      *CodespacesGitStatus          `json:"git_status,omitempty"`
    39  	Location                       *string                       `json:"location,omitempty"`
    40  	IdleTimeoutMinutes             *int                          `json:"idle_timeout_minutes,omitempty"`
    41  	WebURL                         *string                       `json:"web_url,omitempty"`
    42  	MachinesURL                    *string                       `json:"machines_url,omitempty"`
    43  	StartURL                       *string                       `json:"start_url,omitempty"`
    44  	StopURL                        *string                       `json:"stop_url,omitempty"`
    45  	PullsURL                       *string                       `json:"pulls_url,omitempty"`
    46  	RecentFolders                  []string                      `json:"recent_folders,omitempty"`
    47  	RuntimeConstraints             *CodespacesRuntimeConstraints `json:"runtime_constraints,omitempty"`
    48  	PendingOperation               *bool                         `json:"pending_operation,omitempty"`
    49  	PendingOperationDisabledReason *string                       `json:"pending_operation_disabled_reason,omitempty"`
    50  	IdleTimeoutNotice              *string                       `json:"idle_timeout_notice,omitempty"`
    51  	RetentionPeriodMinutes         *int                          `json:"retention_period_minutes,omitempty"`
    52  	RetentionExpiresAt             *Timestamp                    `json:"retention_expires_at,omitempty"`
    53  	LastKnownStopNotice            *string                       `json:"last_known_stop_notice,omitempty"`
    54  }
    55  
    56  // CodespacesGitStatus represents the git status of a codespace.
    57  type CodespacesGitStatus struct {
    58  	Ahead                 *int    `json:"ahead,omitempty"`
    59  	Behind                *int    `json:"behind,omitempty"`
    60  	HasUnpushedChanges    *bool   `json:"has_unpushed_changes,omitempty"`
    61  	HasUncommittedChanges *bool   `json:"has_uncommitted_changes,omitempty"`
    62  	Ref                   *string `json:"ref,omitempty"`
    63  }
    64  
    65  // CodespacesMachine represents the machine type of a codespace.
    66  type CodespacesMachine struct {
    67  	Name                 *string `json:"name,omitempty"`
    68  	DisplayName          *string `json:"display_name,omitempty"`
    69  	OperatingSystem      *string `json:"operating_system,omitempty"`
    70  	StorageInBytes       *int64  `json:"storage_in_bytes,omitempty"`
    71  	MemoryInBytes        *int64  `json:"memory_in_bytes,omitempty"`
    72  	CPUs                 *int    `json:"cpus,omitempty"`
    73  	PrebuildAvailability *string `json:"prebuild_availability,omitempty"`
    74  }
    75  
    76  // CodespacesRuntimeConstraints represents the runtime constraints of a codespace.
    77  type CodespacesRuntimeConstraints struct {
    78  	AllowedPortPrivacySettings []string `json:"allowed_port_privacy_settings,omitempty"`
    79  }
    80  
    81  // ListCodespaces represents the response from the list codespaces endpoints.
    82  type ListCodespaces struct {
    83  	TotalCount *int         `json:"total_count,omitempty"`
    84  	Codespaces []*Codespace `json:"codespaces"`
    85  }
    86  
    87  // ListInRepo lists codespaces for a user in a repository.
    88  //
    89  // Lists the codespaces associated with a specified repository and the authenticated user.
    90  // You must authenticate using an access token with the codespace scope to use this endpoint.
    91  // GitHub Apps must have read access to the codespaces repository permission to use this endpoint.
    92  //
    93  // GitHub API docs: https://docs.github.com/en/rest/codespaces/codespaces?apiVersion=2022-11-28#list-codespaces-in-a-repository-for-the-authenticated-user
    94  func (s *CodespacesService) ListInRepo(ctx context.Context, owner, repo string, opts *ListOptions) (*ListCodespaces, *Response, error) {
    95  	u := fmt.Sprintf("repos/%v/%v/codespaces", owner, repo)
    96  	u, err := addOptions(u, opts)
    97  	if err != nil {
    98  		return nil, nil, err
    99  	}
   100  
   101  	req, err := s.client.NewRequest("GET", u, nil)
   102  	if err != nil {
   103  		return nil, nil, err
   104  	}
   105  
   106  	var codespaces *ListCodespaces
   107  	resp, err := s.client.Do(ctx, req, &codespaces)
   108  	if err != nil {
   109  		return nil, resp, err
   110  	}
   111  
   112  	return codespaces, resp, nil
   113  }
   114  
   115  // ListOptions represents the options for listing codespaces for a user.
   116  type ListCodespacesOptions struct {
   117  	ListOptions
   118  	RepositoryID int64 `url:"repository_id,omitempty"`
   119  }
   120  
   121  // List lists codespaces for an authenticated user.
   122  //
   123  // Lists the authenticated user's codespaces.
   124  // You must authenticate using an access token with the codespace scope to use this endpoint.
   125  // GitHub Apps must have read access to the codespaces repository permission to use this endpoint.
   126  //
   127  // GitHub API docs: https://docs.github.com/en/rest/codespaces/codespaces?apiVersion=2022-11-28#list-codespaces-for-the-authenticated-user
   128  func (s *CodespacesService) List(ctx context.Context, opts *ListCodespacesOptions) (*ListCodespaces, *Response, error) {
   129  	u := "user/codespaces"
   130  	u, err := addOptions(u, opts)
   131  	if err != nil {
   132  		return nil, nil, err
   133  	}
   134  
   135  	req, err := s.client.NewRequest("GET", u, nil)
   136  	if err != nil {
   137  		return nil, nil, err
   138  	}
   139  
   140  	var codespaces *ListCodespaces
   141  	resp, err := s.client.Do(ctx, req, &codespaces)
   142  	if err != nil {
   143  		return nil, resp, err
   144  	}
   145  
   146  	return codespaces, resp, nil
   147  }
   148  
   149  // CreateCodespaceOptions represents options for the creation of a codespace in a repository.
   150  type CreateCodespaceOptions struct {
   151  	Ref *string `json:"ref,omitempty"`
   152  	// Geo represents the geographic area for this codespace.
   153  	// If not specified, the value is assigned by IP.
   154  	// This property replaces location, which is being deprecated.
   155  	// Geo can be one of: `EuropeWest`, `SoutheastAsia`, `UsEast`, `UsWest`.
   156  	Geo                        *string `json:"geo,omitempty"`
   157  	ClientIP                   *string `json:"client_ip,omitempty"`
   158  	Machine                    *string `json:"machine,omitempty"`
   159  	DevcontainerPath           *string `json:"devcontainer_path,omitempty"`
   160  	MultiRepoPermissionsOptOut *bool   `json:"multi_repo_permissions_opt_out,omitempty"`
   161  	WorkingDirectory           *string `json:"working_directory,omitempty"`
   162  	IdleTimeoutMinutes         *int    `json:"idle_timeout_minutes,omitempty"`
   163  	DisplayName                *string `json:"display_name,omitempty"`
   164  	// RetentionPeriodMinutes represents the duration in minutes after codespace has gone idle in which it will be deleted.
   165  	// Must be integer minutes between 0 and 43200 (30 days).
   166  	RetentionPeriodMinutes *int `json:"retention_period_minutes,omitempty"`
   167  }
   168  
   169  // CreateInRepo creates a codespace in a repository.
   170  //
   171  // Creates a codespace owned by the authenticated user in the specified repository.
   172  // You must authenticate using an access token with the codespace scope to use this endpoint.
   173  // GitHub Apps must have write access to the codespaces repository permission to use this endpoint.
   174  //
   175  // GitHub API docs: https://docs.github.com/en/rest/codespaces/codespaces?apiVersion=2022-11-28#create-a-codespace-in-a-repository
   176  func (s *CodespacesService) CreateInRepo(ctx context.Context, owner, repo string, request *CreateCodespaceOptions) (*Codespace, *Response, error) {
   177  	u := fmt.Sprintf("repos/%v/%v/codespaces", owner, repo)
   178  
   179  	req, err := s.client.NewRequest("POST", u, request)
   180  	if err != nil {
   181  		return nil, nil, err
   182  	}
   183  
   184  	var codespace *Codespace
   185  	resp, err := s.client.Do(ctx, req, &codespace)
   186  	if err != nil {
   187  		return nil, resp, err
   188  	}
   189  
   190  	return codespace, resp, nil
   191  }
   192  
   193  // Start starts a codespace.
   194  //
   195  // You must authenticate using an access token with the codespace scope to use this endpoint.
   196  // GitHub Apps must have write access to the codespaces_lifecycle_admin repository permission to use this endpoint.
   197  //
   198  // GitHub API docs: https://docs.github.com/en/rest/codespaces/codespaces?apiVersion=2022-11-28#start-a-codespace-for-the-authenticated-user
   199  func (s *CodespacesService) Start(ctx context.Context, codespaceName string) (*Codespace, *Response, error) {
   200  	u := fmt.Sprintf("user/codespaces/%v/start", codespaceName)
   201  
   202  	req, err := s.client.NewRequest("POST", u, nil)
   203  	if err != nil {
   204  		return nil, nil, err
   205  	}
   206  
   207  	var codespace *Codespace
   208  	resp, err := s.client.Do(ctx, req, &codespace)
   209  	if err != nil {
   210  		return nil, resp, err
   211  	}
   212  
   213  	return codespace, resp, nil
   214  }
   215  
   216  // Stop stops a codespace.
   217  //
   218  // You must authenticate using an access token with the codespace scope to use this endpoint.
   219  // GitHub Apps must have write access to the codespaces_lifecycle_admin repository permission to use this endpoint.
   220  //
   221  // GitHub API docs: https://docs.github.com/en/rest/codespaces/codespaces?apiVersion=2022-11-28#stop-a-codespace-for-the-authenticated-user
   222  func (s *CodespacesService) Stop(ctx context.Context, codespaceName string) (*Codespace, *Response, error) {
   223  	u := fmt.Sprintf("user/codespaces/%v/stop", codespaceName)
   224  
   225  	req, err := s.client.NewRequest("POST", u, nil)
   226  	if err != nil {
   227  		return nil, nil, err
   228  	}
   229  
   230  	var codespace *Codespace
   231  	resp, err := s.client.Do(ctx, req, &codespace)
   232  	if err != nil {
   233  		return nil, resp, err
   234  	}
   235  
   236  	return codespace, resp, nil
   237  }
   238  
   239  // Delete deletes a codespace.
   240  //
   241  // You must authenticate using an access token with the codespace scope to use this endpoint.
   242  // GitHub Apps must have write access to the codespaces repository permission to use this endpoint.
   243  //
   244  // GitHub API docs: https://docs.github.com/en/rest/codespaces/codespaces?apiVersion=2022-11-28#delete-a-codespace-for-the-authenticated-user
   245  func (s *CodespacesService) Delete(ctx context.Context, codespaceName string) (*Response, error) {
   246  	u := fmt.Sprintf("user/codespaces/%v", codespaceName)
   247  
   248  	req, err := s.client.NewRequest("DELETE", u, nil)
   249  	if err != nil {
   250  		return nil, err
   251  	}
   252  
   253  	return s.client.Do(ctx, req, nil)
   254  }
   255
View as plain text