How to Use Your Self-Hosted Gitea Server: A Beginner’s Guide for Developers

You have a self-hosted Git server running Gitea, and your team has invited you to collaborate on a project. Now what?

If you have never used Git before, the terminology can be intimidating: repositories, commits, branches, remotes, SSH keys, pushes, pulls…

Don’t worry. This guide will walk you through everything you need to get started, from configuring your computer to collaborating with other developers.

You don’t need administrator access to the Gitea server, and you don’t need to know how it was installed. You just need a Gitea account, access to a repository, and Git installed on your computer.

1. What You Need Before Getting Started

Ask your team leader or Gitea administrator for the following:

• Gitea address: The URL of your team’s Git server, for example https://git.example.com.
• Your account: Your Gitea username and login credentials.
• Repository access: The repository you will be working on, and confirmation that you have permission to access it.
• SSH clone address: The SSH address of the repository, normally displayed on its Gitea page.

You might also need the SSH port if your administrator has configured SSH to use something other than the standard port 22.

If you don’t have a Gitea account yet, ask your administrator to create one or invite you.

2. Create an SSH Key

SSH keys allow your computer to authenticate with Gitea without repeatedly asking for your account password.

The process involves two files:

• A private key, which stays on your computer and must never be shared.
• A public key, which you upload to your Gitea account.

Check whether you already have an SSH key

On Linux or macOS, open a terminal. On Windows, open PowerShell or Git Bash.

Run:

ls -la ~/.ssh

Look for files such as:

id_ed25519
id_ed25519.pub

If you already have an Ed25519 key that you intend to use, you can skip key generation.

If you don’t, create one:

ssh-keygen -t ed25519 -C "your-email@example.com"

When asked where to save the key, press Enter to accept the default location.

You can also protect your private key with a passphrase. This is recommended, especially on laptops.

You should now have two files:

~/.ssh/id_ed25519
~/.ssh/id_ed25519.pub

Never share id_ed25519. That is your private key.

Add your public key to Gitea

Display your public key:

cat ~/.ssh/id_ed25519.pub

Copy the entire output.

Now open your Gitea website:

1. Sign in to your account.
2. Click your profile picture and open Settings.
3. Navigate to SSH / GPG Keys.
4. Click Add Key.
5. Give the key a descriptive name, such as My Desktop or Work Laptop.
6. Paste your public key and save it.

That’s it! Your computer is now registered with Gitea.

If you use multiple computers, generate and register a separate SSH key for each one. Do not copy your private key between machines.

3. Install Git on Your Computer

Git is the version-control software that manages your projects. Gitea is the server that hosts your Git repositories.

You need Git installed locally, even though your team already has a Git server.

Debian and Ubuntu

sudo apt update
sudo apt install git

Windows

Download and install Git from:

https://git-scm.com/downloads

The installation includes Git Bash, which provides a convenient terminal for running Git commands.

macOS

If you use Homebrew:

brew install git

You can verify that Git is installed by running:

git --version

4. Configure Your Git Identity

Before creating commits, tell Git who you are.

Run:

git config --global user.name "Your Name"
git config --global user.email "your-email@example.com"
git config --global init.defaultBranch main

Use the name and email address you want associated with your contributions.

These settings identify the author of your commits. They are separate from your Gitea username and password.

By default, the main branch is called master, above, we change the default to main, but this is just my preference

To check your configuration:

git config --global --list

You only need to do this once on each computer.

5. Clone Your Team’s Repository

A repository is a project managed by Git. It contains the project’s files and its version history.

In most team environments, you will be given access to an existing repository.

Open the repository in Gitea. You should see a Clone button, which provides HTTPS and SSH addresses.

For this guide, we will use SSH.

An SSH address typically looks like this:

gitea@git.example.com:team/my-project.git

The actual address depends on your server configuration. Always copy the address displayed by your Gitea installation rather than constructing one yourself.

Open a terminal in the directory where you want your projects stored, then run:

git clone gitea@git.example.com:team/my-project.git

Git will download the repository and create a directory for it.

Enter that directory:

cd my-project

Congratulations! You now have a local copy of your team’s project.

What does cloning actually do?

Git does more than download the latest files.

It downloads the repository’s commit history as well. This means you can inspect previous versions, create branches, make commits, and work locally without needing a permanent internet connection.

The Gitea server is the shared repository where team members exchange their work.

6. Understand the Basic Git Workflow

Before making changes, there are a few concepts worth understanding.

• Working directory: The files you are currently editing.
• Staging area: The changes you have selected for your next commit.
• Commit: A recorded snapshot of your project changes.
• Remote: A repository hosted somewhere else, such as your team’s Gitea server.
• Push: Sending your local commits to the remote repository.
• Pull: Retrieving remote changes and integrating them into your local branch.

The basic workflow looks like this:

Edit files
    |
    v
git status
    |
    v
git add
    |
    v
git commit
    |
    v
git push

Let’s put that into practice.

7. Make Your First Change

Open one of the project files and make a small modification.

For example, edit README.md and add a line describing your contribution.

Now run:

git status

Git will show you which files have changed.

To see exactly what you modified:

git diff

When you are satisfied with your changes, stage the file:

git add README.md

If you want to stage all changes in the current directory:

git add .

Now create a commit:

git commit -m "Update project documentation"

A commit records your changes locally. It does not upload anything to the server yet.

Finally, push your commit:

git push

Your changes should now appear in the Gitea repository.

A useful habit

Run git status frequently.

It is one of the most useful Git commands because it tells you which files have changed, which files are staged, and whether your local branch is ahead of or behind its remote counterpart.

8. Get the Latest Changes Before You Start Working

In a team environment, other developers may have pushed changes since your last visit.

Before starting a new task, it is generally a good idea to retrieve the latest changes:

git pull

This fetches changes from the remote repository and integrates them into your current branch.

A good everyday routine is:

git pull

Then make your changes, commit them, and push:

git add .
git commit -m "Describe your changes"
git push

Important: If Git reports that your local branch and the remote branch have diverged, don’t immediately try random commands to force a push. Someone may have pushed changes that you don’t have locally. Read the message carefully and resolve the situation before proceeding.

9. Use Branches Instead of Working Directly on Main

When several people work on the same project, it is usually better to avoid making changes directly on the main branch.

A branch gives you an independent line of development. You can work on a feature or bug fix without immediately changing the main version of the project.

For example, create a branch for a new feature:

git switch -c new-feature

This creates the branch and switches you to it.

Check which branch you are currently using:

git branch

Make your changes and commit them as usual:

git add .
git commit -m "Add new feature"

Push your branch to Gitea:

git push -u origin new-feature

The -u option establishes the upstream relationship, so subsequent pushes can simply use git push.

Your new branch will now be visible in Gitea.

Create a Pull Request

Once your work is ready for review:

1. Open your repository in Gitea.
2. Navigate to Pull Requests.
3. Create a new Pull Request.
4. Select your feature branch as the source and main as the destination.
5. Describe what you changed and why.
6. Submit the Pull Request.

Your teammates can review your changes, leave comments, request modifications, and eventually merge your work into main.

This is a common workflow for development teams and helps prevent unfinished work from accidentally becoming part of the main project.

Your team may have its own branching and review policy, so follow the conventions established by your project maintainers.

10. What Is a Merge Conflict?

A merge conflict occurs when Git cannot automatically combine changes from different branches.

For example:

• Alice changes a particular line in index.html.
• Bob changes that same line independently.
• Both developers push their work.

When Git tries to combine the changes, it may not know which version should be kept.

You may see something like:

<<<<<<< HEAD
<h1>Welcome to our website</h1>
=======
<h1>Welcome to the new website</h1>
>>>>>>> main

These markers identify the competing changes.

You must edit the file, decide what the final content should be, and remove the conflict markers.

After resolving the conflict:

git add index.html
git commit

The exact commands can vary depending on whether you are resolving a merge, a rebase, or a Pull Request conflict.

If you are new to Git, don’t panic. Conflicts are a normal part of collaborative development. Ask a teammate for help if you are unsure which changes should be retained.

11. Use a .gitignore File

Not every file in a project should be committed.

For example, you generally don’t want to upload:

• Temporary files.
• Operating-system metadata.
• IDE settings.
• Dependency directories.
• Local environment configuration.
• Passwords, API keys, or other secrets.

Git uses a file called .gitignore to identify files and directories that should not be tracked.

A simple example:

# Operating system files
.DS_Store
Thumbs.db

# IDE settings
.idea/
.vscode/

# Temporary files and logs
*.tmp
*.log

# Dependencies
node_modules/

# Environment variables and secrets
.env
.env.*
!.env.example

Place this file in your project’s root directory.

A few things to remember:

• .gitignore only prevents Git from tracking matching files that are not already tracked.
• Adding an existing tracked file to .gitignore does not automatically remove it from the repository.
• Never commit secrets, even accidentally. If a secret is committed, removing the file in a later commit does not erase it from the earlier commit history. Rotate the exposed credential.

If your team already has a .gitignore file, don’t replace it without checking with the project maintainers.

12. Useful Git Commands to Keep Handy

Here is a quick reference for the commands you will use most frequently:

Command	Description
git status	Shows the current state of your working directory
git add .	Stages changes in the current directory
git add filename	Stages a specific file
git commit -m "Message"	Creates a commit
git push	Uploads local commits to the remote
git pull	Retrieves and integrates remote changes
git clone URL	Clones a repository
git log --oneline	Displays a compact commit history
git diff	Shows unstaged changes
git diff --staged	Shows staged changes
git branch	Lists local branches
git switch branch-name	Switches to another branch
git switch -c branch-name	Creates and switches to a new branch
git remote -v	Displays configured remote repositories

You don’t need to memorize everything. Keep this guide handy and use it as a reference while you become familiar with Git.

13. A Few Final Tips for Working in a Team

A few simple habits can save you and your teammates a lot of trouble:

1. Pull before you start working. Make sure you have the latest version of the branch.
2. Use descriptive commit messages. “Fix login validation” is much more useful than “Changes”.
3. Commit regularly. Small, focused commits are easier to review and understand.
4. Use branches for new features and bug fixes. Avoid making experimental changes directly on main.
5. Don’t commit secrets. Passwords, private keys, API tokens, and production credentials do not belong in Git.
6. Don’t force-push shared branches. A force push can overwrite commits pushed by other team members.
7. Communicate. Git helps manage code changes, but it doesn’t replace communication between developers.

12. Hands-On: Your First Real Git Project

Enough theory! Let’s put everything we’ve learned into practice.

We’re going to create a tiny website consisting of three files:

my-first-project/
├── index.html
├── style.css
└── magic.js

It won’t be anything spectacular, but that’s the point. We want to concentrate on learning Git, not building a complicated application.

By the end of this exercise, you will have created a local project, uploaded it to your Gitea server, modified it, committed the changes, and retrieved it again.

Step 1: Create Your Project

Open a terminal and create a directory:

mkdir my-first-project
cd my-first-project

Create the three files.

index.html

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My First Git Project</title>
    <link rel="stylesheet" href="style.css">
</head>
<body>
    <h1>Hello, Gitea!</h1>
    <p>This is my first project managed with Git.</p>

    <button onclick="showMagic()">Click Me!</button>

    <script src="magic.js"></script>
</body>
</html>

style.css

body {
    font-family: Arial, sans-serif;
    text-align: center;
    margin-top: 80px;
    background: #f4f4f4;
}

h1 {
    color: #333;
}

button {
    padding: 12px 24px;
    cursor: pointer;
}

magic.js

function showMagic() {
    alert("Congratulations! Your first Git project is working!");
}

You can create these files using your favourite editor. Alternatively, on Linux or macOS, you can use a terminal editor such as nano.

Your project directory should now contain all three files.

Step 2: Initialize Git

Let’s turn this ordinary directory into a Git repository:

git init

Git has now created a hidden .git directory. This is where it stores the repository’s history and metadata.

Check what Git sees:

git status

You should see something similar to:

Untracked files:
  index.html
  magic.js
  style.css

This is Git telling you that it can see the files, but it isn’t tracking them yet.

Step 3: Stage Your Files

Tell Git which files you want included in your next commit:

git add .

The dot means all applicable files in the current directory.

Check the status again:

git status

The files should now appear under Changes to be committed.

This is the staging area. Think of it as preparing the contents of your next snapshot before saving it.

Step 4: Create Your First Commit

Now save your first snapshot:

git commit -m "Initial project"

Congratulations! You have created your first Git commit.

You can inspect your history:

git log --oneline

You should see your new commit listed.

At this point, everything exists locally on your computer. Nothing has been uploaded to Gitea yet.

Step 5: Create a Repository on Gitea

Open your Gitea website and sign in.

1. Click the + button.
2. Select New Repository.
3. Name it my-first-project.
4. Choose whether it should be public or private.
5. Click Create Repository.

For this exercise, leave the repository empty. Do not initialize it with a README, .gitignore, or license, because we have already created and committed our files locally.

Gitea will display the repository’s clone addresses.

Copy the SSH address. It should look something like this:

gitea@git.example.com:YOUR_USERNAME/my-first-project.git

Use the actual address displayed by your server.

Step 6: Connect Your Local Project to Gitea

Return to your terminal, making sure you are still inside my-first-project.

Add the Gitea repository as a remote:

git remote add origin gitea@git.example.com:YOUR_USERNAME/my-first-project.git

Replace the example address with the one you copied from Gitea.

Now make sure your branch is named main:

git branch -M main

Check the remote configuration:

git remote -v

You should see your Gitea address listed.

Step 7: Push Your Project!

This is the moment we’ve been working towards:

git push -u origin main

Git will send your first commit and its files to your Gitea server.

Open your repository in your browser and refresh the page.

You should now see:

index.html
style.css
magic.js

Your first project is officially hosted on your own Git server!

Step 8: Make a Change and Commit It

Let’s make a small change to index.html.

Find:

<h1>Hello, Gitea!</h1>

Replace it with:

<h1>Hello, my own Git server!</h1>

Save the file.

Now ask Git what has changed:

git status

You should see that index.html has been modified.

Want to see exactly what changed?

git diff

Git will show you the difference between the previous committed version and your current file.

Stage the change:

git add index.html

Commit it:

git commit -m "Update homepage greeting"

And push it:

git push

Refresh your Gitea repository in the browser. The updated version should now be visible.

Notice that we didn’t need to specify origin main again. Git remembers the upstream branch because we used -u during our first push.

Step 9: Simulate Working on Another Computer

Now let’s demonstrate something important.

Imagine you are working on your desktop computer and want to continue the project on your laptop.

We can simulate this without needing a second computer.

First, move outside your existing project directory:

cd ..

Clone the repository into a new directory:

git clone gitea@git.example.com:YOUR_USERNAME/my-first-project.git my-second-copy

Again, use your actual SSH address.

Enter the new directory:

cd my-second-copy

Take a look at the files:

ls

You should find all three files, including the updated index.html.

Now let’s make another change. Open magic.js and replace its contents with:

function showMagic() {
    alert("Hello from my second computer!");
}

Check the changes:

git status

Stage and commit:

git add magic.js
git commit -m "Update magic message"

Push the change:

git push

Your Gitea server now contains this latest version.

Step 10: Retrieve the Changes in Your Original Project

Let’s return to the original project directory:

cd ../my-first-project

Remember, this directory still contains the earlier version of magic.js.

Retrieve the latest changes from Gitea:

git pull

Open magic.js.

You should now see the message from your second copy!

You’ve just simulated a very common real-world scenario: working on a project from two different computers and exchanging changes through your Gitea server.

That’s Git in action!

13. Your Git Workflow from Now On

After completing the exercise, you should have a much better understanding of the commands you’ll use every day.

For a typical working session, the process is:

# Get the latest changes
git pull

# See what has changed
git status

# Stage your modifications
git add .

# Save a snapshot
git commit -m "Describe what you changed"

# Send your changes to Gitea
git push

You don’t need to memorize every Git command. Keep this guide handy, experiment with your own projects, and use git status whenever you’re unsure what is happening.

As you become more comfortable, you can explore branches, Pull Requests, merging, rebasing, and the many other features Git offers.

Conclusion

You’ve now gone from an empty directory to a working project hosted on your own Gitea server.

More importantly, you’ve experienced the complete Git workflow rather than simply reading about it.

Whether you’re working alone, switching between computers, or collaborating with an entire development team, the same principles apply.

Welcome to the world of Git, and happy coding!

---

New to self-hosting? If you want to learn how to install and configure your own Gitea server on Debian, see our companion guide: Self-Hosted GitHub: Build Your Own Git Server with Gitea on Debian 13.