feat: add Platform Hub Version Control Settings and GitHub Connections

examples/platform_hub/configure_version_control_settings.go

@@ -0,0 +1,53 @@
+package examples
+
+import (
+	"fmt"
+	"net/url"
+
+	"github.com/OctopusDeploy/go-octopusdeploy/v2/pkg/client"
+	"github.com/OctopusDeploy/go-octopusdeploy/v2/pkg/core"
+	"github.com/OctopusDeploy/go-octopusdeploy/v2/pkg/credentials"
+	"github.com/OctopusDeploy/go-octopusdeploy/v2/pkg/platformhubversioncontrolsettings"
+)
+
+// ConfigurePlatformHubVersionControlSettingsExample provides an example of how to point
+// Platform Hub at a Git repository using username/password credentials.
+//
+// If the repository is already configured, changing the URL will repoint Platform Hub at the new repository.
+func ConfigurePlatformHubVersionControlSettingsExample() {
+	var (
+		apiKey     string = "API-YOUR_API_KEY"
+		octopusURL string = "https://your_octopus_url"
+
+		// version control values
+		gitURL        string = "https://github.com/your-org/your-repo.git"
+		gitUsername   string = "your-username"
+		gitPassword   string = "your-personal-access-token"
+		defaultBranch string = "main"
+		basePath      string = ".octopus/"
+	)
+
+	apiURL, err := url.Parse(octopusURL)
+	if err != nil {
+		_ = fmt.Errorf("error parsing URL for Octopus API: %v", err)
+		return
+	}
+
+	// Platform Hub is system-scoped, so no space ID is required
+	octopusClient, err := client.NewClient(nil, apiURL, apiKey, "")
+	if err != nil {
+		_ = fmt.Errorf("error creating API client: %v", err)
+		return
+	}
+
+	gitCredentials := credentials.NewUsernamePassword(gitUsername, core.NewSensitiveValue(gitPassword))
+	settings := platformhubversioncontrolsettings.NewResource(gitURL, gitCredentials, defaultBranch, basePath)
+
+	updatedSettings, err := platformhubversioncontrolsettings.Update(octopusClient, settings)
+	if err != nil {
+		_ = fmt.Errorf("error updating Platform Hub version control settings: %v", err)
+		return
+	}
+
+	fmt.Printf("Platform Hub configured against: (%s)\n", updatedSettings.URL)
+}

examples/platform_hub/configure_version_control_settings_with_github_connection.go

@@ -0,0 +1,71 @@
+package examples
+
+import (
+	"fmt"
+	"net/url"
+
+	"github.com/OctopusDeploy/go-octopusdeploy/v2/pkg/client"
+	"github.com/OctopusDeploy/go-octopusdeploy/v2/pkg/credentials"
+	"github.com/OctopusDeploy/go-octopusdeploy/v2/pkg/githubconnections"
+	"github.com/OctopusDeploy/go-octopusdeploy/v2/pkg/platformhubgithubconnections"
+	"github.com/OctopusDeploy/go-octopusdeploy/v2/pkg/platformhubversioncontrolsettings"
+)
+
+// ConfigurePlatformHubVersionControlSettingsWithGitHubConnectionExample provides an example
+// of how to point Platform Hub at a repository reachable through a GitHub App connection.
+//
+// The repository listing supplies both the Git URL and the repository's own default branch,
+// so neither needs to be provided.
+func ConfigurePlatformHubVersionControlSettingsWithGitHubConnectionExample() {
+	var (
+		apiKey     string = "API-YOUR_API_KEY"
+		octopusURL string = "https://your_octopus_url"
+
+		// version control values
+		connectionID   string = "GitHubAppConnections-1"
+		repositoryName string = "your-org/your-repo"
+		basePath       string = ".octopus/"
+	)
+
+	apiURL, err := url.Parse(octopusURL)
+	if err != nil {
+		_ = fmt.Errorf("error parsing URL for Octopus API: %v", err)
+		return
+	}
+
+	// Platform Hub is system-scoped, so no space ID is required
+	octopusClient, err := client.NewClient(nil, apiURL, apiKey, "")
+	if err != nil {
+		_ = fmt.Errorf("error creating API client: %v", err)
+		return
+	}
+
+	repositories, err := platformhubgithubconnections.GetRepositories(octopusClient, connectionID)
+	if err != nil {
+		_ = fmt.Errorf("error getting repositories for connection: %v", err)
+		return
+	}
+
+	var repository *githubconnections.Repository
+	for _, r := range repositories {
+		if r.RepositoryName == repositoryName {
+			repository = r
+			break
+		}
+	}
+	if repository == nil {
+		_ = fmt.Errorf("repository (%s) is not accessible through connection (%s)", repositoryName, connectionID)
+		return
+	}
+
+	gitCredentials := credentials.NewGitHubApp(connectionID)
+	settings := platformhubversioncontrolsettings.NewResource(repository.GitURL, gitCredentials, repository.DefaultBranch, basePath)
+
+	updatedSettings, err := platformhubversioncontrolsettings.Update(octopusClient, settings)
+	if err != nil {
+		_ = fmt.Errorf("error updating Platform Hub version control settings: %v", err)
+		return
+	}
+
+	fmt.Printf("Platform Hub configured against: (%s)\n", updatedSettings.URL)
+}

examples/platform_hub/get_github_connection_by_id.go

@@ -0,0 +1,53 @@
+package examples
+
+import (
+	"fmt"
+	"net/url"
+
+	"github.com/OctopusDeploy/go-octopusdeploy/v2/pkg/client"
+	"github.com/OctopusDeploy/go-octopusdeploy/v2/pkg/platformhubgithubconnections"
+)
+
+// GetPlatformHubGitHubConnectionByIDExample provides an example of how to get a single
+// Platform Hub GitHub App connection and the repositories it grants access to.
+func GetPlatformHubGitHubConnectionByIDExample() {
+	var (
+		apiKey     string = "API-YOUR_API_KEY"
+		octopusURL string = "https://your_octopus_url"
+
+		// GitHub connection values
+		connectionID string = "GitHubAppConnections-1"
+	)
+
+	apiURL, err := url.Parse(octopusURL)
+	if err != nil {
+		_ = fmt.Errorf("error parsing URL for Octopus API: %v", err)
+		return
+	}
+
+	// Platform Hub is system-scoped, so no space ID is required
+	octopusClient, err := client.NewClient(nil, apiURL, apiKey, "")
+	if err != nil {
+		_ = fmt.Errorf("error creating API client: %v", err)
+		return
+	}
+
+	connection, err := platformhubgithubconnections.GetByID(octopusClient, connectionID)
+	if err != nil {
+		_ = fmt.Errorf("error getting GitHub connection: %v", err)
+		return
+	}
+
+	fmt.Printf("connection: (%s) %s\n", connection.ID, connection.Installation.AccountLogin)
+	fmt.Printf("status: %s %s\n", connection.Status, connection.StatusUserMessage)
+
+	for _, repository := range connection.Repositories {
+		fmt.Printf("  repository: %s (%s)\n", repository.RepositoryName, repository.GitURL)
+	}
+
+	// repositories configured on the connection that GitHub no longer returns; they may have
+	// been deleted, renamed, or had access revoked
+	for _, repository := range connection.UnknownRepositories {
+		fmt.Printf("  unknown repository: %s (%s)\n", repository.RepositoryName, repository.RepositoryID)
+	}
+}

examples/platform_hub/get_version_control_settings.go

@@ -0,0 +1,53 @@
+package examples
+
+import (
+	"fmt"
+	"net/url"
+
+	"github.com/OctopusDeploy/go-octopusdeploy/v2/pkg/client"
+	"github.com/OctopusDeploy/go-octopusdeploy/v2/pkg/credentials"
+	"github.com/OctopusDeploy/go-octopusdeploy/v2/pkg/platformhubversioncontrolsettings"
+)
+
+// GetPlatformHubVersionControlSettingsExample provides an example of how to read the
+// Platform Hub version control settings from Octopus Deploy through the Go API client.
+func GetPlatformHubVersionControlSettingsExample() {
+	var (
+		apiKey     string = "API-YOUR_API_KEY"
+		octopusURL string = "https://your_octopus_url"
+	)
+
+	apiURL, err := url.Parse(octopusURL)
+	if err != nil {
+		_ = fmt.Errorf("error parsing URL for Octopus API: %v", err)
+		return
+	}
+
+	// Platform Hub is system-scoped, so no space ID is required
+	octopusClient, err := client.NewClient(nil, apiURL, apiKey, "")
+	if err != nil {
+		_ = fmt.Errorf("error creating API client: %v", err)
+		return
+	}
+
+	settings, err := platformhubversioncontrolsettings.Get(octopusClient)
+	if err != nil {
+		_ = fmt.Errorf("error getting Platform Hub version control settings: %v", err)
+		return
+	}
+
+	fmt.Printf("URL: %s\n", settings.URL)
+	fmt.Printf("default branch: %s\n", settings.DefaultBranch)
+	fmt.Printf("base path: %s\n", settings.BasePath)
+
+	switch creds := settings.Credentials.(type) {
+	case *credentials.Anonymous:
+		fmt.Println("credentials: anonymous")
+	case *credentials.UsernamePassword:
+		fmt.Printf("credentials: username/password (%s)\n", creds.Username)
+	case *credentials.GitHubApp:
+		fmt.Printf("credentials: GitHub App connection (%s)\n", creds.ID)
+	case nil:
+		fmt.Println("Platform Hub is not configured for version control")
+	}
+}

examples/platform_hub/list_github_connections.go

@@ -0,0 +1,78 @@
+package examples
+
+import (
+	"fmt"
+	"net/url"
+
+	"github.com/OctopusDeploy/go-octopusdeploy/v2/pkg/client"
+	"github.com/OctopusDeploy/go-octopusdeploy/v2/pkg/githubconnections"
+	"github.com/OctopusDeploy/go-octopusdeploy/v2/pkg/platformhubgithubconnections"
+)
+
+// ListPlatformHubGitHubConnectionsExample provides an example of how to list the GitHub App
+// connections available to Platform Hub, paging through the results.
+func ListPlatformHubGitHubConnectionsExample() {
+	var (
+		apiKey     string = "API-YOUR_API_KEY"
+		octopusURL string = "https://your_octopus_url"
+
+		// paging values; both skip and take are required by the API
+		take int = 30
+	)
+
+	apiURL, err := url.Parse(octopusURL)
+	if err != nil {
+		_ = fmt.Errorf("error parsing URL for Octopus API: %v", err)
+		return
+	}
+
+	// Platform Hub is system-scoped, so no space ID is required
+	octopusClient, err := client.NewClient(nil, apiURL, apiKey, "")
+	if err != nil {
+		_ = fmt.Errorf("error creating API client: %v", err)
+		return
+	}
+
+	settings, err := githubconnections.GetSettings(octopusClient)
+	if err != nil {
+		_ = fmt.Errorf("error getting GitHub App settings: %v", err)
+		return
+	}
+	if !settings.CanUseGitHubApp {
+		fmt.Println("this Octopus instance cannot use GitHub App connections")
+		return
+	}
+
+	var connections []*githubconnections.Connection
+	for {
+		page, err := platformhubgithubconnections.List(octopusClient, len(connections), take)
+		if err != nil {
+			_ = fmt.Errorf("error listing GitHub connections: %v", err)
+			return
+		}
+
+		connections = append(connections, page.Connections...)
+
+		if len(page.Connections) == 0 || len(connections) >= page.TotalResults {
+			break
+		}
+	}
+
+	for _, connection := range connections {
+		fmt.Printf("connection: (%s) %s %s [%s]\n", connection.ID, connection.Installation.AccountType, connection.Installation.AccountLogin, connection.Status)
+
+		if connection.Status != githubconnections.ConnectionStatusConnected {
+			continue
+		}
+
+		repositories, err := platformhubgithubconnections.GetRepositories(octopusClient, connection.ID)
+		if err != nil {
+			_ = fmt.Errorf("error getting repositories for connection: %v", err)
+			return
+		}
+
+		for _, repository := range repositories {
+			fmt.Printf("  repository: %s (%s), default branch: %s\n", repository.RepositoryName, repository.GitURL, repository.DefaultBranch)
+		}
+	}
+}

pkg/githubconnections/connection.go

@@ -0,0 +1,31 @@
+package githubconnections
+
+// ConnectionStatus describes the health of a GitHub App connection.
+type ConnectionStatus string
+
+const (
+	ConnectionStatusConnected             = ConnectionStatus("Connected")
+	ConnectionStatusConnectionNotFound    = ConnectionStatus("ConnectionNotFound")
+	ConnectionStatusInstallationNotFound  = ConnectionStatus("InstallationNotFound")
+	ConnectionStatusInstallationSuspended = ConnectionStatus("InstallationSuspended")
+	ConnectionStatusError                 = ConnectionStatus("Error")
+)
+
+// Installation represents the GitHub App installation backing a connection.
+type Installation struct {
+	InstallationID   string `json:"InstallationId"`
+	AccountID        string `json:"AccountId"`
+	AccountLogin     string `json:"AccountLogin"`
+	AccountAvatarURL string `json:"AccountAvatarUrl"`
+	AccountType      string `json:"AccountType"`
+	// AllRepositories is true when the installation can access every repository in the
+	// account, false when it is restricted to a selected set.
+	AllRepositories bool `json:"AllRepositories"`
+}
+
+// Connection represents a GitHub App connection.
+type Connection struct {
+	ID           string           `json:"Id"`
+	Status       ConnectionStatus `json:"Status,omitempty"`
+	Installation *Installation    `json:"Installation,omitempty"`
+}

pkg/githubconnections/repository.go

@@ -0,0 +1,20 @@
+package githubconnections
+
+// Repository represents a GitHub repository reachable through a GitHub App connection.
+type Repository struct {
+	RepositoryID   string `json:"RepositoryId"`
+	RepositoryName string `json:"RepositoryName"`
+	IsAdmin        bool   `json:"IsAdmin"`
+	IsPrivate      bool   `json:"IsPrivate"`
+	Visibility     string `json:"Visibility"`
+	Language       string `json:"Language,omitempty"`
+	GitURL         string `json:"GitUrl"`
+	DefaultBranch  string `json:"DefaultBranch"`
+}
+
+// UnknownRepository represents a repository configured on a connection that has no
+// matching repository returned from GitHub.
+type UnknownRepository struct {
+	RepositoryID   string `json:"RepositoryId"`
+	RepositoryName string `json:"RepositoryName,omitempty"`
+}

pkg/githubconnections/settings.go

@@ -0,0 +1,18 @@
+package githubconnections
+
+import (
+	"github.com/OctopusDeploy/go-octopusdeploy/v2/pkg/newclient"
+)
+
+const settingsPath = "/api/github/app/settings"
+
+// Settings represents the server-wide GitHub App settings.
+type Settings struct {
+	CanUseGitHubApp   bool `json:"CanUseGitHubApp"`
+	CanUseTrustedFlow bool `json:"CanUseTrustedFlow"`
+}
+
+// GetSettings returns the server's GitHub App settings.
+func GetSettings(client newclient.Client) (*Settings, error) {
+	return newclient.Get[Settings](client.HttpSession(), settingsPath)
+}