Getting started

• Your First Repository
• The Basics of Issue Tracking
• Integrated Wiki
• Email Settings
• Getting started

Your First Repository

Almost everything on Forgejo happens in a repository. Think of a repository as a home for your project, where all of its source code can be organized using Git, as well as where you can track issues and read and write wikis.

This article will guide you through creating your first repository on Forgejo, connecting your local development environment, and making your first commit.

Creating a Repository

To create a new repository, you need to be logged in to your account.

When you're logged in, you can use one of the two buttons shown in the following screenshots to create a new repository:

This will lead you to the page below.

Here's an explanation of the form's fields:

• Owner Here you can specify whether you want this to be your own personal project or whether you want it to be part of an organization that you're a part of.
• Repository name A name for your repository (which will also be part of its path, in this case https://codeberg.org/knut/foobar).
• Visibility Repositories are either public or private. Public means that everyone will be able to access your repository, while your private repositories can only be accessed by you and your collaborators (see Invite Collaborators).
• Description A short description that appears next to your repository's name where appropriate.
• Template Occasionally you may want to generate your repository from an existing template. In that case, you can specify that template here. Otherwise, simply leave this field empty.
• Issue Labels If you want to initialize your project's issue tracker with a set of labels that you can use to categorize issues, you can choose one here. You don't have to choose this right away, though, as you can choose and modify issue labels at a later time as well.
• .gitignore A .gitignore file defines which files Git should not keep track of. This is useful, for example, to prevent configuration files or binaries from being tracked in version control. You can choose to add a predefined file matching the programming language you use now, or add one manually later.
• License Here you can choose from a list of FSF/OSI approved licenses. A LICENSE file will then be added to the repository. For some help on choosing the correct license, have a look at our licensing article.
• README is the first file one should read when accessing a repository. It's also the first file displayed when accessing a repository, a bit like the "homepage" of your repository. On Forgejo, this is interpreted as a Markdown file.
• Initialize repository To add the LICENSE, README, and .gitignore files mentioned above to your new repository, make sure you tick this box.
• Default branch Using this field, you can choose how to name the default branch of your Git repository. We recommend you use the predefined default.
• Object format is the repository's object format. We recommend SHA1 as it's the most compatible. It cannot be changed later once the repository has been created.

It's okay to only specify the owner and repository name if you want to get started quickly. After filling out the fields, click the green "Create Repository" button at the bottom of the page.

You should now see a screen similar to the one below. If you haven't chosen to generate LICENSE, README, and .gitignore, the screen might show instructions instead, which will vanish after your first commit.

Here's what the most important buttons do:

• Repository Settings (1) is where you can make adjustments to your repository settings, such as setting a project website, changing the repository description, enabling/disabling a wiki and issue tracker, or deleting the repository. You may want to give this page a visit right now to get an overview of your options.
• The RSS, Watch, Star, and Fork buttons (2) allow you to interact with other people's repositories. While they don't do much for your own repository, when visiting another user's repository, you can click on "Watch" to get notified about everything important happening in that repository, "Star" to show the user your appreciation (and to help other users find interesting projects more quickly), and "Fork" to create your own copy of the repository, for example, to make modifications that you want to share with the original author. You can also use the RSS button to get the RSS feed of the repository.
• The Repository Tabs (3) contain links to every important feature within this repository (some may not be visible by default):
  • Code lets you browse through all versions of this repository's code.
  • Issues is a very important communication tool between the author, their users, and their contributors. Think of it as part bug-tracker, part forum. For more information on this, have a look at The Basics of Issue Tracking.
  • Pull Requests is where other users can ask the author to "pull" in code, from a fork into the author's program.
  • Releases is a space where the author can upload finished versions of their program, for example binaries.
  • Wiki is a basic wiki feature built into Forgejo.
  • Activity calculates statistics about this repository.
• Repository's Git URLs (4) - use these to let Git know where to find this repository. Don't worry if you don't understand this now, we will look at this in the following section.

Connect a local repository to Forgejo

After creating a new repository, as laid out in the previous section, you can now move on to connect the repository with your local development copy.

In this guide, we'll focus on connecting to Forgejo via HTTP using Git on the command line, but note that there are other ways to connect to Forgejo, as laid out in more detail in these articles:

• Clone & Commit via CLI and
• Clone & Commit via Web

Although we use HTTP in this guide, it is a good idea to set up SSH-based authentication once you feel confident to do so.

Note on the different types of HTTP authentication

When you try to access a git repository over HTTP, you have 3 approaches for authentication. This does not apply to accessing a repository over SSH.

1. Using an API token as your HTTP password
   • In Settings -> Applications, click New access token. Give it any name, set access to All, and repository to Read and write, and click Generate token. Copy the long token that appears.
   • When operating on a repo and are prompted for a password, enter the API token as your password
   • See Access Token Scope for more advanced info.
2. Using the same username and password you use on your Forgejo instance's website. This is the simplest approach but has some downsides as seen below.
3. Using OAuth. This requires a git client with OAuth support, or the installation of a companion tool for the git binary. See OAuth2 Git authentication for more info.

Comparison of options:

Method	Tools needed	Fast LFS?	Suitable for...
API token (Recommended)	Any git tool	Yes ✓	Users who want a general approach that works with any git tool including the bare git binary, and without LFS issues. Users who want to reduce the negative consequences if their git client credentials are leaked, since API tokens can be limited to repository access only.
OAuth (Recommended)	Git tool with OAuth support	Yes ✓	Users using a graphical git client with OAuth support, or who have the technical know-how to install a companion OAuth tool to the bare git binary.
Account's username and password	Any git tool	No ✗	Users who want a general approach that works with any git tool, but accept that LFS will be slow, and 2FA won't work.

Option A: Clone the newly created, empty repository

If you want to start a fresh project (so if you don't already have source code that you want to upload to Forgejo), the quickest way to get started is to clone your newly created repository like this:

1. Navigate to your local workspace (optional)

If you're just getting started, it's a good idea to keep your projects neatly sorted in a dedicated directory, like in this example:

knut@iceberg:~$ mkdir repositories
knut@iceberg:~$ cd repositories
knut@iceberg:~/repositories$

2. Clone the repository

To clone your newly created repository, execute git clone with the URL that is shown in your repository:

knut@iceberg:~/repositories$ git clone https://codeberg.org/knut/foobar
Cloning into 'foobar'...
remote: Enumerating objects: 4, done.
remote: Counting objects: 100% (4/4), done.
remote: Compressing objects: 100% (3/3), done.
remote: Total 4 (delta 0), reused 0 (delta 0)
Unpacking objects: 100% (4/4), 11.94 KiB | 764.00 KiB/s, done.

3. Navigate to the cloned repository

After cloning, the repository should now be in a new directory with the same name as your repository. In this case, it's called foobar.

knut@iceberg:~/repositories$ cd foobar
knut@iceberg:~/repositories/foobar$ ls
LICENSE  README.md

Option B: Connect an existing local source tree

If you have already written source code that you now would like to upload to Forgejo, follow the steps below. An upload to Forgejo is referred to as a push.

1. Initialize a Git Repository

Unless you already have a Git Repository initialized in your local source tree, run git init in your project's directory:

knut@iceberg:~/my-project$ git init
Initialized empty Git repository in /home/knut/my-project/.git/

2. Add Forgejo as the repository's origin

Now you need to tell Git where to push your changes. You would do that by specifying Forgejo as a remote.

In this example, we'll specify Forgejo as the origin remote. You can name your remote any other way, especially if you already have an origin, but origin is the recommended name for the main remote repository.

knut@iceberg:~/my-project$ git remote add origin https://codeberg.org/knut/foobar

When you clone a repository from the Internet, the URL that you got your copy of the repository from will be automatically used for the origin remote.

If your local copy of the repository is missing some commits that exist in the remote repository, pushing will result in an error. There are two ways to fix this:

• Run git pull to combine your local changes with the changes that exist in the remote repository. If this does not work, please follow the instructions in your terminal.
• If you know what you are doing, you can also overwrite the remote repository using git -f push. This action will permanently alter your remote repository and is not suitable if you are working on a project together with other people.

Option C: Migrate an existing git repository to Forgejo

You can migrate existing repos to Forgejo while preserving their entire history, tags, and more.

1. Navigate to your Foregejo instance's web interface
2. In the top right, click + -> New migration
3. Choose the provider you're importing from, and follow the instructions

Making your first commit

Now that you've connected your repository to your local development copy, it's time to make your first commit.

If you didn't generate the LICENSE and README.md files when creating the repository, it's a good idea to add them now. Just put them in your local development copy's directory and add them to your commit, as shown below.

1. Create or edit a file

Let's modify the README.md file.

If you didn't generate README.md, these commands will still work fine. However, instead of "Hello World!" being at the end of the file, it'll be the only line in the file.

knut@iceberg:~/repositories/foobar$ echo "Hello World!" >> README.md
knut@iceberg:~/repositories/foobar$ cat README.md
# foobar

Hello World!

Now, if you ask Git about your repository's status, you should see something similar to this:

knut@iceberg:~/repositories/foobar$ git status
On branch main
Your branch is up to date with 'origin/main'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
	modified:   README.md

no changes added to commit (use "git add" and/or "git commit -a")

You can create or modify more files, if you'd like.

2. Add changes to your commit

Next, you should add each modified file that you'd like to add to your commit with git add:

knut@iceberg:~/repositories/foobar$ git add README.md

This command should output nothing.

If you want to add all modified files in your source tree, you can run git add . but be careful as this might add unwanted files as well, so it's a good idea to double-check by running git status before committing.

3. Commit your changes

By committing your changes, you create a new step in the version history of your program. They act like snapshots of your program's state at a given point in time, and you will later be able to jump back and forth between them.

It is recommended to keep commits small and focused, so that, if necessary, they can be reverted or easily adapted into another context without too many side-effects.

To commit your changes, run git commit and specify a commit message; this will later help you (and others) to identify that commit when looking back at your version history.

knut@iceberg:~/repositories/foobar$ git commit -m "My first commit on Forgejo"
[main 1e12979] My first commit on Forgejo
 1 file changed, 1 insertion(+)

If you look at the version history of your program using git log, you may now see something similar to this:

knut@iceberg:~/repositories/foobar$ git log
commit 1e1297929c8c74d9a439fa71c1f0ffe1dbf3d5ad (HEAD -> main)
Author: Knut <knut@noreply.codeberg-test.org>
Date:   Sat Sep 26 14:01:00 2020 +0200

    My first commit on Forgejo

commit c75b50920e3aa7a7ab3484e898fb3ad77132722a (origin/main, origin/HEAD)
Author: Knut <knut@noreply.codeberg-test.org>
Date:   Sat Sep 26 12:29:57 2020 +0200

    Initial commit

4. Push your changes to Forgejo

If you're happy with the changes you made, the next step is to present them to the world by pushing them to Forgejo:

knut@iceberg:~/repositories/foobar$ git push -u origin main
Username for 'https://codeberg.org': knut
Password for 'https://knut@codeberg.org':
Enumerating objects: 5, done.
Counting objects: 100% (5/5), done.
Delta compression using up to 16 threads
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 315 bytes | 315.00 KiB/s, done.
Total 3 (delta 0), reused 0 (delta 0)
remote: . Processing 1 references
remote: Processed 1 references in total
To https://codeberg.org/knut/foobar
   c75b509..1e12979  main -> main
Branch 'main' set up to track remote branch 'main' from 'origin'.

The -u option sets the upstream remote, which we want to be Codeberg.org, as configured previously.

The main argument sets the name of the branch onto which shall be pushed upstream. For this example, it should be the same branch name that you specified when creating the repository.

When connecting via HTTPS, Git will ask you for your username and password, which you can enter interactively.

After refreshing the repository page, you should now see something similar to this:

Congratulations - you've just made your first source code contribution on Forgejo!

The Basics of Issue Tracking

Issues are an important means of communication on Forgejo. Besides their original purpose - reporting bugs to a project's maintainer - they can be used to suggest enhancements, ask for new features, discuss a project's direction, ask questions, and much more.

The Issue Tracker

You can access the issue tracker of a project by clicking its "Issues" tab (1).

There, you'll see a browsable and filterable (2) list of all issues. Many projects use labels to categorize issues. If you want to contribute to a project, a good label to look for is the "help wanted" label.

You can switch between issues that are still open and those that are already resolved (3).

Some projects define milestones (4), to which issues can be assigned. They are good for visualizing the progress of a project's development.

You can create an issue by clicking on the orange "New Issue" button (5) at the top right of the issues list.

Issues in the issue tracker are public, and everyone is able to read and answer them.

An issue can have an assignee, meaning someone responsible for resolving or moderating the issue. Their profile picture, with a link to their profile, can be seen in the issue list.

Life of an Issue

Once an issue in the Issue Tracker has been created, it will usually pass through a process of review, discussion, and closure, which can be more or less strictly defined, based on the project you're contributing to.

The first thing that might happen is that your issue is categorized using labels. Your issue may be reviewed by the project's maintainer(s) and evaluated whether it is, i.e., a bug report or feature request.

Then, depending on what type of issue it is, there might be additional questions or a discussion and, if applicable, the implementation of a solution (or the rejection of the issue).

Finally, the issue is closed and moved from the list of open issues to the closed one. Issues might have dependencies on other issues or pull requests preventing them from being closed.

Occasionally, issues may become "stale". That's when there hasn't been any progress for an extended period of time (usually months). You might consider reviving these, if there is a strong interest in getting them resolved (and, preferably, if you can contribute something to them).

If you encounter an abandoned project and there's no way of contacting the maintainer(s), consider forking it, if you want to assume responsibility for it (or, rather, your fork).

Things to Consider

Security bugs

If the bug you have found has security implications, do not create an issue right away! Instead, try contacting the project's maintainers privately. Many projects have a dedicated email address for reporting security bugs. If the project in question doesn't, consider writing an email directly to the project's maintainer or asking for the address in the issue tracker.

⚠ What's important is that you don't publicly expose security bugs before they are fixed and the fixes are deployed, because otherwise, you might put the users of that project at severe risk.

Existing issues

Before creating a new issue, please make sure that there isn't already an existing issue about, i.e., the bug you want to report or the feature you want to request.

If there already is an existing issue, please consider commenting on that issue instead, if there is something more that you can contribute to it.

You should also make sure that the issue has not already been solved by having a look at the closed issues (3) as well.

Try to be precise and helpful

Project maintainers love precise information about why, i.e., a bug is happening.

Some projects may even have templates that specifically ask for information like the operating system or database software used.

If you can provide that information, it will be easier for the project maintainer(s) to quickly resolve your issue. And if you want it resolved even quicker, consider writing a Pull Request solving the issue (if possible).

Be (reasonably) patient

Please remember that many project maintainers work on their free software projects in their free time. Some maintainers may answer you within minutes, others within days. Don't be discouraged if there isn't an immediate answer.

Integrated Wiki

A wiki is a collaborative space on the web. It is a common practice to use wikis to collect knowledge and share information. Codeberg allows you to add a wiki to a repository for additional documentation.

The user in these examples is knut, the polar bear, and its repository is foobar.

Activation and Permissions

To enable the wiki for a repository, visit the Settings page and activate Enable repository wiki in the Wiki section under Units. It will default to the built-in wiki which is described here, but you can add a URI to an external site the "Wiki" tab should link to.

Warning Be aware that the wiki, once enabled, is accessible to everyone who has read access to your repository - on public repositories even unauthenticated guests can access the wiki. The wiki is not a suitable place for storing private information or secrets (like passwords).

Activating the Allow anyone to edit the wiki option in Settings will give everyone with an account write access to the wiki.

To edit the wiki, write permission to the repository is required, unless the Allow anyone to edit the wiki setting is activated on the Settings page, in the Wiki section under Units.

Wiki structure

The wiki is essentially a separate Git repository in your repository with a predefined name in the form of <your-repository-name>.wiki.git.

It consists of Markdown files (file extension .md) and additional assets like images. No further stylesheets are needed. The Markdown files are automatically rendered according to the selected Forgejo theme.

Adding content via web

After you have enabled the wiki, you are prompted to create the initial page Home.md.

The web UI in your browser is currently limited to adding, updating, and deleting pages; you can't manage assets like images this way.

Clicking on the "Insert Image" button will make the following text appear in your text editor: ![](https://)

Adding content using a local Git client

You can work with the wiki repository as you would with any other Git repository on Forgejo.

git clone git@codeberg.org:knut/foobar.wiki.git
cd foobar.wiki
nano Home.md # or your editor of choice
git commit -am "create Home page"

Editing locally allows you to use your favorite editor (preferably with Markdown syntax check and highlighting) and manage additional assets like images.

Adding images using a local Git client

You can add images to the root directory or a specific subfolder (like assets or images) using your local Git client.

A feasible workflow might look like this:

# create a subfolder for images
mkdir images
cd images
# copy the image into this folder
git add images/image.png
git commit -m "add image"
git push

Attaching images in Markdown documents

Now, you can reference the image in Markdown, like this:

File in repository:

![image alt text](images/image.png 'image title')

External image:

![image alt text](https://example.com/image.jpg 'image title')

When including images from Forgejo repositories, keep in mind that you should use the raw version of the image.

After saving your changes, the image should be visible.

In contrast to embedding external images, images in Git are only rendered after saving the wiki or Markdown file changes.

Adding a sidebar and a footer

To enhance the usability of your wiki, you can add a custom sidebar and a footer that are shown on every page. The sidebar will be displayed to the right of the main content and the footer below.

To enable the sidebar, just add a file named _Sidebar.md to your wiki. For a footer, the file must be named _Footer.md. Both file types allow common Markdown syntax to adjust the presentation to your needs.

Very basic example for a sidebar:

- [[Home]]

### Content

- [Page 1](https://forgejo.org/docs/v15.0/user/getting-started/wiki/Page-1/)

> knuts wiki

These files starting with _ are hidden, so in the web UI you need to manually browse for the files. E.g. for our user knut and his foobar repo: https://codeberg.org/knut/foobar/wiki/_Sidebar

Embedding LaTeX-style equations

The wiki also supports embedding LaTeX-style equations in Markdown files, using KaTeX.

Such equations go between two $ characters, for example, like this:

$ \frac{1}{2} = 0.5 $

This will then result in the following properly rendered equation:

It is also possible to have LaTeX render in display mode, using $$ or \[ with \]:

\[ \mathbf{R} = \frac 1M \iiint_Q \rho(\mathbf{r}) \mathbf{r} \mathrm dV \]
$$ (p \implies q) \iff (\neg q \implies \neg p) $$

It is however not supported to use either of these syntaxes when the equation spans multiple lines; in that case, a code block with the language math should be used, for example:

```math
\int_0^\pi\ln(1-2\alpha\cos x+\alpha^2) \mathrm dx =
2\pi\ln|\alpha|
```

Email Settings

By default, Forgejo will send notifications to your registered email addresses.

This section only concerns your Forgejo account and will not affect the commits you make outside the website. If you don't know how to configure your name and email in Git, take a look at the "Configuring Git" man page.

Configuring all notifications

To change your notification preferences, go to your Account Settings or manually navigate to the settings page.

You can access it by clicking on the menu button “Profile and Settings...” in the top-right corner of Forgejo. From this dropdown, click on Settings, then click on the Account tab.

In the section “Manage Email Addresses”, you can select one of the following options from the drop-down menu for each email address that you have registered with Forgejo:

Option	Effect
Enable Email Notifications	Enables all notifications, except about your own actions (default setting)
And Your Own Notifications	Enables all notifications, including notifications about your own actions
Only Email on Mention	Forgejo will only send an email to this address if your username is mentioned in an issue or a comment
Disable Email Notifications	Forgejo will not send any emails to this address

When you're finished, press the button “Set Email Preference” to confirm your selection.

Note: Disabling email notifications doesn't mean that you'll stop receiving important messages from the Forgejo organization.

Issue notifications

As soon as you make a comment on an issue, you automatically subscribe to it. Unless you have disabled email notifications for all your email addresses, you will get an email for every change and comment on that issue.

You can check and modify your issue subscription status under the “Notifications” section on the menu on the right side of the issue screen.

Watching repositories

When you watch a repository (by clicking on the “Watch” button in a repository), you will receive emails for every change (creation of issues, pull requests, comments, etc.) done in this repository.

To stop watching a repository, simply click on “Unwatch” in a repository.

To list all of your watched repositories, click on /notifications/watching. Alternatively, you can click the menu button “Profile and Settings...” in the top-right corner of Forgejo and click on "Subscriptions" in the dropdown.

Getting started

Your first steps on Forgejo.