From 3afdfa672f03a50e64279e7e58703d78baab3e35 Mon Sep 17 00:00:00 2001 From: Lourens de Jager <165963988+lourens-octopus@users.noreply.github.com> Date: Fri, 22 May 2026 14:17:21 +1200 Subject: [PATCH 1/2] Clarify docs for self hosted hosting keys --- src/pages/docs/projects/version-control/github/index.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/pages/docs/projects/version-control/github/index.md b/src/pages/docs/projects/version-control/github/index.md index b658961632..182e7cbdaa 100644 --- a/src/pages/docs/projects/version-control/github/index.md +++ b/src/pages/docs/projects/version-control/github/index.md @@ -26,6 +26,11 @@ You install the Octopus GitHub App on an account (organization or user) to give Selecting authorize will take you to GitHub to complete the installation and authorization process. +:::div{.info} +**Note:** +For self-hosted instances, the public [signing key](/docs/infrastructure/signing-keys) must be set up and accessible on the internet before authorizing the app. +::: + If you are authorizing the app for a self-hosted instance, you will be required to copy an access code over to your octopus instance. #### More information on installing and authorizing the Octopus GitHub App From 7a5e0995d20eda23b29c2dc69024cde103c7a711 Mon Sep 17 00:00:00 2001 From: Matt Hilton Date: Fri, 22 May 2026 14:02:41 +0800 Subject: [PATCH 2/2] Provide better decision-making context for GitHub Connections, particularly for self-host --- .../docs/infrastructure/signing-keys/index.md | 28 +++++++++++++------ .../projects/version-control/github/index.md | 13 ++++----- 2 files changed, 25 insertions(+), 16 deletions(-) diff --git a/src/pages/docs/infrastructure/signing-keys/index.md b/src/pages/docs/infrastructure/signing-keys/index.md index 014f47a444..860e4873ff 100644 --- a/src/pages/docs/infrastructure/signing-keys/index.md +++ b/src/pages/docs/infrastructure/signing-keys/index.md @@ -1,35 +1,45 @@ --- layout: src/layouts/Default.astro pubDate: 2023-11-01 -modDate: 2026-04-15 +modDate: 2026-05-22 title: Signing Keys description: Signing keys used for OpenID Connect authentication navOrder: 40 hideInThisSection: true --- -Octopus uses a signing key to sign the generated authorization request tokens used in the authentication flow for OpenID Connect. The public signing key is used by the resource server to validate the token supplied by Octopus. +Octopus uses a signing key to sign the tokens it generates as part of OpenID Connect (OIDC) authentication flows — including [GitHub Connections](/docs/projects/version-control/github) and [OIDC accounts](/docs/infrastructure/accounts/openid-connect) used to authenticate with cloud providers. Services that need to validate these tokens fetch the public key from your Octopus instance's OIDC discovery endpoint. -Depending on your security requirements, your public keys can either be hosted by your Octopus Deploy instance or delegated to a third party. +Your public keys can either be hosted by your Octopus instance or at a separate location you manage. ## Internally hosted -When using internally hosted public keys, your Octopus Deploy instance will host and manage them. Octopus Deploy will automatically rotate and revoke the keys according to your preferences. Any tokens Octopus Deploy creates will include the current public address of your Octopus Deploy instance as the issuer. Ensure your Octopus Deploy instance is accessible at this address. +When using internally hosted public keys, your Octopus instance hosts and manages them automatically. Octopus rotates and revokes keys according to your configured preferences, and tokens include your instance's address as the issuer. + +This is the right choice for **Octopus Cloud instances** and **self-hosted instances that are accessible from the internet**. Any service validating your tokens can reach the OIDC discovery endpoint on your instance directly. + +Ensure your instance is accessible at the address used as its issuer URL. ## Externally hosted -When externally hosting public keys, they will be available for download as a zip file. The contents of this zip file can then be hosted on any hosting provider that publicly serves HTTPS. The location where the files are hosted must be provided as the **OIDC Issuer URL**. When Octopus Deploy creates a token, the issuer will point to the **OIDC Issuer URL**. While the location specified by the issuer URL must be publicly available, the Octopus Deploy instance can be isolated from public access. +External hosting is for **self-hosted instances on private or isolated networks** that are not reachable from the internet. Services like the Octopus GitHub service or cloud providers need to fetch your public keys to validate tokens — if they can't reach your instance directly, you need to host those keys somewhere they can. + +When externally hosting, Octopus generates a ZIP file containing your OIDC discovery document and public key set. Host the contents of this file at any publicly accessible HTTPS location, then provide that address as the **OIDC Issuer URL**. Octopus uses this URL as the issuer in tokens it generates, and external services fetch keys from there instead of from your instance. :::div{.hint} -If the OIDC issuer URL is specified in Octopus Deploy's settings it will be used as the issuer when performing the OIDC authentication regardless of if Internal or External hosting in selected. +If the OIDC Issuer URL is set in Octopus's settings, it will be used as the issuer regardless of whether Internal or External hosting is selected. +::: + +:::div{.warning} +External hosting requires manual key rotation and adds operational overhead. Only use it when your instance is not publicly accessible and internal hosting isn't an option. ::: ### Rotating externally hosted keys -Externally hosted public keys must be manually rotated. Upon clicking **Rotate**, a new set of keys will be downloaded as a zip file. You will then need to upload the contents of this file to your chosen hosting provider. Octopus Deploy will poll the provided **OIDC Issuer URL** for the new keys. After it successfully validates that the new keys are available at the issuer URL, it will start using the new signing key. +Externally hosted keys must be rotated manually. Clicking **Rotate** downloads a new ZIP file with an updated key set. Upload the contents to your hosting provider, then Octopus polls the OIDC Issuer URL for the new keys. Once it confirms the new keys are available, it starts signing tokens with the new key. :::div{.info} -The new key set will include your previous active key. This ensures that all OIDC services continue to function while the key rotation is underway. Octopus Deploy will start signing tokens with the new key only after validating that the new key is available at the issuer URL. +The new key set includes your previous active key, so existing OIDC integrations continue to work while you complete the rotation. Octopus only starts signing with the new key after confirming it's available at the issuer URL. ::: -Support for manually managing signing keys has been added in **2026.2** and later. +Support for manually managing signing keys was added in **2026.2**. diff --git a/src/pages/docs/projects/version-control/github/index.md b/src/pages/docs/projects/version-control/github/index.md index 182e7cbdaa..07345e6ae1 100644 --- a/src/pages/docs/projects/version-control/github/index.md +++ b/src/pages/docs/projects/version-control/github/index.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2024-03-14 -modDate: 2026-04-16 +modDate: 2026-05-22 title: GitHub integration description: Octopus Deploy GitHub integration icon: fa-brands fa-github @@ -26,12 +26,11 @@ You install the Octopus GitHub App on an account (organization or user) to give Selecting authorize will take you to GitHub to complete the installation and authorization process. -:::div{.info} -**Note:** -For self-hosted instances, the public [signing key](/docs/infrastructure/signing-keys) must be set up and accessible on the internet before authorizing the app. -::: +#### Self-hosted instances + +Self-hosted instances have an extra step in the authorization flow compared to Octopus Cloud instances. After authorizing on GitHub, our intermediary GitHub Web App will provide you with an access code. Copy this code, and paste it into the field shown in your Octopus instance to complete the connection. -If you are authorizing the app for a self-hosted instance, you will be required to copy an access code over to your octopus instance. +If your instance is on a **private or isolated network** that is not accessible from the internet, you will also need to configure [external signing key hosting](/docs/infrastructure/signing-keys) before connecting. The Octopus GitHub service verifies your instance's identity by fetching its public signing key from your OIDC discovery endpoint — if your instance isn't reachable from the internet, you need to host those keys at a publicly accessible location first. #### More information on installing and authorizing the Octopus GitHub App @@ -94,7 +93,7 @@ Simply follow the on-screen prompts to reconnect the account and select the same ## Using GitHub App Connections -You can currently use GitHub App Connections to connect to Configuration as Code projects. This removes the need for using Personal Access Tokens to connect to GitHub repositories, and allows users to commit as their GitHub users (rather than using a shared account). +You can currently use GitHub App Connections to connect to Configuration as Code projects. This removes the need for Personal Access Tokens (PAT) to connect to GitHub repositories, and lets users commit as their GitHub users (rather than using a single shared account, as PATs lead you to do). You can also define GitHub Connections in [Platform Hub](/docs/platform-hub). GitHub Connections defined in Platform Hub can only be used to configure Platform Hub's version control settings and can't be used in spaces.