Add SSH Git credentials docs

public/docs/img/infrastructure/git-credentials/images/git-credentials.png.json

@@ -1,5 +1 @@
-{
-  "width": 2530,
-  "height": 1726,
-  "updated": "2025-08-01T08:52:49.163Z"
-}
+{"width":1600,"height":927,"updated":"2026-06-01T03:34:52.312Z"}

public/docs/img/infrastructure/git-credentials/ssh-known-hosts/images/add-ssh-known-hosts.png.json

@@ -0,0 +1 @@
+{"width":645,"height":580,"updated":"2026-06-01T04:06:54.221Z"}

public/docs/img/infrastructure/git-credentials/ssh-known-hosts/images/ssh-known-hosts.png.json

@@ -0,0 +1 @@
+{"width":1600,"height":927,"updated":"2026-06-01T04:06:54.250Z"}

src/pages/docs/administration/spaces/index.mdx

@@ -103,7 +103,7 @@ Once you've done this, follow these steps:
 1. Return to **Configuration ➜ Spaces** and select the space that you wish to nominate as the default space.
 2. Click the overflow button and select **Enable the default space**.
 
-**Remove the default space**
+#### Remove the default space
 
 For organizations that are new to Octopus, especially those that make heavy use of spaces, a default space is not required, and you can remove the default space entirely. However, this comes with some considerations that should be weighed carefully against the needs of your organization.
 
@@ -138,22 +138,23 @@ The following table shows which Octopus resources are space-scoped, system-scope
 If a resource isn't listed below, then it's space-scoped.
 :::
 
-| Resource              | Space-scoped                | System-scoped |
-| --------------------- | --------------------------- | ------------- |
-| Environments          | True                        |               |
-| Lifecycles            | True                        |               |
-| Projects              | True                        |               |
-| Variable sets         | True                        |               |
-| Deployment targets    | True                        |               |
-| Tenants               | True                        |               |
-| Custom Step Templates | True                        |               |
-| Octopus Server nodes  |                             | True          |
-| Authentication        |                             | True          |
-| Users                 |                             | True          |
-| License               |                             | True          |
-| Events                | True                        | True          |
-| Teams                 | True                        | True          |
-| Tasks                 | True                        | True          |
+| Resource              | Space-scoped | System-scoped |
+| --------------------- | ------------ | ------------- |
+| Environments          | True         |               |
+| Lifecycles            | True         |               |
+| Projects              | True         |               |
+| Variable sets         | True         |               |
+| Deployment targets    | True         |               |
+| Tenants               | True         |               |
+| Custom Step Templates | True         |               |
+| Octopus Server nodes  |              | True          |
+| Authentication        |              | True          |
+| SSH Known Hosts       |              | True          |
+| Users                 |              | True          |
+| License               |              | True          |
+| Events                | True         | True          |
+| Teams                 | True         | True          |
+| Tasks                 | True         | True          |
 
 ## Automation changes to be aware of \{#automation-changes}
 

src/pages/docs/infrastructure/git-credentials/index.mdx

@@ -8,25 +8,59 @@ description: How to work with Git credentials.
 navOrder: 35
 ---
 
-Git credentials allow you to define your Git authentication credentials once, and reuse them across projects.
+Git credentials let you define your Git authentication credentials once, and reuse them across projects.
 
 You can manage your Git credentials by navigating to **Manage ➜ Git Credentials** in the Octopus Web Portal:
 
 :::figure
 ![The Git credentials area of Octopus Deploy](/docs/img/infrastructure/git-credentials/images/git-credentials.png)
 :::
 
+## Authentication methods
+
+Octopus supports two ways to authenticate a Git credential:
+
+- **Username and password** – a username with a password or personal access token. This works for any Git provider over HTTPS.
+- **SSH key** – an SSH private key, with an optional passphrase. Use this when you need to connect to a repository over SSH.
+
+You choose the authentication method when you add or edit a Git credential.
+
+### Username and password
+
+Enter the username for your Git provider, and a password or personal access token in the **Password** field. We recommend using a personal access token rather than a password, and following the principle of least privilege when you grant it scopes. For provider-specific guidance on creating an access token, see the [Config as Code authentication reference](/docs/projects/version-control/config-as-code-reference/#authentication).
+
+### SSH key
+
+:::div{.info}
+Available from Octopus 2026.2
+:::
+
+To authenticate with an SSH key:
+
+1. Add your private key either as a file upload or by manually entering it.
+2. If your private key is protected with a passphrase, enter it in the **Passphrase** field. Leave this empty if your key has no passphrase.
+
+Before Octopus can connect to a repository over SSH, it needs to trust the SSH host. Set up the hosts Octopus trusts on the [SSH known hosts](/docs/infrastructure/git-credentials/ssh-known-hosts) page.
+
+:::div{.warning}
+Known limitations with SSH key authentication:
+
+- Git operations that run on a Windows host (either server or Tentacle) aren't supported.
+- Repository URLs must include a username, for example `git@example.com:octopus/repo.git` or `ssh://git@example.com/octopus/repo.git`.
+
+:::
+
 ## Edit your Git credentials
 
-To edit individual environments, click the Git credential name. From here, it is possible to edit the name, description, change the username and password, set repository restrictions, or delete the Git credential.
+To edit an individual Git credential, click the Git credential name. From here you can edit the name and description, change the authentication method and credentials, set repository restrictions, or delete the Git credential.
 
 ## Git credential permissions
 
 You can control who has access to view and edit Git credentials by assigning users to Teams and assigning roles to those teams. For more information, see the section on [managing users and teams](/docs/security/users-and-teams).
 
 ## Repository Restrictions
 
-You can optionally restrict the Git credential to specified repository URL's. These can be complete repository URL’s or you can add a wildcard at the end to include everything under that path.
+You can optionally restrict the Git credential to specified repository URL's. These can be complete repository URL's or you can add a wildcard at the end to include everything under that path.
 
 :::figure
 ![The Git credentials area of Octopus Deploy](/docs/img/infrastructure/git-credentials/images/git-credential-details.png)

src/pages/docs/infrastructure/git-credentials/ssh-known-hosts/index.md

@@ -0,0 +1,53 @@
+---
+layout: src/layouts/Default.astro
+pubDate: 2026-06-01
+modDate: 2026-06-01
+title: SSH known hosts
+icon: fa-solid fa-shield-halved
+description: How to manage the SSH hosts Octopus trusts when connecting to Git repositories over SSH.
+navOrder: 10
+---
+
+When Octopus connects to a Git repository over SSH, it needs to know it's talking to the expected server and not an imposter. SSH known hosts record the public keys of the SSH servers Octopus trusts, so Octopus can verify each connection. They work the same way the `known_hosts` file works on your developer machine.
+
+If you want to authenticate a [Git credential](/docs/infrastructure/git-credentials) with an SSH key, you'll need to add the SSH host for that repository to your known hosts before you use it. Otherwise Octopus can't verify the server and the connection fails.
+
+:::figure
+![The SSH known hosts settings page in Octopus Deploy, showing a list of trusted SSH hosts](/docs/img/infrastructure/git-credentials/ssh-known-hosts/images/ssh-known-hosts.png)
+:::
+
+## Known hosts are system-wide
+
+SSH known hosts are system-wide. They're shared across every space in your instance, rather than being scoped to a single space. A host you add is trusted by every space, and a host you remove is no longer trusted by any space.
+
+## Manage your known hosts
+
+You manage SSH known hosts by navigating to **Configuration ➜ SSH Known Hosts** in the Octopus Web Portal.
+
+Octopus pre-seeds the list of known hosts with those of common cloud providers and will keep this list up to date via Octopus version updates.
+
+To add a new known host, provide the host, key type and a hash of the public key in the form `<host> <keytype> <publickey>` and save.
+
+Octopus accepts these in the same format that `ssh-keyscan` or your local `known_hosts` file stores them in. You can copy and paste from your terminal or local file to add them.
+
+:::figure
+![Adding SSH known hosts with a multi-line entry from ssh-keyscan](/docs/img/infrastructure/git-credentials/ssh-known-hosts/images/add-ssh-known-hosts.png)
+:::
+
+## Permissions
+
+Two permissions control access to SSH known hosts:
+
+| Permission                | Description                           |
+| ------------------------- | ------------------------------------- |
+| `SshKnownHostsView`       | View SSH known hosts                  |
+| `SshKnownHostsAdminister` | Add, edit, and remove SSH known hosts |
+
+Because known hosts are system-wide, these are system-level permissions.
+
+Access to Git credentials and SSH known hosts go hand in hand, so the built-in roles that can view or edit Git credentials are also granted these permissions by default. `SshKnownHostsView` is granted alongside the `GitCredentialView` permission, and `SshKnownHostsAdminister` alongside the `GitCredentialEdit` permission, so most users can view or administer SSH known hosts without any extra setup. For the permissions in each built-in role, see [default permissions for built-in user roles](/docs/security/users-and-teams/default-permissions). For more information on managing access, see [managing users and teams](/docs/security/users-and-teams).
+
+## Learn more
+
+- [Git credentials](/docs/infrastructure/git-credentials)
+- [Configuration as Code](/docs/projects/version-control)

src/pages/docs/projects/version-control/config-as-code-reference.mdx

@@ -333,7 +333,6 @@ All other resources will be referenced from OCL via their ID. We plan on growing
 When designing the config-as-code feature, we made several decisions to keep an appropriate balance of usability and functionality. There are a few limitations and items of note you should be aware of with config-as-code.
 
 - The Octopus Terraform Provider and OCL are not a 1:1 match. You cannot copy resources between the two and expect everything to work. We want to narrow the gap as much as possible, but as of right now, a gap exists.
-- Octopus currently only supports connecting to Git repositories over HTTPS and not SSH.
 - Shared resources (environments, external feeds, channels, etc.) are referenced by their slug from OCL. The API however will still use IDs.
 - Shared resources referenced in OCL that no longer exist in Octopus Server will result in an error when loading through the portal or API. The provided error message should provide information indicating what reference is no longer valid and should be updated or removed before being loaded again.
 - Shared resources must exist before loading an OCL file into Octopus Deploy. What that means is if you copy the OCL files from one Git repo to another, and point a new project at those files, then any shared resource must exist before creating that project. That only applies when projects are in different spaces or on different instances. If the resources do not exist, an error message will appear.