From f3f50105239b2b886ed3a87f951ea60f9758ce62 Mon Sep 17 00:00:00 2001 From: Pravin Barton <9560941+isc-pbarton@users.noreply.github.com> Date: Wed, 18 Feb 2026 16:54:24 -0500 Subject: [PATCH 1/2] doc: step-by-step process for configuring remotes --- README.md | 6 ++-- docs/configuring-remotes.md | 56 +++++++++++++++++++++++++++++++++++++ 2 files changed, 60 insertions(+), 2 deletions(-) create mode 100644 docs/configuring-remotes.md diff --git a/README.md b/README.md index 91b907d0..f72a000f 100644 --- a/README.md +++ b/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: diff --git a/docs/configuring-remotes.md b/docs/configuring-remotes.md new file mode 100644 index 00000000..3184adab --- /dev/null +++ b/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. \ No newline at end of file From eba988f97acf1551979db49b4a8e083bb2c627b1 Mon Sep 17 00:00:00 2001 From: Pravin Barton <9560941+isc-pbarton@users.noreply.github.com> Date: Wed, 18 Feb 2026 17:02:09 -0500 Subject: [PATCH 2/2] docs: swapped option order because individual dev environments is preferred. --- docs/configuring-remotes.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/docs/configuring-remotes.md b/docs/configuring-remotes.md index 3184adab..0c025815 100644 --- a/docs/configuring-remotes.md +++ b/docs/configuring-remotes.md @@ -8,21 +8,22 @@ This guide covers how to configure and interact with remote repositories in Embe - 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 +## Option 1: Configuring SSH authentication with a personal SSH 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. +This option is best for individual development environments using any remote that supports SSH authentication. + +1. Enter a filename in the SSH Private Key File input of the Embedded Git 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. +4. Add the public key to the SSH keys for your individual user on the Git remote. For example in GitHub: https://github.com/settings/ssh/new +5. In your Git remote, 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 +## Option 2: Configuring SSH authentication with a GitHub deploy key -This option is best for individual development environments using any remote that supports SSH authentication. +This option is best for shared development environments using GitHub. -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 +Follow the steps for Option 1, but in step 4, instead of adding the public key to your individual user's SSH keys, add it as a deploy key to the repository (repository settings > Deploy keys > Add deploy key). Check "Allow write access". ## Option 3: Configuring HTTPS authentication with a personal access token