Forgejo improvements
This commit is contained in:
Astra Logical
parent
fbb3a9334a
commit
f4d9e4c8b6
1 changed files with 113 additions and 55 deletions
|
|
@ -1,59 +1,117 @@
|
||||||
# Forgejo — Git Hosting & Code Collaboration
|
# Forgejo: Git Hosting & Code Collaboration
|
||||||
|
|
||||||
**Forgejo** is a lightweight, self-hosted git hosting platform (a fork of Gitea). It provides repositories, pull requests, issue tracking, and a package registry — all accessible via your browser or standard git clients.
|
**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.
|
||||||
|
|
||||||
## Access
|
|
||||||
|
|
||||||
- **Web UI:** <https://weaver.mynest.love>
|
|
||||||
- **SSH:** `ssh -p 22 git@ssh.weaver.mynest.love`
|
|
||||||
- **Package Registry:** <https://weaver.mynest.love/packages>
|
|
||||||
- **Internal (home network):** <http://forgejo.k3s.home.nest:3000>
|
|
||||||
|
|
||||||
## Features
|
|
||||||
|
|
||||||
- Git repository hosting with full history and branching support
|
|
||||||
- Pull requests with code review workflows
|
|
||||||
- Issue tracking and project boards
|
|
||||||
- Built-in CI/CD via Forgejo Actions (GitHub Actions-compatible)
|
|
||||||
- Container and package registry for sharing binaries and Docker images
|
|
||||||
- Wiki pages per repository
|
|
||||||
|
|
||||||
## Getting Started
|
|
||||||
|
|
||||||
1. Open <https://weaver.mynest.love> in your browser.
|
|
||||||
2. Click **Sign In** and choose **Sign in with The Nest**.
|
|
||||||
3. Create a new repository or clone an existing one:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git clone ssh://git@ssh.weaver.mynest.love:22/username/repo.git
|
|
||||||
```
|
|
||||||
|
|
||||||
4. Push your first commit and start collaborating.
|
|
||||||
|
|
||||||
## SSH Configuration
|
|
||||||
|
|
||||||
HTTP Git is disabled for security — use SSH only. Add your public key to your Forgejo account under **Settings → SSH Keys**.
|
|
||||||
|
|
||||||
Example `~/.ssh/config` entry:
|
|
||||||
|
|
||||||
## Package Registry
|
|
||||||
|
|
||||||
Forgejo includes a package registry for sharing binaries, Docker images, and other artifacts:
|
|
||||||
|
|
||||||
- **Docker:** `docker pull weaver.mynest.love/nest/your-image:tag`
|
|
||||||
- **npm/go/python:** Configure your package manager to authenticate with your Forgejo token (generate one under **Settings → Applications → Generate Token**).
|
|
||||||
|
|
||||||
## Tips
|
|
||||||
|
|
||||||
- **Two-factor auth:** While passkeys handle SSO, enable 2FA in Forgejo settings for an extra layer of security on the git server itself.
|
|
||||||
- **Actions:** Use `.forgejo/workflows/` in your repo to define CI pipelines (compatible with GitHub Actions syntax).
|
|
||||||
- **Webhooks:** Set up webhooks to trigger external services when you push code.
|
|
||||||
|
|
||||||
## Related Services
|
|
||||||
|
|
||||||
- [Semaphore](https://semaphore.k3s.home.nest) — Ansible automation UI for infrastructure management
|
|
||||||
- [Keycloak](../technical/security-and-identity.md) — Powers SSO and group-based access control
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
*TODO: Add screenshot of Forgejo repository view with a sample project.*
|
## 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.
|
||||||
|
|
|
||||||
Loading…
Add table
Reference in a new issue