epinio · dcharles525 · Jul 24, 2026 · Jul 10, 2026 · Jul 14, 2026 · Jul 15, 2026
diff --git a/docs/reference/concepts/_category_.json b/docs/reference/concepts/_category_.json
@@ -1 +1 @@
-{ "label": "Concepts", "position": 4, "collapsed": true }
+{ "label": "Concepts", "position": 8, "collapsed": true }
diff --git a/docs/reference/concepts/git-config-flow.png b/docs/reference/concepts/git-config-flow.png
diff --git a/docs/reference/concepts/git_configuration.md b/docs/reference/concepts/git_configuration.md
@@ -11,32 +11,25 @@ doc-topic: [epinio, reference, concepts, git-configuration]
 
 ## Overview
 
-Starting with version **1.10.0**, Epinio supports Git configurations.
-
 Configurations enable cloning of private repositories, disabling of SSL verification, and/or
 extending verification through a custom bundle of certificates.
 
-This is done on a per git host (+user/org, +repository) basis.
-
-Management, including creation, is done through the
-[epinio gitconfig](../cli/gitconfig/epinio_gitconfig.md)
-command ensemble.
-
-## Matching process
+For GitHub and GitLab instances you create a git configuration with a username and
+password/token, and optionally the skip-SSL-verification and global flags. A **global**
+configuration can be used by any user; a non-global one is visible and usable only to the user who
+created it and to administrators. Only administrators may create a global configuration.
 
-When importing from a git repository Epinio will use the most specific matching configuration, if
-there is any.
+For the `git`, GitHub Enterprise (Cloud and Self-Hosted), and GitLab Enterprise types the same
+fields are available plus a **git host** field, where you enter the instance URL.
 
-This means that a matching configuration specifying url, user/organization, and repository has
-priority over matching configurations specifying only url and user/organization, or even just the
-url.
+You attach a configuration to an application by **selecting it** when you set the application's Git
+source. Epinio does not implicitly match a configuration to a repository URL; the selection is
+explicit, and a private repository will fail to clone if no usable configuration is selected.
 
-If no configuration is found then the cloning from the Git repository will run without any
-customization.
 
-## Github/Gitlab specialities
+## Github/Gitlab Specialities
 
-The public Github and Gitlab mega repositories support the use of a `PAT` (Personal Access Token)
+The public Github and Gitlab repositories support the use of a `PAT` (Personal Access Token)
 over a plain combination of user and password.
 
 When using a PAT it has to be set as the password, and the user can be set to anything except empty.
@@ -45,76 +38,52 @@ When using a PAT it has to be set as the password, and the user can be set to an
 For reference, it is useful to set it to the username used to generate the token.
 :::
 
-## Detailed specification
+## Enterprise and self-hosted instances
 
-:::note
-This section contains information useful to operators for debugging and inspection. 
-Regular users should not normally need to consult this section.
-:::
+The enterprise and generic `git` types take a **git host** URL in addition to the credential
+fields:
+
+- **GitHub Enterprise Self-Hosted** (`github_enterprise_self_hosted`): enter the instance host URL
+  (for example `https://github.mycorp.com`). Epinio appends the GitHub Enterprise Server REST path
+  (`/api/v3`).
+- **GitHub Enterprise Cloud** (`github_enterprise_cloud`): enter the API host URL for your
+  Enterprise Cloud instance, for example `https://api.github.com`, or `https://api.<subdomain>.ghe.com`
+  for a data-residency instance. Epinio uses it as given.
+- **GitLab Enterprise** (`gitlab_enterprise`) and generic **Git** (`git`): enter the instance host
+  URL. GitLab is accessed under `/api/v4`.
+
+## Detailed Specification
 
 A Git configuration is a Kubernetes secret with the `epinio.io/api-git-credentials: "true"` label.
 
 The fields are:
 
-|Field		|Required|Meaning									|
-|---		|---	|---										|
-|`url`		|yes	| the host of the git instance							|
-|`provider`	|	| one of `github`, `gitlab`, `git`, `github_enterprise`, `gitlab_enterprise`	|
-|`username`	|	| used during the Basic Authentication						|
-|`password`	|	| used during the Basic Authentication						|
-|`userOrg`	|	| used to restrict the configuration to a specific organization/project		|
-|`repo`		|	| used to restrict the configuration to a specific repository			|
-|`skipSSL`	|	| used to skip the SSL verification						|
-|`certificate`	|	| the CA bundle to load for the SSL verification with self-signed certificates	|
-
-All the fields, except for the URL, are optional.
-
-## Example:
-
-Invoking the commands
-
-```bash
-cat > certfile <<EOF
------BEGIN CERTIFICATE-----
-MIIBaTCCAQ+gAwIBAgIRAN4tvwEOKogvOzT/KccL8t8wCgYIKoZIzj0EAwIwFDES
-***************
------END CERTIFICATE-----
-EOF
-
-epinio gitconfig create github-epinio-example-go-configuration https://github.com \
-    --git-provider github	\
-    --user-org 	   epinio	\
-    --repository   example-go	\
-    --skip-ssl	   		\
-    --username 	   myuser	\
-    --password 	   abcde12345	\
-    --cert-file	   certfile
-```
-
-will generate the secret
-
-```yaml
-apiVersion: v1 
-kind: Secret 
-type: Opaque 
-metadata: 
-  labels: 
-    epinio.io/api-git-credentials: "true"
-  name: github-epinio-example-go-configuration 
-  namespace: epinio 
-stringData:
-  url: https://github.com
-  provider: github
-  username: "myuser" 
-  password: "abcde12345" 
-  userOrg: epinio 
-  repo: example-go 
-  skipSSL: true 
-  certificate: |
-    -----BEGIN CERTIFICATE-----
-    MIIBaTCCAQ+gAwIBAgIRAN4tvwEOKogvOzT/KccL8t8wCgYIKoZIzj0EAwIwFDES
-    ***************
-    -----END CERTIFICATE-----
-```
+|Field		   |Required|Meaning									|
+|---		   |---	    |---										|
+|`id`          |yes     | the name of the secret                                |
+|`url`		   |	    | the host of the git instance							|
+|`provider`	   |yes	    | one of `github`, `gitlab`, `git`, `github_enterprise_cloud`, `github_enterprise_self_hosted`, `gitlab_enterprise`	|
+|`username`	   |	    | used during the Basic Authentication						|
+|`password`	   |	    | used during the Basic Authentication						|
+|`skipSSL`	   |	    | used to skip the SSL verification						|
+| `global`     |       | used to make the configuration available to all users     |
+|`certificate` |	| the CA bundle to load for the SSL verification with self-signed certificates	|
+
+Notes:
+
+- `url` is optional for the SaaS `github` and `gitlab` providers (the host is implied). It is
+  required for `git`, `github_enterprise_cloud`, `github_enterprise_self_hosted`, and
+  `gitlab_enterprise`.
+- `global` may only be set by an administrator.
+- `password` and `certificate` are **write-only**: they are never returned when a configuration is
+  read. There is no update endpoint, editing a configuration means deleting and recreating it, so
+  the password and certificate must be provided again each time.
+
+## Git Configuration Flow
+
+<img
+  src={require('./git-config-flow.png').default}
+  alt="Git Configuration in Epinio"
+/>
 
 For more examples check the [How-to](../../how-to/developer/concepts/git_configuration.md).
diff --git a/docs/reference/customization/_category_.json b/docs/reference/customization/_category_.json
@@ -1 +1 @@
-{ "label": "Customization", "position": 5, "collapsed": true }
+{ "label": "Customization", "position": 9, "collapsed": true }
diff --git a/docs/reference/detailed-push-process.md b/docs/reference/detailed-push-process.md
@@ -1,5 +1,6 @@
 ---
 sidebar_label: "Epinio push process"
+sidebar_position: 6
 title: "The Epinio push process in detail"
 description: The Epinio push process in detail
 keywords: [epinio, kubernetes, push process]

diff --git a/docs/reference/principles.md b/docs/reference/principles.md
@@ -1,5 +1,6 @@
 ---
 sidebar_label: "Principles"
+sidebar_position: 7
 title: "Epinio design principles"
 description: The design principles Epinio is based upon.
 keywords: [epinio, kubernetes, design principles]

diff --git a/docs/reference/security/_category_.json b/docs/reference/security/_category_.json
@@ -1 +1 @@
-{ "label": "Security & auth", "position": 6, "collapsed": true }
+{ "label": "Security & auth", "position": 10, "collapsed": true }
diff --git a/docs/reference/upgrading.md b/docs/reference/upgrading.md
@@ -1,6 +1,6 @@
 ---
 sidebar_label: Upgrading Epinio
-sidebar_position: 8
+sidebar_position: 5
 title: Upgrading Epinio
 description: Breaking changes and migration steps when upgrading Epinio between versions.
 keywords: [epinio, upgrade, migration, breaking changes, versions]
@@ -13,6 +13,29 @@ Review the breaking changes and migration steps for your target version before
 upgrading. For the full list of releases and their release notes, see
 [versions](../versions.md).
 
+## 1.13.X and 1.14.0 to 1.14.1
+
+Git configuration handling changed. Selecting a configuration when deploying from a **private**
+repository is now **explicit**: Epinio no longer implicitly matches a stored configuration to a
+repository URL at push time.
+
+- **New private-repo pushes must select a git configuration.** In the dashboard, choose one in the
+  application's Git source. From the CLI or automation, the git origin must carry
+  `origin.git.gitconfig`; a push that sends no configuration clones unauthenticated and fails with
+  `authentication required`.
+- **Existing applications keep working.** On redeploy, a compatibility fallback still matches
+  configuration-less apps to a stored configuration by repository URL, so they continue to clone as
+  before.
+- **Credentials are bound to their instance host.** A configuration's credentials are only sent to
+  the host it is scoped to; selecting a configuration whose host does not match the repository is
+  rejected.
+- **Global configurations are administrator-only to create.** Non-admin users can use global
+  configurations but cannot create them.
+
+This release also adds a `spec.origin.git.gitconfig` field to the `apps` CRD. If you install CRDs
+from the Helm chart's `crds/` directory out of band, apply the updated CRD on upgrade so the field
+is not pruned. See [Git Configuration](./concepts/git_configuration.md).
+
 ## 1.13.X to 1.14.0
 
 There are no breaking changes in this release. Documentation around performance was
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		{ "label": "Concepts", "position": 4, "collapsed": true }
		{ "label": "Concepts", "position": 8, "collapsed": true }
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		{ "label": "Customization", "position": 5, "collapsed": true }
		{ "label": "Customization", "position": 9, "collapsed": true }
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		{ "label": "Security & auth", "position": 6, "collapsed": true }
		{ "label": "Security & auth", "position": 10, "collapsed": true }