Add workflow-en.md
This commit is contained in:
+263
@@ -0,0 +1,263 @@
|
||||
# Working with a project on git.intecion.net
|
||||
|
||||
> 🇬🇧 English (maintained) · 🇵🇱 [Polski](./gitea-workflow.pl.md)
|
||||
|
||||
A guide for anyone working on a project whose repository lives on the company
|
||||
Gitea (`git.intecion.net`). Covers getting the code, the daily cycle (pull →
|
||||
work → push), juggling several projects, and the most common auth errors.
|
||||
|
||||
The server is internal — every operation that reaches it needs authentication.
|
||||
You have two routes: **HTTPS with a token** (simpler to start) or **SSH with a
|
||||
key** (more convenient long-term, since it doesn't prompt every time). Pick one.
|
||||
|
||||
---
|
||||
|
||||
## One-time access setup
|
||||
|
||||
### HTTPS route (token)
|
||||
|
||||
Nothing to install — you only need a token.
|
||||
|
||||
1. Gitea → avatar → **Settings → Applications → Generate New Token**.
|
||||
2. Scope: **`write:repository`** (lets you read and push code).
|
||||
3. Copy the token — it's shown only once.
|
||||
|
||||
On your first `git push`/`clone` of a private repo, Git asks for credentials:
|
||||
- **Username:** your Gitea login
|
||||
- **Password:** paste the **token** (not your account password — Gitea doesn't
|
||||
accept the password for git operations over HTTPS)
|
||||
|
||||
To avoid retyping it every time, enable credential storage:
|
||||
|
||||
```bash
|
||||
# macOS — uses Keychain
|
||||
git config --global credential.helper osxkeychain
|
||||
|
||||
# Windows — uses Credential Manager
|
||||
git config --global credential.helper manager
|
||||
|
||||
# Linux/Ubuntu — cache in memory for 1h (safer than storing plaintext)
|
||||
git config --global credential.helper 'cache --timeout=3600'
|
||||
```
|
||||
|
||||
### SSH route (key)
|
||||
|
||||
More work up front, then no password prompts at all.
|
||||
|
||||
1. Generate a key if you don't have one:
|
||||
```bash
|
||||
ssh-keygen -t ed25519 -C "[email protected]"
|
||||
# Enter through all prompts (default location, with or without a passphrase)
|
||||
```
|
||||
2. Copy the **public** key:
|
||||
```bash
|
||||
# macOS
|
||||
pbcopy < ~/.ssh/id_ed25519.pub
|
||||
# Linux
|
||||
cat ~/.ssh/id_ed25519.pub # select and copy
|
||||
# Windows (PowerShell)
|
||||
Get-Content ~/.ssh/id_ed25519.pub | Set-Clipboard
|
||||
```
|
||||
3. Gitea → **Settings → SSH / GPG Keys → Add Key** → paste.
|
||||
4. Test the connection (mind the port — Gitea may use a non-standard one):
|
||||
```bash
|
||||
ssh -T -p 22222 [email protected]
|
||||
```
|
||||
"Hi <login>! You've successfully authenticated" → it works.
|
||||
`Permission denied (publickey)` → key not added, or wrong port.
|
||||
|
||||
---
|
||||
|
||||
## Getting the project (first time)
|
||||
|
||||
Find the repo address on its page in Gitea (the **Clone** button). Pick the HTTPS
|
||||
or SSH tab matching the route you set up.
|
||||
|
||||
```bash
|
||||
# HTTPS
|
||||
git clone https://git.intecion.net/IntecionSoftware/project-name.git
|
||||
|
||||
# SSH (port as in your Gitea)
|
||||
git clone ssh://[email protected]:22222/IntecionSoftware/project-name.git
|
||||
```
|
||||
|
||||
**What happens:** Git connects to the server (token or key), downloads the full
|
||||
history and files into a new `project-name` directory.
|
||||
|
||||
```bash
|
||||
cd project-name
|
||||
pnpm install # fetch dependencies (see the project's README)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## The daily cycle
|
||||
|
||||
### Before you start — pull others' changes
|
||||
|
||||
```bash
|
||||
git pull
|
||||
```
|
||||
|
||||
**What it does:** downloads commits others pushed since your last pull, and
|
||||
merges them into your copy. Do it at the start of the day and before every
|
||||
`push` — otherwise your push may be rejected (see below).
|
||||
|
||||
### While working — save progress locally
|
||||
|
||||
```bash
|
||||
git status # what you changed (sends nothing)
|
||||
git add . # mark changes to be saved
|
||||
git commit -m "describe what the change is about"
|
||||
```
|
||||
|
||||
**What happens:** a commit saves a snapshot **locally**, on your disk. The server
|
||||
doesn't know about it yet. You can make several commits before sending anything.
|
||||
|
||||
### When you finish a piece — send it to the server
|
||||
|
||||
```bash
|
||||
git push
|
||||
```
|
||||
|
||||
**What it does:** sends your local commits to the repository on Gitea, so the
|
||||
team can see them. This is the first command in the cycle that **changes** the
|
||||
server's state.
|
||||
|
||||
---
|
||||
|
||||
## Working on a branch (recommended)
|
||||
|
||||
Instead of working straight on `main`, split off a branch for your changes —
|
||||
easier to review, fewer conflicts.
|
||||
|
||||
```bash
|
||||
git checkout -b my-feature # create and switch to a new branch
|
||||
# ... work, commits ...
|
||||
git push -u origin my-feature # send the branch to the server (first time with -u)
|
||||
```
|
||||
|
||||
Then open a **Pull Request** in Gitea from `my-feature` into `main`, so someone
|
||||
reviews it before it lands on the main branch.
|
||||
|
||||
---
|
||||
|
||||
## Working on several projects at once
|
||||
|
||||
Each project is a separate directory with its own repository. There's no single
|
||||
"switch project" command — you simply `cd` into the project you want to work on.
|
||||
Git reads its config (server address, branch, history) from whatever directory
|
||||
you're currently in.
|
||||
|
||||
### Where to keep projects
|
||||
|
||||
Keep them side by side in one place, e.g.:
|
||||
|
||||
```
|
||||
~/projects/
|
||||
client-a/ ← its own repo, its own remote
|
||||
client-b/ ← its own repo, its own remote
|
||||
ipal-kit/ ← the plugin
|
||||
```
|
||||
|
||||
Switching between them is a change of directory:
|
||||
|
||||
```bash
|
||||
cd ~/projects/client-a
|
||||
# ... work on A ...
|
||||
|
||||
cd ~/projects/client-b
|
||||
# ... work on B ...
|
||||
```
|
||||
|
||||
Every `git pull` / `git push` / `git status` acts on the project **whose
|
||||
directory you're currently in**. That's why your first reflex after `cd` should
|
||||
be checking where you are and in what state.
|
||||
|
||||
### After entering a project — get your bearings
|
||||
|
||||
Three commands give the full picture:
|
||||
|
||||
```bash
|
||||
pwd # which project am I in (full path)
|
||||
git remote -v # which repo on Gitea does this push to
|
||||
git status # which branch, any unsaved changes
|
||||
```
|
||||
|
||||
`git status` shows the branch at the top (`On branch ...`) — make sure it's the
|
||||
one you mean to work on before you start committing.
|
||||
|
||||
### Pitfalls with multiple projects
|
||||
|
||||
- **Pushing to the wrong repo.** If you set up project B by copying project A's
|
||||
directory (instead of `git clone`), the remote still points at A's repo — and
|
||||
you'll push B's changes into A. Always clone with `git clone`, never by copying
|
||||
a directory. Check `git remote -v` on the first push of a new project.
|
||||
- **Forgotten unsaved changes.** `cd`-ing to another project doesn't lose changes
|
||||
in the previous one — they wait in that directory. But it's easy to forget you
|
||||
left something uncommitted. `git status` reminds you when you return.
|
||||
- **Dependencies are per project.** Each project has its own `node_modules`.
|
||||
After moving to a project you haven't touched in a while, run `git pull` then
|
||||
`pnpm install` — someone may have added dependencies you don't have.
|
||||
|
||||
### Quick orientation — which project, which branch
|
||||
|
||||
It's worth configuring your prompt to **show the current branch** automatically —
|
||||
then you always see where you are without typing `git status`.
|
||||
|
||||
On macOS/Linux (zsh/bash) most ready-made setups add this (oh-my-zsh, starship).
|
||||
If you don't have one, starship (`https://starship.rs`) works on all three
|
||||
systems and shows directory + branch automatically.
|
||||
|
||||
### Several projects open in the editor
|
||||
|
||||
In WebStorm/VSCode, open each project as a **separate window** (its own directory
|
||||
as the root). The editor then reads the right `.git` and shows the right branch
|
||||
in the corner. Opening the parent directory (`~/projects/`) as a single project
|
||||
mixes repositories — avoid that.
|
||||
|
||||
---
|
||||
|
||||
## Common errors and what they mean
|
||||
|
||||
| Message | What happened | What to do |
|
||||
|---|---|---|
|
||||
| `Permission denied (publickey)` | SSH: server doesn't know your key, or wrong port | add the key in Gitea; check the port (`-p 22222`) |
|
||||
| `remote: Unauthorized` / repeated password prompt | HTTPS: bad token, or you gave your account password instead of the token | use the token as the password; check the `write:repository` scope |
|
||||
| `failed to push ... non-fast-forward` | someone pushed changes you don't have locally | `git pull` (merge), then `git push` |
|
||||
| `Updates were rejected because the tip of your current branch is behind` | same as above — you're "behind" the server | `git pull`, resolve any conflicts, `git push` |
|
||||
| `fatal: repository not found` | wrong address, or no access to the repo in Gitea | check the address (Clone in Gitea); ask for access |
|
||||
| merge conflict after `git pull` | you and someone else changed the same lines | Git marks the files; edit, `git add`, `git commit` |
|
||||
|
||||
### When a push is rejected (non-fast-forward)
|
||||
|
||||
This is the most common case. The server has commits you don't — it won't let you
|
||||
overwrite them. The order:
|
||||
|
||||
```bash
|
||||
git pull # fetch and merge others' changes
|
||||
# if there's a conflict: Git shows the files, resolve them, then:
|
||||
git add .
|
||||
git commit -m "merge"
|
||||
git push # now it goes through
|
||||
```
|
||||
|
||||
Don't force (`git push --force`) on a shared branch (`main`) — you'd overwrite
|
||||
others' work. Force is only safe on your own branch that nobody else uses.
|
||||
|
||||
---
|
||||
|
||||
## Checking where your project points
|
||||
|
||||
If you're unsure whether a local repo is wired to Gitea:
|
||||
|
||||
```bash
|
||||
git remote -v
|
||||
```
|
||||
|
||||
It shows the server address. It should contain `git.intecion.net`. If it points
|
||||
elsewhere (e.g. an old GitHub), change it:
|
||||
|
||||
```bash
|
||||
git remote set-url origin https://git.intecion.net/IntecionSoftware/project-name.git
|
||||
```
|
||||
Reference in New Issue
Block a user