hannah-eee/forjero-docs huggingface dataset:
File: docs\user\labels.md

---
title: 'Labels'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/e865de1e9d65dc09797d165a51c8e705d2a86030/docs/content/usage/labels.en-us.md'
---

You can use labels to classify issues and pull requests and to improve your overview of them.

Labels can be created by going to the `Issues` page of a repository and clicking on `Labels` to show the labels management page.

![repository labels management](../_images/user/labels/repository-labels-management.png)

For organizations, you can define organization-wide labels that are shared with all organization repositories, including both already-existing repositories as well as newly created ones. Organization-wide labels can be created in the organization `Settings`.

![organization labels management](../_images/user/labels/organization-labels-management.png)

## Creating Labels

From the labels management page, click on the `New Label` button.

![create a label](../_images/user/labels/label-new.png)

Labels have a mandatory name, a mandatory color, an optional description, and must either be exclusive or not (see [Scoped Labels](#scoped-labels) below).

When you create a repository (or an organization), you can ensure certain labels exist by using the `Issue Labels` option. This option lists a number of available label sets that are configured globally on your instance.

## Archiving Labels

When a label is no longer useful but needs to be kept around because
it is still associated with existing pull requests or issues, it can be archived.

- The label won't show up as a suggestion when you're adding/editing labels.
- The label cannot be assigned to new issues or pull requests.

To archive a label, edit the label and click the `Archive` checkbox.

![archive a label](../_images/user/labels/label-archive.png)

## Scoped Labels

Scoped labels are used to ensure at most a single label with the same scope is assigned to an issue or pull request. For example, if labels `kind/bug` and `kind/enhancement` have the Exclusive option set, an issue can only be classified as a bug or an enhancement.

![list of labels](../_images/user/labels/label-list.png)

A scoped label must contain `/` in its name (not at either end of the name). The scope of a label is determined based on the **last** `/`, so for example the scope of label `scope/subscope/item` is `scope/subscope`.

## Applying Labels

Labels can be applied to issues or pull requests on their pages by clicking on `Labels`. In the dropdown menu, labels can be added or removed. Of a set of scoped labels with the same scope, only one can be selected. Archived labels are disabled for addition.

![apply labels](../_images/user/labels/label-apply.png)

## Filtering by Label

Issue and pull request lists can be filtered by label. Selecting multiple labels shows issues and pull requests that have all selected labels assigned.

By holding alt and clicking the label, issues and pull requests with the chosen label are excluded from the list.
File: docs\user\profile.md

---
title: 'Profile customization'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/e865de1e9d65dc09797d165a51c8e705d2a86030/docs/content/usage/profile-readme.en-us.md'
---

By default, the profile page of a user (or an organization) is the list of repositories they
own. It is possible to customize it with a short description that
shows to the left, under their avatar. It can now be fully
personalized with a markdown file that is displayed instead of the
list of repositories.

![Profile page](../_images/user/profile/profile-step1.png)

It uses the `README.md` file from the `.profile` repository of the
user (or organization), if it exists.

Forked `.profile` repositories do not display profile content - only regular
`.profile` repositories (not forks) will be used to populate the profile page.
If you want to use content from a forked `.profile` repository, convert the
fork to a regular repository in the "Danger Zone" section of repository
settings.

![Profile README.md](../_images/user/profile/profile-step2.png)

Making the `.profile` repository private will hide the Profile README.

Rather than supporting multiple social links on the profile card, under the user
avatar, such links - including
[`rel=me`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/me)
attributes - can be placed in the `.profile` README instead. This gives a user a
lot of flexibility on how they wish to display these links. To add a `rel=me`
attribute, the link should be written in HTML, rather than in Markdown format,
for example: `<a rel="me"
href="https://social.example.com/@username">Fediverse</a>`.
File: docs\user\project.md

---
title: 'Projects'
license: 'CC-BY-SA-4.0'
---

A project is a [kanban board](<https://en.wikipedia.org/wiki/Kanban_(development)>) to organize issues.

![screenshot of the project page](../_images/user/project/project.png)

## Card previews images

If the card preview in the project is set to **Images and Text**, the card preview displays images found in the corresponding issue. The most recent is displayed first, up to five images.

![example of card image preview](../_images/user/project/project-image.png)
File: docs\user\push-to-create.md

---
title: 'Push Options'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/e865de1e9d65dc09797d165a51c8e705d2a86030/docs/content/usage/push.en-us.md'
---

## Push To Create

Push to create is a feature that allows you to push to a repository that does not yet exist in Forgejo. This is useful for automation and for allowing users to create repositories without having to go through the web interface. This feature is disabled by default.

### Enabling Push To Create

In the `app.ini` file, under the section `[repository]`, set `ENABLE_PUSH_CREATE_USER` to `true` and `ENABLE_PUSH_CREATE_ORG` to `true` if you want to allow users to create repositories in their own user account and in organizations they are members of, respectively. Restart Forgejo for the changes to take effect. You can read more about these two options in the Configuration Cheat Sheet.

### Using Push To Create

Assuming you have a git repository in the current directory, you can push to a repository that does not yet exist in Forgejo by running the following command:

```shell
# Add the remote you want to push to
git remote add origin git@{domain}:{username}/{repo name that does not exist yet}.git

# push to the remote
git push -u origin main
```

This assumes you are using an SSH remote, but you can also use HTTPS remotes as well.

### Push options

Push-to-create will default to the visibility defined by `DEFAULT_PUSH_CREATE_PRIVATE` in `app.ini`. To explicitly set the visibility, there is support for some [push options](https://git-scm.com/docs/git-push#Documentation/git-push.txt--oltoptiongt).

- `repo.private` (true|false) - Change the repository's visibility.

  This is particularly useful when combined with push-to-create.

- `repo.template` (true|false) - Change whether the repository is a template.

Example of changing a repository's visibility to public:

```shell
git push -o repo.private=false -u origin main
```
File: docs\user\readme-badges.md

---
title: README badges
license: 'CC-BY-SA-4.0'
---

If the [badges service](../../admin/config-cheat-sheet/#badges-badges) is enabled, Forgejo makes it possible to add badges - transparently generated by a service like `shields.io` - to your READMEs and other documentation. These badges let you display useful information about your repository within documentation that might also be displayed elsewhere, outside of the forge itself (such as on container information pages, library documentation sites, and so on). Information such as the latest release, stars, pull request and issue information, or [Actions workflow](../actions/) statuses.

The badges are returned in SVG format and are available under the `https://forgejo.example.com/{username}/{repository}/badges` path. Forgejo currently supports generating the following badges:

- `/release.svg`: The latest release made in the repository.
- `/stars.svg`: The number of stars the repository has.
- `/issues.svg`: The total number of issues in the repository, open and closed combined.
- `/issues/open.svg`: The number of open issues.
- `/issues/closed.svg`: The number of closed issues.
- `/pulls.svg`: The number of pull requests against the repository, open and closed combined.
- `/pulls/open.svg`: The number of open pull requests.
- `/pulls/closed.svg`: The number of closed pull requests.
- `/workflows/{workflow_file}/badge.svg`: The status of the `{workflow_file}` workflow. Additional restrictions can be given for this badge by using the `branch` and/or `event` query parameters. The `branch` query parameter will display the status of the workflow from the given branch (defaulting to the repository's main branch if not explicitly specified), while the `event` parameter will only display results if a run was triggered by the specified event.

All query parameters not known to Forgejo will be passed along to the badge generator service as is. If using the default - `shields.io`-based - generator, this means that query parameters such as `style` and `color` will be respected.
File: docs\user\repository-activity.md

---
title: Repository Activity
license: 'CC-BY-SA-4.0'
---

For each repository, the Activity tab displays insights about the recent changes. It helps figure out how lively it is and which contributors are the most active at a given moment in time.

## Contributors

![screenshot showing the contributors graph](../_images/user/repository-activity/contributors.png)

The overall graph shows all commits over time and allows you to select a range of dates to get a more detailed view. The contributors are also displayed with their individual graphs. The contributor with the most commits is shown first.

## Pulse

![screenshot showing the pulse graph](../_images/user/repository-activity/pulse.png)

A high-level view of the most recent commits and pull requests.

## Code frequency

![screenshot showing the code frequency graph](../_images/user/repository-activity/code-frequency.png)

Shows the ratio of added and deleted lines over time.

## Recent commits

![screenshot showing the recent commits graph](../_images/user/repository-activity/recent-commits.png)

The total number of commits over time.
File: docs\admin\advanced\adopt.md

---
title: 'Adopt existing git directories'
license: 'CC-BY-SA-4.0'
---

If directories containing bare git repositories exist in the
`[repository].ROOT` hierarchy, they can be imported using the admin
panel.

- Make sure the directory names are lowercase.
- `[repository].ROOT/{user,org}/{repo}.git` will become a project owned by the user or the org.
- Go to `/admin/repos/unadopted`
- In trusted environments, users can also be given similar permissions via the [`ALLOW_ADOPTION_OF_UNADOPTED_REPOSITORIES`](../../config-cheat-sheet/#repository-repository) setting.
File: docs\admin\advanced\customization.md

---
title: 'Interface customization'
license: 'CC-BY-SA-4.0'
---

Forgejo currently has limited capabilities for customizing the user interface.

## Configurations and UI settings

Some settings are provided to customize the look and feel of the Forgejo user interface.

This includes the default theme, the name of your Forgejo instance, as well as the description that appears in Forgejo's homepage. A complete list of those settings can be found in the config cheat sheet:

- In the [UI section](../../config-cheat-sheet/#ui-ui) and below.
- The `APP_NAME` setting in the [Overall section](../../config-cheat-sheet/#overall-default).

They are documented and supported to be backward compatible between versions.

## Serving custom resources, logos and pages

### A word of warning (Here be dragons!)

Setting a custom logo for your instance, serving custom public files or modifying pages shown by Forgejo (such as the homepage) is possible. However, they impose an additional maintenance burden on administrators and, most importantly, **are unsupported**.

**Unsupported** means that future updates **are likely to break** your changes **without any warning**.

#### Templates

The most dangerous types of modifications are the ones concerning **template files** (`.tmpl`) served by Forgejo, as Forgejo issues backward incompatible updates to its templates very regularly.

Before deploying your changes to production or upgrading a modified Forgejo instance, we urge that you test your custom modifications in a testing environment first.

### Instructions

For the reasons mentioned above, the instructions on performing such tasks can be found in the [developer section on interface customization](../../../contributor/customization/).

At this stage, it is also worth mentioning that it is possible to customize Forgejo by [modifying its source code and compiling the changes](../../../contributor/from-source), or by extracting and modifying the files of your choice using the command `forgejo embedded extract`. However, these methods are, for the same reasons as mentioned above, also **unsupported**.
File: docs\admin\advanced\incoming-email.md

---
title: 'Incoming Email'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/e865de1e9d65dc09797d165a51c8e705d2a86030/docs/content/usage/incoming-email.en-us.md'
---

Forgejo supports the execution of several actions through incoming mails. This page describes how to set this up.

## Requirements

Handling incoming email messages requires an IMAP-enabled email account.
The recommended strategy is to use [email sub-addressing](https://en.wikipedia.org/wiki/Email_address#Sub-addressing) but a catch-all mailbox does work too.
The receiving email address contains a user/action specific token which tells Forgejo which action should be performed.
This token is expected in the `To` and `Delivered-To` header fields.

Forgejo tries to detect automatic responses to skip and the email server should be configured to reduce the incoming noise too (spam, newsletter).

## Configuration

To activate the handling of incoming email messages you have to configure the `email.incoming` section in the configuration file.

The `REPLY_TO_ADDRESS` contains the address an email client will respond to.
This address needs to contain the `%{token}` placeholder which will be replaced with a token describing the user/action.
This placeholder must only appear once in the address and must be in the user part of the address (before the `@`).

An example using email sub-addressing may look like this: `incoming+%{token}@example.com`

If a catch-all mailbox is used, the placeholder may be used anywhere in the user part of the address, for example:

- `incoming+%{token}@example.com`
- `incoming_%{token}@example.com`
- `%{token}@example.com`
File: docs\admin\advanced\oauth2-provider.md

---
title: 'OAuth2 provider'
license: 'CC-BY-SA-4.0'
---

## Pre-registered applications

The following OAuth2 applications are pre-registered because it is generally useful for Forgejo to be an OAuth2 provider for the corresponding third party software. Their usage is explained in the [Forgejo user guide](../../../user/oauth2-provider/).

- **git-credential-manager** is the name of the OAuth2 application for the [Git Credential Manager](https://github.com/git-ecosystem/git-credential-manager) (a Git [credential helper](https://git-scm.com/docs/gitcredentials#_custom_helpers))
- **git-credential-oauth** is the name of the OAuth2 application for the [git-credential-oauth](https://github.com/hickford/git-credential-oauth) (a Git [credential helper](https://git-scm.com/docs/gitcredentials#_custom_helpers))

All pre-registered applications are activated by default in the [`[oauth2].DEFAULT_APPLICATIONS`](../../config-cheat-sheet/#oauth2-oauth2) setting as displayed in the `/admin/applications` page.

![pre-registered Git credential applications](../../_images/admin/oauth2-provider/oauth-git-credential-server.png)
File: docs\admin\advanced\search-engines.md

---
title: 'Search Engines Indexation'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/e865de1e9d65dc09797d165a51c8e705d2a86030/docs/content/administration/search-engines-indexation.en-us.md'
---

## Search engines indexation of your Forgejo installation

By default, your Forgejo installation will be indexed by search engines.
If you don't want your repository to be visible for search engines read further.

### Block search engines indexation using robots.txt

To make Forgejo serve a custom `robots.txt` (default: empty 404) for top level installations,
create a file with path `public/robots.txt` at the root of the `Custom File Root Path` as displayed in the `/admin/config` page.

Examples on how to configure the `robots.txt` can be found at [https://moz.com/learn/seo/robotstxt](https://moz.com/learn/seo/robotstxt).

```txt
User-agent: *
Disallow: /
```

If you installed Forgejo in a subdirectory, you will need to create or edit the `robots.txt` in the top level directory.

```txt
User-agent: *
Disallow: /forgejo/
```

### Disallow crawling archives to save disk space

If the archive files are crawled, they will be generated dynamically
and kept around which can amount to a lot of disk. To prevent that
from happening, add the following to the `robots.txt` file:

```txt
User-agent: *
Disallow: /*/*/archive/
```

See also a more complete example [at Codeberg](https://codeberg.org/robots.txt).
File: docs\admin\installation\index.md

---
title: 'Installation'
license: 'CC-BY-SA-4.0'
---

Forgejo publishes a stable release every three months and a long term support
(LTS) release every year. Patch releases are published more frequently and
provide fixes for bugs and security vulnerabilities. Please review the
[releases management](../../contributor/release) and
also the
[Forgejo versioning scheme](../../user/versions) documentation for further
information.

Get started in a few simple steps:

1. Set up Forgejo on your system ...
   - [from binary](./binary/)
   - [with Docker](./docker/)
   - with third-party packaging for various platforms [(see the "Delightful Forgejo" list)](https://codeberg.org/forgejo-contrib/delightful-forgejo#packaging). Unlike the two official installation methods, these resources are not extensively tested to work on every release.
2. Connect to the web interface and complete the configuration, and,
3. register the first user which will be granted administrative permissions.

If you already have Gitea installed through your package manager, look at the [Gitea
migration](../upgrade/from-gitea/) guide for information on how to install Forgejo, while
preserving your data from your Gitea installation.
File: docs\admin\setup\email.md

---
title: 'Email setup'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/e865de1e9d65dc09797d165a51c8e705d2a86030/docs/content/administration/email-setup.en-us.md'
---

Forgejo can be set to send emails such as a registration confirmation, either with [Sendmail](https://man7.org/linux/man-pages/man8/sendmail.8.html) (or compatible MTAs like Postfix and msmtp) or by connecting to an SMTP server.

## Using SMTP

Directly use SMTP server as relay. This option is useful if you don't want to set up MTA on your instance but you have an account at an email provider.

```ini
[mailer]
ENABLED        = true
FROM           = forgejo@example.com
PROTOCOL       = smtps
SMTP_ADDR      = mail.example.com
SMTP_PORT      = 465
USER           = forgejo@example.com
PASSWD         = `mysecurepassword`
```

Restart Forgejo for the configuration changes to take effect.

To send a test email to validate the settings, go to Forgejo > Site Administration > Configuration > SMTP Mailer Configuration.

To enable users to receive email notifications for pull requests or issues, you can set `ENABLE_NOTIFY_MAIL=true` in the configuration.

For the full list of options check the [Config Cheat Sheet](../../config-cheat-sheet/#mailer-mailer).

> **NOTE:** authentication is only supported when the SMTP server communication is encrypted with TLS or `HOST=localhost`. This is due to protections imposed by the Go internal libraries against STRIPTLS attacks. TLS encryption can be through:

- STARTTLS (also known as Opportunistic TLS) via port 587. Initial connection is done over cleartext, but then be upgraded over TLS if the server supports it.
- SMTPS connection (SMTP over TLS) via `SMTP_PORT=465` and/or `PROTOCOL=smtps`. Connections to the server use TLS from the beginning, also known as Implicit TLS. It is recommended by [RFC8314](https://tools.ietf.org/html/rfc8314#section-3).

## Using Sendmail

Use `sendmail` command as mailer.

> **NOTE:** For Internet-facing sites consult the documentation of your MTA for instructions to send emails over TLS. Also set up SPF, DMARC, and DKIM DNS records to make emails sent be accepted as legitimate by various email providers.

```ini
[mailer]
ENABLED       = true
FROM          = forgejo@example.com
PROTOCOL      = sendmail
SENDMAIL_PATH = /usr/sbin/sendmail
SENDMAIL_ARGS = "--" ; most "sendmail" programs take options, "--" will prevent an email address being interpreted as an option.
```
File: docs\admin\troubleshooting\seek-assistance.md

---
title: 'Seek Assistance'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/e865de1e9d65dc09797d165a51c8e705d2a86030/docs/content/help/support.en-us.md'
---

- [Chatroom](https://matrix.to/#/#forgejo-chat:matrix.org)
- [Issue tracker](https://codeberg.org/forgejo/forgejo/issues)

**NOTE:** When asking for support, it may be a good idea to have the following available so that the person helping has all the info they need:

1. Your `app.ini` (with any sensitive data scrubbed as necessary).
2. The Forgejo logs, and any other appropriate log files for the situation.
   - When using systemd, use `journalctl --lines 1000 --unit forgejo` to collect logs.
   - When using docker, use `docker logs --tail 1000 <forgejo-container>` to collect logs.
   - By default, the logs are outputted to console. If you need to collect logs from files,
     you could copy the following config into your `app.ini` (remove all other `[log]` sections),
     then you can find the `*.log` files in Forgejo's log directory (default: `%(FORGEJO_WORK_DIR)/log`).

   ```ini
   ; To show all SQL logs, you can also set LOG_SQL=true in the [database] section
   [log]
   LEVEL=debug
   MODE=console,file
   ROUTER=console,file
   XORM=console,file
   ENABLE_XORM_LOG=true
   FILE_NAME=forgejo.log
   [log.file.router]
   FILE_NAME=router.log
   [log.file.xorm]
   FILE_NAME=xorm.log
   ```

3. Any error messages you are seeing.
4. If you meet slow/hanging/deadlock problems, please report the stack trace when the problem occurs:
   1. Enable pprof in `app.ini` and restart Forgejo.

      ```ini
      [server]
      ENABLE_PPROF = true
      ```

   2. Trigger the bug, and when Forgejo gets stuck, use curl or browser to visit: `http://127.0.0.1:6060/debug/pprof/goroutine?debug=1` (IP must be `127.0.0.1` and port must be `6060`).
   3. If you are using Docker, please use `docker exec -it <container-name> curl "http://127.0.0.1:6060/debug/pprof/goroutine?debug=1"`.
   4. Report the output (the stack trace doesn't contain sensitive data).