Document OCTOPUS__Git__CacheFullThresholdMb env var (#3087)

* Document OCTOPUS__Git__CacheFullThresholdMb env var

* Fix inaccurate list of affected operations

* Add converting to VCS as affected operation

* Fix markdownlint errors in config-as-code-reference

* Remove heading ID that breaks MDX parser

Author: HuyPhanNguyen

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

@@ -21,18 +21,18 @@ Currently, the Project level resources saved to Git are:
 
 - Deployment Process
 - Deployment Settings
-    - Release Versioning
-    - Release Notes Template
-    - Deployment Targets Required
-    - Transient Deployment Targets
-    - Deployment Changes Template
-    - Default Failure Mode
+  - Release Versioning
+  - Release Notes Template
+  - Deployment Targets Required
+  - Transient Deployment Targets
+  - Deployment Changes Template
+  - Default Failure Mode
 - Runbook Process
 - Runbook Settings
-    - Multi-tenancy Mode
-    - Run Retention Policy
-    - Connectivity Policy
-    - Default Failure Mode
+  - Multi-tenancy Mode
+  - Run Retention Policy
+  - Connectivity Policy
+  - Default Failure Mode
 - Variables (excluding Sensitive variables)
 
 :::div{.hint}
@@ -49,11 +49,11 @@ Currently, the Project level resources saved to SQL Server when version control
 - Deployments
 - Sensitive Variables
 - General Settings
-    - Project Name
-    - Enabled / Disabled
-    - Logo
-    - Description
-    - Project Group
+  - Project Name
+  - Enabled / Disabled
+  - Logo
+  - Description
+  - Project Group
 
 :::div{.hint}
 Sensitive Variables are planned for future releases of config-as-code.
@@ -64,36 +64,36 @@ Sensitive Variables are planned for future releases of config-as-code.
 The config-as-code feature manages project-level resources. However, it is worth explicitly mentioning some things that are **not included**:
 
 - Infrastructure
-    - Environments
-    - Deployment Targets
-    - Workers
-    - Worker Pools        
-    - Machine Policies
-    - Machine Proxies
-    - Accounts
+  - Environments
+  - Deployment Targets
+  - Workers
+  - Worker Pools
+  - Machine Policies
+  - Machine Proxies
+  - Accounts
 - Tenants
 - Library
-    - Certificates
-    - External Feeds
-    - Lifecycles
-    - Packages
-    - Build Information
-    - Script Modules
-    - Step Templates
-    - Variable Sets
+  - Certificates
+  - External Feeds
+  - Lifecycles
+  - Packages
+  - Build Information
+  - Script Modules
+  - Step Templates
+  - Variable Sets
 - Server Configuration
-    - Feature Flags
-    - License
-    - Node Settings (Task Cap and Server Uri)
-    - Issue Tracker Settings
-    - External Auth Provider Settings
-    - SMTP
-    - Spaces
-    - Teams (both membership and role assignment)
-    - Users
-    - User Roles
-
-Currently, there are no plans to include these resources in the config-as-code feature. Several of the resources above can be put into version control using the [Octopus Terraform Provider](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs). 
+  - Feature Flags
+  - License
+  - Node Settings (Task Cap and Server Uri)
+  - Issue Tracker Settings
+  - External Auth Provider Settings
+  - SMTP
+  - Spaces
+  - Teams (both membership and role assignment)
+  - Users
+  - User Roles
+
+Currently, there are no plans to include these resources in the config-as-code feature. Several of the resources above can be put into version control using the [Octopus Terraform Provider](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs).
 
 :::div{.hint}
 Resources managed by the Octopus Terraform Provider will have their state managed by Terraform. Resources managed by the Octopus config-as-code feature will have the state managed by Octopus Deploy. The two are not the same and shouldn't be treated as such.
@@ -105,36 +105,37 @@ Project version control settings can be accessed by clicking on the **Settings 
 
 ### Git repository
 
-The _Git Repository_ field should contain the URL for the repository you wish the Octopus configuration to be persisted to. e.g. `https://github.com/OctopusSamples/OctoFX.git`  
+The *Git Repository* field should contain the URL for the repository you wish the Octopus configuration to be persisted to. e.g. `https://github.com/OctopusSamples/OctoFX.git`
 
 <VersionControlRepositoryUrlFormat />
 
 The repository must be initialized (i.e. contain at least one branch) prior to saving. Octopus will convert the existing items in the project to OCL (Octopus Configuration Language) and save it to that repository when you click save. If the repository isn't initialized, that will fail.
 
 ### Authentication
 
-The config-as-code feature is designed to work with _any_ Git repository. When configuring a project to be version-controlled, you can optionally provide credentials for authentication.
+The config-as-code feature is designed to work with *any* Git repository. When configuring a project to be version-controlled, you can optionally provide credentials for authentication.
 
 :::div{.hint}
 Do not use credentials from a personal account. Select a shared or service account. When Octopus Deploy saves to your Git repo, you will typically see the message `[User Name] authored and [Service Account] committed on [Date].`
 :::
 
 For the Password field, we recommend using a personal access token. We also recommend that you follow the principle of least privilege when selecting scopes or permissions to grant this personal access token.
 
-Git providers allow you to create an access token in different ways. The recommended _scope_ for each provider is listed in brackets.
+Git providers allow you to create an access token in different ways. The recommended *scope* for each provider is listed in brackets.
 
--   [GitHub - Creating a fine-grained personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#creating-a-fine-grained-personal-access-token); (Permission - `Contents - Read and Write`)
--   [GitHub - Creating a personal access token (Classic)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#creating-a-personal-access-token-classic); (Scope - `repo`)
--   [Azure DevOps](https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate); (Scope - `vso.code_full`)
--   [GitLab](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html); (Scope - `write_repository`)
--   [BitBucket Server](https://confluence.atlassian.com/bitbucketserver063/personal-access-tokens-972354166.html); (Permission - `Project admin`)
--   [BitBucket Cloud - Use App Passwords](https://support.atlassian.com/bitbucket-cloud/docs/app-passwords/); (Permission - `Repositories - Read & Write`)
+- [GitHub - Creating a fine-grained personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#creating-a-fine-grained-personal-access-token); (Permission - `Contents - Read and Write`)
+- [GitHub - Creating a personal access token (Classic)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#creating-a-personal-access-token-classic); (Scope - `repo`)
+- [Azure DevOps](https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate); (Scope - `vso.code_full`)
+- [GitLab](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html); (Scope - `write_repository`)
+- [BitBucket Server](https://confluence.atlassian.com/bitbucketserver063/personal-access-tokens-972354166.html); (Permission - `Project admin`)
+- [BitBucket Cloud - Use App Passwords](https://support.atlassian.com/bitbucket-cloud/docs/app-passwords/); (Permission - `Repositories - Read & Write`)
 
 :::div{.hint}
 Some VCS providers require that you use only a username and personal access token for authentication, not an email address (i.e. BitBucket).
 :::
 
 #### BitBucket repository access tokens
+
 BitBucket's repository access tokens allow you to create repository-specific access tokens. For these to work with your Git repositories in Octopus, you must set the username to `x-token-auth`, and the password to the token.
 
 :::figure
@@ -143,7 +144,7 @@ BitBucket's repository access tokens allow you to create repository-specific acc
 
 ### File storage
 
-_Git File Storage Directory_ specifies the path within the repository where the Octopus configuration will be stored. The default directory is `.octopus`, but that can be changed. If only a single Octopus project will be stored in the repo, we recommend putting the configuration directly under the `.octopus` directory.
+*Git File Storage Directory* specifies the path within the repository where the Octopus configuration will be stored. The default directory is `.octopus`, but that can be changed. If only a single Octopus project will be stored in the repo, we recommend putting the configuration directly under the `.octopus` directory.
 
 :::div{.hint}
 If multiple projects will be persisted to the repository, adding the project name to the path is the recommended convention, e.g. `./octopus/acme`
@@ -155,9 +156,9 @@ We recommend storing projects alongside the application code. While it is possib
 
 #### Default branch name
 
-The _Default Branch Name_ is the branch on which the Octopus configuration will be written. It is also the default branch that will be used in various situations, for example:
+The *Default Branch Name* is the branch on which the Octopus configuration will be written. It is also the default branch that will be used in various situations, for example:
 
-- When users view the project's deployment process for the first time in the Octopus UI, this is the initially selected branch 
+- When users view the project's deployment process for the first time in the Octopus UI, this is the initially selected branch
 - When creating releases, this will be the default branch selected
 - When running Runbooks, variable values will be pulled from this branch
 
@@ -169,31 +170,37 @@ When snapshotting a Runbook in a Git project that is not yet using config-as-cod
 
 #### Initial commit branch
 
-If the default branch is protected in your repository, select the *Is the default branch protected?* checkbox. This will allow you to use a different _Initial Commit Branch_. If this branch does not exist, Octopus will create the branch automatically. 
+If the default branch is protected in your repository, select the *Is the default branch protected?* checkbox. This will allow you to use a different *Initial Commit Branch*. If this branch does not exist, Octopus will create the branch automatically.
 
-The Octopus configurations will be written to the initial commit branch instead of the default branch. You will need to merge the changes from this branch into the default branch outside of Octopus. 
+The Octopus configurations will be written to the initial commit branch instead of the default branch. You will need to merge the changes from this branch into the default branch outside of Octopus.
 
 #### Protected branches pattern
 
 You can also nominate protected branches for your Project. This will prevent users from making direct commits to the nominated branches from the Octopus UI and encourage them to create a new branch instead. To nominate protected branches, type in the name or a wildcard pattern in the Protected Branches Pattern field under Branch Settings. This will apply to all existing and future branches.
 
+## Git repository cache
+
+Octopus Server caches Git repositories locally in the `Git` subdirectory of the server home directory. This cache has a default size limit of **20 GB**. When exceeded, Git operations such as creating releases, deploying, or converting projects to version control will fail with:
 
+> Unable to perform this operation as the local git cache is using more space than is available as set by the configured limit of 20 GB. Please use a smaller repository or remove any not in use.
+
+To change the limit, set the `OCTOPUS__Git__CacheFullThresholdMb` system environment variable to the desired value in **megabytes** (e.g. `30720` for 30 GB), then **restart the Octopus Server service**. Setting the value to `0` disables the limit.
 
 ## OCL files
 
 After successfully configuring a project to be version controlled, the specified Git repository will be populated with a set of Octopus Configuration Language (OCL) files. These files are created in the directory you define during setup. E.g. `./octopus/acme`
 
 Currently, Octopus creates the following files and folders:
 
-* deployment_process.ocl
-* deployment_settings.ocl
-* variables.ocl
-* schema_version.ocl
-* runbooks/
+- deployment_process.ocl
+- deployment_settings.ocl
+- variables.ocl
+- schema_version.ocl
+- runbooks/
 
-The runbooks/ directory will contain runbook-name.ocl files for any published runbooks. 
+The runbooks/ directory will contain runbook-name.ocl files for any published runbooks.
 
-The _deployment_process.ocl_ file contains the configuration for your project's steps. Below is an example _deployment_process.ocl_ for a project containing a single _Deploy a Package_ step.
+The *deployment_process.ocl* file contains the configuration for your project's steps. Below is an example *deployment_process.ocl* for a project containing a single *Deploy a Package* step.
 
 ```hcl
 step "deploy-a-package" {
@@ -227,7 +234,7 @@ step "deploy-a-package" {
 }
 ```
 
-The _deployment_settings.ocl_ file contains the configuration for the deployment settings associated with the deployment process. If using the default deployment process settings, the .ocl will be mostly empty.
+The *deployment_settings.ocl* file contains the configuration for the deployment settings associated with the deployment process. If using the default deployment process settings, the .ocl will be mostly empty.
 
 ```hcl
 connectivity_policy {
@@ -272,7 +279,7 @@ versioning_strategy {
 }
 ```
 
-The _variables.ocl_ file contains all non-sensitive variables for the project.
+The *variables.ocl* file contains all non-sensitive variables for the project.
 
 ```hcl
 variable "DatabaseName" {
@@ -307,6 +314,7 @@ In Git projects, [Octopus will continue apply variable permissions based on scop
 ## Slugs in OCL
 
 The following resources will be referenced via their slug:
+
 - Account
 - Channel
 - Deployment Action
@@ -325,7 +333,7 @@ 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. 
+- 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.
@@ -335,4 +343,4 @@ When designing the config-as-code feature, we made several decisions to keep an
 ## Older versions
 
 - Prior to version 2022.3.4517, Git projects would reference shared resources using their name in OCL. This had a side-effect causing API responses for Git projects to contain names instead of IDs.
-From version 2022.3.4517 onwards, a handful of resources are referenced from OCL by their slug. IDs will be used in API responses instead of names.
+From version 2022.3.4517 onwards, a handful of resources are referenced from OCL by their slug. IDs will be used in API responses instead of names.