From 7f2c8d46beff84060dfa82b1c75ec7a6d67c632d Mon Sep 17 00:00:00 2001 From: Rob E Date: Thu, 12 Feb 2026 14:03:05 +1000 Subject: [PATCH 1/7] Document requested permissions for GitHub App Added section on requested permissions for GitHub App connections, detailing repository and account permissions needed for Octopus. --- .../docs/projects/version-control/github/index.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/src/pages/docs/projects/version-control/github/index.md b/src/pages/docs/projects/version-control/github/index.md index dd6373dcab..18a94c278c 100644 --- a/src/pages/docs/projects/version-control/github/index.md +++ b/src/pages/docs/projects/version-control/github/index.md @@ -57,6 +57,18 @@ To connect a repository, you must be an administrator of the repository on GitHu ## 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). +## Requested Permissions +There are specific GitHub permissions that the Octopus GitHub App requests in order to perform it's tasks. + +* **Repository Permissions** + * **Contents: Read and Write** Allows Octopus to access the files in your repositories for usage such as [Config As Code](https://octopus.com/docs/projects/version-control) projects or Git Project Dependencies. + * **Metadata: Read-only** Default permission required by all GitHub Apps in to lead basic repository information. + * **Pull Requests: Read and Write** Used by Octopus when executing some steps, for example deploying releases for [Argo CD](https://octopus.com/docs/argo-cd). +* **Account Permissions** + * **Email addresses (Read-only):** Required so that Octopus can attempt to obtain the correct email address used when comitting the author information to a commmit. + +Where viable, whenever Octopus uses a token to perform an action a minimal token is used, scoped down in accordance with the principle of least privilege. + ## 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. @@ -72,4 +84,4 @@ Installing and authorizing are both GitHub concepts. If you want to find out mor ## 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. \ No newline at end of file +- 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. From dae1b036f1f179346228310603d691c6ab1a89cc Mon Sep 17 00:00:00 2001 From: Rob E Date: Thu, 12 Feb 2026 14:04:57 +1000 Subject: [PATCH 2/7] Update GitHub permissions description in index.md Clarify repository permissions for Octopus GitHub App. --- src/pages/docs/projects/version-control/github/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/pages/docs/projects/version-control/github/index.md b/src/pages/docs/projects/version-control/github/index.md index 18a94c278c..c5d3780b89 100644 --- a/src/pages/docs/projects/version-control/github/index.md +++ b/src/pages/docs/projects/version-control/github/index.md @@ -61,8 +61,8 @@ You can currently use GitHub App Connections to connect to Configuration as Code There are specific GitHub permissions that the Octopus GitHub App requests in order to perform it's tasks. * **Repository Permissions** - * **Contents: Read and Write** Allows Octopus to access the files in your repositories for usage such as [Config As Code](https://octopus.com/docs/projects/version-control) projects or Git Project Dependencies. - * **Metadata: Read-only** Default permission required by all GitHub Apps in to lead basic repository information. + * **Contents: Read and Write** Allows Octopus to access the files in the approved repositories for usage such as [Config As Code](https://octopus.com/docs/projects/version-control) projects or Git Project Dependencies. + * **Metadata: Read-only** Default permission required by all GitHub Apps in to load basic repository information. * **Pull Requests: Read and Write** Used by Octopus when executing some steps, for example deploying releases for [Argo CD](https://octopus.com/docs/argo-cd). * **Account Permissions** * **Email addresses (Read-only):** Required so that Octopus can attempt to obtain the correct email address used when comitting the author information to a commmit. From 5c59d2bd76380eaec3568597f4f8619249c8edde Mon Sep 17 00:00:00 2001 From: Rob E Date: Thu, 12 Feb 2026 14:12:25 +1000 Subject: [PATCH 3/7] Update index.md linting rules --- .../projects/version-control/github/index.md | 22 +++++++++++++------ 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/src/pages/docs/projects/version-control/github/index.md b/src/pages/docs/projects/version-control/github/index.md index c5d3780b89..d00d0a1820 100644 --- a/src/pages/docs/projects/version-control/github/index.md +++ b/src/pages/docs/projects/version-control/github/index.md @@ -11,15 +11,17 @@ 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. +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. ## 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. ### Connecting a GitHub account + Before you can use an GitHub account in Octopus Deploy, you need to connect the account to the Space. :::figure @@ -31,6 +33,7 @@ To connect a new account, select any currently disconnected account to go to the If you don't see an account that you're expecting in this list, the app probably hasn't been installed (Octopus cannot see an account that have the app installed). To install the Octopus GitHub App in a new account, select the link at the bottom of the screen to go to GitHub and complete the installation process. ### Editing GitHub Connections + When you first open the GitHub connection page, you will be in view mode. This will show the connection details and the currently connected repositories. To edit the connection, click the edit button at the top of the screen. This will put the connection in edit mode, and load the GitHub repositories that you are able to connect. You will not be able to save the connection unless you have at least 1 repository selected. To remove all repositories, disconnect the account completely using the Disconnect button in the overflow menu. @@ -40,11 +43,13 @@ You will not be able to save the connection unless you have at least 1 repositor ::: ### Selecting repositories on the GitHub Connection + Each GitHub Connection defines its own set of repositories (this is on top of the list of repositories configured on the installation in GitHub). GitHub accounts can only have a single GitHub App installation, so this installation is shared by all Octopus instances connected to that account. By requiring repositories are set for each connection as well, you are able to fine-tune the GitHub resources that each connection in each Space can access. If you ever add more repositories to the installation in GitHub, you can be confident that any existing connections cannot access this repository until you explicitly add it to those connections. This does add an extra step every time you want to add a new repository, but we believe this is worth it for the extra security this provides. #### If you can't see a repository + Octopus can only see repositories that are available to the app installation and the current user. If you can't see a repository that you expect to see on this screen, it may not be accessible to either you or the installation. To configure more repositories on a connection, follow the link at the bottom of the repository selection screen to configure more repositories on GitHub. :::figure @@ -52,20 +57,23 @@ Octopus can only see repositories that are available to the app installation and ::: #### Only repository administrators can connect repositories + To connect a repository, you must be an administrator of the repository on GitHub. If you're not an administrator (but can view the repository), you will still see the repository in the list, but will not be able to select it. ## 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). ## Requested Permissions + There are specific GitHub permissions that the Octopus GitHub App requests in order to perform it's tasks. -* **Repository Permissions** - * **Contents: Read and Write** Allows Octopus to access the files in the approved repositories for usage such as [Config As Code](https://octopus.com/docs/projects/version-control) projects or Git Project Dependencies. - * **Metadata: Read-only** Default permission required by all GitHub Apps in to load basic repository information. - * **Pull Requests: Read and Write** Used by Octopus when executing some steps, for example deploying releases for [Argo CD](https://octopus.com/docs/argo-cd). -* **Account Permissions** - * **Email addresses (Read-only):** Required so that Octopus can attempt to obtain the correct email address used when comitting the author information to a commmit. +- **Repository Permissions** + - **Contents: Read and Write** Allows Octopus to access the files in the approved repositories for usage such as [Config As Code](https://octopus.com/docs/projects/version-control) projects or Git Project Dependencies. + - **Metadata: Read-only** Default permission required by all GitHub Apps in to load basic repository information. + - **Pull Requests: Read and Write** Used by Octopus when executing some steps, for example deploying releases for [Argo CD](https://octopus.com/docs/argo-cd). +- **Account Permissions** + - **Email addresses (Read-only):** Required so that Octopus can attempt to obtain the correct email address used when comitting the author information to a commmit. Where viable, whenever Octopus uses a token to perform an action a minimal token is used, scoped down in accordance with the principle of least privilege. From fa0c810bb2f0f0111148ebf9a1d1920ce376cc03 Mon Sep 17 00:00:00 2001 From: Rob E Date: Thu, 12 Feb 2026 14:19:51 +1000 Subject: [PATCH 4/7] Update index.md --- src/pages/docs/projects/version-control/github/index.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/pages/docs/projects/version-control/github/index.md b/src/pages/docs/projects/version-control/github/index.md index d00d0a1820..993fc93387 100644 --- a/src/pages/docs/projects/version-control/github/index.md +++ b/src/pages/docs/projects/version-control/github/index.md @@ -69,15 +69,17 @@ You can currently use GitHub App Connections to connect to Configuration as Code There are specific GitHub permissions that the Octopus GitHub App requests in order to perform it's tasks. - **Repository Permissions** - - **Contents: Read and Write** Allows Octopus to access the files in the approved repositories for usage such as [Config As Code](https://octopus.com/docs/projects/version-control) projects or Git Project Dependencies. + - **Contents: Read and Write** Allows Octopus to access the files in the approved repositories for usage such as [Config As Code](https://octopus.com/docs/projects/version-control) projects or Git Project Dependencies. Writing using the installation token is only utilized during non-user triggered operations that result in new commits, such as deployments. - **Metadata: Read-only** Default permission required by all GitHub Apps in to load basic repository information. - **Pull Requests: Read and Write** Used by Octopus when executing some steps, for example deploying releases for [Argo CD](https://octopus.com/docs/argo-cd). - **Account Permissions** - **Email addresses (Read-only):** Required so that Octopus can attempt to obtain the correct email address used when comitting the author information to a commmit. + Where viable, whenever Octopus uses a token to perform an action a minimal token is used, scoped down in accordance with the principle of least privilege. ## 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: From db7115369f9354b88de43dd4c2e9faf8e4781714 Mon Sep 17 00:00:00 2001 From: Rob E Date: Thu, 12 Feb 2026 14:23:39 +1000 Subject: [PATCH 5/7] Update index.md --- src/pages/docs/projects/version-control/github/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/pages/docs/projects/version-control/github/index.md b/src/pages/docs/projects/version-control/github/index.md index 993fc93387..bf74d00dda 100644 --- a/src/pages/docs/projects/version-control/github/index.md +++ b/src/pages/docs/projects/version-control/github/index.md @@ -69,9 +69,9 @@ You can currently use GitHub App Connections to connect to Configuration as Code There are specific GitHub permissions that the Octopus GitHub App requests in order to perform it's tasks. - **Repository Permissions** - - **Contents: Read and Write** Allows Octopus to access the files in the approved repositories for usage such as [Config As Code](https://octopus.com/docs/projects/version-control) projects or Git Project Dependencies. Writing using the installation token is only utilized during non-user triggered operations that result in new commits, such as deployments. + - **Contents: Read and Write** Allows Octopus to access the files in the approved repositories for usage such as [Config As Code](https://octopus.com/docs/projects/version-control) projects, [Git Resources in deployments](https://octopus.com/blog/git-resources-in-deployments) or during some steps such as [Argo CD](https://octopus.com/docs/argo-cd). - **Metadata: Read-only** Default permission required by all GitHub Apps in to load basic repository information. - - **Pull Requests: Read and Write** Used by Octopus when executing some steps, for example deploying releases for [Argo CD](https://octopus.com/docs/argo-cd). + - **Pull Requests: Read and Write** Used by Octopus when executing some steps, for example supporting pull requests for Argo CD deployments. - **Account Permissions** - **Email addresses (Read-only):** Required so that Octopus can attempt to obtain the correct email address used when comitting the author information to a commmit. From 891919b683cc03a25b6808cb794a137e12b0035a Mon Sep 17 00:00:00 2001 From: Rob E Date: Thu, 12 Feb 2026 14:25:09 +1000 Subject: [PATCH 6/7] Update index.md --- src/pages/docs/projects/version-control/github/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/pages/docs/projects/version-control/github/index.md b/src/pages/docs/projects/version-control/github/index.md index bf74d00dda..e9cdf62013 100644 --- a/src/pages/docs/projects/version-control/github/index.md +++ b/src/pages/docs/projects/version-control/github/index.md @@ -75,8 +75,8 @@ There are specific GitHub permissions that the Octopus GitHub App requests in or - **Account Permissions** - **Email addresses (Read-only):** Required so that Octopus can attempt to obtain the correct email address used when comitting the author information to a commmit. - -Where viable, whenever Octopus uses a token to perform an action a minimal token is used, scoped down in accordance with the principle of least privilege. + +Whenever possible, Octopus uses a token scoped down to minimal permissions in accordance with the principle of least privilege. ## More information on installing and authorizing the Octopus GitHub App From 6a08d844f4eb780923c758dcea98d8905f229b1e Mon Sep 17 00:00:00 2001 From: Steve Fenton <99181436+steve-fenton-octopus@users.noreply.github.com> Date: Mon, 16 Feb 2026 08:08:57 +0000 Subject: [PATCH 7/7] Fix spelling errors --- src/pages/docs/projects/version-control/github/index.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/src/pages/docs/projects/version-control/github/index.md b/src/pages/docs/projects/version-control/github/index.md index e9cdf62013..da9be88229 100644 --- a/src/pages/docs/projects/version-control/github/index.md +++ b/src/pages/docs/projects/version-control/github/index.md @@ -73,8 +73,7 @@ There are specific GitHub permissions that the Octopus GitHub App requests in or - **Metadata: Read-only** Default permission required by all GitHub Apps in to load basic repository information. - **Pull Requests: Read and Write** Used by Octopus when executing some steps, for example supporting pull requests for Argo CD deployments. - **Account Permissions** - - **Email addresses (Read-only):** Required so that Octopus can attempt to obtain the correct email address used when comitting the author information to a commmit. - + - **Email addresses (Read-only):** Required so that Octopus can attempt to obtain the correct email address used when committing the author information to a commit. Whenever possible, Octopus uses a token scoped down to minimal permissions in accordance with the principle of least privilege. @@ -90,7 +89,7 @@ Installing and authorizing are both GitHub concepts. If you want to find out mor ## Known limitations -* Connecting to GitHub organizations with IP allow lists enabled is not currently supported with Octopus GitHub App Connections. +- Connecting to GitHub organizations with IP allow lists enabled is not currently supported with Octopus GitHub App Connections. ## Older versions