Modifying repository guide

content/en/docs/neo-porch/4_tutorials_and_how-tos/_index.md

@@ -1,8 +1,8 @@
 ---
-title: "Tutorials & How-to's"
+title: "Guides"
 type: docs
 weight: 4
-description: Tutorials in Porch
+description: Guides detailing how to use Porch
 ---
 
 ## Overview

content/en/docs/neo-porch/4_tutorials_and_how-tos/upgrading-packages.md

@@ -12,7 +12,7 @@ For detailed command reference, see the [porchctl CLI guide]({{% relref "/docs/n
 ## Prerequisites
 
 *   Porch installed in your Kubernetes cluster, along with its CLI `porchctl`. [Setup Guide]({{% relref "/docs/neo-porch/3_getting_started/installing-porch.md" %}})
-*   A Git Repository registered with Porch, in this example it's assumed that the Porch-Repository's name is "porch-test". [Repository Guide]({{% relref "/docs/neo-porch/4_tutorials_and_how-tos/setting-up-repositories" %}})
+*   A Git Repository registered with Porch, in this example it's assumed that the Porch-Repository's name is "porch-test". [Repository Guide]({{% relref "/docs/neo-porch/4_tutorials_and_how-tos/working_with_porch_repositories/repository-registration.md" %}})
 
 ## Key Concepts
 

content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/_index.md

@@ -0,0 +1,7 @@
+---
+title: "Working with Package Revisions"
+type: docs
+weight: 3
+description: 
+---
+

content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_porch_repositories/_index.md

@@ -0,0 +1,118 @@
+---
+title: "Working with Porch Repositories"
+type: docs
+weight: 2
+description: A group of guides outlining how to interact with Porch repositories
+---
+
+## Prerequisites
+
+- Porch deployed on a Kubernetes cluster [Setup Porch Guide]({{% relref "/docs/neo-porch/3_getting_started/installing-porch.md" %}}).
+- **Porchctl** CLI tool installed [Setup Porchctl Guide]({{% relref "/docs/neo-porch/3_getting_started/installing-porchctl.md" %}}).
+- **Kubectl** configured to access your cluster.
+- A Git repository to register with Porch. If you need to create one, see [GitHub's Repository Guide](https://docs.github.com/en/repositories/creating-and-managing-repositories/quickstart-for-repositories).
+
+---
+
+## Understanding Repositories
+
+Before Porch can manage packages, you must register repositories where those packages are stored. Repositories tell Porch:
+
+- Where to find package blueprints
+- Where to store deployment packages
+- How to authenticate with the repository
+
+Porch primarily supports **Git repositories** from providers like GitHub, GitLab, Gitea, Bitbucket, and other Git-compatible services.
+
+**Repository Types by Purpose:**
+
+- **Blueprint Repositories**: Contain upstream package templates and blueprints that can be cloned and customized. These are typically read-only sources of reusable configurations.
+- **Deployment Repositories**: Store deployment-ready packages that are actively managed and deployed to clusters. Mark repositories as deployment repositories using the `--deployment` flag during registration.
+
+---
+
+## Repository Types
+
+Porch primarily supports Git repositories for storing and managing packages. Git is the recommended and production-ready storage backend.
+
+### Git Repositories
+
+Git repositories are the primary and recommended type for use with Porch.
+
+**Requirements:**
+
+- Git repository with an initial commit (to establish main branch)
+- For private repos: Personal Access Token or Basic Auth credentials
+
+**Supported Git hosting services:**
+
+- GitHub
+- GitLab
+- Gitea
+- Bitbucket
+- Any Git-compatible service
+
+---
+
+### OCI Repositories (Experimental)
+
+{{% alert title="Warning" color="warning" %}}
+OCI repository support is **experimental** and not actively maintained. Use at your own risk. This feature may have limitations, bugs, or breaking changes. For production deployments, use Git repositories.
+{{% /alert %}}
+
+Porch has experimental support for OCI (Open Container Initiative) repositories that store packages as container images. This feature is not recommended for production use.
+
+---
+
+## Troubleshooting
+
+Common issues when working with repositories and their solutions:
+
+**Repository shows READY: False?**
+
+- Check repository URL is accessible
+- Verify authentication credentials are correct
+- Inspect repository conditions: `porchctl repo get <name> -n <namespace> -o yaml`
+- Check Porch server logs for detailed errors
+
+**Packages not appearing after registration?**
+
+- Ensure repository has been synchronized (check SYNC SCHEDULE or trigger manual sync)
+- Verify packages have valid Kptfile in repository
+- Check repository directory configuration matches package location
+- If re-registering a previously unregistered repository, packages in Git will reappear after sync
+
+**Authentication failures?**
+
+- For GitHub: Ensure Personal Access Token has `repo` scope
+- For private repos: Verify credentials are correctly configured
+- Check secret exists: `kubectl get secret <secret-name> -n <namespace>`
+
+**Need to change repository configuration?**
+
+- Repository settings (branch, directory, credentials) cannot be updated via porchctl
+- Use `kubectl edit repository <name> -n <namespace>` to modify the Repository resource
+- Alternatively, unregister and re-register the repository with new settings
+
+**Sync not working?**
+
+- Verify cron expression syntax is correct
+- Check minimum 1-minute delay for manual syncs
+- Inspect repository status for sync errors
+
+---
+
+## Key Concepts
+
+Important terms and concepts for working with Porch repositories:
+
+- **Repository**: A Git repository registered with Porch for package management. Repositories are namespace-scoped Kubernetes resources.
+- **Blueprint Repository**: Contains upstream package templates that can be cloned and customized. Typically used as read-only sources.
+- **Deployment Repository**: Repository marked with `--deployment` flag containing deployment-ready packages that are actively managed.
+- **Sync Schedule**: Cron expression defining periodic repository synchronization (e.g., `*/10 * * * *` for every 10 minutes).
+- **Content Type**: Defines what the repository stores. `Package` is the standard type for KRM configuration packages. Other types like `Function` exist for storing KRM functions.
+- **Branch**: Git branch Porch monitors for packages (defaults to `main`). Each repository tracks a single branch.
+- **Directory**: Subdirectory within repository where packages are located. Use `/` for root or specify a path like `/blueprints`.
+- **Namespace Scope**: Repositories exist within a Kubernetes namespace. Repository names must be unique per namespace, and packages inherit the repository's namespace. The same Git repository can be registered in multiple namespaces with different names, creating isolated package views per namespace.
+
+---

content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_porch_repositories/repository-basic-usage.md

@@ -0,0 +1,174 @@
+---
+title: "Repositories Basic Usage"
+type: docs
+weight: 4
+description: "A basic usage of repositories guide in Porch"
+---
+
+## Basic Operations
+
+These operations cover the fundamental commands for viewing and managing registered repositories.
+
+### List Registered Repositories
+
+View all repositories registered with Porch:
+
+```bash
+porchctl repo get --namespace default
+```
+
+**What this does:**
+
+- Queries Porch for all registered repositories in the specified namespace
+- Displays repository type, content, sync schedule, and status
+- Shows the repository address
+
+{{% alert title="Note" color="primary" %}}
+`porchctl repo list` is an alias for `porchctl repo get` and can be used interchangeably:
+
+```bash
+porchctl repo list --namespace default
+```
+
+{{% /alert %}}
+
+**Using kubectl:**
+
+You can also use kubectl to list repositories:
+
+```bash
+kubectl get repositories -n default
+```
+
+List repositories across all namespaces:
+
+```bash
+kubectl get repositories --all-namespaces
+```
+
+**Example output:**
+
+```bash
+NAME         TYPE   CONTENT   SYNC SCHEDULE   DEPLOYMENT   READY   ADDRESS
+porch-test   git    Package                                True    https://github.com/example-org/test-packages.git
+blueprints   git    Package   */10 * * * *                 True    https://github.com/example/blueprints.git
+infra        git    Package   */10 * * * *    true         True    https://github.com/nephio-project/catalog
+```
+
+**Understanding the output:**
+
+- **NAME**: Repository name in Kubernetes
+- **TYPE**: Repository type (`git` or `oci`)
+- **CONTENT**: Content type (typically `Package`)
+- **SYNC SCHEDULE**: Cron expression for periodic synchronization (if configured).
+- **DEPLOYMENT**: Whether this is a deployment repository
+- **READY**: Repository health status
+- **ADDRESS**: Repository URL
+
+---
+
+### Get Detailed Repository Information
+
+View complete details about a specific repository:
+
+```bash
+porchctl repo get porch-test --namespace default -o yaml
+```
+
+**What this does:**
+
+- Retrieves the full Repository resource
+- Shows configuration, authentication, and status information
+- Displays in YAML format for easy reading
+
+**Example output:**
+
+```yaml
+apiVersion: config.porch.kpt.dev/v1alpha1
+kind: Repository
+metadata:
+  name: porch-test
+  namespace: default
+  creationTimestamp: "2025-11-21T16:27:27Z"
+spec:
+  content: Package
+  type: git
+  git:
+    repo: https://github.com/example-org/test-packages.git
+    branch: main
+    directory: /
+    secretRef:
+      name: porch-test-auth
+status:
+  conditions:
+  - type: Ready
+    status: "True"
+    reason: Ready
+    message: 'Repository Ready (next sync scheduled at: 2025-11-26T09:48:03Z)'
+    lastTransitionTime: "2025-11-26T09:45:03Z"
+```
+
+**Key fields to inspect:**
+
+- **spec.type**: Repository type (typically `git`)
+- **spec.git**: Git-specific configuration (repo URL, branch, directory, credentials)
+- **spec.content**: Content type stored in repository
+- **status.conditions**: Repository health and sync status
+  - **status**: `"True"` (healthy) or `"False"` (error)
+  - **reason**: `Ready` or `Error`
+  - **message**: Detailed error message when status is False
+
+---
+
+### Update Repository Configuration
+
+The typical workflow for changing repository settings is to unregister and re-register the repository with new configuration. This is the recommended approach.
+
+{{% alert title="Note" color="primary" %}}
+There is no `porchctl repo update` command. The standard approach is unregister/reregister.
+{{% /alert %}}
+
+**Recommended approach - Unregister and re-register:**
+
+```bash
+# Unregister the repository
+porchctl repo unregister porch-test --namespace default
+
+# Re-register with new configuration
+porchctl repo register https://github.com/example/porch-test.git \
+  --namespace default \
+  --name=porch-test \
+  --branch=develop \
+  --directory=/new-path
+```
+
+**Alternative - Direct kubectl editing (NOT RECOMMENDED):**
+
+While you can edit the repository resource directly with kubectl, this is highly discouraged:
+
+```bash
+kubectl edit repository porch-test -n default
+```
+
+{{% alert title="Warning" color="warning" %}}
+Direct editing with kubectl is not recommended because:
+
+- Some values like `url`, `branch`, and `directory` are immutable or not designed to be changed this way
+- Changes to authentication secrets (like `secretRef`) are cached by Porch and won't take effect immediately
+- Secret changes only apply when authentication fails and Porch refreshes the cached credentials
+- This can lead to unpredictable behavior
+{{% /alert %}}
+
+**If you must use kubectl editing:**
+
+Only modify fields that are safe to change, such as:
+
+- `secretRef.name`: Change authentication credentials (with caching caveats above)
+
+Avoid changing:
+
+- `url`: Repository URL
+- `branch`: Git branch
+- `directory`: Package directory path
+
+---