foster/forgejo-docs
0
0
Fork 0
mirror of https://codeberg.org/forgejo/docs.git synced 2024-11-24 18:09:26 -05:00
Code Issues Activity

Run prettier (#196)

Browse source 
- Format according to prettier.

Co-authored-by: Gusted <postmaster@gusted.xyz>
Reviewed-on: https://codeberg.org/forgejo/website/pulls/196
Reviewed-by: Loïc Dachary <dachary@noreply.codeberg.org>

# Conflicts:
#	v1.19/index.md
#	v1.19/user/project.md
#	v1.19/user/protection.md
#	v1.19/user/wiki.md
#	v1.20/admin/config-cheat-sheet.md
#	v1.20/admin/database-preparation.md
#	v1.20/developer/code-forgejo-org.md
#	v1.20/license.md
#	v1.20/user/api-usage.md
#	v1.20/user/authentication.md
#	v1.20/user/email-settings.md
#	v1.20/user/issue-pull-request-templates.md
#	v1.20/user/oauth2-provider.md
#	v1.20/user/packages/index.md
#	v1.20/user/packages/maven.md
#	v1.20/user/semver.md
This commit is contained in:
Gusted 2023-03-31 20:57:57 +00:00 committed by Caesar Schinas
parent 1d88a5c1a7
commit 04488991b1
No known key found for this signature in database
GPG key ID: AE9108461BEA5ACF
16 changed files with 302 additions and 293 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
admin/config-cheat-sheet.md
View file

@ -866,9 +866,9 @@ Default templates for project boards:
- You must be very careful to ensure that this template does not throw errors or panics as this template runs outside of the panic/recovery script.
- `REQUEST_ID_HEADERS`: **\<empty\>**: You can configure multiple values that are splited by comma here. It will match in the order of configuration, and the first match will be finally printed in the access log.
- e.g.
- In the Request Header: X-Request-ID: **test-id-123**
- Configuration in app.ini: REQUEST_ID_HEADERS = X-Request-ID
- Print in log: 127.0.0.1:58384 - - [14/Feb/2023:16:33:51 +0800] "**test-id-123**" ...
- In the Request Header: X-Request-ID: **test-id-123**
- Configuration in app.ini: REQUEST_ID_HEADERS = X-Request-ID
- Print in log: 127.0.0.1:58384 - - [14/Feb/2023:16:33:51 +0800] "**test-id-123**" ...
### Log subsections (`log.name`, `log.name.*`)

274
admin/database-preparation.md
View file

@ -15,149 +15,149 @@ Note: All steps below requires that the database engine of your choice is instal
1. For remote database setup, you will need to make MySQL listen to your IP address. Edit `bind-address` option on `/etc/mysql/my.cnf` on database instance to:
```ini
bind-address = 203.0.113.3
```
```ini
bind-address = 203.0.113.3
```
2. On database instance, login to database console as root:
```
mysql -u root -p
```
```
mysql -u root -p
```
Enter the password as prompted.
Enter the password as prompted.
3. Create database user which will be used by Forgejo, authenticated by password. This example uses `'forgejo'` as password. Please use a secure password for your instance.
For local database:
For local database:
```sql
SET old_passwords=0;
CREATE USER 'forgejo' IDENTIFIED BY 'forgejo';
```
```sql
SET old_passwords=0;
CREATE USER 'forgejo' IDENTIFIED BY 'forgejo';
```
For remote database:
For remote database:
```sql
SET old_passwords=0;
CREATE USER 'forgejo'@'192.0.2.10' IDENTIFIED BY 'forgejo';
```
```sql
SET old_passwords=0;
CREATE USER 'forgejo'@'192.0.2.10' IDENTIFIED BY 'forgejo';
```
where `192.0.2.10` is the IP address of your Forgejo instance.
where `192.0.2.10` is the IP address of your Forgejo instance.
Replace username and password above as appropriate.
Replace username and password above as appropriate.
4. Create database with UTF-8 charset and collation. Make sure to use `utf8mb4` charset instead of `utf8` as the former supports all Unicode characters (including emojis) beyond _Basic Multilingual Plane_. Also, collation chosen depending on your expected content. When in doubt, use either `unicode_ci` or `general_ci`.
```sql
CREATE DATABASE forgejodb CHARACTER SET 'utf8mb4' COLLATE 'utf8mb4_unicode_ci';
```
```sql
CREATE DATABASE forgejodb CHARACTER SET 'utf8mb4' COLLATE 'utf8mb4_unicode_ci';
```
Replace database name as appropriate.
Replace database name as appropriate.
5. Grant all privileges on the database to database user created above.
For local database:
For local database:
```sql
GRANT ALL PRIVILEGES ON forgejodb.* TO 'forgejo';
FLUSH PRIVILEGES;
```
```sql
GRANT ALL PRIVILEGES ON forgejodb.* TO 'forgejo';
FLUSH PRIVILEGES;
```
For remote database:
For remote database:
```sql
GRANT ALL PRIVILEGES ON forgejodb.* TO 'forgejo'@'192.0.2.10';
FLUSH PRIVILEGES;
```
```sql
GRANT ALL PRIVILEGES ON forgejodb.* TO 'forgejo'@'192.0.2.10';
FLUSH PRIVILEGES;
```
6. Quit from database console by `exit`.
7. On your Forgejo server, test connection to the database:
```
mysql -u forgejo -h 203.0.113.3 -p forgejodb
```
```
mysql -u forgejo -h 203.0.113.3 -p forgejodb
```
where `forgejo` is database username, `forgejodb` is database name, and `203.0.113.3` is IP address of database instance. Omit `-h` option for local database.
where `forgejo` is database username, `forgejodb` is database name, and `203.0.113.3` is IP address of database instance. Omit `-h` option for local database.
You should be connected to the database.
You should be connected to the database.
## PostgreSQL
1. For remote database setup, configure PostgreSQL on database instance to listen to your IP address by editing `listen_addresses` on `postgresql.conf` to:
```ini
listen_addresses = 'localhost, 203.0.113.3'
```
```ini
listen_addresses = 'localhost, 203.0.113.3'
```
2. PostgreSQL uses `md5` challenge-response encryption scheme for password authentication by default. Nowadays this scheme is not considered secure anymore. Use SCRAM-SHA-256 scheme instead by editing the `postgresql.conf` configuration file on the database server to:
```ini
password_encryption = scram-sha-256
```
```ini
password_encryption = scram-sha-256
```
Restart PostgreSQL to apply the setting.
Restart PostgreSQL to apply the setting.
3. On the database server, login to the database console as superuser:
```
su -c "psql" - postgres
```
```
su -c "psql" - postgres
```
4. Create database user (role in PostgreSQL terms) with login privilege and password. Please use a secure, strong password instead of `'forgejo'` below:
```sql
CREATE ROLE forgejo WITH LOGIN PASSWORD 'forgejo';
```
```sql
CREATE ROLE forgejo WITH LOGIN PASSWORD 'forgejo';
```
Replace username and password as appropriate.
Replace username and password as appropriate.
5. Create database with UTF-8 charset and owned by the database user created earlier. Any `libc` collations can be specified with `LC_COLLATE` and `LC_CTYPE` parameter, depending on expected content:
```sql
CREATE DATABASE forgejodb WITH OWNER forgejo TEMPLATE template0 ENCODING UTF8 LC_COLLATE 'en_US.UTF-8' LC_CTYPE 'en_US.UTF-8';
```
```sql
CREATE DATABASE forgejodb WITH OWNER forgejo TEMPLATE template0 ENCODING UTF8 LC_COLLATE 'en_US.UTF-8' LC_CTYPE 'en_US.UTF-8';
```
Replace database name as appropriate.
Replace database name as appropriate.
6. Allow the database user to access the database created above by adding the following authentication rule to `pg_hba.conf`.
For local database:
For local database:
```ini
local forgejodb forgejo scram-sha-256
```
```ini
local forgejodb forgejo scram-sha-256
```
For remote database:
For remote database:
```ini
host forgejodb forgejo 192.0.2.10/32 scram-sha-256
```
```ini
host forgejodb forgejo 192.0.2.10/32 scram-sha-256
```
Replace database name, user, and IP address of Forgejo instance with your own.
Replace database name, user, and IP address of Forgejo instance with your own.
Note: rules on `pg_hba.conf` are evaluated sequentially, that is the first matching rule will be used for authentication. Your PostgreSQL installation may come with generic authentication rules that match all users and databases. You may need to place the rules presented here above such generic rules if it is the case.
Note: rules on `pg_hba.conf` are evaluated sequentially, that is the first matching rule will be used for authentication. Your PostgreSQL installation may come with generic authentication rules that match all users and databases. You may need to place the rules presented here above such generic rules if it is the case.
Restart PostgreSQL to apply new authentication rules.
Restart PostgreSQL to apply new authentication rules.
7. On your Forgejo server, test connection to the database.
For local database:
For local database:
```
psql -U forgejo -d forgejodb
```
```
psql -U forgejo -d forgejodb
```
For remote database:
For remote database:
```
psql "postgres://forgejo@203.0.113.3/forgejodb"
```
```
psql "postgres://forgejo@203.0.113.3/forgejodb"
```
where `forgejo` is database user, `forgejodb` is database name, and `203.0.113.3` is IP address of your database instance.
where `forgejo` is database user, `forgejodb` is database name, and `203.0.113.3` is IP address of your database instance.
You should be prompted to enter password for the database user, and connected to the database.
You should be prompted to enter password for the database user, and connected to the database.
## Database Connection over TLS
@ -176,67 +176,67 @@ The PostgreSQL driver used by Forgejo supports two-way TLS. In two-way TLS, both
1. On the server with the database instance, place the following credentials:
- `/path/to/postgresql.crt`: Database instance certificate
- `/path/to/postgresql.key`: Database instance private key
- `/path/to/root.crt`: CA certificate chain to validate client certificates
- `/path/to/postgresql.crt`: Database instance certificate
- `/path/to/postgresql.key`: Database instance private key
- `/path/to/root.crt`: CA certificate chain to validate client certificates
2. Add following options to `postgresql.conf`:
```ini
ssl = on
ssl_ca_file = '/path/to/root.crt'
ssl_cert_file = '/path/to/postgresql.crt'
ssl_key_file = '/path/to/postgresql.key'
ssl_min_protocol_version = 'TLSv1.2'
```
```ini
ssl = on
ssl_ca_file = '/path/to/root.crt'
ssl_cert_file = '/path/to/postgresql.crt'
ssl_key_file = '/path/to/postgresql.key'
ssl_min_protocol_version = 'TLSv1.2'
```
3. Adjust credentials ownership and permission, as required by PostgreSQL:
```
chown postgres:postgres /path/to/root.crt /path/to/postgresql.crt /path/to/postgresql.key
chmod 0600 /path/to/root.crt /path/to/postgresql.crt /path/to/postgresql.key
```
```
chown postgres:postgres /path/to/root.crt /path/to/postgresql.crt /path/to/postgresql.key
chmod 0600 /path/to/root.crt /path/to/postgresql.crt /path/to/postgresql.key
```
4. Edit `pg_hba.conf` rule to only allow Forgejo database user to connect over SSL, and to require client certificate verification.
For PostgreSQL 12:
For PostgreSQL 12:
```ini
hostssl forgejodb forgejo 192.0.2.10/32 scram-sha-256 clientcert=verify-full
```
```ini
hostssl forgejodb forgejo 192.0.2.10/32 scram-sha-256 clientcert=verify-full
```
For PostgreSQL 11 and earlier:
For PostgreSQL 11 and earlier:
```ini
hostssl forgejodb forgejo 192.0.2.10/32 scram-sha-256 clientcert=1
```
```ini
hostssl forgejodb forgejo 192.0.2.10/32 scram-sha-256 clientcert=1
```
Replace database name, user, and IP address of Forgejo instance as appropriate.
Replace database name, user, and IP address of Forgejo instance as appropriate.
5. Restart PostgreSQL to apply configurations above.
6. On the server running the Forgejo instance, place the following credentials under the home directory of the user who runs Forgejo (e.g. `git`):
- `~/.postgresql/postgresql.crt`: Database client certificate
- `~/.postgresql/postgresql.key`: Database client private key
- `~/.postgresql/root.crt`: CA certificate chain to validate server certificate
- `~/.postgresql/postgresql.crt`: Database client certificate
- `~/.postgresql/postgresql.key`: Database client private key
- `~/.postgresql/root.crt`: CA certificate chain to validate server certificate
Note: Those file names above are hardcoded in PostgreSQL and it is not possible to change them.
Note: Those file names above are hardcoded in PostgreSQL and it is not possible to change them.
7. Adjust credentials, ownership and permission as required:
```
chown git:git ~/.postgresql/postgresql.crt ~/.postgresql/postgresql.key ~/.postgresql/root.crt
chown 0600 ~/.postgresql/postgresql.crt ~/.postgresql/postgresql.key ~/.postgresql/root.crt
```
```
chown git:git ~/.postgresql/postgresql.crt ~/.postgresql/postgresql.key ~/.postgresql/root.crt
chown 0600 ~/.postgresql/postgresql.crt ~/.postgresql/postgresql.key ~/.postgresql/root.crt
```
8. Test the connection to the database:
```
psql "postgres://forgejo@example.db/forgejodb?sslmode=verify-full"
```
```
psql "postgres://forgejo@example.db/forgejodb?sslmode=verify-full"
```
You should be prompted to enter password for the database user, and then be connected to the database.
You should be prompted to enter password for the database user, and then be connected to the database.
### MySQL
@ -246,46 +246,46 @@ In one-way TLS, the database client verifies the certificate sent from server du
1. On the database instance, place the following credentials:
- `/path/to/mysql.crt`: Database instance certificate
- `/path/to/mysql.key`: Database instance key
- `/path/to/ca.crt`: CA certificate chain. This file isn't used on one-way TLS, but is used to validate client certificates on two-way TLS.
- `/path/to/mysql.crt`: Database instance certificate
- `/path/to/mysql.key`: Database instance key
- `/path/to/ca.crt`: CA certificate chain. This file isn't used on one-way TLS, but is used to validate client certificates on two-way TLS.
2. Add following options to `my.cnf`:
```ini
[mysqld]
ssl-ca = /path/to/ca.crt
ssl-cert = /path/to/mysql.crt
ssl-key = /path/to/mysql.key
tls-version = TLSv1.2,TLSv1.3
```
```ini
[mysqld]
ssl-ca = /path/to/ca.crt
ssl-cert = /path/to/mysql.crt
ssl-key = /path/to/mysql.key
tls-version = TLSv1.2,TLSv1.3
```
3. Adjust credentials ownership and permission:
```
chown mysql:mysql /path/to/ca.crt /path/to/mysql.crt /path/to/mysql.key
chmod 0600 /path/to/ca.crt /path/to/mysql.crt /path/to/mysql.key
```
```
chown mysql:mysql /path/to/ca.crt /path/to/mysql.crt /path/to/mysql.key
chmod 0600 /path/to/ca.crt /path/to/mysql.crt /path/to/mysql.key
```
4. Restart MySQL to apply the setting.
5. The database user for Forgejo may have been created earlier, but it would authenticate only against the IP addresses of the server running Forgejo. To authenticate against its domain name, recreate the user, and this time also set it to require TLS for connecting to the database:
```sql
DROP USER 'forgejo'@'192.0.2.10';
CREATE USER 'forgejo'@'example.forgejo' IDENTIFIED BY 'forgejo' REQUIRE SSL;
GRANT ALL PRIVILEGES ON forgejodb.* TO 'forgejo'@'example.forgejo';
FLUSH PRIVILEGES;
```
```sql
DROP USER 'forgejo'@'192.0.2.10';
CREATE USER 'forgejo'@'example.forgejo' IDENTIFIED BY 'forgejo' REQUIRE SSL;
GRANT ALL PRIVILEGES ON forgejodb.* TO 'forgejo'@'example.forgejo';
FLUSH PRIVILEGES;
```
Replace database user name, password, and Forgejo instance domain as appropriate.
Replace database user name, password, and Forgejo instance domain as appropriate.
6. Make sure that the CA certificate chain required to validate the database server certificate is on the system certificate store of both the database and Forgejo servers. Consult your system documentation for instructions on adding a CA certificate to the certificate store.
7. On the server running Forgejo, test connection to the database:
```
mysql -u forgejo -h example.db -p --ssl
```
```
mysql -u forgejo -h example.db -p --ssl
```
You should be connected to the database.
You should be connected to the database.

14
developer/code-forgejo-org.md
View file

@ -7,16 +7,16 @@ license: 'CC-BY-SA-4.0'
https://code.forgejo.org is a Forgejo instance running the latest stable
version. It is dedicated to hosting the following repositories:
* Default Forgejo Runner actions https://code.forgejo.org/actions
* Forgejo Runner https://code.forgejo.org/forgejo/runner
* [ACT](https://github.com/nektos/act) soft fork https://code.forgejo.org/forgejo/act
* [Infrastructure as code](https://enough-community.readthedocs.io) used to deploy code.forgejo.org https://code.forgejo.org/forgejo/infrastructure
* [Infrastructure as code](https://enough-community.readthedocs.io) secrets in a private repository
- Default Forgejo Runner actions https://code.forgejo.org/actions
- Forgejo Runner https://code.forgejo.org/forgejo/runner
- [ACT](https://github.com/nektos/act) soft fork https://code.forgejo.org/forgejo/act
- [Infrastructure as code](https://enough-community.readthedocs.io) used to deploy code.forgejo.org https://code.forgejo.org/forgejo/infrastructure
- [Infrastructure as code](https://enough-community.readthedocs.io) secrets in a private repository
To make these repositories easier to find, the following push mirrors are in place:
* https://code.forgejo.org/forgejo/runner => https://codeberg.org/forgejo/runner
* https://code.forgejo.org/forgejo/act => https://codeberg.org/forgejo/act
- https://code.forgejo.org/forgejo/runner => https://codeberg.org/forgejo/runner
- https://code.forgejo.org/forgejo/act => https://codeberg.org/forgejo/act
## Infrastructure

14
index.md
View file

@ -3,10 +3,10 @@ layout: '~/layouts/Markdown.astro'
title: 'Forgejo v1.20 documentation'
---
* [What is Forgejo?](https://forgejo.org/)
* [Installation](https://forgejo.org/download/)
* [FAQ](https://forgejo.org/faq/)
* [Administrator guide](admin)
* [User guide](user)
* [Developer guide](developer)
* [License](license)
- [What is Forgejo?](https://forgejo.org/)
- [Installation](https://forgejo.org/download/)
- [FAQ](https://forgejo.org/faq/)
- [Administrator guide](admin)
- [User guide](user)
- [Developer guide](developer)
- [License](license)

2
license.md
View file

@ -1,6 +1,6 @@
---
layout: '~/layouts/Markdown.astro'
title: "License"
title: 'License'
---
This documentation is licensed under [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/deed.en).

4
user/api-usage.md
View file

@ -31,8 +31,8 @@ $ curl -H "Content-Type: application/json" -d '{"name":"test"}' -u username:pass
{"id":1,"name":"test","sha1":"9fcb1158165773dd010fca5f0cf7174316c3e37d","token_last_eight":"16c3e37d"}
```
The ``sha1`` (the token) is only returned once and is not stored in
plain-text. It will not be displayed when listing tokens with a `GET`
The `sha1` (the token) is only returned once and is not stored in
plain-text. It will not be displayed when listing tokens with a `GET`
request; e.g.
```sh

51
user/authentication.md
View file

@ -154,47 +154,50 @@ Uses the following fields:
## PAM (Pluggable Authentication Module)
This procedure enables PAM authentication. Users may still be added to the
system manually using the user administration. PAM provides a mechanism to
This procedure enables PAM authentication. Users may still be added to the
system manually using the user administration. PAM provides a mechanism to
automatically add users to the current database by testing them against PAM
authentication. To work with normal Linux passwords, the user running Forgejo
authentication. To work with normal Linux passwords, the user running Forgejo
must also have read access to `/etc/shadow` in order to check the validity of
the account when logging in using a public key.
**Note**: If a user has added SSH public keys into Forgejo, the use of these
keys _may_ bypass the login check system. Therefore, if you wish to disable a user who
keys _may_ bypass the login check system. Therefore, if you wish to disable a user who
authenticates with PAM, you _should_ also manually disable the account in Forgejo using the
built-in user manager.
1. Configure and prepare the installation.
- It is recommended that you create an administrative user.
- Deselecting automatic sign-up may also be desired.
- It is recommended that you create an administrative user.
- Deselecting automatic sign-up may also be desired.
1. Once the database has been initialized, log in as the newly created
administrative user.
administrative user.
1. Navigate to the user setting (icon in top-right corner), and select
`Site Administration` -> `Authentication Sources`, and select
`Add Authentication Source`.
`Site Administration` -> `Authentication Sources`, and select
`Add Authentication Source`.
1. Fill out the field as follows:
- `Authentication Type` : `PAM`
- `Name` : Any value should be valid here, use "System Authentication" if
you'd like.
- `PAM Service Name` : Select the appropriate file listed under `/etc/pam.d/`
that performs the authentication desired.[^1]
- `PAM Email Domain` : The e-mail suffix to append to user authentication.
For example, if the login system expects a user called `gituser`, and this
field is set to `mail.com`, then Forgejo will expect the `user email` field
for an authenticated GIT instance to be `gituser@mail.com`.[^2]
- `Authentication Type` : `PAM`
- `Name` : Any value should be valid here, use "System Authentication" if
you'd like.
- `PAM Service Name` : Select the appropriate file listed under `/etc/pam.d/`
that performs the authentication desired.[^1]
- `PAM Email Domain` : The e-mail suffix to append to user authentication.
For example, if the login system expects a user called `gituser`, and this
field is set to `mail.com`, then Forgejo will expect the `user email` field
for an authenticated GIT instance to be `gituser@mail.com`.[^2]
**Note**: PAM support is added via build-time flags (TAGS="pam" make build),
and the official binaries provided do not have this enabled. PAM requires that
and the official binaries provided do not have this enabled. PAM requires that
the necessary libpam dynamic library be available and the necessary PAM
development headers be accessible to the compiler.
[^1]: For example, using standard Linux log-in on Debian "Bullseye" use
`common-session-noninteractive` - this value may be valid for other flavors of
Debian including Ubuntu and Mint, consult your distribution's documentation.
[^2]: **This is a required field for PAM**. Be aware: In the above example, the
user will log into the Forgejo web interface as `gituser` and not `gituser@mail.com`
[^1]:
For example, using standard Linux log-in on Debian "Bullseye" use
`common-session-noninteractive` - this value may be valid for other flavors of
Debian including Ubuntu and Mint, consult your distribution's documentation.
[^2]:
**This is a required field for PAM**. Be aware: In the above example, the
user will log into the Forgejo web interface as `gituser` and not `gituser@mail.com`
## FreeIPA

14
user/email-settings.md
View file

@ -15,11 +15,11 @@ You can access it by clicking on the menu button “Profile and Settings...” i
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 (default setting) |
| 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 |
| Option | Effect |
| :-------------------------- | :----------------------------------------------------------------------------------------------------- |
| Enable Email Notifications | Enables all notifications (default setting) |
| 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.
@ -28,12 +28,12 @@ When you're finished, press the button “Set Email Preference” to confirm you
## Issue notifications
As soon as you make a comment on an issue, you automatically subscribe to it. Unless you disabled email notifications for all your email addresses, you will get an email for every change and comment on that issue.
As soon as you make a comment on an issue, you automatically subscribe to it. Unless you 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.
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.

47
user/issue-pull-request-templates.md
View file

@ -79,16 +79,13 @@ Inside the directory can be multiple markdown (`.md`) or yaml (`.yaml`/`.yml`) i
```md
---
name: "Template Name"
about: "This template is for testing!"
title: "[TEST] "
ref: "main"
name: 'Template Name'
about: 'This template is for testing!'
title: '[TEST] '
ref: 'main'
labels:
- bug
- "help needed"
- bug
- 'help needed'
---
This is the template!
@ -106,7 +103,7 @@ This example YAML configuration file defines an issue form using several inputs
```yaml
name: Bug Report
about: File a bug report
title: "[Bug]: "
title: '[Bug]: '
body:
- type: markdown
attributes:
@ -126,7 +123,7 @@ body:
label: What happened?
description: Also tell us, what did you expect to happen?
placeholder: Tell us what you see!
value: "A bug happened!"
value: 'A bug happened!'
validations:
required: true
- type: dropdown
@ -172,7 +169,7 @@ You can use a `markdown` element to display Markdown in your form that provides
Attributes:
| Key | Description | Required | Type | Default | Valid values |
|-------|--------------------------------------------------------------|----------|--------|---------|--------------|
| ----- | ------------------------------------------------------------ | -------- | ------ | ------- | ------------ |
| value | The text that is rendered. Markdown formatting is supported. | Required | String | - | - |
### Textarea
@ -181,18 +178,18 @@ You can use a `textarea` element to add a multi-line text field to your form. Co
Attributes:
| Key | Description | Required | Type | Default | Valid values |
|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|--------|--------------|---------------------------|
| label | A brief description of the expected user input, which is also displayed in the form. | Required | String | - | - |
| description | A description of the text area to provide context or guidance, which is displayed in the form. | Optional | String | Empty String | - |
| placeholder | A semi-opaque placeholder that renders in the text area when empty. | Optional | String | Empty String | - |
| value | Text that is pre-filled in the text area. | Optional | String | - | - |
| Key | Description | Required | Type | Default | Valid values |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------ | ------------ | --------------------------- |
| label | A brief description of the expected user input, which is also displayed in the form. | Required | String | - | - |
| description | A description of the text area to provide context or guidance, which is displayed in the form. | Optional | String | Empty String | - |
| placeholder | A semi-opaque placeholder that renders in the text area when empty. | Optional | String | Empty String | - |
| value | Text that is pre-filled in the text area. | Optional | String | - | - |
| render | If a value is provided, submitted text will be formatted into a codeblock. When this key is provided, the text area will not expand for file attachments or Markdown editing. | Optional | String | - | Languages known to Forgejo. |
Validations:
| Key | Description | Required | Type | Default | Valid values |
|----------|------------------------------------------------------|----------|---------|---------|--------------|
| -------- | ---------------------------------------------------- | -------- | ------- | ------- | ------------ |
| required | Prevents form submission until element is completed. | Optional | Boolean | false | - |
### Input
@ -202,7 +199,7 @@ You can use an `input` element to add a single-line text field to your form.
Attributes:
| Key | Description | Required | Type | Default | Valid values |
|-------------|--------------------------------------------------------------------------------------------|----------|--------|--------------|--------------|
| ----------- | ------------------------------------------------------------------------------------------ | -------- | ------ | ------------ | ------------ |
| label | A brief description of the expected user input, which is also displayed in the form. | Required | String | - | - |
| description | A description of the field to provide context or guidance, which is displayed in the form. | Optional | String | Empty String | - |
| placeholder | A semi-transparent placeholder that renders in the field when empty. | Optional | String | Empty String | - |
@ -211,7 +208,7 @@ Attributes:
Validations:
| Key | Description | Required | Type | Default | Valid values |
|-----------|--------------------------------------------------------------------------------------------------|----------|---------|---------|--------------------------------------------------------------------------|
| --------- | ------------------------------------------------------------------------------------------------ | -------- | ------- | ------- | ------------------------------------------------------------------------ |
| required | Prevents form submission until element is completed. | Optional | Boolean | false | - |
| is_number | Prevents form submission until element is filled with a number. | Optional | Boolean | false | - |
| regex | Prevents form submission until element is filled with a value that match the regular expression. | Optional | String | - | a [regular expression](https://en.wikipedia.org/wiki/Regular_expression) |
@ -223,7 +220,7 @@ You can use a `dropdown` element to add a dropdown menu in your form.
Attributes:
| Key | Description | Required | Type | Default | Valid values |
|-------------|-----------------------------------------------------------------------------------------------------|----------|--------------|--------------|--------------|
| ----------- | --------------------------------------------------------------------------------------------------- | -------- | ------------ | ------------ | ------------ |
| label | A brief description of the expected user input, which is displayed in the form. | Required | String | - | - |
| description | A description of the dropdown to provide extra context or guidance, which is displayed in the form. | Optional | String | Empty String | - |
| multiple | Determines if the user can select more than one option. | Optional | Boolean | false | - |
@ -232,7 +229,7 @@ Attributes:
Validations:
| Key | Description | Required | Type | Default | Valid values |
|----------|------------------------------------------------------|----------|---------|---------|--------------|
| -------- | ---------------------------------------------------- | -------- | ------- | ------- | ------------ |
| required | Prevents form submission until element is completed. | Optional | Boolean | false | - |
### Checkboxes
@ -242,7 +239,7 @@ You can use the `checkboxes` element to add a set of checkboxes to your form.
Attributes:
| Key | Description | Required | Type | Default | Valid values |
|-------------|-------------------------------------------------------------------------------------------------------|----------|--------|--------------|--------------|
| ----------- | ----------------------------------------------------------------------------------------------------- | -------- | ------ | ------------ | ------------ |
| label | A brief description of the expected user input, which is displayed in the form. | Required | String | - | - |
| description | A description of the set of checkboxes, which is displayed in the form. Supports Markdown formatting. | Optional | String | Empty String | - |
| options | An array of checkboxes that the user can select. For syntax, see below. | Required | Array | - | - |
@ -250,6 +247,6 @@ Attributes:
For each value in the options array, you can set the following keys.
| Key | Description | Required | Type | Default | Options |
|----------|------------------------------------------------------------------------------------------------------------------------------------------|----------|---------|---------|---------|
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ------- | ------- |
| label | The identifier for the option, which is displayed in the form. Markdown is supported for bold or italic text formatting, and hyperlinks. | Required | String | - | - |
| required | Prevents form submission until element is completed. | Optional | Boolean | false | - |

66
user/oauth2-provider.md
View file

@ -30,39 +30,39 @@ To use the Authorization Code Grant as a third party application it is required
Forgejo supports the following scopes for tokens:
| Name | Description |
| ---- | ----------- |
| **(no scope)** | Grants read-only access to public user profile and public repositories. |
| **repo** | Full control over all repositories. |
| &nbsp;&nbsp;&nbsp; **repo:status** | Grants read/write access to commit status in all repositories. |
| &nbsp;&nbsp;&nbsp; **public_repo** | Grants read/write access to public repositories only. |
| **admin:repo_hook** | Grants access to repository hooks of all repositories. This is included in the `repo` scope. |
| &nbsp;&nbsp;&nbsp; **write:repo_hook** | Grants read/write access to repository hooks |
| &nbsp;&nbsp;&nbsp; **read:repo_hook** | Grants read-only access to repository hooks |
| **admin:org** | Grants full access to organization settings |
| &nbsp;&nbsp;&nbsp; **write:org** | Grants read/write access to organization settings |
| &nbsp;&nbsp;&nbsp; **read:org** | Grants read-only access to organization settings |
| **admin:public_key** | Grants full access for managing public keys |
| &nbsp;&nbsp;&nbsp; **write:public_key** | Grant read/write access to public keys |
| &nbsp;&nbsp;&nbsp; **read:public_key** | Grant read-only access to public keys |
| **admin:org_hook** | Grants full access to organizational-level hooks |
| **notification** | Grants full access to notifications |
| **user** | Grants full access to user profile info |
| &nbsp;&nbsp;&nbsp; **read:user** | Grants read access to user's profile |
| &nbsp;&nbsp;&nbsp; **user:email** | Grants read access to user's email addresses |
| &nbsp;&nbsp;&nbsp; **user:follow** | Grants access to follow/un-follow a user |
| **delete_repo** | Grants access to delete repositories as an admin |
| **package** | Grants full access to hosted packages |
| &nbsp;&nbsp;&nbsp; **write:package** | Grants read/write access to packages |
| &nbsp;&nbsp;&nbsp; **read:package** | Grants read access to packages |
| &nbsp;&nbsp;&nbsp; **delete:package** | Grants delete access to packages |
| **admin:gpg_key** | Grants full access for managing GPG keys |
| &nbsp;&nbsp;&nbsp; **write:gpg_key** | Grants read/write access to GPG keys |
| &nbsp;&nbsp;&nbsp; **read:gpg_key** | Grants read-only access to GPG keys |
| **admin:application** | Grants full access to manage applications |
| &nbsp;&nbsp;&nbsp; **write:application** | Grants read/write access for managing applications |
| &nbsp;&nbsp;&nbsp; **read:application** | Grants read access for managing applications |
| **sudo** | Allows to perform actions as the site admin. |
| Name | Description |
| ---------------------------------------- | -------------------------------------------------------------------------------------------- |
| **(no scope)** | Grants read-only access to public user profile and public repositories. |
| **repo** | Full control over all repositories. |
| &nbsp;&nbsp;&nbsp; **repo:status** | Grants read/write access to commit status in all repositories. |
| &nbsp;&nbsp;&nbsp; **public_repo** | Grants read/write access to public repositories only. |
| **admin:repo_hook** | Grants access to repository hooks of all repositories. This is included in the `repo` scope. |
| &nbsp;&nbsp;&nbsp; **write:repo_hook** | Grants read/write access to repository hooks |
| &nbsp;&nbsp;&nbsp; **read:repo_hook** | Grants read-only access to repository hooks |
| **admin:org** | Grants full access to organization settings |
| &nbsp;&nbsp;&nbsp; **write:org** | Grants read/write access to organization settings |
| &nbsp;&nbsp;&nbsp; **read:org** | Grants read-only access to organization settings |
| **admin:public_key** | Grants full access for managing public keys |
| &nbsp;&nbsp;&nbsp; **write:public_key** | Grant read/write access to public keys |
| &nbsp;&nbsp;&nbsp; **read:public_key** | Grant read-only access to public keys |
| **admin:org_hook** | Grants full access to organizational-level hooks |
| **notification** | Grants full access to notifications |
| **user** | Grants full access to user profile info |
| &nbsp;&nbsp;&nbsp; **read:user** | Grants read access to user's profile |
| &nbsp;&nbsp;&nbsp; **user:email** | Grants read access to user's email addresses |
| &nbsp;&nbsp;&nbsp; **user:follow** | Grants access to follow/un-follow a user |
| **delete_repo** | Grants access to delete repositories as an admin |
| **package** | Grants full access to hosted packages |
| &nbsp;&nbsp;&nbsp; **write:package** | Grants read/write access to packages |
| &nbsp;&nbsp;&nbsp; **read:package** | Grants read access to packages |
| &nbsp;&nbsp;&nbsp; **delete:package** | Grants delete access to packages |
| **admin:gpg_key** | Grants full access for managing GPG keys |
| &nbsp;&nbsp;&nbsp; **write:gpg_key** | Grants read/write access to GPG keys |
| &nbsp;&nbsp;&nbsp; **read:gpg_key** | Grants read-only access to GPG keys |
| **admin:application** | Grants full access to manage applications |
| &nbsp;&nbsp;&nbsp; **write:application** | Grants read/write access for managing applications |
| &nbsp;&nbsp;&nbsp; **read:application** | Grants read access for managing applications |
| **sudo** | Allows to perform actions as the site admin. |
## Client types

40
user/packages/index.md
View file

@ -7,23 +7,23 @@ title: 'Package Registry'
The following package managers are currently supported:
| Name | Language | Package client |
| ---- | -------- | -------------- |
| [Cargo](cargo) | Rust | `cargo` |
| [Chef](chef) | - | `knife` |
| [Composer](composer) | PHP | `composer` |
| [Conan](conan) | C++ | `conan` |
| [Conda](conda) | - | `conda` |
| [Container](container) | - | any OCI compliant client |
| [Generic](generic) | - | any HTTP client |
| [Helm](helm) | - | any HTTP client, `cm-push` |
| [Maven](maven) | Java | `mvn`, `gradle` |
| [npm](npm) | JavaScript | `npm`, `yarn`, `pnpm` |
| [NuGet](nuget) | .NET | `nuget` |
| [Pub](pub) | Dart | `dart`, `flutter` |
| [PyPI](pypi) | Python | `pip`, `twine` |
| [RubyGems](rubygems) | Ruby | `gem`, `Bundler` |
| [Vagrant](vagrant) | - | `vagrant` |
| Name | Language | Package client |
| ---------------------- | ---------- | -------------------------- |
| [Cargo](cargo) | Rust | `cargo` |
| [Chef](chef) | - | `knife` |
| [Composer](composer) | PHP | `composer` |
| [Conan](conan) | C++ | `conan` |
| [Conda](conda) | - | `conda` |
| [Container](container) | - | any OCI compliant client |
| [Generic](generic) | - | any HTTP client |
| [Helm](helm) | - | any HTTP client, `cm-push` |
| [Maven](maven) | Java | `mvn`, `gradle` |
| [npm](npm) | JavaScript | `npm`, `yarn`, `pnpm` |
| [NuGet](nuget) | .NET | `nuget` |
| [Pub](pub) | Dart | `dart`, `flutter` |
| [PyPI](pypi) | Python | `pip`, `twine` |
| [RubyGems](rubygems) | Ruby | `gem`, `Bundler` |
| [Vagrant](vagrant) | - | `vagrant` |
**The following paragraphs only apply if Packages are not globally disabled!**
@ -39,10 +39,10 @@ and shows a link to the repository on the package site (as well as a link to the
## Access Restrictions
| Package owner type | User | Organization |
|--------------------|------|--------------|
| Package owner type | User | Organization |
| ------------------ | ----------------------------------------------------------- | -------------------------------------------------------- |
| **read** access | public, if user is public too; otherwise for this user only | public, if org is public, otherwise for org members only |
| **write** access | owner only | org members with admin or write access to the org |
| **write** access | owner only | org members with admin or write access to the org |
N.B.: These access restrictions are subject to change, where more finegrained control will be added via a dedicated organization team permission.

12
user/packages/maven.md
View file

@ -55,10 +55,10 @@ Afterwards add the following sections to your project `pom.xml` file:
</distributionManagement>
```
| Parameter | Description |
| -------------- | ----------- |
| Parameter | Description |
| -------------- | ------------------------------------------------------------------------------------------------ |
| `access_token` | Your [personal access token]({{< relref "doc/developers/api-usage.en-us.md#authentication" >}}). |
| `owner` | The owner of the package. |
| `owner` | The owner of the package. |
### Gradle variant
@ -114,9 +114,9 @@ If you want to publish a prebuild package to the registry, you can use [`mvn dep
mvn deploy:deploy-file -Durl=https://forgejo.example.com/api/packages/{owner}/maven -DrepositoryId=forgejo -Dfile=/path/to/package.jar
```
| Parameter | Description |
| -------------- | ----------- |
| `owner` | The owner of the package. |
| Parameter | Description |
| --------- | ------------------------- |
| `owner` | The owner of the package. |
You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first.

2
user/project.md
View file

@ -4,7 +4,7 @@ title: 'Projects'
license: 'CC-BY-SA-4.0'
---
A project is a [kanban board](https://en.wikipedia.org/wiki/Kanban_(development)) to organize issues.
A project is a [kanban board](<https://en.wikipedia.org/wiki/Kanban_(development)>) to organize issues.
![screenshot of the project page](../../../../images/v1.20/user/project/project.png)

2
user/protection.md
View file

@ -17,7 +17,7 @@ To protect a branch, you need to go to the repository’s **Settings** >
![Add a new rule](../../../../images/v1.20/user/protection/branch-protect.png)
The name of the branch can be a glob where / is the separator and **
spans accross separators. For instance `main`, `release/**` or `precious*`.
spans accross separators. For instance `main`, `release/**`or`precious\*`.
If two rules apply to the same branch, the one that has no glob takes
precedence.

23
user/semver.md
View file

@ -10,7 +10,8 @@ license: 'CC-BY-SA-4.0'
- Minor is increased for backwards-compatible new features.
- Major is increased for breaking changes.
*something* could be :
_something_ could be :
- a command, an option or an argument, for a CLI ;
- a route path, a query parameter or a body property, for a REST API ;
- a text node, a button or a field, for a GUI.
@ -21,13 +22,13 @@ Since Forgejo has all of the above, changes to all of those components should be
As of Forgejo v1.19, there are two version numbering schemes:
* [Following the Gitea version](https://codeberg.org/forgejo/forgejo/src/branch/forgejo/CONTRIBUTING/RELEASE.md#release-numbering) which is not a semantic version
* Used to name release files
* Used for tagging releases
* Displayed in the web interface
* Returned by the `/api/v1/version` API endpoint
* Forgejo semantic version
* Returned by the `/api/forgejo/v1/version` API endpoint
- [Following the Gitea version](https://codeberg.org/forgejo/forgejo/src/branch/forgejo/CONTRIBUTING/RELEASE.md#release-numbering) which is not a semantic version
- Used to name release files
- Used for tagging releases
- Displayed in the web interface
- Returned by the `/api/v1/version` API endpoint
- Forgejo semantic version
- Returned by the `/api/forgejo/v1/version` API endpoint
For instance, the semantic version for https://code.forgejo.org can be obtained with:
@ -40,6 +41,6 @@ $ curl https://code.forgejo.org/api/forgejo/v1/version
The structure of the version number is `<major>.<minor>.<patch>+<build>-gitea-<gitea version>` where:
* `<major>.<minor>.<patch>` is conformant to [Semantic Versioning 2.0.0](https://semver.org/#semantic-versioning-200)
* `<build>` is the release build number of an otherwise identical source
* `gitea-<gitea version>` is the Gitea version this Forgejo release depends on
- `<major>.<minor>.<patch>` is conformant to [Semantic Versioning 2.0.0](https://semver.org/#semantic-versioning-200)
- `<build>` is the release build number of an otherwise identical source
- `gitea-<gitea version>` is the Gitea version this Forgejo release depends on

24
user/wiki.md
View file

@ -5,27 +5,30 @@ license: 'CC-BY-SA-4.0'
origin_url: 'https://codeberg.org/Codeberg/Documentation/src/commit/ceec82002bbdc62cf27974e84df51369a4bfe0f9/content/getting-started/wiki.md'
---
A [wiki](https://en.wikipedia.org/wiki/Wiki) is a collaborative space on the web. It is a common practice to use wikis to collect knowledge and share information.
A [wiki](https://en.wikipedia.org/wiki/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 repo 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 `Advanced Section`. It will default to the built-in wiki which is described here, but you can add an URI to an external site the "Wiki" tab should link to.
> **Warning**
> Be aware that the wiki, once enabled, is accessible for *everyone* who has `read` access to your repository - on public repositories even anonymous guests can access the wiki.
> The wiki is *not* a suitable place for storing private information or secrets (like passwords).
> **Warning**
> Be aware that the wiki, once enabled, is accessible for _everyone_ who has `read` access to your repository - on public repositories even anonymous guests can access the wiki.
> The wiki is _not_ a suitable place for storing private information or secrets (like passwords).
To edit the wiki `write` permission to the repository is required.
## Wiki structure
The wiki is essentially a separate Git repo in your repository with a predefined name in the form of `<your-repository-name>.wiki.git`.
It consists of [Markdown](https://en.wikipedia.org/wiki/Markdown) files (file extension `.md`) and additional assets like images.
It consists of [Markdown](https://en.wikipedia.org/wiki/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
## 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.
@ -33,6 +36,7 @@ The web UI in your browser is currently limited to adding, updating, and deletin
![Wiki home page with edit buttons](../../../../images/v1.20/user/wiki/wiki_pageview.png)
## Adding content via a local Git client
You can work with the wiki repo as you would with any other Git repo on Forgejo.
```shell
@ -45,6 +49,7 @@ 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
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:
@ -62,7 +67,7 @@ git push
Now, you can reference the image in Markdown, like this:
```markdown
![image alt text](images/image.png "image title")
![image alt text](images/image.png 'image title')
```
After saving your changes, the image should be visible.
@ -70,20 +75,23 @@ 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:
```markdown
- [[Home]]
### Content
- [Page 1](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:
> 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`