diff --git a/public/docs/img/api-and-integration/github/github-connections-authorize-app.png b/public/docs/img/api-and-integration/github/github-connections-authorize-app.png new file mode 100644 index 0000000000..b730a5e264 Binary files /dev/null and b/public/docs/img/api-and-integration/github/github-connections-authorize-app.png differ diff --git a/public/docs/img/api-and-integration/github/github-connections-authorize-app.png.json b/public/docs/img/api-and-integration/github/github-connections-authorize-app.png.json new file mode 100644 index 0000000000..70d9f517aa --- /dev/null +++ b/public/docs/img/api-and-integration/github/github-connections-authorize-app.png.json @@ -0,0 +1,5 @@ +{ + "width": 1907, + "height": 1039, + "updated": "2026-04-21T01:05:53.678Z" +} diff --git a/src/pages/docs/projects/version-control/github/index.md b/src/pages/docs/projects/version-control/github/index.md index 131be2c8f4..b658961632 100644 --- a/src/pages/docs/projects/version-control/github/index.md +++ b/src/pages/docs/projects/version-control/github/index.md @@ -10,16 +10,32 @@ navOrder: 30 The Octopus Deploy GitHub App provides seamless integration between Octopus Deploy and GitHub. -:::div{.hint} -The Octopus Deploy GitHub App is only supported on Octopus Cloud instances. -::: - -To get started, go to the GitHub Connections page in the Deploy -> Manage section of your Octopus cloud instance, and follow the prompts. +To get started, go to the GitHub Connections page in the Deploy -> Manage section of your Octopus cloud instance. ## GitHub App Connections GitHub Connections is the recommended way to connect Octopus to your GitHub accounts (organizations or users). It provides seamless and secure connection via the Octopus GitHub App, without using personal access tokens. +### Installing and authorizing the Octopus GitHub App + +You install the Octopus GitHub App on an account (organization or user) to give it access to the repositories or other content within that account. Authorizing gives the Octopus GitHub App permission to act on your behalf in any account that has the app installed. + +:::figure +![Screenshot of GitHub Connections screen showing the Authorize Octopus Deploy GitHub App button](/docs/img/api-and-integration/github/github-connections-authorize-app.png) +::: + +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. + +#### More information on installing and authorizing the Octopus GitHub App + +Installing and authorizing are both GitHub concepts. If you want to find out more about what installing and authorizing GitHub App and how to manage these installation and authorizations, refer to the GitHub documentation: + +- [GitHub Apps documentation](https://docs.github.com/en/apps/using-github-apps/about-using-github-apps) +- [Installing GitHub apps documentation](https://docs.github.com/en/apps/using-github-apps/installing-a-github-app-from-a-third-party) +- [Authorizing GitHub apps documentation](https://docs.github.com/en/apps/using-github-apps/authorizing-github-apps) + ### Connecting a GitHub account Before you can use an GitHub account in Octopus Deploy, you need to connect the account to the Space. @@ -101,16 +117,7 @@ In order to use Octopus Deploy with GitHub allow lists, the IP address of your O Due to a limitation in the way that GitHub supports inheritance of IP addresses when performing actions on behalf of a user, the IP address for the GitHub App needs to be configured manually and cannot be inherited from the app settings. For more information please refer to [GitHub's Documentation](https://docs.github.com/en/enterprise-cloud@latest/apps/maintaining-github-apps/managing-allowed-ip-addresses-for-a-github-app#about-ip-address-allow-lists-for-github-apps) -## More information on installing and authorizing the Octopus GitHub App - -You install the Octopus GitHub App on an account (organization or user) to give the repositories or other content within that account. Authorizing gives the Octopus GitHub App permission to act on your behalf in any account that has the app installed. - -Installing and authorizing are both GitHub concepts. If you want to find out more about what installing and authorizing GitHub App and how to manage these installation and authorizations, refer to the GitHub documentation: - -- [GitHub Apps documentation](https://docs.github.com/en/apps/using-github-apps/about-using-github-apps) -- [Installing GitHub apps documentation](https://docs.github.com/en/apps/using-github-apps/installing-a-github-app-from-a-third-party) -- [Authorizing GitHub apps documentation](https://docs.github.com/en/apps/using-github-apps/authorizing-github-apps) - ## Older versions - Prior to version 2024.3.12703 when the new UI navigation was introduced, the GitHub Connections page is located in the Library section of Octopus. +- The Octopus GitHub App for self-hosted instances is only available from Octopus **2026.2** onwards.