doc: step-by-step process for configuring remotes

Author: isc-pbarton

README.md

@@ -1,4 +1,4 @@
-# git-source-control
+# Embedded Git for InterSystems
 Embedded Git support for InterSystems platforms, supporting unified source control for changes made via IDEs (e.g., VSCode over isfs) and the Management Portal (Interoperability and Business Intelligence).
 
 ## Prerequisites/Dependencies
@@ -128,7 +128,9 @@ again for more information.
 It is important for the namespace temp folder to be owned by the user IRIS runs as. (On Unix, commonly irisusr; on Windows, generally a designated service account or SYSTEM.) Setting this config flag is unlikely to actually help; just make sure the ownership is correct.
 
 #### Interacting with Remotes
-If you want to interact with remotes from VSCode/Studio directly (e.g., to push/pull), you must use ssh (rather than https), create a public/private key pair to identify the instance (not yourself), configure the private key file for use in Settings, and configure the public key as a deploy key in the remote(s).
+For detailed instructions on configuring remotes, see [this guide](/docs/configuring-remotes.md).
+
+If you want to interact with remotes from VSCode/Studio directly (e.g., to push/pull), you should use ssh (rather than https), create a public/private key pair to identify the instance (not yourself), configure the private key file for use in Settings, and configure the public key as a deploy key in the remote(s).
 
 #### IRIS Privileges
 For developers to be able to run this extension, they'll need the following privileges:

docs/configuring-remotes.md

@@ -0,0 +1,56 @@
+# Configuring Remotes
+
+This guide covers how to configure and interact with remote repositories in Embedded Git using the settings page.
+
+## Prerequisites
+
+- Git and Embedded Git installed on the server
+- A remote repository (e.g., GitHub, GitLab, Bitbucket)
+- Access to the Embedded Git settings page on the instance: https://hostname:port/prefix/isc/studio/usertemplates/gitsourcecontrol/gitprojectsettings.csp
+
+## Option 1: Configuring SSH authentication with a GitHub deploy key
+
+This option is best for shared development environments using GitHub.
+1. Enter a filename in the SSH Private Key File input of the settings form. Save the form.
+2. Click the "File not found - generate a new key pair?" button. Save the form.
+3. Copy the value of the "Public key" input on the settings page.
+4. In GitHub, go to repository settings > Deploy keys > Add deploy key. Paste the value from the previous step into the key. Check "Allow write access". Save the new key.
+5. In GitHub, copy the link to clone the repository via SSH.
+6. In Embedded Git settings, click the "Clone" button and paste the SSH repository URL into the confirmation dialog.
+
+## Option 2: Configuring SSH authentication with a personal SSH key
+
+This option is best for individual development environments using any remote that supports SSH authentication.
+
+Follow the steps for Option 1, but instead of adding the public key as a deploy key to the repository, add it to the SSH keys for your individual user on the Git remote. For example in GitHub here: https://github.com/settings/ssh/new
+
+## Option 3: Configuring HTTPS authentication with a personal access token
+
+This option is best for individual development environments using GitHub where SSH access to the remote is not permitted from the development server.
+
+1. In the GitHub repository, go to Settings > Developer Settings > Personal Access Tokens > Tokens (classic) > Generate new token (classic)
+2. Give the new token scope "repo". Click "Generate Token"
+3. Copy the token - it looks like ghp_abunchoflettersandnumbers
+4. In the Embedded Git settings page, click the "Clone" button. Include the personal access token in the remote URL like this: https://my-github-username:ghp_abunchoflettersandnumbers@github.com/org/repo.git
+
+## Option 4: Configuring HTTPS authentication with a project access token
+
+This option is best for shared development environments using GitLab where SSH access to the remote is not permitted from the development server.
+1. In GitLab, go to repository settings > Access Tokens > Add new token
+2. Give the token permissions to read and write the repository.
+3. Copy the token and save it somewhere secure.
+4. In the Embedded Git settings page, click the "Clone" button. Include the project access token in the URL like this: https://git:pastetokenhere@my-gitlab-tenant.example.com/org/repo.git
+
+## Frequently Asked Questions
+
+### How do I verify that my remote connection is working?
+
+After configuring your remote, refresh the Embedded Git settings page. The "Remote Repository" input should display the remote URL with a "Connection successful" message underneath. If you see an error message instead, review your authentication settings.
+
+### If multiple developers are pushing changes with the same deploy key or access token, will they all look like they came from the same user?
+
+In the git repository history, each commit will still be attributed to the individual user who made the commit.
+
+### My firewall blocks outgoing traffic on port 22. Can I still use SSH authentication?
+
+For GitHub specifically, you may be able to enable SSH connections over HTTPS following this guide: https://docs.github.com/en/authentication/troubleshooting-ssh/using-ssh-over-the-https-port. That involves making some changes to an SSH config file. To force Embedded Git to use a specific config file, edit the "Path to SSH Config File" input on the Embedded Git settings page.