Skip to content

Provide more context on setting up GitHub Connections for self-hosted customers #3171

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mjhilton wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Provide more context on setting up GitHub Connections for self-hosted customers #3171

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3afdfa6
Clarify docs for self hosted hosting keys
lourens-octopus May 22, 2026
7a5e099
Provide better decision-making context for GitHub Connections, partic…
mjhilton May 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 19 additions & 9 deletions src/pages/docs/infrastructure/signing-keys/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Copy link
Copy Markdown
Contributor

@lourens-octopus lourens-octopus May 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: I think we generally refer to it as the Octopus GitHub app


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.
Copy link
Copy Markdown
Contributor

@stevencl840 stevencl840 May 24, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You need to provide the address you will use before generating the zip file, the issuer property of the discover document will be set correctly. To be this paragraph implies it can be changed after the files have been gernated whish not correct.


:::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**.
10 changes: 7 additions & 3 deletions src/pages/docs/projects/version-control/github/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -26,7 +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.

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.
#### 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 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

Expand Down Expand Up @@ -89,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.

Expand Down
Loading