github.com/google/go-github/v66@v66.0.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/rest/codespaces/ 17 type CodespacesService service 18 19 // Codespace represents a codespace. 20 // 21 // GitHub API docs: https://docs.github.com/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/rest/codespaces/codespaces#list-codespaces-in-a-repository-for-the-authenticated-user 94 // 95 //meta:operation GET /repos/{owner}/{repo}/codespaces 96 func (s *CodespacesService) ListInRepo(ctx context.Context, owner, repo string, opts *ListOptions) (*ListCodespaces, *Response, error) { 97 u := fmt.Sprintf("repos/%v/%v/codespaces", owner, repo) 98 u, err := addOptions(u, opts) 99 if err != nil { 100 return nil, nil, err 101 } 102 103 req, err := s.client.NewRequest("GET", u, nil) 104 if err != nil { 105 return nil, nil, err 106 } 107 108 var codespaces *ListCodespaces 109 resp, err := s.client.Do(ctx, req, &codespaces) 110 if err != nil { 111 return nil, resp, err 112 } 113 114 return codespaces, resp, nil 115 } 116 117 // ListCodespacesOptions represents the options for listing codespaces for a user. 118 type ListCodespacesOptions struct { 119 ListOptions 120 RepositoryID int64 `url:"repository_id,omitempty"` 121 } 122 123 // List lists codespaces for an authenticated user. 124 // 125 // Lists the authenticated user's codespaces. 126 // You must authenticate using an access token with the codespace scope to use this endpoint. 127 // GitHub Apps must have read access to the codespaces repository permission to use this endpoint. 128 // 129 // GitHub API docs: https://docs.github.com/rest/codespaces/codespaces#list-codespaces-for-the-authenticated-user 130 // 131 //meta:operation GET /user/codespaces 132 func (s *CodespacesService) List(ctx context.Context, opts *ListCodespacesOptions) (*ListCodespaces, *Response, error) { 133 u := "user/codespaces" 134 u, err := addOptions(u, opts) 135 if err != nil { 136 return nil, nil, err 137 } 138 139 req, err := s.client.NewRequest("GET", u, nil) 140 if err != nil { 141 return nil, nil, err 142 } 143 144 var codespaces *ListCodespaces 145 resp, err := s.client.Do(ctx, req, &codespaces) 146 if err != nil { 147 return nil, resp, err 148 } 149 150 return codespaces, resp, nil 151 } 152 153 // CreateCodespaceOptions represents options for the creation of a codespace in a repository. 154 type CreateCodespaceOptions struct { 155 Ref *string `json:"ref,omitempty"` 156 // Geo represents the geographic area for this codespace. 157 // If not specified, the value is assigned by IP. 158 // This property replaces location, which is being deprecated. 159 // Geo can be one of: `EuropeWest`, `SoutheastAsia`, `UsEast`, `UsWest`. 160 Geo *string `json:"geo,omitempty"` 161 ClientIP *string `json:"client_ip,omitempty"` 162 Machine *string `json:"machine,omitempty"` 163 DevcontainerPath *string `json:"devcontainer_path,omitempty"` 164 MultiRepoPermissionsOptOut *bool `json:"multi_repo_permissions_opt_out,omitempty"` 165 WorkingDirectory *string `json:"working_directory,omitempty"` 166 IdleTimeoutMinutes *int `json:"idle_timeout_minutes,omitempty"` 167 DisplayName *string `json:"display_name,omitempty"` 168 // RetentionPeriodMinutes represents the duration in minutes after codespace has gone idle in which it will be deleted. 169 // Must be integer minutes between 0 and 43200 (30 days). 170 RetentionPeriodMinutes *int `json:"retention_period_minutes,omitempty"` 171 } 172 173 // CreateInRepo creates a codespace in a repository. 174 // 175 // Creates a codespace owned by the authenticated user in the specified repository. 176 // You must authenticate using an access token with the codespace scope to use this endpoint. 177 // GitHub Apps must have write access to the codespaces repository permission to use this endpoint. 178 // 179 // GitHub API docs: https://docs.github.com/rest/codespaces/codespaces#create-a-codespace-in-a-repository 180 // 181 //meta:operation POST /repos/{owner}/{repo}/codespaces 182 func (s *CodespacesService) CreateInRepo(ctx context.Context, owner, repo string, request *CreateCodespaceOptions) (*Codespace, *Response, error) { 183 u := fmt.Sprintf("repos/%v/%v/codespaces", owner, repo) 184 185 req, err := s.client.NewRequest("POST", u, request) 186 if err != nil { 187 return nil, nil, err 188 } 189 190 var codespace *Codespace 191 resp, err := s.client.Do(ctx, req, &codespace) 192 if err != nil { 193 return nil, resp, err 194 } 195 196 return codespace, resp, nil 197 } 198 199 // Start starts a codespace. 200 // 201 // You must authenticate using an access token with the codespace scope to use this endpoint. 202 // GitHub Apps must have write access to the codespaces_lifecycle_admin repository permission to use this endpoint. 203 // 204 // GitHub API docs: https://docs.github.com/rest/codespaces/codespaces#start-a-codespace-for-the-authenticated-user 205 // 206 //meta:operation POST /user/codespaces/{codespace_name}/start 207 func (s *CodespacesService) Start(ctx context.Context, codespaceName string) (*Codespace, *Response, error) { 208 u := fmt.Sprintf("user/codespaces/%v/start", codespaceName) 209 210 req, err := s.client.NewRequest("POST", u, nil) 211 if err != nil { 212 return nil, nil, err 213 } 214 215 var codespace *Codespace 216 resp, err := s.client.Do(ctx, req, &codespace) 217 if err != nil { 218 return nil, resp, err 219 } 220 221 return codespace, resp, nil 222 } 223 224 // Stop stops a codespace. 225 // 226 // You must authenticate using an access token with the codespace scope to use this endpoint. 227 // GitHub Apps must have write access to the codespaces_lifecycle_admin repository permission to use this endpoint. 228 // 229 // GitHub API docs: https://docs.github.com/rest/codespaces/codespaces#stop-a-codespace-for-the-authenticated-user 230 // 231 //meta:operation POST /user/codespaces/{codespace_name}/stop 232 func (s *CodespacesService) Stop(ctx context.Context, codespaceName string) (*Codespace, *Response, error) { 233 u := fmt.Sprintf("user/codespaces/%v/stop", codespaceName) 234 235 req, err := s.client.NewRequest("POST", u, nil) 236 if err != nil { 237 return nil, nil, err 238 } 239 240 var codespace *Codespace 241 resp, err := s.client.Do(ctx, req, &codespace) 242 if err != nil { 243 return nil, resp, err 244 } 245 246 return codespace, resp, nil 247 } 248 249 // Delete deletes a codespace. 250 // 251 // You must authenticate using an access token with the codespace scope to use this endpoint. 252 // GitHub Apps must have write access to the codespaces repository permission to use this endpoint. 253 // 254 // GitHub API docs: https://docs.github.com/rest/codespaces/codespaces#delete-a-codespace-for-the-authenticated-user 255 // 256 //meta:operation DELETE /user/codespaces/{codespace_name} 257 func (s *CodespacesService) Delete(ctx context.Context, codespaceName string) (*Response, error) { 258 u := fmt.Sprintf("user/codespaces/%v", codespaceName) 259 260 req, err := s.client.NewRequest("DELETE", u, nil) 261 if err != nil { 262 return nil, err 263 } 264 265 return s.client.Do(ctx, req, nil) 266 }