github.com/google/go-github/v53@v53.2.0/github/codespaces.go (about) 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 := fmt.Sprint("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 }