117 lines
5.1 KiB
Markdown
117 lines
5.1 KiB
Markdown
# 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.
|