266 lines
7.3 KiB
Markdown
266 lines
7.3 KiB
Markdown
# 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.
|