docs/user-facing/productivity-and-creation/forgejo.md

# Forgejo: Git Hosting & Code Collaboration

**Forgejo** is the central self-hosted Git platform for **The Nest**. A lightweight fork of Gitea, Forgejo provides version control, code review workflows, issue tracking, and container/package registries—all fully integrated into our single sign-on identity system.

---

## 1. Web Access & Initial Setup

1. Open **[weaver.mynest.love](https://weaver.mynest.love)** in your Web browser.
2. Click **Sign In** and select **"Sign in with The Nest"**.
3. Log in using your standard Nest passkey.

---

## 2. Setting Up SSH Keys (Required for Git Push/Pull)

> [!WARNING]
> **HTTP Git Access is Disabled**
> For security reasons, HTTP/HTTPS Git cloning and pushing are completely disabled on The Nest. All command-line Git interactions must use **SSH**.

To interact with repositories from your terminal or command line, you must add your SSH public key to your Forgejo account.

### Step 1: Generate an SSH Key Pair
If you don't already have an SSH key, open your terminal (macOS/Linux) or Git Bash / PowerShell (Windows) and run:

```bash
ssh-keygen -t ed25519 -C "your_email@example.com"
```
Press `Enter` to accept the default file location. You can optionally enter a passphrase for extra security.

### Step 2: Copy Your Public Key
Display and copy your **public** key (never share or copy your private key!):

* **macOS:** `pbcopy < ~/.ssh/id_ed25519.pub`
* **Linux:** `xclip -selection clipboard < ~/.ssh/id_ed25519.pub` (or `cat ~/.ssh/id_ed25519.pub`)
* **Windows (PowerShell):** `Get-Content ~/.ssh/id_ed25519.pub | Set-Clipboard`

### Step 3: Add Your Public Key to Forgejo
1. Sign into **[weaver.mynest.love](https://weaver.mynest.love)**.
2. Click your profile avatar in the top-right corner and select **Settings**.
3. Select **SSH / GPG Keys** from the left sidebar.
4. Click **Add Key**.
5. Give your key a recognizable name (e.g., `MacBook Pro` or `Desktop Workstation`), paste your copied public key into the **Content** box, and click **Add Key**.

### Step 4: Test Your SSH Connection
In your terminal, test your authentication against The Nest's SSH Git server:

```bash
ssh -T -p 22 git@ssh.weaver.mynest.love
```

If configured correctly, Forgejo will output a welcome message confirming successful authentication!

---

## 3. How to Contribute & Collaborate

Whether you are writing code, tweaking configuration files, or reporting bugs, everyone can contribute to projects hosted on The Nest.

### Option A: Opening Issues (Bug Reports & Feature Requests)
If you find something broken, want to request a feature, or need to ask a question:

1. Navigate to the project's repository on **[weaver.mynest.love](https://weaver.mynest.love)**.
2. Click the **Issues** tab at the top of the repository.
3. Click the green **New Issue** button.
4. Fill in a descriptive **Title**.
5. In the **Description** box, include:
   * **Summary:** What is the issue or feature request?
   * **Steps to Reproduce:** (For bugs) Step-by-step instructions to recreate the problem.
   * **Expected vs. Actual Behavior:** What you expected to happen vs. what actually happened.
6. Click **Create Issue**. You will automatically receive updates when project maintainers comment or update the issue status.

### Option B: Contributing Code via Pull Requests
1. **Clone the repository using SSH:**
   ```bash
   git clone git@ssh.weaver.mynest.love:organization/repository-name.git
   ```
2. **Create a local working branch:**
   ```bash
   git checkout -b feature/my-changes
   ```
3. **Commit and push your changes:**
   ```bash
   git commit -m "Describe your changes clearly"
   git push origin feature/my-changes
   ```
4. **Open a Pull Request:** Navigate to the repository on Forgejo, click **New Pull Request**, select your branch, and submit it for review.

---

## 4. Package Registry & CI/CD Pipelines

### Container & Package Registry
Forgejo hosts a built-in package registry for sharing container images and dependencies:

* **Docker / OCI Registry:**
  ```bash
  docker pull weaver.mynest.love/nest/your-image:tag
  ```
* **Language Package Managers (npm / Python / Go):**
  Generate a personal access token under **Settings → Applications → Generate Token**, then configure your local package manager to authenticate with `weaver.mynest.love`.

### Automated Workflows (Forgejo Actions)
Repositories can automate builds, tests, and deployments using Forgejo Actions (compatible with GitHub Actions syntax). Place your workflow definition files inside `.forgejo/workflows/` in your repository root.

---

## 5. Service Summary & Related Links

| Component | Endpoint / URL | Access Method | Purpose |
| :--- | :--- | :--- | :--- |
| **Web UI** | [weaver.mynest.love](https://weaver.mynest.love) | Browser (Passkey) | Repository management, issue tracking, and PRs |
| **Git SSH Server** | `ssh.weaver.mynest.love` (Port `22`) | SSH Key | Command-line Git cloning, pulling, and pushing |
| **Package Registry** | [weaver.mynest.love/packages](https://weaver.mynest.love/packages) | API / Token | Container images and package management |

### Related Nest Documentation:
* **[Semaphore](https://semaphore.k3s.home.nest):** Ansible automation UI for infrastructure deployment and execution.