feat: Support git push via SSH (#2397)

Fixes: #2339

## Changes
- Automatically determine if HTTPS or SSH should be used based on the
remote URI
- SSH is configured via go-git transport using ssh-agent. Requires users
to upload their private keys to ssh-agent so that it can be picked up.
SSH-Agent is used so that the private key path + passphrase doesn't need
to passed in via env vars or flags.

## Result from running cloudtop
Command used: `librarian release init -push`. Resulted in PR created:
#2449

Logs from invocation:
```
level=INFO msg="Authenticating with SSH"
level=INFO msg="Successfully pushed changes"
level=INFO [msg="Creating PR" branch=librarian-20250926T172344Z base=main title="chore: librarian release pull request: 20250926T172344Z"](#2449)
level=INFO msg="PR created" url=#2449
level=INFO msg="Labels added to issue" number=2449 labels=[release:pending]
```

---------

Signed-off-by: Lawrence Qiu <[email protected]>

Author: lqiu96

README.md

@@ -52,13 +52,66 @@ command to run the latest released version:
 go run github.com/googleapis/librarian/cmd/librarian@latest -help
 ```
 
+### Setup and Configuration
+To run librarian, you will need to configure a Github Token and set it to the `LIBRARIAN_GITHUB_TOKEN` environment variable. This will use the Github token as authentication to push to Github and to run Github API commands (e.g. Creating a PR and Adding Labels to a PR).
+
+Unless specifically configured, Librarian will use HTTPS for pushing to remote. See the [SSH](#using-ssh) section for push to remote via SSH.
+
+### Github Token
+There are two main options to get a Github token:
+1. Use the [gh cli](https://cli.github.com/) tool to easily authenticate with github. Run the following commands once the tool is installed:
+```shell
+# Follow the instructions from the tool. If using SSH, see the section
+# below regarding additional setup.You still need a Github Token to run
+# Github API commands (e.g. creating a pull request).
+gh auth login 
+# This will output the token to use as the Github Token
+gh auth token
+```
+This will create a token with the `repo` scope.
+
+2. Alternatively, follow the steps listed in the Github [guide](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic) to create a Personal Access Token (PAT). You will need the `repo` scope for your token.
+
+Once you have created a token, set the token as the environment variable:
+```shell
+export LIBRARIAN_GITHUB_TOKEN={YOUR_TOKEN_HERE}
+```
+
+### Using SSH
+There are two main ways to configure SSH:
+1. Using the [gh cli](https://cli.github.com/) to upload your SSH public key to Github. When following the steps in the gh cli tool, you will select your public key to be added to Github. Additionally, you will need to add your private key to the [ssh-agent](https://linux.die.net/man/1/ssh-agent).
+
+Typically, your private keys will be `~/.ssh/id_ed25519` or `~/.ssh/id_rsa` and your public keys will be the same with the `.pub` suffix. You should be able to see this by running `ls ~/.ssh`. If you do not see a public/ private key combination, you can follow this [guide](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent) to generate a new key.
+
+Running the following commands to add your private key to ssh-agent:
+```sh
+# This will start the ssh-agent if it hasn't already been started
+eval "$(ssh-agent -s)"
+
+# This adds your private key to the ssh-agent.
+# Note: The private key will not have the `.pub` suffix.
+ssh-add ~/.ssh/{PRIVATE_KEY_FILE}
+
+# Run this command to verify that your private key is added
+# You should see an output of a SHA with an absolute path to the private key
+# e.g. `256 SHA:{MY_SHA} .../.ssh/id_ed25519`
+ssh-add -l
+```
+
+2. Follow the steps [here](https://docs.github.com/en/authentication/connecting-to-github-with-ssh). You will need to either create a new SSH key or using an existing one, add it to the ssh-agent, and then upload it to Github.
+
+Once everything has been configured, set the `origin` remote to the SSH URI:
+```shell
+git remote set-url origin [email protected]:googleapis/librarian.git
+```
+
 ## Documentation
 
 - [CLI Documentation](https://pkg.go.dev/github.com/googleapis/librarian/cmd/librarian)
 - [Language Onboarding Guide](doc/language-onboarding.md)
 - [How We Write Go](doc/howwewritego.md)
 - [State Schema](doc/state-schema.md)
-- [Config Schema](doc/config-schema.md))
+- [Config Schema](doc/config-schema.md)
 - [Running Tests](doc/testing.md)
 - [sidekick](doc/sidekick.md)
 

cmd/librarian/doc.go

@@ -77,7 +77,9 @@ in '.librarian/state.yaml'.
     the container to compile and validate the generated code.
   - If the '--push' flag is provided, the changes are committed to a new branch,
     and a pull request is created on GitHub. Otherwise, the changes are left in
-    your local working directory for inspection.
+    your local working directory for inspection. When pushing to a remote branch,
+    you have the option of using HTTPS or SSH. Librarian will automatically determine
+    whether to use HTTPS or SSH based on the remote URI.
 
 Example with build and push:
 
@@ -165,7 +167,9 @@ By default, 'release init' leaves the changes in your local working directory
 for inspection. Use the '--push' flag to automatically commit the changes to
 a new branch and create a pull request on GitHub. The '--commit' flag may be
 used to create a local commit without creating a pull request; this flag is
-ignored if '--push' is also specified.
+ignored if '--push' is also specified. When pushing to a remote branch,
+you have the option of using HTTPS or SSH. Librarian will automatically determine
+whether to use HTTPS or SSH based on the remote URI.
 
 Examples:
 

internal/config/config_test.go

@@ -35,8 +35,7 @@ func TestNew(t *testing.T) {
 		{
 			name: "All environment variables set",
 			envVars: map[string]string{
-				LibrarianGithubToken:        "gh_token",
-				"LIBRARIAN_SYNC_AUTH_TOKEN": "sync_token",
+				LibrarianGithubToken: "gh_token",
 			},
 			want: Config{
 				GitHubToken: "gh_token",
@@ -47,7 +46,6 @@ func TestNew(t *testing.T) {
 			name:    "No environment variables set",
 			envVars: map[string]string{},
 			want: Config{
-				GitHubToken: "",
 				CommandName: "test",
 			},
 		},

internal/gitrepo/gitrepo.go

@@ -19,6 +19,7 @@ import (
 	"errors"
 	"fmt"
 	"log/slog"
+	"net/url"
 	"os"
 	"os/exec"
 	"path/filepath"
@@ -29,7 +30,9 @@ import (
 	"github.com/go-git/go-git/v5/config"
 	"github.com/go-git/go-git/v5/plumbing"
 	"github.com/go-git/go-git/v5/plumbing/object"
+	"github.com/go-git/go-git/v5/plumbing/transport"
 	httpAuth "github.com/go-git/go-git/v5/plumbing/transport/http"
+	"github.com/go-git/go-git/v5/plumbing/transport/ssh"
 )
 
 // Repository defines the interface for git repository operations.
@@ -472,16 +475,29 @@ func (r *LocalRepository) DeleteBranch(branchName string) error {
 
 func (r *LocalRepository) pushRefSpec(refSpec string) error {
 	slog.Info("Pushing changes", "refSpec", refSpec)
-	var auth *httpAuth.BasicAuth
-	if r.gitPassword != "" {
-		slog.Info("Authenticating with basic auth")
-		auth = &httpAuth.BasicAuth{
-			// GitHub's authentication needs the username set to a non-empty value, but
-			// it does not need to match the token
-			Username: "cloud-sdk-librarian",
-			Password: r.gitPassword,
+
+	// Check for the configured URI for the `origin` remote.
+	// If there are multiple URLs, the first one is selected.
+	var remoteURI string
+	remotes, err := r.Remotes()
+	if err != nil {
+		return err
+	}
+	for _, remote := range remotes {
+		if remote.Name == "origin" {
+			if len(remote.URLs) > 0 {
+				remoteURI = remote.URLs[0]
+			}
 		}
 	}
+
+	useSSH := canUseSSH(remoteURI)
+	// While cloning a public repo does not require any authCreds, pushing
+	// to the repo requires authentication and verification of identity
+	auth, err := r.authCreds(useSSH)
+	if err != nil {
+		return err
+	}
 	if err := r.repo.Push(&git.PushOptions{
 		RemoteName: "origin",
 		RefSpecs:   []config.RefSpec{config.RefSpec(refSpec)},
@@ -493,6 +509,55 @@ func (r *LocalRepository) pushRefSpec(refSpec string) error {
 	return nil
 }
 
+// canUseSSH returns if the remote URI can connect via https ssh. It attempts to
+// automatically determine the type and returns false as a default if it's unable
+// to make a determination.
+func canUseSSH(remoteURI string) bool {
+	// First, try to parse it as a standard URL
+	// e.g. "https://github.com/golang/go.git", "ssh://[email protected]/golang/go.git"
+	parsedURL, err := url.Parse(remoteURI)
+	if err == nil && parsedURL.Scheme != "" {
+		// Check the scheme directly
+		switch parsedURL.Scheme {
+		case "https":
+			return false
+		case "ssh":
+			return true
+		}
+	}
+
+	// If parsing fails or the scheme is not standard, check for the `user@hostname`
+	// SSH syntax (e.g., "[email protected]:user/repo.git"). This format doesn't
+	// have a "://" and contains a ":"
+	if !strings.Contains(remoteURI, "://") && strings.Contains(remoteURI, ":") {
+		return true
+	}
+
+	return false
+}
+
+// authCreds returns the configured AuthMethod to used to pushing to the
+// remote repository. The useSSH determines if Basic Auth or SSH is used.
+func (r *LocalRepository) authCreds(useSSH bool) (transport.AuthMethod, error) {
+	if useSSH {
+		slog.Info("Authenticating with SSH")
+		// This is the generic `git` username when cloning via SSH. It is the value
+		// that exists before the URL. e.g. [email protected]:googleapis/librarian.git
+		auth, err := ssh.DefaultAuthBuilder("git")
+		if err != nil {
+			return nil, err
+		}
+		return auth, nil
+	}
+	slog.Info("Authenticating with basic auth")
+	return &httpAuth.BasicAuth{
+		// GitHub's authentication needs the username set to a non-empty value, but
+		// it does not need to match the token
+		Username: "cloud-sdk-librarian",
+		Password: r.gitPassword,
+	}, nil
+}
+
 // Restore restores changes in the working tree, leaving staged area untouched.
 // Note that untracked files, if any, are not touched.
 //

internal/gitrepo/gitrepo_test.go

@@ -1368,3 +1368,40 @@ func setupRepoForGetCommitsTest(t *testing.T) (*LocalRepository, map[string]stri
 
 	return &LocalRepository{Dir: dir, repo: repo}, commits
 }
+
+func TestCanUseSSH(t *testing.T) {
+	t.Parallel()
+	for _, test := range []struct {
+		name      string
+		remoteURI string
+		want      bool
+	}{
+		{
+			name:      "remote_https_uri",
+			remoteURI: "https://github.com/googleapis/librarian.git",
+			want:      false,
+		},
+		{
+			name:      "remote_ssh_uri",
+			remoteURI: "[email protected]:googleapis/librarian.git",
+			want:      true,
+		},
+		{
+			name:      "remote_ssh_uri_with_scheme",
+			remoteURI: "ssh://[email protected]/googleapis/librarian.git",
+			want:      true,
+		},
+		{
+			name:      "invalid_remote_uri",
+			remoteURI: "nonsense-uri",
+			want:      false,
+		},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			got := canUseSSH(test.remoteURI)
+			if diff := cmp.Diff(test.want, got); diff != "" {
+				t.Errorf("canUseSSH() mismatch in %s (-want +got):\n%s", test.name, diff)
+			}
+		})
+	}
+}

internal/librarian/help.go

@@ -68,7 +68,9 @@ in '.librarian/state.yaml'.
   the container to compile and validate the generated code.
 - If the '--push' flag is provided, the changes are committed to a new branch,
   and a pull request is created on GitHub. Otherwise, the changes are left in
-  your local working directory for inspection.
+  your local working directory for inspection. When pushing to a remote branch,
+  you have the option of using HTTPS or SSH. Librarian will automatically determine
+  whether to use HTTPS or SSH based on the remote URI.
 
 Example with build and push:
   LIBRARIAN_GITHUB_TOKEN=xxx librarian generate --push --build`
@@ -96,7 +98,9 @@ By default, 'release init' leaves the changes in your local working directory
 for inspection. Use the '--push' flag to automatically commit the changes to
 a new branch and create a pull request on GitHub. The '--commit' flag may be
 used to create a local commit without creating a pull request; this flag is
-ignored if '--push' is also specified.
+ignored if '--push' is also specified. When pushing to a remote branch,
+you have the option of using HTTPS or SSH. Librarian will automatically determine
+whether to use HTTPS or SSH based on the remote URI.
 
 Examples:
   # Create a release PR for all libraries with pending changes.