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.

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)

---

$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.

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.

$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:

   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:

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:

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

9) Test the SSH connection

---

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)

---

# 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:

  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:

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:

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)

---

# 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.