Skip to content

Git workflow with Forgejo

PerfShop is hosted on Forgejo, a community fork of Gitea which behaves exactly like GitHub or GitLab from the developer's point of view. Git commands are identical, only the interface names differ (GitLab's "Merge Request" name is not used; Forgejo uses "Pull Request" like GitHub).

Note

PerfShop does not use GitLab. All source code management goes through self-hosted Forgejo. The PerfShop dev / git workflow documentation only describes this Forgejo workflow.

Creating a Forgejo account

On the local PerfShop Forgejo instance (http://<HOST_IP>:3009), a forgejo-admin account is created at startup by the seed. The administrator can then create other accounts or allow public registrations.

For instances dedicated to training, each student receives an individual account created in advance by the instructor.

Cloning

See Cloning from Forgejo for the exact commands.

Branch workflow

The standard contribution workflow is as follows:

flowchart LR
  Main[main] -->|git checkout -b| Feat[feature/my-feature]
  Feat -->|commits| Feat
  Feat -->|git push| Remote[origin/feature/my-feature]
  Remote -->|Pull Request| Review[Review + CI]
  Review -->|merge| Main

1. Create a branch

From an up-to-date main:

git checkout main
git pull
git checkout -b feature/my-feature

Recommended branch naming:

Prefix Usage
feature/... New feature
fix/... Bug fix
docs/... Documentation update only
refactor/... Refactoring without behavior change
chore/... Technical tasks (dependencies, CI, build)

2. Commit

git add .
git commit -m "feat(frontend): add category filter on catalog"

PerfShop does not enforce a rigid commit format (no mandatory Conventional Commits, no message linter), but maintainers appreciate clear and concise messages in English or French. The first line summarizes the intent in 72 characters maximum; following lines (optional, after a blank line) detail the context.

3. Push

git push -u origin feature/my-feature

The -u flag (or --set-upstream) configures the local branch to track the remote branch, which then allows you to simply use git push and git pull.

4. Open a Pull Request

On the Forgejo interface, go to the repository and click New Pull Request. Forgejo automatically detects unmerged branches and suggests creating a PR.

Fill in:

  • Title — takes over the subject of the main commit
  • Description — explains the context, design choices, tests performed
  • Reviewers — designate one or more maintainers
  • Labels — optional tags (bug, enhancement, documentation, question)

5. Iterate on the review

If reviewers ask for changes, keep committing and pushing to the same branch. The Forgejo PR updates automatically.

git add .
git commit -m "fix: address review comments"
git push

6. Merge

Once the PR is approved and CI is green (if it exists), a maintainer merges the PR. Three strategies are available in Forgejo, as in GitHub:

  • Create a merge commit — preserves the full branch history (separate merge commit)
  • Squash and merge — combines all commits into a single one
  • Rebase and merge — replays the branch's commits on top of main without a merge commit

The choice depends on project policy. By default, PerfShop does not enforce any strategy — it is up to the maintainer performing the merge to decide.

Useful commands

Syncing with main

If your branch has diverged from main and you want to bring it up to date:

git checkout main
git pull
git checkout feature/my-feature
git rebase main

If conflicts appear, resolve them manually then:

git add <resolved-files>
git rebase --continue

And force push (your history has been rewritten):

git push --force-with-lease

--force-with-lease is safer than --force: it refuses to push if someone else has pushed to the same branch in the meantime.

Undoing the last local commit

git reset --soft HEAD~1

The changes remain in the staging area — you can re-commit with another message or different files.

Viewing the diff of a commit

git show <sha>

Searching the history

git log --grep="checkout"
git log --author="Philippe"
git log -- frontend/src/pages/Cart.jsx

SSH keys on Forgejo

To avoid entering your password on every push:

  1. Generate an SSH key if you do not have one: 
    ssh-keygen -t ed25519 -C "your@email.com"
  2. Copy the content of ~/.ssh/id_ed25519.pub
  3. In Forgejo: Settings → SSH / GPG Keys → Add Key
  4. Change the remote URL from HTTPS to SSH: 
    git remote set-url origin git@forgejo.example.com:perfshop/perfshop.git

Personal access tokens

For scripts and CI that cannot use SSH, Forgejo offers personal access tokens to create in Settings → Applications → Generate New Token. The token replaces the password in HTTPS URLs:

git clone https://USERNAME:TOKEN@forgejo.example.com/perfshop/perfshop.git

Never store tokens in plaintext in a versioned file.

.gitignore and sensitive files

The project's root .gitignore already excludes:

  • .env (local configuration values)
  • node_modules/
  • backend/target/
  • frontend/dist/
  • IDE files (.idea/, .vscode/, *.iml)
  • Logs and dumps

Never commit a .env file with real credentials, a private keystore, a PGP key, or an access token. If you do it by accident, immediately rotate the compromised credentials — a git revert is not enough because the history remains accessible.

Optional hooks

PerfShop does not provide any mandatory Git hooks. You can add your own local hooks in .git/hooks/ (e.g., a pre-commit that runs mvn spotless:apply or npm run lint); they will not be versioned.

CI / continuous integration

Forgejo supports a GitHub Actions–compatible action system (via Forgejo Actions). If a PerfShop instance has configured runners, you can add workflows in .forgejo/workflows/ that will run on every push or PR. Check your instance's Forgejo interface to see the actions executed on your PRs.

See also