foster/forgejo-docs
0
0
Fork 0
mirror of https://codeberg.org/forgejo/docs.git synced 2025-02-02 03:45:09 -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. - 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. - `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. - e.g.
- In the Request Header: X-Request-ID: **test-id-123** - In the Request Header: X-Request-ID: **test-id-123**
- Configuration in app.ini: REQUEST_ID_HEADERS = X-Request-ID - 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**" ... - Print in log: 127.0.0.1:58384 - - [14/Feb/2023:16:33:51 +0800] "**test-id-123**" ...
### Log subsections (`log.name`, `log.name.*`) ### 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: 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 ```ini
bind-address = 203.0.113.3 bind-address = 203.0.113.3
``` ```
2. On database instance, login to database console as root: 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. 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 ```sql
SET old_passwords=0; SET old_passwords=0;
CREATE USER 'forgejo' IDENTIFIED BY 'forgejo'; CREATE USER 'forgejo' IDENTIFIED BY 'forgejo';
``` ```
For remote database: For remote database:
```sql ```sql
SET old_passwords=0; SET old_passwords=0;
CREATE USER 'forgejo'@'192.0.2.10' IDENTIFIED BY 'forgejo'; 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`. 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 ```sql
CREATE DATABASE forgejodb CHARACTER SET 'utf8mb4' COLLATE 'utf8mb4_unicode_ci'; 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. 5. Grant all privileges on the database to database user created above.
For local database: For local database:
```sql ```sql
GRANT ALL PRIVILEGES ON forgejodb.* TO 'forgejo'; GRANT ALL PRIVILEGES ON forgejodb.* TO 'forgejo';
FLUSH PRIVILEGES; FLUSH PRIVILEGES;
``` ```
For remote database: For remote database:
```sql ```sql
GRANT ALL PRIVILEGES ON forgejodb.* TO 'forgejo'@'192.0.2.10'; GRANT ALL PRIVILEGES ON forgejodb.* TO 'forgejo'@'192.0.2.10';
FLUSH PRIVILEGES; FLUSH PRIVILEGES;
``` ```
6. Quit from database console by `exit`. 6. Quit from database console by `exit`.
7. On your Forgejo server, test connection to the database: 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 ## 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: 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 ```ini
listen_addresses = 'localhost, 203.0.113.3' 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: 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 ```ini
password_encryption = scram-sha-256 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: 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: 4. Create database user (role in PostgreSQL terms) with login privilege and password. Please use a secure, strong password instead of `'forgejo'` below:
```sql ```sql
CREATE ROLE forgejo WITH LOGIN PASSWORD 'forgejo'; 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: 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 ```sql
CREATE DATABASE forgejodb WITH OWNER forgejo TEMPLATE template0 ENCODING UTF8 LC_COLLATE 'en_US.UTF-8' LC_CTYPE 'en_US.UTF-8'; 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`. 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 ```ini
local forgejodb forgejo scram-sha-256 local forgejodb forgejo scram-sha-256
``` ```
For remote database: For remote database:
```ini ```ini
host forgejodb forgejo 192.0.2.10/32 scram-sha-256 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. 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 ## 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: 1. On the server with the database instance, place the following credentials:
- `/path/to/postgresql.crt`: Database instance certificate - `/path/to/postgresql.crt`: Database instance certificate
- `/path/to/postgresql.key`: Database instance private key - `/path/to/postgresql.key`: Database instance private key
- `/path/to/root.crt`: CA certificate chain to validate client certificates - `/path/to/root.crt`: CA certificate chain to validate client certificates
2. Add following options to `postgresql.conf`: 2. Add following options to `postgresql.conf`:
```ini ```ini
ssl = on ssl = on
ssl_ca_file = '/path/to/root.crt' ssl_ca_file = '/path/to/root.crt'
ssl_cert_file = '/path/to/postgresql.crt' ssl_cert_file = '/path/to/postgresql.crt'
ssl_key_file = '/path/to/postgresql.key' ssl_key_file = '/path/to/postgresql.key'
ssl_min_protocol_version = 'TLSv1.2' ssl_min_protocol_version = 'TLSv1.2'
``` ```
3. Adjust credentials ownership and permission, as required by PostgreSQL: 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 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 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. 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 ```ini
hostssl forgejodb forgejo 192.0.2.10/32 scram-sha-256 clientcert=verify-full 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 ```ini
hostssl forgejodb forgejo 192.0.2.10/32 scram-sha-256 clientcert=1 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. 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`): 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.crt`: Database client certificate
- `~/.postgresql/postgresql.key`: Database client private key - `~/.postgresql/postgresql.key`: Database client private key
- `~/.postgresql/root.crt`: CA certificate chain to validate server certificate - `~/.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: 7. Adjust credentials, ownership and permission as required:
``` ```
chown git:git ~/.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 chown 0600 ~/.postgresql/postgresql.crt ~/.postgresql/postgresql.key ~/.postgresql/root.crt
``` ```
8. Test the connection to the database: 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 ### 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: 1. On the database instance, place the following credentials:
- `/path/to/mysql.crt`: Database instance certificate - `/path/to/mysql.crt`: Database instance certificate
- `/path/to/mysql.key`: Database instance key - `/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/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`: 2. Add following options to `my.cnf`:
```ini ```ini
[mysqld] [mysqld]
ssl-ca = /path/to/ca.crt ssl-ca = /path/to/ca.crt
ssl-cert = /path/to/mysql.crt ssl-cert = /path/to/mysql.crt
ssl-key = /path/to/mysql.key ssl-key = /path/to/mysql.key
tls-version = TLSv1.2,TLSv1.3 tls-version = TLSv1.2,TLSv1.3
``` ```
3. Adjust credentials ownership and permission: 3. Adjust credentials ownership and permission:
``` ```
chown mysql:mysql /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 chmod 0600 /path/to/ca.crt /path/to/mysql.crt /path/to/mysql.key
``` ```
4. Restart MySQL to apply the setting. 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: 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 ```sql
DROP USER 'forgejo'@'192.0.2.10'; DROP USER 'forgejo'@'192.0.2.10';
CREATE USER 'forgejo'@'example.forgejo' IDENTIFIED BY 'forgejo' REQUIRE SSL; CREATE USER 'forgejo'@'example.forgejo' IDENTIFIED BY 'forgejo' REQUIRE SSL;
GRANT ALL PRIVILEGES ON forgejodb.* TO 'forgejo'@'example.forgejo'; GRANT ALL PRIVILEGES ON forgejodb.* TO 'forgejo'@'example.forgejo';
FLUSH PRIVILEGES; 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. 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: 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 https://code.forgejo.org is a Forgejo instance running the latest stable
version. It is dedicated to hosting the following repositories: version. It is dedicated to hosting the following repositories:
* Default Forgejo Runner actions https://code.forgejo.org/actions - Default Forgejo Runner actions https://code.forgejo.org/actions
* Forgejo Runner https://code.forgejo.org/forgejo/runner - Forgejo Runner https://code.forgejo.org/forgejo/runner
* [ACT](https://github.com/nektos/act) soft fork https://code.forgejo.org/forgejo/act - [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) 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 - [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: 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/runner => https://codeberg.org/forgejo/runner
* https://code.forgejo.org/forgejo/act => https://codeberg.org/forgejo/act - https://code.forgejo.org/forgejo/act => https://codeberg.org/forgejo/act
## Infrastructure ## Infrastructure

14
index.md
View file

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

2
license.md
View file

@ -1,6 +1,6 @@
--- ---
layout: '~/layouts/Markdown.astro' 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). 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"} {"id":1,"name":"test","sha1":"9fcb1158165773dd010fca5f0cf7174316c3e37d","token_last_eight":"16c3e37d"}
``` ```
The ``sha1`` (the token) is only returned once and is not stored in 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` plain-text. It will not be displayed when listing tokens with a `GET`
request; e.g. request; e.g.
```sh ```sh

51
user/authentication.md
View file

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

10
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: 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 | | Option | Effect |
|:----------------------------|:---------------------------------------------------------------------------------------------------------------| | :-------------------------- | :----------------------------------------------------------------------------------------------------- |
| Enable Email Notifications | Enables all notifications (default setting) | | 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 | | 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 | | 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. When you're finished, press the button “Set Email Preference” to confirm your selection.

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 ```md
--- ---
name: 'Template Name'
name: "Template Name" about: 'This template is for testing!'
about: "This template is for testing!" title: '[TEST] '
title: "[TEST] " ref: 'main'
ref: "main"
labels: labels:
- bug
- bug - 'help needed'
- "help needed"
--- ---
This is the template! This is the template!
@ -106,7 +103,7 @@ This example YAML configuration file defines an issue form using several inputs
```yaml ```yaml
name: Bug Report name: Bug Report
about: File a bug report about: File a bug report
title: "[Bug]: " title: '[Bug]: '
body: body:
- type: markdown - type: markdown
attributes: attributes:
@ -126,7 +123,7 @@ body:
label: What happened? label: What happened?
description: Also tell us, what did you expect to happen? description: Also tell us, what did you expect to happen?
placeholder: Tell us what you see! placeholder: Tell us what you see!
value: "A bug happened!" value: 'A bug happened!'
validations: validations:
required: true required: true
- type: dropdown - type: dropdown
@ -172,7 +169,7 @@ You can use a `markdown` element to display Markdown in your form that provides
Attributes: Attributes:
| Key | Description | Required | Type | Default | Valid values | | Key | Description | Required | Type | Default | Valid values |
|-------|--------------------------------------------------------------|----------|--------|---------|--------------| | ----- | ------------------------------------------------------------ | -------- | ------ | ------- | ------------ |
| value | The text that is rendered. Markdown formatting is supported. | Required | String | - | - | | value | The text that is rendered. Markdown formatting is supported. | Required | String | - | - |
### Textarea ### Textarea
@ -181,18 +178,18 @@ You can use a `textarea` element to add a multi-line text field to your form. Co
Attributes: Attributes:
| Key | Description | Required | Type | Default | Valid values | | 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 | - | - | | 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 | - | | 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 | - | | 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 | - | - | | 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. | | 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: Validations:
| Key | Description | Required | Type | Default | Valid values | | Key | Description | Required | Type | Default | Valid values |
|----------|------------------------------------------------------|----------|---------|---------|--------------| | -------- | ---------------------------------------------------- | -------- | ------- | ------- | ------------ |
| required | Prevents form submission until element is completed. | Optional | Boolean | false | - | | required | Prevents form submission until element is completed. | Optional | Boolean | false | - |
### Input ### Input
@ -202,7 +199,7 @@ You can use an `input` element to add a single-line text field to your form.
Attributes: Attributes:
| Key | Description | Required | Type | Default | Valid values | | 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 | - | - | | 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 | - | | 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 | - | | placeholder | A semi-transparent placeholder that renders in the field when empty. | Optional | String | Empty String | - |
@ -211,7 +208,7 @@ Attributes:
Validations: Validations:
| Key | Description | Required | Type | Default | Valid values | | Key | Description | Required | Type | Default | Valid values |
|-----------|--------------------------------------------------------------------------------------------------|----------|---------|---------|--------------------------------------------------------------------------| | --------- | ------------------------------------------------------------------------------------------------ | -------- | ------- | ------- | ------------------------------------------------------------------------ |
| required | Prevents form submission until element is completed. | Optional | Boolean | false | - | | 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 | - | | 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) | | 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: Attributes:
| Key | Description | Required | Type | Default | Valid values | | Key | Description | Required | Type | Default | Valid values |
|-------------|-----------------------------------------------------------------------------------------------------|----------|--------------|--------------|--------------| | ----------- | --------------------------------------------------------------------------------------------------- | -------- | ------------ | ------------ | ------------ |
| label | A brief description of the expected user input, which is displayed in the form. | Required | String | - | - | | 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 | - | | 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 | - | | multiple | Determines if the user can select more than one option. | Optional | Boolean | false | - |
@ -232,7 +229,7 @@ Attributes:
Validations: Validations:
| Key | Description | Required | Type | Default | Valid values | | Key | Description | Required | Type | Default | Valid values |
|----------|------------------------------------------------------|----------|---------|---------|--------------| | -------- | ---------------------------------------------------- | -------- | ------- | ------- | ------------ |
| required | Prevents form submission until element is completed. | Optional | Boolean | false | - | | required | Prevents form submission until element is completed. | Optional | Boolean | false | - |
### Checkboxes ### Checkboxes
@ -242,7 +239,7 @@ You can use the `checkboxes` element to add a set of checkboxes to your form.
Attributes: Attributes:
| Key | Description | Required | Type | Default | Valid values | | Key | Description | Required | Type | Default | Valid values |
|-------------|-------------------------------------------------------------------------------------------------------|----------|--------|--------------|--------------| | ----------- | ----------------------------------------------------------------------------------------------------- | -------- | ------ | ------------ | ------------ |
| label | A brief description of the expected user input, which is displayed in the form. | Required | String | - | - | | 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 | - | | 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 | - | - | | 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. For each value in the options array, you can set the following keys.
| Key | Description | Required | Type | Default | Options | | 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 | - | - | | 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 | - | | 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: Forgejo supports the following scopes for tokens:
| Name | Description | | Name | Description |
| ---- | ----------- | | ---------------------------------------- | -------------------------------------------------------------------------------------------- |
| **(no scope)** | Grants read-only access to public user profile and public repositories. | | **(no scope)** | Grants read-only access to public user profile and public repositories. |
| **repo** | Full control over all 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; **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. | | &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. | | **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; **write:repo_hook** | Grants read/write access to repository hooks |
| &nbsp;&nbsp;&nbsp; **read:repo_hook** | Grants read-only 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 | | **admin:org** | Grants full access to organization settings |
| &nbsp;&nbsp;&nbsp; **write:org** | Grants read/write 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 | | &nbsp;&nbsp;&nbsp; **read:org** | Grants read-only access to organization settings |
| **admin:public_key** | Grants full access for managing public keys | | **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; **write:public_key** | Grant read/write access to public keys |
| &nbsp;&nbsp;&nbsp; **read:public_key** | Grant read-only 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 | | **admin:org_hook** | Grants full access to organizational-level hooks |
| **notification** | Grants full access to notifications | | **notification** | Grants full access to notifications |
| **user** | Grants full access to user profile info | | **user** | Grants full access to user profile info |
| &nbsp;&nbsp;&nbsp; **read:user** | Grants read access to user's profile | | &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:email** | Grants read access to user's email addresses |
| &nbsp;&nbsp;&nbsp; **user:follow** | Grants access to follow/un-follow a user | | &nbsp;&nbsp;&nbsp; **user:follow** | Grants access to follow/un-follow a user |
| **delete_repo** | Grants access to delete repositories as an admin | | **delete_repo** | Grants access to delete repositories as an admin |
| **package** | Grants full access to hosted packages | | **package** | Grants full access to hosted packages |
| &nbsp;&nbsp;&nbsp; **write:package** | Grants read/write access to 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; **read:package** | Grants read access to packages |
| &nbsp;&nbsp;&nbsp; **delete:package** | Grants delete access to packages | | &nbsp;&nbsp;&nbsp; **delete:package** | Grants delete access to packages |
| **admin:gpg_key** | Grants full access for managing GPG keys | | **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; **write:gpg_key** | Grants read/write access to GPG keys |
| &nbsp;&nbsp;&nbsp; **read:gpg_key** | Grants read-only 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 | | **admin:application** | Grants full access to manage applications |
| &nbsp;&nbsp;&nbsp; **write:application** | Grants read/write access for managing applications | | &nbsp;&nbsp;&nbsp; **write:application** | Grants read/write access for managing applications |
| &nbsp;&nbsp;&nbsp; **read:application** | Grants read access for managing applications | | &nbsp;&nbsp;&nbsp; **read:application** | Grants read access for managing applications |
| **sudo** | Allows to perform actions as the site admin. | | **sudo** | Allows to perform actions as the site admin. |
## Client types ## Client types

40
user/packages/index.md
View file

@ -7,23 +7,23 @@ title: 'Package Registry'
The following package managers are currently supported: The following package managers are currently supported:
| Name | Language | Package client | | Name | Language | Package client |
| ---- | -------- | -------------- | | ---------------------- | ---------- | -------------------------- |
| [Cargo](cargo) | Rust | `cargo` | | [Cargo](cargo) | Rust | `cargo` |
| [Chef](chef) | - | `knife` | | [Chef](chef) | - | `knife` |
| [Composer](composer) | PHP | `composer` | | [Composer](composer) | PHP | `composer` |
| [Conan](conan) | C++ | `conan` | | [Conan](conan) | C++ | `conan` |
| [Conda](conda) | - | `conda` | | [Conda](conda) | - | `conda` |
| [Container](container) | - | any OCI compliant client | | [Container](container) | - | any OCI compliant client |
| [Generic](generic) | - | any HTTP client | | [Generic](generic) | - | any HTTP client |
| [Helm](helm) | - | any HTTP client, `cm-push` | | [Helm](helm) | - | any HTTP client, `cm-push` |
| [Maven](maven) | Java | `mvn`, `gradle` | | [Maven](maven) | Java | `mvn`, `gradle` |
| [npm](npm) | JavaScript | `npm`, `yarn`, `pnpm` | | [npm](npm) | JavaScript | `npm`, `yarn`, `pnpm` |
| [NuGet](nuget) | .NET | `nuget` | | [NuGet](nuget) | .NET | `nuget` |
| [Pub](pub) | Dart | `dart`, `flutter` | | [Pub](pub) | Dart | `dart`, `flutter` |
| [PyPI](pypi) | Python | `pip`, `twine` | | [PyPI](pypi) | Python | `pip`, `twine` |
| [RubyGems](rubygems) | Ruby | `gem`, `Bundler` | | [RubyGems](rubygems) | Ruby | `gem`, `Bundler` |
| [Vagrant](vagrant) | - | `vagrant` | | [Vagrant](vagrant) | - | `vagrant` |
**The following paragraphs only apply if Packages are not globally disabled!** **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 ## 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 | | **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. 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> </distributionManagement>
``` ```
| Parameter | Description | | Parameter | Description |
| -------------- | ----------- | | -------------- | ------------------------------------------------------------------------------------------------ |
| `access_token` | Your [personal access token]({{< relref "doc/developers/api-usage.en-us.md#authentication" >}}). | | `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 ### 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 mvn deploy:deploy-file -Durl=https://forgejo.example.com/api/packages/{owner}/maven -DrepositoryId=forgejo -Dfile=/path/to/package.jar
``` ```
| Parameter | Description | | Parameter | Description |
| -------------- | ----------- | | --------- | ------------------------- |
| `owner` | The owner of the package. | | `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. 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' 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) ![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) ![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 ** 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 If two rules apply to the same branch, the one that has no glob takes
precedence. 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. - Minor is increased for backwards-compatible new features.
- Major is increased for breaking changes. - Major is increased for breaking changes.
*something* could be : _something_ could be :
- a command, an option or an argument, for a CLI ; - 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 route path, a query parameter or a body property, for a REST API ;
- a text node, a button or a field, for a GUI. - 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: 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 - [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 to name release files
* Used for tagging releases - Used for tagging releases
* Displayed in the web interface - Displayed in the web interface
* Returned by the `/api/v1/version` API endpoint - Returned by the `/api/v1/version` API endpoint
* Forgejo semantic version - Forgejo semantic version
* Returned by the `/api/forgejo/v1/version` API endpoint - Returned by the `/api/forgejo/v1/version` API endpoint
For instance, the semantic version for https://code.forgejo.org can be obtained with: 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: 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) - `<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 - `<build>` is the release build number of an otherwise identical source
* `gitea-<gitea version>` is the Gitea version this Forgejo release depends on - `gitea-<gitea version>` is the Gitea version this Forgejo release depends on

16
user/wiki.md
View file

@ -11,21 +11,24 @@ 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`. The user in these examples is `knut`, the polar bear and its repository is `foobar`.
## Activation and Permissions ## 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. 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** > **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. > 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). > 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. To edit the wiki `write` permission to the repository is required.
## Wiki structure ## 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`. 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. 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`. 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. 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) ![Wiki home page with edit buttons](../../../../images/v1.20/user/wiki/wiki_pageview.png)
## Adding content via a local Git client ## Adding content via a local Git client
You can work with the wiki repo as you would with any other Git repo on Forgejo. You can work with the wiki repo as you would with any other Git repo on Forgejo.
```shell ```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. Editing locally allows you to use your favorite editor (preferably with Markdown syntax check and highlighting) and manage additional assets like images.
### Adding images ### Adding images
You can add images to the root directory or a specific subfolder (like `assets` or `images`) using your 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: A feasible workflow might look like this:
@ -62,7 +67,7 @@ git push
Now, you can reference the image in Markdown, like this: Now, you can reference the image in Markdown, like this:
```markdown ```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. 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. > 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 ## 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 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`. 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. Both file types allow common Markdown syntax to adjust the presentation to your needs.
Very basic example for a sidebar: Very basic example for a sidebar:
```markdown ```markdown
- [[Home]] - [[Home]]
### Content ### Content
- [Page 1](Page-1) - [Page 1](Page-1)
> knuts wiki > 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` > `https://codeberg.org/knut/foobar/wiki/_Sidebar`