kubara-io · Matthiator · Jun 9, 2026 · Jun 12, 2026 · Jul 21, 2026 · Jul 21, 2026
diff --git a/.github/workflows/pr-checks.yaml b/.github/workflows/pr-checks.yaml
@@ -278,13 +278,37 @@ jobs:
       - name: Checkout
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
+      # TODO: Remove this checkout and the local packaging step once catalog
+      # version 1.1.0 has been published by kubara-io/catalogs#6.
+      - name: Checkout matching catalogs
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          repository: kubara-io/catalogs
+          ref: feat/catalog-repository-auth
+          path: .ci/catalogs
+
       - name: Setup Go
         uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16 # v6.5.0
         with:
           go-version-file: src/go.mod
           cache: true
           cache-dependency-path: src/go.sum
 
+      - name: Build kubara CLI
+        working-directory: src
+        run: go build -o "${RUNNER_TEMP}/kubara" .
+
+      - name: Package matching catalogs locally
+        run: |
+          set -euo pipefail
+          for catalog in bootstrap general; do
+            (
+              cd ".ci/catalogs/${catalog}"
+              "${RUNNER_TEMP}/kubara" catalog package \
+                oci://ghcr.io/kubara-io/catalogs/
+            )
+          done
+
       - name: Create output directory
         run: |
           echo "output dir: ${{ env.OUTPUT_GENERATED_DIR }}"
@@ -293,8 +317,9 @@ jobs:
       - name: kubara init --prep
         run: |
           set -euo pipefail
-          cd src
-          go run main.go --work-dir "${{ env.OUTPUT_GENERATED_DIR }}" init --prep
+          "${RUNNER_TEMP}/kubara" \
+            --work-dir "${{ env.OUTPUT_GENERATED_DIR }}" \
+            init --prep
 
       - name: Update .env (strict template mode)
         run: |
@@ -304,8 +329,9 @@ jobs:
       - name: kubara init
         run: |
           set -euo pipefail
-          cd src
-          go run main.go --work-dir "${{ env.OUTPUT_GENERATED_DIR }}" init
+          "${RUNNER_TEMP}/kubara" \
+            --work-dir "${{ env.OUTPUT_GENERATED_DIR }}" \
+            init
 
       - name: Update config.yaml (strict mode)
         run: |
@@ -314,8 +340,9 @@ jobs:
 
       - name: Generate kubara artifacts
         run: |
-          cd src
-          go run main.go --work-dir "${{ env.OUTPUT_GENERATED_DIR }}" generate
+          "${RUNNER_TEMP}/kubara" \
+            --work-dir "${{ env.OUTPUT_GENERATED_DIR }}" \
+            generate
 
       - name: Upload generated helm and terraform files
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7

diff --git a/.scripts/kubara-config-update.sh b/.scripts/kubara-config-update.sh
@@ -47,6 +47,5 @@ apply_yaml_if_set KUBARA_STACKIT_PROJECT_ID  ".clusters[0].terraform.projectId"
 apply_yaml_if_set KUBARA_KUBERNETES_TYPE     ".clusters[0].terraform.kubernetesType"
 apply_yaml_if_set KUBARA_KUBERNETES_VERSION  ".clusters[0].terraform.kubernetesVersion"
 apply_yaml_if_set KUBARA_DNS_NAME            ".clusters[0].dnsName"
-apply_yaml_if_set KUBARA_DNS_NAME            ".clusters[0].terraform.dns.name"
 
 log "✅ config.yaml updated"
diff --git a/docs/content/1_getting_started/bootstrapping.md b/docs/content/1_getting_started/bootstrapping.md
@@ -61,6 +61,34 @@ The easiest way is to run `kubara` inside the repository (but do not add the bin
         Keep in mind that weak passwords such as `123456` for `ARGOCD_WIZARD_ACCOUNT_PASSWORD` are a bad idea, since your
         platform will be publicly available by default via your DNS zone.
 
+#### Git repository authentication
+
+kubara creates the initial Argo CD repository secret during `kubara bootstrap`.
+`ARGOCD_GIT_AUTH_MODE` controls which credential fields are written:
+
+| Mode | Required values | Notes |
+| --- | --- | --- |
+| `https` | `ARGOCD_GIT_URL` or legacy `ARGOCD_GIT_HTTPS_URL` | Backward-compatible default. `ARGOCD_GIT_USERNAME` + `ARGOCD_GIT_PAT_OR_PASSWORD` are optional: omit them for public repositories, set both for private ones. `PAT` usually means Personal Access Token and is often tied to a user account. Prefer a technical or machine account and use that account name for `ARGOCD_GIT_USERNAME`; exact username behavior is provider-dependent. |
+| `ssh` | `ARGOCD_GIT_URL`, `ARGOCD_GIT_SSH_PRIVATE_KEY` | Use an SSH repository URL such as `git@github.com:org/repo.git`. Argo CD must know the SSH host key before it can connect securely. |
+| `github-app` | `ARGOCD_GIT_URL`, `ARGOCD_GIT_GITHUB_APP_ID`, `ARGOCD_GIT_GITHUB_APP_INSTALLATION_ID`, `ARGOCD_GIT_GITHUB_APP_PRIVATE_KEY` | Use GitHub App authentication for organization-owned automation. For GitHub Enterprise, set `ARGOCD_GIT_GITHUB_APP_ENTERPRISE_BASE_URL` as well. |
+
+For new setups, prefer `ARGOCD_GIT_URL`.
+`ARGOCD_GIT_HTTPS_URL` is still supported for existing HTTPS/PAT setups.
+
+For SSH, keep strict host verification enabled.
+The bundled Argo CD Helm chart already includes known hosts for common public providers.
+For private Git hosts, add trusted host keys to the generated Argo CD values before bootstrapping, for example in `platform-configs/<cluster>/helm/argo-cd/values-additional.yaml`:
+
+```yaml
+argo-cd:
+  configs:
+    ssh:
+      extraHosts: |
+        git.example.com ssh-ed25519 <trusted-host-key>
+```
+
+If the required host key is missing, Argo CD will reject the SSH connection as an unknown SSH host.
+
 
 
 ### 1.3 Generate Base Configuration
@@ -73,6 +101,9 @@ kubara init
 
 This command creates a `config.yaml` file based on the values from your `.env`.
 If you make changes to `.env` later, you can re-run the command with `--overwrite` to update the configuration.
+The generated Argo CD repository config records the selected Git auth mode in `argocd.repo.authMode`.
+Repository URLs are stored under `argocd.repo.git`.
+Older configs are migrated up to `v1alpha5` when kubara loads and saves the config: the old `argocd.repo.https` key moves to `argocd.repo.git`, and the old `terraform.dns` block is replaced by `terraform.dnsContactEmail` (the zone name is derived from the cluster `dnsName`).
 
 By default, the generated cluster references kubara's versioned general catalog. Use repeated `--catalog` flags to initialize it with a different ordered catalog set:
 
@@ -123,7 +154,7 @@ For editor integration (e.g. VS Code with YAML language server), reference the s
 Example:
 
 ```yaml
-bootstrapCatalog: oci://ghcr.io/kubara-io/catalogs/bootstrap:1.0.0
+bootstrapCatalog: oci://ghcr.io/kubara-io/catalogs/bootstrap:1.1.0
 clusters:
   - name: project-name-from-env-file
     stage: project-stage-something-like-dev
@@ -133,15 +164,13 @@ clusters:
     ssoOrg: <oidc-org> 
     ssoTeam: <org-team>
     catalogs:
-      - oci://ghcr.io/kubara-io/catalogs/general:1.0.0
+      - oci://ghcr.io/kubara-io/catalogs/general:1.1.0
     terraform:
       provider: stackit # currently supported: stackit, t-cloud-public
       projectId: <project-id-or-tenant-name>
       kubernetesType: <ske, edge or cce>
       kubernetesVersion: 1.34
-      dns:
-        name: <dns-name>
-        email: <email>
+      dnsContactEmail: <email>
 ...
     services:  
       ...

diff --git a/docs/content/2_concepts/catalogs.md b/docs/content/2_concepts/catalogs.md
@@ -66,11 +66,11 @@ kubara resolves catalogs in layers:
 New configurations use kubara's general catalog unless catalogs are supplied during `init`. The selected catalog references are stored on the cluster:
 
 ```yaml
-bootstrapCatalog: oci://ghcr.io/kubara-io/catalogs/bootstrap:1.0.0
+bootstrapCatalog: oci://ghcr.io/kubara-io/catalogs/bootstrap:1.1.0
 clusters:
   - name: production
     catalogs:
-      - oci://ghcr.io/kubara-io/catalogs/general:1.0.0
+      - oci://ghcr.io/kubara-io/catalogs/general:1.1.0
       - oci://ghcr.io/acme/platform-catalogs/security:2.1.0
 ```
 

diff --git a/docs/content/3_infrastructure/stackit_ske.md b/docs/content/3_infrastructure/stackit_ske.md
@@ -30,9 +30,7 @@ terraform:
   projectId: <project-id>
   kubernetesType: ske
   kubernetesVersion: 1.34
-  dns:
-    name: <dns-name>
-    email: <email>
+  dnsContactEmail: <email>
 ```
 
 For STACKIT SKE, set `projectId` to the STACKIT project ID that should own the DNS zone, IAM resources, Secrets Manager, optional Velero bucket, and the SKE cluster.

diff --git a/docs/content/3_infrastructure/t-cloud-public.md b/docs/content/3_infrastructure/t-cloud-public.md
@@ -14,9 +14,7 @@ terraform:
   projectId: <tenant-name>
   kubernetesType: cce
   kubernetesVersion: 1.29
-  dns:
-    name: <dns-name>
-    email: <email>
+  dnsContactEmail: <email>
 ```
 
 For T Cloud Public, set `projectId` to the tenant/project name used as `tenant_name`, not to a UUID.

diff --git a/docs/content/5_workload_onboarding/add_app_repository.md b/docs/content/5_workload_onboarding/add_app_repository.md
@@ -7,34 +7,104 @@ For more information check:
 https://argo-cd.readthedocs.io/en/stable/user-guide/private-repositories/
 
 ## **Add credentials to vault**
-Add the repository credentials to your vault at
-`<cluster-name>/<stage>/repo_pat`. This can be a `password` or a `PAT`.
+Add the repository credentials to your vault below `<cluster-name>/<stage>`.
+The examples below use one secret value per repository credential.
+
+For HTTPS username + password/PAT authentication, `PAT` usually means Personal Access Token and is often tied to a user account.
+For platform automation, prefer a technical or machine account instead of a personal user account.
+Set `username` to the account name expected by your Git provider; the exact value is provider-dependent.
+
 ```json
 {
   "repo_pat": {
-    "pat": "<the kubeconfig>"
+    "pat": "<password-or-PAT>"
+  }
+}
+```
+
+For SSH deploy key authentication:
+
+```json
+{
+  "repo_ssh": {
+    "privateKey": "-----BEGIN OPENSSH PRIVATE KEY-----\n...\n-----END OPENSSH PRIVATE KEY-----"
+  }
+}
+```
+
+For GitHub App authentication:
+
+```json
+{
+  "repo_github_app": {
+    "privateKey": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"
   }
 }
 ```
+
 ## **Modify Argo CD overlays**
-Add the following to your Argo CD overlay, typically `platform-configs/<hub-cluster-name>/helm/argo-cd/values-additional.yaml`.
+Add one of the following repository definitions to your Argo CD overlay, typically
+`platform-configs/<hub-cluster-name>/helm/argo-cd/values-additional.yaml`.
+
+HTTPS username + password/PAT:
+
+```yaml
+repositories:
+  - name: user-repo-mock
+    authMode: https
+    projectScope: k8s-spoke-0
+    remoteRef:
+      remoteKey: <cluster-name>/<stage>/repo_pat
+      remoteKeyProperty: pat
+    repoType: git
+    secretStoreRef:
+      kind: ClusterSecretStore
+      name: hub-0-production
+    url: https://git.example.com/org/repo.git
+    username: <technical-account-username>
+```
+
+SSH deploy key:
+
 ```yaml
 repositories:
-    - name: user-repo-mock
-      projectScope: k8s-spoke-0
-      # # This points to the secret in vault
-      remoteRef:
-        remoteKey: <cluster-name>/<stage>/repo_pat
-        remoteKeyProperty: pat
-      repoType: git
-      secretStoreRef:
-        kind: ClusterSecretStore
-        name: hub-0-production
-      url: <the repo url you want to add>
-      username: <the username for connection. also needed for PAT>
+  - name: user-repo-ssh
+    authMode: ssh
+    projectScope: k8s-spoke-0
+    sshPrivateKeyRemoteRef:
+      remoteKey: <cluster-name>/<stage>/repo_ssh
+      remoteKeyProperty: privateKey
+    repoType: git
+    secretStoreRef:
+      kind: ClusterSecretStore
+      name: hub-0-production
+    url: git@git.example.com:org/repo.git
 ```
 
-That whats happening behind the scenes:
+For SSH repositories, make sure Argo CD already trusts the SSH host key. See the bootstrap documentation for `configs.ssh.extraHosts`.
+
+GitHub App:
+
+```yaml
+repositories:
+  - name: user-repo-github-app
+    authMode: github-app
+    projectScope: k8s-spoke-0
+    githubAppID: "123456"
+    githubAppInstallationID: "987654"
+    githubAppPrivateKeyRemoteRef:
+      remoteKey: <cluster-name>/<stage>/repo_github_app
+      remoteKeyProperty: privateKey
+    repoType: git
+    secretStoreRef:
+      kind: ClusterSecretStore
+      name: hub-0-production
+    url: https://github.com/org/repo.git
+```
+
+For GitHub Enterprise, also set `githubAppEnterpriseBaseUrl`.
+
+That's what's happening behind the scenes:
 
 ![Add Repository](../images/add-repository.png)
 

diff --git a/docs/content/6_components/network_external_dns.md b/docs/content/6_components/network_external_dns.md
@@ -49,9 +49,7 @@ clusters:
 
     terraform:
       provider: stackit # currently supported: stackit
-      dns:
-        name: "example-zone"
-        email: "hostmaster@example.com"
+      dnsContactEmail: "hostmaster@example.com"
 
     services:
       external-dns:
@@ -60,8 +58,8 @@ clusters:
 
 ### Explanation
 
-- **`dnsName`** → base domain for the cluster  
-- **`terraform.dns`** → defines the zone for which kubara generates Terraform code (name and contact email).
+- **`dnsName`** → base domain for the cluster, also used as the zone name for which kubara generates Terraform code
+- **`terraform.dnsContactEmail`** → administrative contact email for the managed DNS zone.
 - **`services.external-dns.status`** → when set to `enabled`, ExternalDNS is templated into the Helm charts for deployment via Argo CD.
 - **provider-specific settings** → configure them in the chart overlay values (`values.generated.yaml` plus any extra `values-*.yaml` files you add).