how-to-contribute/README.md

# How to contribute

1. Generate an SSH key pair via `ssh-keygen` in your terminal (make sure not to overwrite an existing key!).

2. Add the configuration in `.ssh/config` to your local SSH configuration file.

3. Point the `IdentityFile` parameter to your local key file location (in most cases `~/.ssh/id_ed25519` or equivalent with RSA).

4. Go into your Gitea Settings, then SSH/GPG Keys section, then upload your public key (in most cases, a file called `id_ed25519.pub`).

5. You can now contribute code!

## Test connection

`ssh code.kpuig.net`

If this command gives you anything but an affirmative that you're configured correctly, that means you have misconfigured something, most likely in SSH but possibly in git.

# Using PowerShell for Git/Gitea over SSH (Windows)

This guide assumes some PowerShell experience. It walks you from setup → generating SSH keys → fixing permissions → testing → cloning/pushing with Git. It also includes simple PowerShell basics you’ll reuse later.

### 1) Open PowerShell (two ways)

---

- **Normal window (most tasks):** Press **Start** → type **PowerShell** → Enter.
- **Administrator window (needed for ownership/ACL fixes):** Start → type **PowerShell** → **Right‑click → Run as administrator**.

How to tell: the title bar will say **Administrator: Windows PowerShell** if elevated.

### 2) Check/OpenSSH is installed (client)

---

Most modern Windows include it already.

```powershell
ssh -V  # shows version if installed
```

If you see an error:

1. **Settings** → **Apps** → **Optional features** → **Add a feature** → Install **OpenSSH Client**.
2. Reopen PowerShell and try `ssh -V` again.

### 3) PowerShell basics you’ll use

---

- **Current user home**: `C:\Users\<YourName>` (shortcut in PowerShell: `$env:USERPROFILE`)
- **Change directory**: `cd <path>`
  Example: `cd $env:USERPROFILE\.ssh`
- **List files**: `dir` or `ls`
- **Create folder**: `New-Item -ItemType Directory -Path <path>`
- **View a file**: `type <file>` (or `notepad <file>` to open Notepad)

### 4) Create the **.ssh** folder (if it doesn’t exist)

---

```powershell
$ssh = "$env:USERPROFILE\.ssh"
if (!(Test-Path $ssh)) { New-Item -ItemType Directory -Path $ssh | Out-Null }
cd $ssh
```

### 5) Generate an SSH key pair (private + public)

---

Use **ed25519** unless your host requires RSA.

```powershell
ssh-keygen -t ed25519 -C "your.email@example.com" -f "$env:USERPROFILE\.ssh\some_id"
```

- When prompted for a passphrase: press **Enter** (no passphrase) or set one for extra security.
- This creates two files:

  - **`some_id`** (private key — **keep secret**)
  - **`some_id.pub`** (public key — you’ll upload this)

> If you already have a key, skip generation and just make sure you know the file name.

### 6) Lock down private‑key permissions (Windows ACLs)

---

Open **PowerShell as Administrator** for this section.

```powershell
$k = "$env:USERPROFILE\.ssh\some_id"
# Make you the owner
icacls $k /setowner "$env:USERNAME"
# Stop inheriting broader folder permissions
icacls $k /inheritance:r
# Remove groups that make it too open (ignore errors if not present)
icacls $k /remove "BUILTIN\Administrators" "Users" "Authenticated Users" "Everyone" 2>$null
# Grant yourself read access (enough for SSH)
icacls $k /grant:r "$env:USERNAME:R"
# (Optional) allow SYSTEM read
icacls $k /grant:r "NT AUTHORITY\SYSTEM:R"
# Verify
icacls $k
```

Expected output includes only **`<YourName>:(R)`** (and optionally **`NT AUTHORITY\SYSTEM:(R)`**).

> If you see: **“WARNING: UNPROTECTED PRIVATE KEY FILE!”** later, re‑run the ACL steps above.

### 7) Upload your **public** key to Gitea

---

1. Show/copy your public key:

   ```powershell
   type "$env:USERPROFILE\.ssh\some_id.pub"
   ```

2. Go to your Gitea **Profile → Settings → SSH / GPG Keys → Add Key**.
3. Paste the entire single‑line key (starts with `ssh-ed25519` or `ssh-rsa`). Save.

> **Never** upload the private key (`some_id`). Only the `.pub` file.

### 8) Tell SSH which key to use for your host

---

Create/edit `C:\Users\<You>\.ssh\config`:

```text
Host code.kpuig.net
  User git
  IdentityFile C:\Users\<You>\.ssh\some_id
  IdentitiesOnly yes
  # Port 22        # If your Gitea shows a different port, set it here
```

You can create this file via Notepad:

```powershell
notepad "$env:USERPROFILE\.ssh\config"
```

### 9) Test the SSH connection

---

```powershell
ssh -T git@code.kpuig.net   # add -p <port> if needed
```

**Success looks like:**

```
Hi there, <username>! You've successfully authenticated ... but Gitea does not provide shell access.
```

If you see **PTY allocation request failed** — that’s normal; it’s just saying there’s no shell. Authentication still worked.

### 10) Use Git with SSH (clone, fetch, push)

---

```powershell
# Navigate to where you keep projects
cd $env:USERPROFILE\Projects
# Clone via SSH (check the clone URL in Gitea)
git clone git@code.kpuig.net:owner/repo.git
cd repo
# Typical workflow
git pull
# make changes
git add .
git commit -m "Your message"
git push
```

> If Git says “Permission denied (publickey)”: verify your `~/.ssh/config` host, the key path, and that the **matching** public key is in Gitea.

### 11) Common errors & quick fixes

---

**A) `Load key "... .pub": invalid format`**
You pointed SSH to the **public** key. Use the **private** key (no `.pub`).

**B) `WARNING: UNPROTECTED PRIVATE KEY FILE!`**
Reapply the ACLs from step 6 (only you should have Read on the private key).

**C) `Permission denied (publickey)`**

- Ensure the public key in Gitea matches your private key:

  ```powershell
  ssh-keygen -y -f "$env:USERPROFILE\.ssh\some_id" > "$env:USERPROFILE\.ssh\some_id.pub"
  ```

- Confirm your SSH config host & port; try `ssh -vvv -T git@code.kpuig.net` and read the last lines.

**D) Host key changed / MITM warning**
If the server was rebuilt, clear the old fingerprint:

```powershell
ssh-keygen -R code.kpuig.net
```

Retry to accept the new host key.

### 12) Optional: `ssh-agent` convenience (cache passphrase)

---

If your private key has a passphrase:

```powershell
Start-Service ssh-agent  # may require admin the first time
Get-Service ssh-agent
ssh-add "$env:USERPROFILE\.ssh\some_id"
```

Now SSH/Git can use the key without asking for the passphrase every time.

### 13) Quick glossary

---

- **PowerShell**: Windows command shell
- **SSH**: Secure shell protocol for authentication and Git
- **Private key**: Stays on your PC; keep secret
- **Public key**: Safe to upload; server uses it to verify you
- **ACL/Permissions**: Who can read a file
- **Gitea**: Self‑hosted Git service

### 14) Copy‑paste checklist (TL;DR)

---

```powershell
# 1) Create folder
mkdir $env:USERPROFILE\.ssh -ea 0

# 2) Generate key
ssh-keygen -t ed25519 -C "your.email@example.com" -f "$env:USERPROFILE\.ssh\some_id"

# 3) Lock private key (Run PowerShell as Admin)
$k = "$env:USERPROFILE\.ssh\some_id"
icacls $k /setowner "$env:USERNAME"
icacls $k /inheritance:r
icacls $k /remove "BUILTIN\Administrators" "Users" "Authenticated Users" "Everyone" 2>$null
icacls $k /grant:r "$env:USERNAME:R"

# 4) Put pubkey into Gitea
notepad "$env:USERPROFILE\.ssh\some_id.pub"  # copy to Gitea → Settings → SSH Keys

# 5) SSH config
notepad "$env:USERPROFILE\.ssh\config"  # paste Host block pointing to some_id

# 6) Test
ssh -T git@code.kpuig.net
```

You’re ready to clone and push.