foster/forgejo-docs
0
0
Fork 0
mirror of https://codeberg.org/forgejo/docs.git synced 2024-11-21 17:36:59 -05:00
Code Issues Activity

Add hidden documentation

Browse source
This commit is contained in:
Loïc Dachary 2023-02-27 00:08:07 +01:00
commit f64e62428a
22 changed files with 3985 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

110
admin/api-usage.md Normal file
View file

@ -0,0 +1,110 @@
---
layout: '~/layouts/Markdown.astro'
title: 'API Usage'
---
## Enabling/configuring API access
By default, `ENABLE_SWAGGER` is true, and `MAX_RESPONSE_ITEMS` is set to 50.
## Authentication
Forgejo supports these methods of API authentication:
- HTTP basic authentication
- `token=...` parameter in URL query string
- `access_token=...` parameter in URL query string
- `Authorization: token ...` header in HTTP headers
## Generating and listing API tokens
A new token can be generated with a `POST` request to
`/users/:name/tokens`.
Note that `/users/:name/tokens` is a special endpoint and requires you
to authenticate using `BasicAuth` and a password, as follows:
```sh
$ curl -H "Content-Type: application/json" -d '{"name":"test"}' -u username:password https://forgejo.your.host/api/v1/users/<username>/tokens
{"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`
request; e.g.
```sh
$ curl --url https://yourusername:password@forgejo.your.host/api/v1/users/<username>/tokens
[{"name":"test","sha1":"","token_last_eight:"........":},{"name":"dev","sha1":"","token_last_eight":"........"}]
```
To use the API with basic authentication with two factor authentication
enabled, you'll need to send an additional header that contains the one
time password (6 digitrotating token).
An example of the header is `X-Forgejo-OTP: 123456` where `123456`
is where you'd place the code from your authenticator.
Here is how the request would look like in curl:
```sh
$ curl -H "X-Forgejo-OTP: 123456" --url https://yourusername:yourpassword@forgejo.your.host/api/v1/users/yourusername/tokens
```
You can also create an API key token via your Forgejo installation's web
interface: `Settings | Applications | Generate New Token`.
## OAuth2 Provider
Access tokens obtained from Forgejo's OAuth2 provider are accepted by these methods:
- `Authorization bearer ...` header in HTTP headers
- `token=...` parameter in URL query string
- `access_token=...` parameter in URL query string
### More on the `Authorization:` header
For historical reasons, Forgejo needs the word `token` included before
the API key token in an authorization header, like this:
```sh
Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675
```
In a `curl` command, for instance, this would look like:
```sh
curl "http://localhost:4000/api/v1/repos/test1/test1/issues" \
-H "accept: application/json" \
-H "Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675" \
-H "Content-Type: application/json" -d "{ \"body\": \"testing\", \"title\": \"test 20\"}" -i
```
As mentioned above, the token used is the same one you would use in
the `token=` string in a GET request.
## Pagination
The API supports pagination. The `page` and `limit` parameters are used to specify the page number and the number of items per page. As well, the `Link` header is returned with the next, previous, and last page links if there are more than one pages. The `x-total-count` is also returned to indicate the total number of items.
```sh
curl -v "http://localhost/api/v1/repos/search?limit=1"
...
< link: <http://localhost/api/v1/repos/search?limit=1&page=2>; rel="next",<http://localhost/api/v1/repos/search?limit=1&page=5252>; rel="last"
...
< x-total-count: 5252
```
## API Guide:
API Reference guide is auto-generated by swagger and available on:
`https://forgejo.your.host/api/swagger`.
The OpenAPI document is at:
`https://forgejo.your.host/swagger.v1.json`
## Sudo
The API allows admin users to sudo API requests as another user. Simply add either a `sudo=` parameter or `Sudo:` request header with the username of the user to sudo.
## SDKs
- See [the list at delightful Forgejo](https://codeberg.org/forgejo-contrib/delightful-forgejo)

295
admin/authentication.md Normal file
View file

@ -0,0 +1,295 @@
---
layout: '~/layouts/Markdown.astro'
title: 'Authentication'
---
## LDAP (Lightweight Directory Access Protocol)
Both the LDAP via BindDN and the simple auth LDAP share the following fields:
- Authorization Name **(required)**
- A name to assign to the new method of authorization.
- Host **(required)**
- The address where the LDAP server can be reached.
- Example: `mydomain.com`
- Port **(required)**
- The port to use when connecting to the server.
- Example: `389` for LDAP or `636` for LDAP SSL
- Enable TLS Encryption (optional)
- Whether to use TLS when connecting to the LDAP server.
- Admin Filter (optional)
- An LDAP filter specifying if a user should be given administrator
privileges. If a user account passes the filter, the user will be
privileged as an administrator.
- Example: `(objectClass=adminAccount)`
- Example for Microsoft Active Directory (AD): `(memberOf=CN=admin-group,OU=example,DC=example,DC=org)`
- Username attribute (optional)
- The attribute of the user's LDAP record containing the user name. Given
attribute value will be used for new Forgejo account user name after first
successful sign-in. Leave empty to use login name given on sign-in form.
- This is useful when supplied login name is matched against multiple
attributes, but only single specific attribute should be used for Forgejo
account name, see "User Filter".
- Example: `uid`
- Example for Microsoft Active Directory (AD): `sAMAccountName`
- First name attribute (optional)
- The attribute of the user's LDAP record containing the user's first name.
This will be used to populate their account information.
- Example: `givenName`
- Surname attribute (optional)
- The attribute of the user's LDAP record containing the user's surname.
This will be used to populate their account information.
- Example: `sn`
- E-mail attribute **(required)**
- The attribute of the user's LDAP record containing the user's email
address. This will be used to populate their account information.
- Example: `mail`
### LDAP via BindDN
Adds the following fields:
- Bind DN (optional)
- The DN to bind to the LDAP server with when searching for the user. This
may be left blank to perform an anonymous search.
- Example: `cn=Search,dc=mydomain,dc=com`
- Bind Password (optional)
- The password for the Bind DN specified above, if any. _Note: The password
is stored encrypted with the SECRET_KEY on the server. It is still recommended
to ensure that the Bind DN has as few privileges as possible._
- User Search Base **(required)**
- The LDAP base at which user accounts will be searched for.
- Example: `ou=Users,dc=mydomain,dc=com`
- User Filter **(required)**
- An LDAP filter declaring how to find the user record that is attempting to
authenticate. The `%s` matching parameter will be substituted with login
name given on sign-in form.
- Example: `(&(objectClass=posixAccount)(uid=%s))`
- Example for Microsoft Active Directory (AD): `(&(objectCategory=Person)(memberOf=CN=user-group,OU=example,DC=example,DC=org)(sAMAccountName=%s)(!(UserAccountControl:1.2.840.113556.1.4.803:=2)))`
- To substitute more than once, `%[1]s` should be used instead, e.g. when
matching supplied login name against multiple attributes such as user
identifier, email or even phone number.
- Example: `(&(objectClass=Person)(|(uid=%[1]s)(mail=%[1]s)(mobile=%[1]s)))`
- Enable user synchronization
- This option enables a periodic task that synchronizes the Forgejo users with
the LDAP server. The default period is every 24 hours but that can be
changed in the app.ini file. See the _cron.sync_external_users_ section in
the [sample
app.ini](https://codeberg.org/forgejo/forgejo/src/branch/forgejo/custom/conf/app.example.ini)
for detailed comments about that section. The _User Search Base_ and _User
Filter_ settings described above will limit which users can use Forgejo and
which users will be synchronized. When initially run the task will create
all LDAP users that match the given settings so take care if working with
large Enterprise LDAP directories.
### LDAP using simple auth
Adds the following fields:
- User DN **(required)**
- A template to use as the user's DN. The `%s` matching parameter will be
substituted with login name given on sign-in form.
- Example: `cn=%s,ou=Users,dc=mydomain,dc=com`
- Example: `uid=%s,ou=Users,dc=mydomain,dc=com`
- User Search Base (optional)
- The LDAP base at which user accounts will be searched for.
- Example: `ou=Users,dc=mydomain,dc=com`
- User Filter **(required)**
- An LDAP filter declaring when a user should be allowed to log in. The `%s`
matching parameter will be substituted with login name given on sign-in
form.
- Example: `(&(objectClass=posixAccount)(cn=%s))`
- Example: `(&(objectClass=posixAccount)(uid=%s))`
### Verify group membership in LDAP
Uses the following fields:
- Group Search Base (optional)
- The LDAP DN used for groups.
- Example: `ou=group,dc=mydomain,dc=com`
- Group Name Filter (optional)
- An LDAP filter declaring how to find valid groups in the above DN.
- Example: `(|(cn=forgejo_users)(cn=admins))`
- User Attribute in Group (optional)
- Which user LDAP attribute is listed in the group.
- Example: `uid`
- Group Attribute for User (optional)
- Which group LDAP attribute contains an array above user attribute names.
- Example: `memberUid`
## 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
automatically add users to the current database by testing them against PAM
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
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.
1. Once the database has been initialized, log in as the newly created
administrative user.
1. Navigate to the user setting (icon in top-right corner), and select
`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]
**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
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`
## SMTP (Simple Mail Transfer Protocol)
This option allows Forgejo to log in to an SMTP host as a Forgejo user. To
configure this, set the fields below:
- Authentication Name **(required)**
- A name to assign to the new method of authorization.
- SMTP Authentication Type **(required)**
- Type of authentication to use to connect to SMTP host, PLAIN or LOGIN.
- Host **(required)**
- The address where the SMTP host can be reached.
- Example: `smtp.mydomain.com`
- Port **(required)**
- The port to use when connecting to the server.
- Example: `587`
- Allowed Domains
- Restrict what domains can log in if using a public SMTP host or SMTP host
with multiple domains.
- Example: `forgejo.org,mydomain.com,mydomain2.com`
- Force SMTPS
- SMTPS will be used by default for connections to port 465, if you wish to use SMTPS
for other ports. Set this value.
- Otherwise if the server provides the `STARTTLS` extension this will be used.
- Skip TLS Verify
- Disable TLS verify on authentication.
- This Authentication Source is Activated
- Enable or disable this authentication source.
## FreeIPA
- In order to log in to Forgejo using FreeIPA credentials, a bind account needs to
be created for Forgejo:
- On the FreeIPA server, create a `forgejo.ldif` file, replacing `dc=example,dc=com`
with your DN, and provide an appropriately secure password:
```sh
dn: uid=forgejo,cn=sysaccounts,cn=etc,dc=example,dc=com
changetype: add
objectclass: account
objectclass: simplesecurityobject
uid: forgejo
userPassword: secure password
passwordExpirationTime: 20380119031407Z
nsIdleTimeout: 0
```
- Import the LDIF (change localhost to an IPA server if needed). A prompt for
Directory Manager password will be presented:
```sh
ldapmodify -h localhost -p 389 -x -D \
"cn=Directory Manager" -W -f forgejo.ldif
```
- Add an IPA group for forgejo_users :
```sh
ipa group-add --desc="Forgejo Users" forgejo_users
```
- Note: For errors about IPA credentials, run `kinit admin` and provide the
domain admin account password.
- Log in to Forgejo as an Administrator and click on "Authentication" under Admin Panel.
Then click `Add New Source` and fill in the details, changing all where appropriate.
## Reverse Proxy
Forgejo supports Reverse Proxy Header authentication, it will read headers as a trusted login user name or user email address. This hasn't been enabled by default, you can enable it with
```ini
[service]
ENABLE_REVERSE_PROXY_AUTHENTICATION = true
```
The default login user name is in the `X-WEBAUTH-USER` header, you can change it via changing `REVERSE_PROXY_AUTHENTICATION_USER` in app.ini. If the user doesn't exist, you can enable automatic registration with `ENABLE_REVERSE_PROXY_AUTO_REGISTRATION=true`.
The default login user email is `X-WEBAUTH-EMAIL`, you can change it via changing `REVERSE_PROXY_AUTHENTICATION_EMAIL` in app.ini, this could also be disabled with `ENABLE_REVERSE_PROXY_EMAIL`
If set `ENABLE_REVERSE_PROXY_FULL_NAME=true`, a user full name expected in `X-WEBAUTH-FULLNAME` will be assigned to the user when auto creating the user. You can also change the header name with `REVERSE_PROXY_AUTHENTICATION_FULL_NAME`.
You can also limit the reverse proxy's IP address range with `REVERSE_PROXY_TRUSTED_PROXIES` which default value is `127.0.0.0/8,::1/128`. By `REVERSE_PROXY_LIMIT`, you can limit trusted proxies level.
Notice: Reverse Proxy Auth doesn't support the API. You still need an access token or basic auth to make API requests.

536
admin/command-line.md Normal file
View file

@ -0,0 +1,536 @@
---
layout: '~/layouts/Markdown.astro'
title: 'Command Line'
---
## Usage
`forgejo [global options] command [command or global options] [arguments...]`
## Global options
All global options can be placed at the command level.
- `--help`, `-h`: Show help text and exit. Optional.
- `--version`, `-v`: Show version and exit. Optional. (example: `Forgejo version 1.19.0 built with: bindata, sqlite`).
- `--custom-path path`, `-C path`: Location of the Forgejo custom folder. Optional. (default: `AppWorkPath`/custom or `$FORGEJO_CUSTOM`).
- `--config path`, `-c path`: Forgejo configuration file path. Optional. (default: `custom`/conf/app.ini).
- `--work-path path`, `-w path`: Forgejo `AppWorkPath`. Optional. (default: location of the Forgejo binary or `$FORGEJO_WORK_DIR`)
NB: The defaults custom-path, config and work-path can also be
changed at build time (if preferred).
## Commands
### web
Starts the server:
- Options:
- `--port number`, `-p number`: Port number. Optional. (default: 3000). Overrides configuration file.
- `--install-port number`: Port number to run the install page on. Optional. (default: 3000). Overrides configuration file.
- `--pid path`, `-P path`: Pidfile path. Optional.
- `--quiet`, `-q`: Only emit Fatal logs on the console for logs emitted before logging set up.
- `--verbose`: Emit tracing logs on the console for logs emitted before logging is set-up.
- Examples:
- `forgejo web`
- `forgejo web --port 80`
- `forgejo web --config /etc/forgejo.ini --pid /some/custom/forgejo.pid`
- Notes:
- Forgejo should not be run as root. To bind to a port below 1024, you can use setcap on
Linux: `sudo setcap 'cap_net_bind_service=+ep' /path/to/forgejo`. This will need to be
redone every time you update Forgejo.
### admin
Admin operations:
- Commands:
- `user`:
- `list`:
- Options:
- `--admin`: List only admin users. Optional.
- Description: lists all users that exist
- Examples:
- `forgejo admin user list`
- `delete`:
- Options:
- `--email`: Email of the user to be deleted.
- `--username`: Username of user to be deleted.
- `--id`: ID of user to be deleted.
- One of `--id`, `--username` or `--email` is required. If more than one is provided then all have to match.
- Examples:
- `forgejo admin user delete --id 1`
- `create`:
- Options:
- `--username value`: Username. Required.
- `--password value`: Password. Required.
- `--email value`: Email. Required.
- `--admin`: If provided, this makes the user an admin. Optional.
- `--access-token`: If provided, an access token will be created for the user. Optional. (default: false).
- `--must-change-password`: If provided, the created user will be required to choose a newer password after the
initial login. Optional. (default: true).
- `--random-password`: If provided, a randomly generated password will be used as the password of the created
user. The value of `--password` will be discarded. Optional.
- `--random-password-length`: If provided, it will be used to configure the length of the randomly generated
password. Optional. (default: 12)
- Examples:
- `forgejo admin user create --username myname --password asecurepassword --email me@example.com`
- `change-password`:
- Options:
- `--username value`, `-u value`: Username. Required.
- `--password value`, `-p value`: New password. Required.
- Examples:
- `forgejo admin user change-password --username myname --password asecurepassword`
- `must-change-password`:
- Args:
- `[username...]`: Users that must change their passwords
- Options:
- `--all`, `-A`: Force a password change for all users
- `--exclude username`, `-e username`: Exclude the given user. Can be set multiple times.
- `--unset`: Revoke forced password change for the given users
- `regenerate`
- Options:
- `hooks`: Regenerate Git Hooks for all repositories
- `keys`: Regenerate authorized_keys file
- Examples:
- `forgejo admin regenerate hooks`
- `forgejo admin regenerate keys`
- `auth`:
- `list`:
- Description: lists all external authentication sources that exist
- Examples:
- `forgejo admin auth list`
- `delete`:
- Options:
- `--id`: ID of source to be deleted. Required.
- Examples:
- `forgejo admin auth delete --id 1`
- `add-oauth`:
- Options:
- `--name`: Application Name.
- `--provider`: OAuth2 Provider.
- `--key`: Client ID (Key).
- `--secret`: Client Secret.
- `--auto-discover-url`: OpenID Connect Auto Discovery URL (only required when using OpenID Connect as provider).
- `--use-custom-urls`: Use custom URLs for GitLab/GitHub OAuth endpoints.
- `--custom-tenant-id`: Use custom Tenant ID for OAuth endpoints.
- `--custom-auth-url`: Use a custom Authorization URL (option for GitLab/GitHub).
- `--custom-token-url`: Use a custom Token URL (option for GitLab/GitHub).
- `--custom-profile-url`: Use a custom Profile URL (option for GitLab/GitHub).
- `--custom-email-url`: Use a custom Email URL (option for GitHub).
- `--icon-url`: Custom icon URL for OAuth2 login source.
- `--skip-local-2fa`: Allow source to override local 2FA. (Optional)
- `--scopes`: Additional scopes to request for this OAuth2 source. (Optional)
- `--required-claim-name`: Claim name that has to be set to allow users to login with this source. (Optional)
- `--required-claim-value`: Claim value that has to be set to allow users to login with this source. (Optional)
- `--group-claim-name`: Claim name providing group names for this source. (Optional)
- `--admin-group`: Group Claim value for administrator users. (Optional)
- `--restricted-group`: Group Claim value for restricted users. (Optional)
- `--group-team-map`: JSON mapping between groups and org teams. (Optional)
- `--group-team-map-removal`: Activate automatic team membership removal depending on groups. (Optional)
- Examples:
- `forgejo admin auth add-oauth --name external-github --provider github --key OBTAIN_FROM_SOURCE --secret OBTAIN_FROM_SOURCE`
- `update-oauth`:
- Options:
- `--id`: ID of source to be updated. Required.
- `--name`: Application Name.
- `--provider`: OAuth2 Provider.
- `--key`: Client ID (Key).
- `--secret`: Client Secret.
- `--auto-discover-url`: OpenID Connect Auto Discovery URL (only required when using OpenID Connect as provider).
- `--use-custom-urls`: Use custom URLs for GitLab/GitHub OAuth endpoints.
- `--custom-tenant-id`: Use custom Tenant ID for OAuth endpoints.
- `--custom-auth-url`: Use a custom Authorization URL (option for GitLab/GitHub).
- `--custom-token-url`: Use a custom Token URL (option for GitLab/GitHub).
- `--custom-profile-url`: Use a custom Profile URL (option for GitLab/GitHub).
- `--custom-email-url`: Use a custom Email URL (option for GitHub).
- `--icon-url`: Custom icon URL for OAuth2 login source.
- `--skip-local-2fa`: Allow source to override local 2FA. (Optional)
- `--scopes`: Additional scopes to request for this OAuth2 source.
- `--required-claim-name`: Claim name that has to be set to allow users to login with this source. (Optional)
- `--required-claim-value`: Claim value that has to be set to allow users to login with this source. (Optional)
- `--group-claim-name`: Claim name providing group names for this source. (Optional)
- `--admin-group`: Group Claim value for administrator users. (Optional)
- `--restricted-group`: Group Claim value for restricted users. (Optional)
- Examples:
- `forgejo admin auth update-oauth --id 1 --name external-github-updated`
- `add-smtp`:
- Options:
- `--name`: Application Name. Required.
- `--auth-type`: SMTP Authentication Type (PLAIN/LOGIN/CRAM-MD5). Default to PLAIN.
- `--host`: SMTP host. Required.
- `--port`: SMTP port. Required.
- `--force-smtps`: SMTPS is always used on port 465. Set this to force SMTPS on other ports.
- `--skip-verify`: Skip TLS verify.
- `--helo-hostname`: Hostname sent with HELO. Leave blank to send current hostname.
- `--disable-helo`: Disable SMTP helo.
- `--allowed-domains`: Leave empty to allow all domains. Separate multiple domains with a comma (',').
- `--skip-local-2fa`: Skip 2FA to log on.
- `--active`: This Authentication Source is Activated.
Remarks:
`--force-smtps`, `--skip-verify`, `--disable-helo`, `--skip-loca-2fs` and `--active` options can be used in form:
- `--option`, `--option=true` to enable
- `--option=false` to disable
If those options are not specified value would not be changed in `update-smtp` or would use default `false` value in `add-smtp`
- Examples:
- `forgejo admin auth add-smtp --name ldap --host smtp.mydomain.org --port 587 --skip-verify --active`
- `update-smtp`:
- Options:
- `--id`: ID of source to be updated. Required.
- other options are shared with `add-smtp`
- Examples:
- `forgejo admin auth update-smtp --id 1 --host smtp.mydomain.org --port 587 --skip-verify=false`
- `forgejo admin auth update-smtp --id 1 --active=false`
- `add-ldap`: Add new LDAP (via Bind DN) authentication source
- Options:
- `--name value`: Authentication name. Required.
- `--not-active`: Deactivate the authentication source.
- `--security-protocol value`: Security protocol name. Required.
- `--skip-tls-verify`: Disable TLS verification.
- `--host value`: The address where the LDAP server can be reached. Required.
- `--port value`: The port to use when connecting to the LDAP server. Required.
- `--user-search-base value`: The LDAP base at which user accounts will be searched for. Required.
- `--user-filter value`: An LDAP filter declaring how to find the user record that is attempting to authenticate. Required.
- `--admin-filter value`: An LDAP filter specifying if a user should be given administrator privileges.
- `--restricted-filter value`: An LDAP filter specifying if a user should be given restricted status.
- `--username-attribute value`: The attribute of the user’s LDAP record containing the user name.
- `--firstname-attribute value`: The attribute of the user’s LDAP record containing the user’s first name.
- `--surname-attribute value`: The attribute of the user’s LDAP record containing the user’s surname.
- `--email-attribute value`: The attribute of the user’s LDAP record containing the user’s email address. Required.
- `--public-ssh-key-attribute value`: The attribute of the user’s LDAP record containing the user’s public ssh key.
- `--avatar-attribute value`: The attribute of the user’s LDAP record containing the user’s avatar.
- `--bind-dn value`: The DN to bind to the LDAP server with when searching for the user.
- `--bind-password value`: The password for the Bind DN, if any.
- `--attributes-in-bind`: Fetch attributes in bind DN context.
- `--synchronize-users`: Enable user synchronization.
- `--page-size value`: Search page size.
- Examples:
- `forgejo admin auth add-ldap --name ldap --security-protocol unencrypted --host mydomain.org --port 389 --user-search-base "ou=Users,dc=mydomain,dc=org" --user-filter "(&(objectClass=posixAccount)(uid=%s))" --email-attribute mail`
- `update-ldap`: Update existing LDAP (via Bind DN) authentication source
- Options:
- `--id value`: ID of authentication source. Required.
- `--name value`: Authentication name.
- `--not-active`: Deactivate the authentication source.
- `--security-protocol value`: Security protocol name.
- `--skip-tls-verify`: Disable TLS verification.
- `--host value`: The address where the LDAP server can be reached.
- `--port value`: The port to use when connecting to the LDAP server.
- `--user-search-base value`: The LDAP base at which user accounts will be searched for.
- `--user-filter value`: An LDAP filter declaring how to find the user record that is attempting to authenticate.
- `--admin-filter value`: An LDAP filter specifying if a user should be given administrator privileges.
- `--restricted-filter value`: An LDAP filter specifying if a user should be given restricted status.
- `--username-attribute value`: The attribute of the user’s LDAP record containing the user name.
- `--firstname-attribute value`: The attribute of the user’s LDAP record containing the user’s first name.
- `--surname-attribute value`: The attribute of the user’s LDAP record containing the user’s surname.
- `--email-attribute value`: The attribute of the user’s LDAP record containing the user’s email address.
- `--public-ssh-key-attribute value`: The attribute of the user’s LDAP record containing the user’s public ssh key.
- `--avatar-attribute value`: The attribute of the user’s LDAP record containing the user’s avatar.
- `--bind-dn value`: The DN to bind to the LDAP server with when searching for the user.
- `--bind-password value`: The password for the Bind DN, if any.
- `--attributes-in-bind`: Fetch attributes in bind DN context.
- `--synchronize-users`: Enable user synchronization.
- `--page-size value`: Search page size.
- Examples:
- `forgejo admin auth update-ldap --id 1 --name "my ldap auth source"`
- `forgejo admin auth update-ldap --id 1 --username-attribute uid --firstname-attribute givenName --surname-attribute sn`
- `add-ldap-simple`: Add new LDAP (simple auth) authentication source
- Options:
- `--name value`: Authentication name. Required.
- `--not-active`: Deactivate the authentication source.
- `--security-protocol value`: Security protocol name. Required.
- `--skip-tls-verify`: Disable TLS verification.
- `--host value`: The address where the LDAP server can be reached. Required.
- `--port value`: The port to use when connecting to the LDAP server. Required.
- `--user-search-base value`: The LDAP base at which user accounts will be searched for.
- `--user-filter value`: An LDAP filter declaring how to find the user record that is attempting to authenticate. Required.
- `--admin-filter value`: An LDAP filter specifying if a user should be given administrator privileges.
- `--restricted-filter value`: An LDAP filter specifying if a user should be given restricted status.
- `--username-attribute value`: The attribute of the user’s LDAP record containing the user name.
- `--firstname-attribute value`: The attribute of the user’s LDAP record containing the user’s first name.
- `--surname-attribute value`: The attribute of the user’s LDAP record containing the user’s surname.
- `--email-attribute value`: The attribute of the user’s LDAP record containing the user’s email address. Required.
- `--public-ssh-key-attribute value`: The attribute of the user’s LDAP record containing the user’s public ssh key.
- `--avatar-attribute value`: The attribute of the user’s LDAP record containing the user’s avatar.
- `--user-dn value`: The user’s DN. Required.
- Examples:
- `forgejo admin auth add-ldap-simple --name ldap --security-protocol unencrypted --host mydomain.org --port 389 --user-dn "cn=%s,ou=Users,dc=mydomain,dc=org" --user-filter "(&(objectClass=posixAccount)(cn=%s))" --email-attribute mail`
- `update-ldap-simple`: Update existing LDAP (simple auth) authentication source
- Options:
- `--id value`: ID of authentication source. Required.
- `--name value`: Authentication name.
- `--not-active`: Deactivate the authentication source.
- `--security-protocol value`: Security protocol name.
- `--skip-tls-verify`: Disable TLS verification.
- `--host value`: The address where the LDAP server can be reached.
- `--port value`: The port to use when connecting to the LDAP server.
- `--user-search-base value`: The LDAP base at which user accounts will be searched for.
- `--user-filter value`: An LDAP filter declaring how to find the user record that is attempting to authenticate.
- `--admin-filter value`: An LDAP filter specifying if a user should be given administrator privileges.
- `--restricted-filter value`: An LDAP filter specifying if a user should be given restricted status.
- `--username-attribute value`: The attribute of the user’s LDAP record containing the user name.
- `--firstname-attribute value`: The attribute of the user’s LDAP record containing the user’s first name.
- `--surname-attribute value`: The attribute of the user’s LDAP record containing the user’s surname.
- `--email-attribute value`: The attribute of the user’s LDAP record containing the user’s email address.
- `--public-ssh-key-attribute value`: The attribute of the user’s LDAP record containing the user’s public ssh key.
- `--avatar-attribute value`: The attribute of the user’s LDAP record containing the user’s avatar.
- `--user-dn value`: The user’s DN.
- Examples:
- `forgejo admin auth update-ldap-simple --id 1 --name "my ldap auth source"`
- `forgejo admin auth update-ldap-simple --id 1 --username-attribute uid --firstname-attribute givenName --surname-attribute sn`
### cert
Generates a self-signed SSL certificate. Outputs to `cert.pem` and `key.pem` in the current
directory and will overwrite any existing files.
- Options:
- `--host value`: Comma separated hostnames and ips which this certificate is valid for.
Wildcards are supported. Required.
- `--ecdsa-curve value`: ECDSA curve to use to generate a key. Optional. Valid options
are P224, P256, P384, P521.
- `--rsa-bits value`: Size of RSA key to generate. Optional. Ignored if --ecdsa-curve is
set. (default: 2048).
- `--start-date value`: Creation date. Optional. (format: `Jan 1 15:04:05 2011`).
- `--duration value`: Duration which the certificate is valid for. Optional. (default: 8760h0m0s)
- `--ca`: If provided, this cert generates it's own certificate authority. Optional.
- Examples:
- `forgejo cert --host git.example.com,example.com,www.example.com --ca`
### dump
Dumps all files and databases into a zip file. Outputs into a file like `forgejo-dump-1482906742.zip`
in the current directory.
- Options:
- `--file name`, `-f name`: Name of the dump file with will be created. Optional. (default: forgejo-dump-[timestamp].zip).
- `--tempdir path`, `-t path`: Path to the temporary directory used. Optional. (default: /tmp).
- `--skip-repository`, `-R`: Skip the repository dumping. Optional.
- `--skip-custom-dir`: Skip dumping of the custom dir. Optional.
- `--skip-lfs-data`: Skip dumping of LFS data. Optional.
- `--skip-attachment-data`: Skip dumping of attachment data. Optional.
- `--skip-package-data`: Skip dumping of package data. Optional.
- `--skip-log`: Skip dumping of log data. Optional.
- `--database`, `-d`: Specify the database SQL syntax. Optional.
- `--verbose`, `-V`: If provided, shows additional details. Optional.
- `--type`: Set the dump output format. Optional. (default: zip)
- Examples:
- `forgejo dump`
- `forgejo dump --verbose`
### generate
Generates random values and tokens for usage in configuration file. Useful for generating values
for automatic deployments.
- Commands:
- `secret`:
- Options:
- `INTERNAL_TOKEN`: Token used for an internal API call authentication.
- `JWT_SECRET`: LFS & OAUTH2 JWT authentication secret (LFS_JWT_SECRET is aliased to this option for backwards compatibility).
- `SECRET_KEY`: Global secret key.
- Examples:
- `forgejo generate secret INTERNAL_TOKEN`
- `forgejo generate secret JWT_SECRET`
- `forgejo generate secret SECRET_KEY`
### keys
Provides an SSHD AuthorizedKeysCommand. Needs to be configured in the sshd config file:
```ini
...
# The value of -e and the AuthorizedKeysCommandUser should match the
# username running Forgejo
AuthorizedKeysCommandUser git
AuthorizedKeysCommand /path/to/forgejo keys -e git -u %u -t %t -k %k
```
The command will return the appropriate authorized_keys line for the
provided key. You should also set the value
`SSH_CREATE_AUTHORIZED_KEYS_FILE=false` in the `[server]` section of
`app.ini`.
NB: opensshd requires the Forgejo program to be owned by root and not
writable by group or others. The program must be specified by an absolute
path.
NB: Forgejo must be running for this command to succeed.
### migrate
Migrates the database. This command can be used to run other commands before starting the server for the first time.
This command is idempotent.
### convert
Converts an existing MySQL database from utf8 to utf8mb4.
### doctor
Diagnose the problems of current Forgejo instance according the given configuration.
Currently there are a check list below:
- Check if OpenSSH authorized_keys file id correct
When your Forgejo instance support OpenSSH, your Forgejo instance binary path will be written to `authorized_keys`
when there is any public key added or changed on your Forgejo instance.
Sometimes if you moved or renamed your Forgejo binary when upgrade and you haven't run `Update the '.ssh/authorized_keys' file with Forgejo SSH keys. (Not needed for the built-in SSH server.)` on your Admin Panel. Then all pull/push via SSH will not be work.
This check will help you to check if it works well.
For contributors, if you want to add more checks, you can write a new function like `func(ctx *cli.Context) ([]string, error)` and
append it to `doctor.go`.
```go
var checklist = []check{
{
title: "Check if OpenSSH authorized_keys file id correct",
f: runDoctorLocationMoved,
},
// more checks please append here
}
```
This function will receive a command line context and return a list of details about the problems or error.
#### doctor recreate-table
Sometimes when there are migrations the old columns and default values may be left
unchanged in the database schema. This may lead to warning such as:
```
2020/08/02 11:32:29 ...rm/session_schema.go:360:Sync2() [W] Table user Column keep_activity_private db default is , struct default is 0
```
You can cause Forgejo to recreate these tables and copy the old data into the new table
with the defaults set appropriately by using:
```
forgejo doctor recreate-table user
```
You can ask Forgejo to recreate multiple tables using:
```
forgejo doctor recreate-table table1 table2 ...
```
And if you would like Forgejo to recreate all tables simply call:
```
forgejo doctor recreate-table
```
It is highly recommended to back-up your database before running these commands.
### manager
Manage running server operations:
- Commands:
- `shutdown`: Gracefully shutdown the running process
- `restart`: Gracefully restart the running process - (not implemented for windows servers)
- `flush-queues`: Flush queues in the running process
- Options:
- `--timeout value`: Timeout for the flushing process (default: 1m0s)
- `--non-blocking`: Set to true to not wait for flush to complete before returning
- `logging`: Adjust logging commands
- Commands:
- `pause`: Pause logging
- Notes:
- The logging level will be raised to INFO temporarily if it is below this level.
- Forgejo will buffer logs up to a certain point and will drop them after that point.
- `resume`: Resume logging
- `release-and-reopen`: Cause Forgejo to release and re-open files and connections used for logging (Equivalent to sending SIGUSR1 to Forgejo.)
- `remove name`: Remove the named logger
- Options:
- `--group group`, `-g group`: Set the group to remove the sublogger from. (defaults to `default`)
- `add`: Add a logger
- Commands:
- `console`: Add a console logger
- Options:
- `--group value`, `-g value`: Group to add logger to - will default to "default"
- `--name value`, `-n value`: Name of the new logger - will default to mode
- `--level value`, `-l value`: Logging level for the new logger
- `--stacktrace-level value`, `-L value`: Stacktrace logging level
- `--flags value`, `-F value`: Flags for the logger
- `--expression value`, `-e value`: Matching expression for the logger
- `--prefix value`, `-p value`: Prefix for the logger
- `--color`: Use color in the logs
- `--stderr`: Output console logs to stderr - only relevant for console
- `file`: Add a file logger
- Options:
- `--group value`, `-g value`: Group to add logger to - will default to "default"
- `--name value`, `-n value`: Name of the new logger - will default to mode
- `--level value`, `-l value`: Logging level for the new logger
- `--stacktrace-level value`, `-L value`: Stacktrace logging level
- `--flags value`, `-F value`: Flags for the logger
- `--expression value`, `-e value`: Matching expression for the logger
- `--prefix value`, `-p value`: Prefix for the logger
- `--color`: Use color in the logs
- `--filename value`, `-f value`: Filename for the logger -
- `--rotate`, `-r`: Rotate logs
- `--max-size value`, `-s value`: Maximum size in bytes before rotation
- `--daily`, `-d`: Rotate logs daily
- `--max-days value`, `-D value`: Maximum number of daily logs to keep
- `--compress`, `-z`: Compress rotated logs
- `--compression-level value`, `-Z value`: Compression level to use
- `conn`: Add a network connection logger
- Options:
- `--group value`, `-g value`: Group to add logger to - will default to "default"
- `--name value`, `-n value`: Name of the new logger - will default to mode
- `--level value`, `-l value`: Logging level for the new logger
- `--stacktrace-level value`, `-L value`: Stacktrace logging level
- `--flags value`, `-F value`: Flags for the logger
- `--expression value`, `-e value`: Matching expression for the logger
- `--prefix value`, `-p value`: Prefix for the logger
- `--color`: Use color in the logs
- `--reconnect-on-message`, `-R`: Reconnect to host for every message
- `--reconnect`, `-r`: Reconnect to host when connection is dropped
- `--protocol value`, `-P value`: Set protocol to use: tcp, unix, or udp (defaults to tcp)
- `--address value`, `-a value`: Host address and port to connect to (defaults to :7020)
- `smtp`: Add an SMTP logger
- Options:
- `--group value`, `-g value`: Group to add logger to - will default to "default"
- `--name value`, `-n value`: Name of the new logger - will default to mode
- `--level value`, `-l value`: Logging level for the new logger
- `--stacktrace-level value`, `-L value`: Stacktrace logging level
- `--flags value`, `-F value`: Flags for the logger
- `--expression value`, `-e value`: Matching expression for the logger
- `--prefix value`, `-p value`: Prefix for the logger
- `--color`: Use color in the logs
- `--username value`, `-u value`: Mail server username
- `--password value`, `-P value`: Mail server password
- `--host value`, `-H value`: Mail server host (defaults to: 127.0.0.1:25)
- `--send-to value`, `-s value`: Email address(es) to send to
- `--subject value`, `-S value`: Subject header of sent emails
- `processes`: Display Forgejo processes and goroutine information
- Options:
- `--flat`: Show processes as flat table rather than as tree
- `--no-system`: Do not show system processes
- `--stacktraces`: Show stacktraces for goroutines associated with processes
- `--json`: Output as json
- `--cancel PID`: Send cancel to process with PID. (Only for non-system processes.)
### dump-repo
Dump-repo dumps repository data from Forgejo/Git/GitHub/Gitea/GitLab:
- Options:
- `--git_service service` : Git service, it could be `git`, `github`, `gitea`, `gitlab`, If clone_addr could be recognized, this could be ignored.
- `--repo_dir <dir>`, `-r dir`: Repository dir path to store the data
- `--clone_addr <addr>`: The URL will be clone, currently could be a forgejo/git/github/gitea/gitlab http/https URL. e.g. https://codeberg.org/owner/repo.git
- `--auth_username <username>`: The username to visit the clone_addr
- `--auth_password <password>`: The password to visit the clone_addr
- `--auth_token <token>`: The personal token to visit the clone_addr
- `--owner_name <owner>`: The data will be stored on a directory with owner name if not empty
- `--repo_name <repo>`: The data will be stored on a directory with repository name if not empty
- `--units <units>`: Which items will be migrated, one or more units should be separated as comma. wiki, issues, labels, releases, release_assets, milestones, pull_requests, comments are allowed. Empty means all units.
### restore-repo
Restore-repo restore repository data from disk dir:
- Options:
- `--repo_dir <dir>`, `-r dir`: Repository dir path to restore from
- `--owner_name <owner>`: Restore destination owner name
- `--repo_name <repo>`: Restore destination repository name
- `--units <units>`: Which items will be restored, one or more units should be separated as comma. wiki, issues, labels, releases, release_assets, milestones, pull_requests, comments are allowed. Empty means all units.

1360
admin/config-cheat-sheet.md Normal file
View file

File diff suppressed because it is too large Load diff

98
admin/packages/cargo.md Normal file
View file

@ -0,0 +1,98 @@
---
layout: '~/layouts/Markdown.astro'
title: 'Cargo Packages Repository'
---
Publish [Cargo](https://doc.rust-lang.org/stable/cargo/) packages for your user or organization.
**Table of Contents**
{{< toc >}}
## Requirements
To work with the Cargo package registry, you need [Rust and Cargo](https://www.rust-lang.org/tools/install).
Cargo stores informations about the available packages in a package index stored in a git repository.
This repository is needed to work with the registry.
The following section describes how to create it.
## Index Repository
Cargo stores informations about the available packages in a package index stored in a git repository.
In Forgejo this repository has the special name `_cargo-index`.
After a package was uploaded, its metadata is automatically written to the index.
The content of this repository should not be manually modified.
The user or organization package settings page allows to create the index repository along with the configuration file.
If needed this action will rewrite the configuration file.
This can be useful if for example the Forgejo instance domain was changed.
If the case arises where the packages stored in Forgejo and the information in the index repository are out of sync, the settings page allows to rebuild the index repository.
This action iterates all packages in the registry and writes their information to the index.
If there are lot of packages this process may take some time.
## Configuring the package registry
To register the package registry the Cargo configuration must be updated.
Add the following text to the configuration file located in the current users home directory (for example `~/.cargo/config.toml`):
```
[registry]
default = "forgejo"
[registries.forgejo]
index = "https://forgejo.example.com/{owner}/_cargo-index.git"
[net]
git-fetch-with-cli = true
```
| Parameter | Description |
| --------- | ----------- |
| `owner` | The owner of the package. |
If the registry is private or you want to publish new packages, you have to configure your credentials.
Add the credentials section to the credentials file located in the current users home directory (for example `~/.cargo/credentials.toml`):
```
[registries.forgejo]
token = "Bearer {token}"
```
| Parameter | Description |
| --------- | ----------- |
| `token` | Your [personal access token]({{< relref "doc/developers/api-usage.en-us.md#authentication" >}}) |
## Publish a package
Publish a package by running the following command in your project:
```shell
cargo publish
```
You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first.
## Install a package
To install a package from the package registry, execute the following command:
```shell
cargo add {package_name}
```
| Parameter | Description |
| -------------- | ----------- |
| `package_name` | The package name. |
## Supported commands
```
cargo publish
cargo add
cargo install
cargo yank
cargo unyank
cargo search
```

85
admin/packages/chef.md Normal file
View file

@ -0,0 +1,85 @@
---
layout: '~/layouts/Markdown.astro'
title: 'Chef Packages Repository'
---
Publish [Chef](https://chef.io/) cookbooks for your user or organization.
**Table of Contents**
{{< toc >}}
## Requirements
To work with the Chef package registry, you have to use [`knife`](https://docs.chef.io/workstation/knife/).
## Authentication
The Chef package registry does not use an username:password authentication but signed requests with a private:public key pair.
Visit the package owner settings page to create the necessary key pair.
Only the public key is stored inside Forgejo. if you loose access to the private key you must re-generate the key pair.
[Configure `knife`](https://docs.chef.io/workstation/knife_setup/) to use the downloaded private key with your Forgejo username as `client_name`.
## Configure the package registry
To [configure `knife`](https://docs.chef.io/workstation/knife_setup/) to use the Forgejo package registry add the url to the `~/.chef/config.rb` file.
```
knife[:supermarket_site] = 'https://forgejo.example.com/api/packages/{owner}/chef'
```
| Parameter | Description |
| --------- | ----------- |
| `owner` | The owner of the package. |
## Publish a package
To publish a Chef package execute the following command:
```shell
knife supermarket share {package_name}
```
| Parameter | Description |
| -------------- | ----------- |
| `package_name` | The package name. |
You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first.
## Install a package
To install a package from the package registry, execute the following command:
```shell
knife supermarket install {package_name}
```
Optional you can specify the package version:
```shell
knife supermarket install {package_name} {package_version}
```
| Parameter | Description |
| ----------------- | ----------- |
| `package_name` | The package name. |
| `package_version` | The package version. |
## Delete a package
If you want to remove a package from the registry, execute the following command:
```shell
knife supermarket unshare {package_name}
```
Optional you can specify the package version:
```shell
knife supermarket unshare {package_name}/versions/{package_version}
```
| Parameter | Description |
| ----------------- | ----------- |
| `package_name` | The package name. |
| `package_version` | The package version. |

111
admin/packages/composer.md Normal file
View file

@ -0,0 +1,111 @@
---
layout: '~/layouts/Markdown.astro'
title: 'Composer Packages Repository'
---
Publish [Composer](https://getcomposer.org/) packages for your user or organization.
**Table of Contents**
{{< toc >}}
## Requirements
To work with the Composer package registry, you can use [Composer](https://getcomposer.org/download/) to consume and a HTTP upload client like `curl` to publish packages.
## Publish a package
To publish a Composer package perform a HTTP PUT operation with the package content in the request body.
The package content must be the zipped PHP project with the `composer.json` file.
You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first.
```
PUT https://forgejo.example.com/api/packages/{owner}/composer
```
| Parameter | Description |
| ---------- | ----------- |
| `owner` | The owner of the package. |
If the `composer.json` file does not contain a `version` property, you must provide it as a query parameter:
```
PUT https://forgejo.example.com/api/packages/{owner}/composer?version={x.y.z}
```
Example request using HTTP Basic authentication:
```shell
curl --user your_username:your_password_or_token \
--upload-file path/to/project.zip \
https://forgejo.example.com/api/packages/testuser/composer
```
Or specify the package version as query parameter:
```shell
curl --user your_username:your_password_or_token \
--upload-file path/to/project.zip \
https://forgejo.example.com/api/packages/testuser/composer?version=1.0.3
```
If you are using 2FA or OAuth use a [personal access token]({{< relref "doc/developers/api-usage.en-us.md#authentication" >}}) instead of the password.
The server responds with the following HTTP Status codes.
| HTTP Status Code | Meaning |
| ----------------- | ------- |
| `201 Created` | The package has been published. |
| `400 Bad Request` | The package name and/or version are invalid or a package with the same name and version already exist. |
## Configuring the package registry
To register the package registry you need to add it to the Composer `config.json` file (which can usually be found under `<user-home-dir>/.composer/config.json`):
```json
{
"repositories": [{
"type": "composer",
"url": "https://forgejo.example.com/api/packages/{owner}/composer"
}
]
}
```
To access the package registry using credentials, you must specify them in the `auth.json` file as follows:
```json
{
"http-basic": {
"forgejo.example.com": {
"username": "{username}",
"password": "{password}"
}
}
}
```
| Parameter | Description |
| ---------- | ----------- |
| `owner` | The owner of the package. |
| `username` | Your Forgejo username. |
| `password` | Your Forgejo password or a personal access token. |
## Install a package
To install a package from the package registry, execute the following command:
```shell
composer require {package_name}
```
Optional you can specify the package version:
```shell
composer require {package_name}:{package_version}
```
| Parameter | Description |
| ----------------- | ----------- |
| `package_name` | The package name. |
| `package_version` | The package version. |

90
admin/packages/conan.md Normal file
View file

@ -0,0 +1,90 @@
---
layout: '~/layouts/Markdown.astro'
title: 'Conan Packages Repository'
---
Publish [Conan](https://conan.io/) packages for your user or organization.
**Table of Contents**
{{< toc >}}
## Requirements
To work with the Conan package registry, you need to use the [conan](https://conan.io/downloads.html) command line tool to consume and publish packages.
## Configuring the package registry
To register the package registry you need to configure a new Conan remote:
```shell
conan remote add {remote} https://forgejo.example.com/api/packages/{owner}/conan
conan user --remote {remote} --password {password} {username}
```
| Parameter | Description |
| -----------| ----------- |
| `remote` | The remote name. |
| `username` | Your Forgejo username. |
| `password` | Your Forgejo password. If you are using 2FA or OAuth use a [personal access token]({{< relref "doc/developers/api-usage.en-us.md#authentication" >}}) instead of the password. |
| `owner` | The owner of the package. |
For example:
```shell
conan remote add forgejo https://forgejo.example.com/api/packages/testuser/conan
conan user --remote forgejo --password password123 testuser
```
## Publish a package
Publish a Conan package by running the following command:
```shell
conan upload --remote={remote} {recipe}
```
| Parameter | Description |
| ----------| ----------- |
| `remote` | The remote name. |
| `recipe` | The recipe to upload. |
For example:
```shell
conan upload --remote=forgejo ConanPackage/1.2@forgejo/final
```
The Forgejo Conan package registry has full [revision](https://docs.conan.io/en/latest/versioning/revisions.html) support.
## Install a package
To install a Conan package from the package registry, execute the following command:
```shell
conan install --remote={remote} {recipe}
```
| Parameter | Description |
| ----------| ----------- |
| `remote` | The remote name. |
| `recipe` | The recipe to download. |
For example:
```shell
conan install --remote=forgejo ConanPackage/1.2@forgejo/final
```
## Supported commands
```
conan install
conan get
conan info
conan search
conan upload
conan user
conan download
conan remove
```

74
admin/packages/conda.md Normal file
View file

@ -0,0 +1,74 @@
---
layout: '~/layouts/Markdown.astro'
title: 'Conda Packages Repository'
---
Publish [Conda](https://docs.conda.io/en/latest/) packages for your user or organization.
**Table of Contents**
{{< toc >}}
## Requirements
To work with the Conda package registry, you need to use [conda](https://docs.conda.io/projects/conda/en/stable/user-guide/install/index.html).
## Configuring the package registry
To register the package registry and provide credentials, edit your `.condarc` file:
```yaml
channel_alias: https://forgejo.example.com/api/packages/{owner}/conda
channels:
- https://forgejo.example.com/api/packages/{owner}/conda
default_channels:
- https://forgejo.example.com/api/packages/{owner}/conda
```
| Placeholder | Description |
| ------------ | ----------- |
| `owner` | The owner of the package. |
See the [official documentation](https://conda.io/projects/conda/en/latest/user-guide/configuration/use-condarc.html) for explanations of the individual settings.
If you need to provide credentials, you may embed them as part of the channel url (`https://user:password@forgejo.example.com/...`).
## Publish a package
To publish a package, perform a HTTP PUT operation with the package content in the request body.
```
PUT https://forgejo.example.com/api/packages/{owner}/conda/{channel}/{filename}
```
| Placeholder | Description |
| ------------ | ----------- |
| `owner` | The owner of the package. |
| `channel` | The [channel](https://conda.io/projects/conda/en/latest/user-guide/concepts/channels.html) of the package. (optional) |
| `filename` | The name of the file. |
Example request using HTTP Basic authentication:
```shell
curl --user your_username:your_password_or_token \
--upload-file path/to/package-1.0.conda \
https://forgejo.example.com/api/packages/testuser/conda/package-1.0.conda
```
You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first.
## Install a package
To install a package from the package registry, execute one of the following commands:
```shell
conda install {package_name}
conda install {package_name}={package_version}
conda install -c {channel} {package_name}
```
| Parameter | Description |
| ----------------- | ----------- |
| `package_name` | The package name. |
| `package_version` | The package version. |
| `channel` | The channel of the package. (optional) |

82
admin/packages/container.md Normal file
View file

@ -0,0 +1,82 @@
---
layout: '~/layouts/Markdown.astro'
title: 'Container Registry'
---
Publish [Open Container Initiative](https://opencontainers.org/) compliant images for your user or organization.
The container registry follows the OCI specs and supports all compatible images like [Docker](https://www.docker.com/) and [Helm Charts](https://helm.sh/).
**Table of Contents**
{{< toc >}}
## Requirements
To work with the Container registry, you can use the tools for your specific image type.
The following examples use the `docker` client.
## Login to the container registry
To push an image or if the image is in a private registry, you have to authenticate:
```shell
docker login forgejo.example.com
```
If you are using 2FA or OAuth use a [personal access token]({{< relref "doc/developers/api-usage.en-us.md#authentication" >}}) instead of the password.
## Image naming convention
Images must follow this naming convention:
`{registry}/{owner}/{image}`
For example, these are all valid image names for the owner `testuser`:
`forgejo.example.com/testuser/myimage`
`forgejo.example.com/testuser/my-image`
`forgejo.example.com/testuser/my/image`
**NOTE:** The registry only supports case-insensitive tag names. So `image:tag` and `image:Tag` get treated as the same image and tag.
## Push an image
Push an image by executing the following command:
```shell
docker push forgejo.example.com/{owner}/{image}:{tag}
```
| Parameter | Description |
| ----------| ----------- |
| `owner` | The owner of the image. |
| `image` | The name of the image. |
| `tag` | The tag of the image. |
For example:
```shell
docker push forgejo.example.com/testuser/myimage:latest
```
## Pull an image
Pull an image by executing the following command:
```shell
docker pull forgejo.example.com/{owner}/{image}:{tag}
```
| Parameter | Description |
| ----------| ----------- |
| `owner` | The owner of the image. |
| `image` | The name of the image. |
| `tag` | The tag of the image. |
For example:
```shell
docker pull forgejo.example.com/testuser/myimage:latest
```

136
admin/packages/generic.md Normal file
View file

@ -0,0 +1,136 @@
---
layout: '~/layouts/Markdown.astro'
title: 'Generic Packages Repository'
---
Publish generic files, like release binaries or other output, for your user or organization.
**Table of Contents**
{{< toc >}}
## Authenticate to the package registry
To authenticate to the Package Registry, you need to provide [custom HTTP headers or use HTTP Basic authentication]({{< relref "doc/developers/api-usage.en-us.md#authentication" >}}).
## Publish a package
To publish a generic package perform a HTTP PUT operation with the package content in the request body.
You cannot publish a file with the same name twice to a package. You must delete the existing package version first.
```
PUT https://forgejo.example.com/api/packages/{owner}/generic/{package_name}/{package_version}/{file_name}
```
| Parameter | Description |
| ----------------- | ----------- |
| `owner` | The owner of the package. |
| `package_name` | The package name. It can contain only lowercase letters (`a-z`), uppercase letter (`A-Z`), numbers (`0-9`), dots (`.`), hyphens (`-`), pluses (`+`), or underscores (`_`). |
| `package_version` | The package version, a non-empty string without trailing or leading whitespaces. |
| `file_name` | The filename. It can contain only lowercase letters (`a-z`), uppercase letter (`A-Z`), numbers (`0-9`), dots (`.`), hyphens (`-`), pluses (`+`), or underscores (`_`). |
Example request using HTTP Basic authentication:
```shell
curl --user your_username:your_password_or_token \
--upload-file path/to/file.bin \
https://forgejo.example.com/api/packages/testuser/generic/test_package/1.0.0/file.bin
```
If you are using 2FA or OAuth use a [personal access token]({{< relref "doc/developers/api-usage.en-us.md#authentication" >}}) instead of the password.
The server reponds with the following HTTP Status codes.
| HTTP Status Code | Meaning |
| ----------------- | ------- |
| `201 Created` | The package has been published. |
| `400 Bad Request` | The package name and/or version and/or file name are invalid. |
| `409 Conflict` | A file with the same name exist already in the package. |
## Download a package
To download a generic package perform a HTTP GET operation.
```
GET https://forgejo.example.com/api/packages/{owner}/generic/{package_name}/{package_version}/{file_name}
```
| Parameter | Description |
| ----------------- | ----------- |
| `owner` | The owner of the package. |
| `package_name` | The package name. |
| `package_version` | The package version. |
| `file_name` | The filename. |
The file content is served in the response body. The response content type is `application/octet-stream`.
Example request using HTTP Basic authentication:
```shell
curl --user your_username:your_token_or_password \
https://forgejo.example.com/api/packages/testuser/generic/test_package/1.0.0/file.bin
```
The server reponds with the following HTTP Status codes.
| HTTP Status Code | Meaning |
| ----------------- | ------- |
| `200 OK` | Success |
| `404 Not Found` | The package or file was not found. |
## Delete a package
To delete a generic package perform a HTTP DELETE operation. This will delete all files of this version.
```
DELETE https://forgejo.example.com/api/packages/{owner}/generic/{package_name}/{package_version}
```
| Parameter | Description |
| ----------------- | ----------- |
| `owner` | The owner of the package. |
| `package_name` | The package name. |
| `package_version` | The package version. |
Example request using HTTP Basic authentication:
```shell
curl --user your_username:your_token_or_password -X DELETE \
https://forgejo.example.com/api/packages/testuser/generic/test_package/1.0.0
```
The server reponds with the following HTTP Status codes.
| HTTP Status Code | Meaning |
| ----------------- | ------- |
| `204 No Content` | Success |
| `404 Not Found` | The package was not found. |
## Delete a package file
To delete a file of a generic package perform a HTTP DELETE operation. This will delete the package version too if there is no file left.
```
DELETE https://forgejo.example.com/api/packages/{owner}/generic/{package_name}/{package_version}/{filename}
```
| Parameter | Description |
| ----------------- | ----------- |
| `owner` | The owner of the package. |
| `package_name` | The package name. |
| `package_version` | The package version. |
| `filename` | The filename. |
Example request using HTTP Basic authentication:
```shell
curl --user your_username:your_token_or_password -X DELETE \
https://forgejo.example.com/api/packages/testuser/generic/test_package/1.0.0/file.bin
```
The server reponds with the following HTTP Status codes.
| HTTP Status Code | Meaning |
| ----------------- | ------- |
| `204 No Content` | Success |
| `404 Not Found` | The package or file was not found. |

56
admin/packages/helm.md Normal file
View file

@ -0,0 +1,56 @@
---
layout: '~/layouts/Markdown.astro'
title: 'Helm Chart Registry'
---
Publish [Helm](https://helm.sh/) charts for your user or organization.
**Table of Contents**
{{< toc >}}
## Requirements
To work with the Helm Chart registry use a simple HTTP client like `curl` or the [`helm cm-push`](https://github.com/chartmuseum/helm-push/) plugin.
## Publish a package
Publish a package by running the following command:
```shell
curl --user {username}:{password} -X POST --upload-file ./{chart_file}.tgz https://forgejo.example.com/api/packages/{owner}/helm/api/charts
```
or with the `helm cm-push` plugin:
```shell
helm repo add --username {username} --password {password} {repo} https://forgejo.example.com/api/packages/{owner}/helm
helm cm-push ./{chart_file}.tgz {repo}
```
| Parameter | Description |
| ------------ | ----------- |
| `username` | Your Forgejo username. |
| `password` | Your Forgejo password. If you are using 2FA or OAuth use a [personal access token]({{< relref "doc/developers/api-usage.en-us.md#authentication" >}}) instead of the password. |
| `repo` | The name for the repository. |
| `chart_file` | The Helm Chart archive. |
| `owner` | The owner of the package. |
## Install a package
To install a Helm char from the registry, execute the following command:
```shell
helm repo add --username {username} --password {password} {repo} https://forgejo.example.com/api/packages/{owner}/helm
helm repo update
helm install {name} {repo}/{chart}
```
| Parameter | Description |
| ---------- | ----------- |
| `username` | Your Forgejo username. |
| `password` | Your Forgejo password or a personal access token. |
| `repo` | The name for the repository. |
| `owner` | The owner of the package. |
| `name` | The local name. |
| `chart` | The name Helm Chart. |

109
admin/packages/maven.md Normal file
View file

@ -0,0 +1,109 @@
---
layout: '~/layouts/Markdown.astro'
title: 'Maven Packages Repository'
---
Publish [Maven](https://maven.apache.org) packages for your user or organization.
**Table of Contents**
{{< toc >}}
## Requirements
To work with the Maven package registry, you can use [Maven](https://maven.apache.org/install.html) or [Gradle](https://gradle.org/install/).
The following examples use `Maven`.
## Configuring the package registry
To register the package registry you first need to add your access token to the [`settings.xml`](https://maven.apache.org/settings.html) file:
```xml
<settings>
<servers>
<server>
<id>forgejo</id>
<configuration>
<httpHeaders>
<property>
<name>Authorization</name>
<value>token {access_token}</value>
</property>
</httpHeaders>
</configuration>
</server>
</servers>
</settings>
```
Afterwards add the following sections to your project `pom.xml` file:
```xml
<repositories>
<repository>
<id>forgejo</id>
<url>https://forgejo.example.com/api/packages/{owner}/maven</url>
</repository>
</repositories>
<distributionManagement>
<repository>
<id>forgejo</id>
<url>https://forgejo.example.com/api/packages/{owner}/maven</url>
</repository>
<snapshotRepository>
<id>forgejo</id>
<url>https://forgejo.example.com/api/packages/{owner}/maven</url>
</snapshotRepository>
</distributionManagement>
```
| Parameter | Description |
| -------------- | ----------- |
| `access_token` | Your [personal access token]({{< relref "doc/developers/api-usage.en-us.md#authentication" >}}). |
| `owner` | The owner of the package. |
## Publish a package
To publish a package simply run:
```shell
mvn deploy
```
If you want to publish a prebuild package to the registry, you can use [`mvn deploy:deploy-file`](https://maven.apache.org/plugins/maven-deploy-plugin/deploy-file-mojo.html):
```shell
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. |
You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first.
## Install a package
To install a Maven package from the package registry, add a new dependency to your project `pom.xml` file:
```xml
<dependency>
<groupId>com.test.package</groupId>
<artifactId>test_project</artifactId>
<version>1.0.0</version>
</dependency>
```
Afterwards run:
```shell
mvn install
```
## Supported commands
```
mvn install
mvn deploy
mvn dependency:get:
```

133
admin/packages/npm.md Normal file
View file

@ -0,0 +1,133 @@
---
layout: '~/layouts/Markdown.astro'
title: 'npm Packages Repository'
---
Publish [npm](https://www.npmjs.com/) packages for your user or organization.
**Table of Contents**
{{< toc >}}
## Requirements
To work with the npm package registry, you need [Node.js](https://nodejs.org/en/download/) coupled with a package manager such as [Yarn](https://classic.yarnpkg.com/en/docs/install) or [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm/) itself.
The registry supports [scoped](https://docs.npmjs.com/misc/scope/) and unscoped packages.
The following examples use the `npm` tool with the scope `@test`.
## Configuring the package registry
To register the package registry you need to configure a new package source.
```shell
npm config set {scope}:registry https://forgejo.example.com/api/packages/{owner}/npm/
npm config set -- '//forgejo.example.com/api/packages/{owner}/npm/:_authToken' "{token}"
```
| Parameter | Description |
| ------------ | ----------- |
| `scope` | The scope of the packages. |
| `owner` | The owner of the package. |
| `token` | Your [personal access token]({{< relref "doc/developers/api-usage.en-us.md#authentication" >}}). |
For example:
```shell
npm config set @test:registry https://forgejo.example.com/api/packages/testuser/npm/
npm config set -- '//forgejo.example.com/api/packages/testuser/npm/:_authToken' "personal_access_token"
```
or without scope:
```shell
npm config set registry https://forgejo.example.com/api/packages/testuser/npm/
npm config set -- '//forgejo.example.com/api/packages/testuser/npm/:_authToken' "personal_access_token"
```
## Publish a package
Publish a package by running the following command in your project:
```shell
npm publish
```
You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first.
## Unpublish a package
Delete a package by running the following command:
```shell
npm unpublish {package_name}[@{package_version}]
```
| Parameter | Description |
| ----------------- | ----------- |
| `package_name` | The package name. |
| `package_version` | The package version. |
For example:
```shell
npm unpublish @test/test_package
npm unpublish @test/test_package@1.0.0
```
## Install a package
To install a package from the package registry, execute the following command:
```shell
npm install {package_name}
```
| Parameter | Description |
| -------------- | ----------- |
| `package_name` | The package name. |
For example:
```shell
npm install @test/test_package
```
## Tag a package
The registry supports [version tags](https://docs.npmjs.com/adding-dist-tags-to-packages/) which can be managed by `npm dist-tag`:
```shell
npm dist-tag add {package_name}@{version} {tag}
```
| Parameter | Description |
| -------------- | ----------- |
| `package_name` | The package name. |
| `version` | The version of the package. |
| `tag` | The tag name. |
For example:
```shell
npm dist-tag add test_package@1.0.2 release
```
The tag name must not be a valid version. All tag names which are parsable as a version are rejected.
## Search packages
The registry supports [searching](https://docs.npmjs.com/cli/v7/commands/npm-search/) but does not support special search qualifiers like `author:forgejo`.
## Supported commands
```
npm install
npm ci
npm publish
npm unpublish
npm dist-tag
npm view
npm search
```

107
admin/packages/nuget.md Normal file
View file

@ -0,0 +1,107 @@
---
layout: '~/layouts/Markdown.astro'
title: 'NuGet Packages Repository'
---
Publish [NuGet](https://www.nuget.org/) packages for your user or organization. The package registry supports the V2 and V3 API protocol and you can work with [NuGet Symbol Packages](https://docs.microsoft.com/en-us/nuget/create-packages/symbol-packages-snupkg) too.
**Table of Contents**
{{< toc >}}
## Requirements
To work with the NuGet package registry, you can use command-line interface tools as well as NuGet features in various IDEs like Visual Studio.
More information about NuGet clients can be found in [the official documentation](https://docs.microsoft.com/en-us/nuget/install-nuget-client-tools).
The following examples use the `dotnet nuget` tool.
## Configuring the package registry
To register the package registry you need to configure a new NuGet feed source:
```shell
dotnet nuget add source --name {source_name} --username {username} --password {password} https://forgejo.example.com/api/packages/{owner}/nuget/index.json
```
| Parameter | Description |
| ------------- | ----------- |
| `source_name` | The desired source name. |
| `username` | Your Forgejo username. |
| `password` | Your Forgejo password. If you are using 2FA or OAuth use a [personal access token]({{< relref "doc/developers/api-usage.en-us.md#authentication" >}}) instead of the password. |
| `owner` | The owner of the package. |
For example:
```shell
dotnet nuget add source --name forgejo --username testuser --password password123 https://forgejo.example.com/api/packages/testuser/nuget/index.json
```
You can add the source without credentials and use the [`--api-key`](https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-nuget-push) parameter when publishing packages. In this case you need to provide a [personal access token]({{< relref "doc/developers/api-usage.en-us.md#authentication" >}}).
## Publish a package
Publish a package by running the following command:
```shell
dotnet nuget push --source {source_name} {package_file}
```
| Parameter | Description |
| -------------- | ----------- |
| `source_name` | The desired source name. |
| `package_file` | Path to the package `.nupkg` file. |
For example:
```shell
dotnet nuget push --source forgejo test_package.1.0.0.nupkg
```
You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first.
### Symbol Packages
The NuGet package registry has build support for a symbol server. The PDB files embedded in a symbol package (`.snupkg`) can get requested by clients.
To do so, register the NuGet package registry as symbol source:
```
https://forgejo.example.com/api/packages/{owner}/nuget/symbols
```
| Parameter | Description |
| --------- | ----------- |
| `owner` | The owner of the package registry. |
For example:
```
https://forgejo.example.com/api/packages/testuser/nuget/symbols
```
## Install a package
To install a NuGet package from the package registry, execute the following command:
```shell
dotnet add package --source {source_name} --version {package_version} {package_name}
```
| Parameter | Description |
| ----------------- | ----------- |
| `source_name` | The desired source name. |
| `package_name` | The package name. |
| `package_version` | The package version. |
For example:
```shell
dotnet add package --source forgejo --version 1.0.0 test_package
```
## Supported commands
```
dotnet add
dotnet nuget push
dotnet nuget delete
```

92
admin/packages/overview.md Normal file
View file

@ -0,0 +1,92 @@
---
layout: '~/layouts/Markdown.astro'
title: 'Package Registry'
---
**Table of Contents**
{{< toc >}}
## Supported package managers
The following package managers are currently supported:
| Name | Language | Package client |
| ---- | -------- | -------------- |
| [Cargo]({{< relref "doc/packages/cargo.en-us.md" >}}) | Rust | `cargo` |
| [Chef]({{< relref "doc/packages/chef.en-us.md" >}}) | - | `knife` |
| [Composer]({{< relref "doc/packages/composer.en-us.md" >}}) | PHP | `composer` |
| [Conan]({{< relref "doc/packages/conan.en-us.md" >}}) | C++ | `conan` |
| [Conda]({{< relref "doc/packages/conda.en-us.md" >}}) | - | `conda` |
| [Container]({{< relref "doc/packages/container.en-us.md" >}}) | - | any OCI compliant client |
| [Generic]({{< relref "doc/packages/generic.en-us.md" >}}) | - | any HTTP client |
| [Helm]({{< relref "doc/packages/helm.en-us.md" >}}) | - | any HTTP client, `cm-push` |
| [Maven]({{< relref "doc/packages/maven.en-us.md" >}}) | Java | `mvn`, `gradle` |
| [npm]({{< relref "doc/packages/npm.en-us.md" >}}) | JavaScript | `npm`, `yarn`, `pnpm` |
| [NuGet]({{< relref "doc/packages/nuget.en-us.md" >}}) | .NET | `nuget` |
| [Pub]({{< relref "doc/packages/pub.en-us.md" >}}) | Dart | `dart`, `flutter` |
| [PyPI]({{< relref "doc/packages/pypi.en-us.md" >}}) | Python | `pip`, `twine` |
| [RubyGems]({{< relref "doc/packages/rubygems.en-us.md" >}}) | Ruby | `gem`, `Bundler` |
| [Vagrant]({{< relref "doc/packages/vagrant.en-us.md" >}}) | - | `vagrant` |
**The following paragraphs only apply if Packages are not globally disabled!**
## Repository-Packages
A package always belongs to an owner (a user or organisation), not a repository.
To link an (already uploaded) package to a repository, open the settings page
on that package and choose a repository to link this package to.
The entire package will be linked, not just a single version.
Linking a package results in showing that package in the repository's package list,
and shows a link to the repository on the package site (as well as a link to the repository issues).
## Access Restrictions
| 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 |
N.B.: These access restrictions are subject to change, where more finegrained control will be added via a dedicated organization team permission.
## Create or upload a package
Depending on the type of package, use the respective package-manager for that. Check out the sub-page of a specific package manager for instructions.
## View packages
You can view the packages of a repository on the repository page.
1. Go to the repository.
1. Go to **Packages** in the navigation bar.
To view more details about a package, select the name of the package.
## Download a package
To download a package from your repository:
1. Go to **Packages** in the navigation bar.
1. Select the name of the package to view the details.
1. In the **Assets** section, select the name of the package file you want to download.
## Delete a package
You cannot edit a package after you have published it in the Package Registry. Instead, you
must delete and recreate it.
To delete a package from your repository:
1. Go to **Packages** in the navigation bar.
1. Select the name of the package to view the details.
1. Click **Delete package** to permanently delete the package.
## Disable the Package Registry
The Package Registry is automatically enabled. To disable it for a single repository:
1. Go to **Settings** in the navigation bar.
1. Disable **Enable Repository Packages Registry**.
Previously published packages are not deleted by disabling the Package Registry.

72
admin/packages/pub.md Normal file
View file

@ -0,0 +1,72 @@
---
layout: '~/layouts/Markdown.astro'
title: 'Pub Packages Repository'
---
Publish [Pub](https://dart.dev/guides/packages) packages for your user or organization.
**Table of Contents**
{{< toc >}}
## Requirements
To work with the Pub package registry, you need to use the tools [dart](https://dart.dev/tools/dart-tool) and/or [flutter](https://docs.flutter.dev/reference/flutter-cli).
The following examples use dart.
## Configuring the package registry
To register the package registry and provide credentials, execute:
```shell
dart pub token add https://forgejo.example.com/api/packages/{owner}/pub
```
| Placeholder | Description |
| ------------ | ----------- |
| `owner` | The owner of the package. |
You need to provide your [personal access token]({{< relref "doc/developers/api-usage.en-us.md#authentication" >}}).
## Publish a package
To publish a package, edit the `pubspec.yaml` and add the following line:
```yaml
publish_to: https://forgejo.example.com/api/packages/{owner}/pub
```
| Placeholder | Description |
| ------------ | ----------- |
| `owner` | The owner of the package. |
Now you can publish the package by running the following command:
```shell
dart pub publish
```
You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first.
## Install a package
To install a Pub package from the package registry, execute the following command:
```shell
dart pub add {package_name} --hosted-url=https://forgejo.example.com/api/packages/{owner}/pub/
```
| Parameter | Description |
| ----------------- | ----------- |
| `owner` | The owner of the package. |
| `package_name` | The package name. |
For example:
```shell
# use latest version
dart pub add mypackage --hosted-url=https://forgejo.example.com/api/packages/testuser/pub/
# specify version
dart pub add mypackage:1.0.8 --hosted-url=https://forgejo.example.com/api/packages/testuser/pub/
```

76
admin/packages/pypi.md Normal file
View file

@ -0,0 +1,76 @@
---
layout: '~/layouts/Markdown.astro'
title: 'PyPI Packages Repository'
---
Publish [PyPI](https://pypi.org/) packages for your user or organization.
**Table of Contents**
{{< toc >}}
## Requirements
To work with the PyPI package registry, you need to use the tools [pip](https://pypi.org/project/pip/) to consume and [twine](https://pypi.org/project/twine/) to publish packages.
## Configuring the package registry
To register the package registry you need to edit your local `~/.pypirc` file. Add
```ini
[distutils]
index-servers = forgejo
[forgejo]
repository = https://forgejo.example.com/api/packages/{owner}/pypi
username = {username}
password = {password}
```
| Placeholder | Description |
| ------------ | ----------- |
| `owner` | The owner of the package. |
| `username` | Your Forgejo username. |
| `password` | Your Forgejo password. If you are using 2FA or OAuth use a [personal access token]({{< relref "doc/developers/api-usage.en-us.md#authentication" >}}) instead of the password. |
## Publish a package
Publish a package by running the following command:
```shell
python3 -m twine upload --repository forgejo /path/to/files/*
```
The package files have the extensions `.tar.gz` and `.whl`.
You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first.
## Install a package
To install a PyPI package from the package registry, execute the following command:
```shell
pip install --index-url https://{username}:{password}@forgejo.example.com/api/packages/{owner}/pypi/simple --no-deps {package_name}
```
| Parameter | Description |
| ----------------- | ----------- |
| `username` | Your Forgejo username. |
| `password` | Your Forgejo password or a personal access token. |
| `owner` | The owner of the package. |
| `package_name` | The package name. |
For example:
```shell
pip install --index-url https://testuser:password123@forgejo.example.com/api/packages/testuser/pypi/simple --no-deps test_package
```
You can use `--extra-index-url` instead of `--index-url` but that makes you vulnerable to dependency confusion attacks because `pip` checks the official PyPi repository for the package before it checks the specified custom repository. Read the `pip` docs for more information.
## Supported commands
```
pip install
twine upload
```

116
admin/packages/rubygems.md Normal file
View file

@ -0,0 +1,116 @@
---
layout: '~/layouts/Markdown.astro'
title: 'RubyGems Packages Repository'
---
Publish [RubyGems](https://guides.rubygems.org/) packages for your user or organization.
**Table of Contents**
{{< toc >}}
## Requirements
To work with the RubyGems package registry, you need to use the [gem](https://guides.rubygems.org/command-reference/) command line tool to consume and publish packages.
## Configuring the package registry
To register the package registry edit the `~/.gem/credentials` file and add:
```ini
---
https://forgejo.example.com/api/packages/{owner}/rubygems: Bearer {token}
```
| Parameter | Description |
| ------------- | ----------- |
| `owner` | The owner of the package. |
| `token` | Your [personal access token]({{< relref "doc/developers/api-usage.en-us.md#authentication" >}}). |
For example:
```
---
https://forgejo.example.com/api/packages/testuser/rubygems: Bearer 3bd626f84b01cd26b873931eace1e430a5773cc4
```
## Publish a package
Publish a package by running the following command:
```shell
gem push --host {host} {package_file}
```
| Parameter | Description |
| -------------- | ----------- |
| `host` | URL to the package registry. |
| `package_file` | Path to the package `.gem` file. |
For example:
```shell
gem push --host https://forgejo.example.com/api/packages/testuser/rubygems test_package-1.0.0.gem
```
You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first.
## Install a package
To install a package from the package registry you can use [Bundler](https://bundler.io) or `gem`.
### Bundler
Add a new `source` block to your `Gemfile`:
```
source "https://forgejo.example.com/api/packages/{owner}/rubygems" do
gem "{package_name}"
end
```
| Parameter | Description |
| ----------------- | ----------- |
| `owner` | The owner of the package. |
| `package_name` | The package name. |
For example:
```
source "https://forgejo.example.com/api/packages/testuser/rubygems" do
gem "test_package"
end
```
Afterwards run the following command:
```shell
bundle install
```
### gem
Execute the following command:
```shell
gem install --host https://forgejo.example.com/api/packages/{owner}/rubygems {package_name}
```
| Parameter | Description |
| ----------------- | ----------- |
| `owner` | The owner of the package. |
| `package_name` | The package name. |
For example:
```shell
gem install --host https://forgejo.example.com/api/packages/testuser/rubygems test_package
```
## Supported commands
```
gem install
bundle install
gem push
```

73
admin/packages/storage.md Normal file
View file

@ -0,0 +1,73 @@
---
layout: '~/layouts/Markdown.astro'
title: 'Storage'
---
This document describes the storage of the package registry and how it can be managed.
**Table of Contents**
{{< toc >}}
## Deduplication
The package registry has a build-in deduplication of uploaded blobs.
If two identical files are uploaded only one blob is saved on the filesystem.
This ensures no space is wasted for duplicated files.
If two packages are uploaded with identical files, both packages will display the same size but on the filesystem they require only half of the size.
Whenever a package gets deleted only the references to the underlaying blobs are removed.
The blobs get not removed at this moment, so they still require space on the filesystem.
When a new package gets uploaded the existing blobs may get referenced again.
These unreferenced blobs get deleted by a [clean up job]({{< relref "doc/advanced/config-cheat-sheet.en-us.md#cron---cleanup-expired-packages-croncleanup_packages" >}}).
The config setting `OLDER_THAN` configures how long unreferenced blobs are kept before they get deleted.
## Cleanup Rules
Package registries can become large over time without cleanup.
It's recommended to delete unnecessary packages and set up cleanup rules to automatically manage the package registry usage.
Every package owner (user or organization) manages the cleanup rules which are applied to their packages.
|Setting|Description|
|-|-|
|Enabled|Turn the cleanup rule on or off.|
|Type|Every rule manages a specific package type.|
|Apply pattern to full package name|If enabled, the patterns below are applied to the full package name (`package/version`). Otherwise only the version (`version`) is used.|
|Keep the most recent|How many versions to *always* keep for each package.|
|Keep versions matching|The regex pattern that determines which versions to keep. An empty pattern keeps no version while `.+` keeps all versions. The container registry will always keep the `latest` version even if not configured.|
|Remove versions older than|Remove only versions older than the selected days.|
|Remove versions matching|The regex pattern that determines which versions to remove. An empty pattern or `.+` leads to the removal of every package if no other setting tells otherwise.|
Every cleanup rule can show a preview of the affected packages.
This can be used to check if the cleanup rules is proper configured.
### Regex examples
Regex patterns are automatically surrounded with `\A` and `\z` anchors.
Do not include any `\A`, `\z`, `^` or `$` token in the regex patterns as they are not necessary.
The patterns are case-insensitive which matches the behaviour of the package registry in Forgejo.
|Pattern|Description|
|-|-|
|`.*`|Match every possible version.|
|`v.+`|Match versions that start with `v`.|
|`release`|Match only the version `release`.|
|`release.*`|Match versions that are either named or start with `release`.|
|`.+-temp-.+`|Match versions that contain `-temp-`.|
|`v.+\|release`|Match versions that either start with `v` or are named `release`.|
|`package/v.+\|other/release`|Match versions of the package `package` that start with `v` or the version `release` of the package `other`. This needs the setting *Apply pattern to full package name* enabled.|
### How the cleanup rules work
The cleanup rules are part of the [clean up job]({{< relref "doc/advanced/config-cheat-sheet.en-us.md#cron---cleanup-expired-packages-croncleanup_packages" >}}) and run periodically.
The cleanup rule:
1. Collects all packages of the package type for the owners registry.
1. For every package it collects all versions.
1. Excludes from the list the # versions based on the *Keep the most recent* value.
1. Excludes from the list any versions matching the *Keep versions matching* value.
1. Excludes from the list the versions more recent than the *Remove versions older than* value.
1. Excludes from the list any versions not matching the *Remove versions matching* value.
1. Deletes the remaining versions.

67
admin/packages/vagrant.md Normal file
View file

@ -0,0 +1,67 @@
---
layout: '~/layouts/Markdown.astro'
title: 'Vagrant Packages Repository'
---
Publish [Vagrant](https://www.vagrantup.com/) packages for your user or organization.
**Table of Contents**
{{< toc >}}
## Requirements
To work with the Vagrant package registry, you need [Vagrant](https://www.vagrantup.com/downloads) and a tool to make HTTP requests like `curl`.
## Publish a package
Publish a Vagrant box by performing a HTTP PUT request to the registry:
```
PUT https://forgejo.example.com/api/packages/{owner}/vagrant/{package_name}/{package_version}/{provider}.box
```
| Parameter | Description |
| ----------------- | ----------- |
| `owner` | The owner of the package. |
| `package_name` | The package name. |
| `package_version` | The package version, semver compatible. |
| `provider` | One of the [supported provider names](https://www.vagrantup.com/docs/providers). |
Example for uploading a Hyper-V box:
```shell
curl --user your_username:your_password_or_token \
--upload-file path/to/your/vagrant.box \
https://forgejo.example.com/api/packages/testuser/vagrant/test_system/1.0.0/hyperv.box
```
You cannot publish a box if a box of the same name, version and provider already exists. You must delete the existing package first.
## Install a package
To install a box from the package registry, execute the following command:
```shell
vagrant box add "https://forgejo.example.com/api/packages/{owner}/vagrant/{package_name}"
```
| Parameter | Description |
| -------------- | ----------- |
| `owner` | The owner of the package. |
| `package_name` | The package name. |
For example:
```shell
vagrant box add "https://forgejo.example.com/api/packages/testuser/vagrant/test_system"
```
This will install the latest version of the package. To add a specific version, use the `--box-version` parameter.
If the registry is private you can pass your [personal access token]({{< relref "doc/developers/api-usage.en-us.md#authentication" >}}) in the `VAGRANT_CLOUD_TOKEN` environment variable.
## Supported commands
```
vagrant box add
```

107
admin/upgrade.md Normal file
View file

@ -0,0 +1,107 @@
---
layout: '~/layouts/Markdown.astro'
title: "Forgejo upgrade guide"
---
This guide helps Forgejo admins perform upgrades safely and provides guidance to troubleshoot problems. It covers upgrades from Gitea back to version 1.2.0.
### Backup
To be safe, make sure to perform a full backup before upgrading. It is a requirement when upgrading to a new stable release (going from v1.18 to v1.19 for instance) but is also a good precaution when installing a patch release (going from v1.18.3-1 to v1.18.3-2 for instance).
The reliable way to perform a backup is with a synchronized point-in-time snapshot of all the storage used by Forgejo.
For instance, if everything (SQLite database + repositories etc.) is on a single QCOW2 disk attached to a virtual machine, a [qemu snapshot](https://wiki.qemu.org/Features/Snapshots) guarantees the backup is consistent and can be done while the Forgejo server is running.
However, if Forgejo uses a S3 storage for attachments with a PostgresQL database, stores Git repositories on a remote file system and queues in a Redis server, the only way to ensure a consistent state is to shutdown Forgejo during the backup.
In the simplest case where everything is on a single file system and if the instance is not busy (no mirrors, no users), the backup can be done with:
* `forgejo dump` to collect everything into one zip file
* `psql/mysql/sqlite dump`. Although the zip file created by `forgejo dump` contains a copy of the database it has serious long standing open bugs that may introduce problems when re-injecting the SQL dump in a new database.
### Verify Forgejo works
It is **critical** to verify that Forgejo works very carefully. Restoring the backup done before the upgrade is easy and does not loose any information. But if a problem is discovered days or weeks after the upgrade, it will not be an option and fixing it on a live Forgejo instance will be much more challenging.
* Run `forgejo doctor --all --log-file /tmp/doctor.log` and make sure it does not report any problem.
* Manually verify via the web interface. Making a checklist of a typical use case is a good way to not miss anything.
* If there is a problem of any kind, increase the log level and take a look at the logs. If you cannot figure out what the problem is, ask for help [in the Forgejo chatroom](https://matrix.to/#/#forgejo-chat:matrix.org) before trying to fix it.
### Preparing the Forgejo upgrade
* Manually analyze (reading the patches to the sources of the template directory) and update the customized CSS / content.
* Do not use `forgejo help` to figure out the location of `CustomPath`, look at the configuration tab of the `Site administration` panel when logged in as an admin.
* `forgejo manager flush-queues`. If it timesout, run it again with a more generous `--timeout` argument. It is important because the queues contain serialized data that is not guaranteed to be backward compatible between versions.
* Go to the `Site administration` panel and pause all queues
Note: Forgejo requires [docker >= 20.10.6](https://wiki.alpinelinux.org/wiki/Release_Notes_for_Alpine_3.14.0) otherwise mysterious problems will happen (mysterious in the sense that the problem will about something unrelated to the Docker version").
### Performing the upgrade
* If the upgrade is from a Gitea version [lower than 1.6](https://github.com/go-gitea/gitea/blob/e82db15cfa0d1cd85ee493128960a481eb44271c/models/migrations/migrations.go#L63) and greater or equal to 1.2.0, proceed as follows:
* Upgrade to 1.2.3 and manually verify it runs
* Upgrade to 1.4.3 and manually verify it runs
* Upgrade to 1.5.3 and manually verify it runs
* Upgrade to 1.6.4 and manually verify it runs
* If the upgrade is from a Gitea version greater or equal to 1.6.4 that is not mentioned to be problematic below, upgrade directly to the latest stable Forgejo version, there is no need to upgrade to intermediate versions.
* Verify Forgejo works
### Troubleshooting
* Increase the log level with `forgejo manager logging add console -n traceconsole -l TRACE -e '((modules/git)|(services/mirror))'`
* If the upgrade from version x.y to version x.y+2 fails and there is a need to narrow down the problem, try upgrading to the latest minor version of each major version and verify it works. It will show which major version causes the issue and help debug the problem. For instance, if upgrading from Forgejo 1.18.2-0 to Forgejo 1.19.0-0 does not work:
* Upgrade from Forgejo 1.18.2 to Forgejo 1.18.5 (the last minor version of the 1.18 major version) and verify Forgejo works.
* Upgrade to Forgejo 1.19.0-0 (the last minor version of the 1.19 major version) and verify Forgejo works.
#### Unexpected database version
The database version is stored in the database and can be retrieved with **select * from version**. If the version found in the database does not match what is in the following table, it probably means the instance was installed from the development tree instead of a package and **the database may be in a state that has not been tested for upgrades**.
| Forgejo version | Date | Database |
| ----------------| ---- | -------- |
|[1.18.5-0](https://codeberg.org/forgejo/forgejo/src/branch/forgejo/RELEASE-NOTES.md#1-18-5-0) | February 2023 | v231 |
| Gitea version | Date | Database |
| --------------| ---- | -------- |
|[1.17.4](https://github.com/go-gitea/gitea/releases/tag/v1.17.4) | December 2022 | v224 |
|[1.16.9](https://github.com/go-gitea/gitea/releases/tag/v1.16.9) | July 2022 | v211 |
|[1.15.11](https://github.com/go-gitea/gitea/releases/tag/v1.15.11) | January 2022| v189 |
|[1.14.7](https://github.com/go-gitea/gitea/releases/tag/v1.14.7) | September 2021| v178 |
|[1.13.7](https://github.com/go-gitea/gitea/releases/tag/v1.13.7) | April 2021| v156 *Note that [the comment in the source](https://github.com/go-gitea/gitea/blob/63f6e6c0bd6a5314b76b7598dee77ceee1dde81a/models/migrations/migrations.go#L257) incorrectly mention it should be v155.* |
|[1.12.6](https://github.com/go-gitea/gitea/releases/tag/v1.12.6) | November 2020| v141 *Note that [the comment in the source](https://github.com/go-gitea/gitea/blob/63f6e6c0bd6a5314b76b7598dee77ceee1dde81a/models/migrations/migrations.go#L224) incorrectly mention it should be v140.* |
|[1.11.8](https://github.com/go-gitea/gitea/releases/tag/v1.11.8) | June 2020| v118 *Note that [the comment in the source](https://github.com/go-gitea/gitea/blob/63f6e6c0bd6a5314b76b7598dee77ceee1dde81a/models/migrations/migrations.go#L175) incorrectly mention it should be v117.* |
|[1.10.6](https://github.com/go-gitea/gitea/releases/tag/v1.10.6) | March 2020| v103 *Note that [the comment in the source](https://github.com/go-gitea/gitea/blob/63f6e6c0bd6a5314b76b7598dee77ceee1dde81a/models/migrations/migrations.go#L142) incorrectly mention it should be v102.* |
|[1.9.6](https://github.com/go-gitea/gitea/releases/tag/v1.9.6) | November 2019| v89 *Note that [the comment in the source](https://github.com/go-gitea/gitea/blob/63f6e6c0bd6a5314b76b7598dee77ceee1dde81a/models/migrations/migrations.go#L111) incorrectly mention it should be v88.* |
#### When upgrading from a specific version...
* Any version before [Gitea 1.17](https://github.com/go-gitea/gitea/releases/tag/v1.17.4)
* preserve a custom gitconfig: [episode 1](https://gna.org/blog/1-17-breaking-episode-1/), [episode 2](https://gna.org/blog/1-17-breaking-episode-2/)
* [Gitea 1.13.0](https://blog.gitea.io/2020/12/gitea-1.13.0-is-released/)
* The Webhook shared secret inside the webhook payload has been deprecated and will be removed in 1.14.0: https://github.com/go-gitea/gitea/issues/11755 please use the secret header that uses an hmac signature to validate the webhook payload.
* Git hooks now default to `off`! ([#13058](https://github.com/go-gitea/gitea/pull/13058))
In your config, you can check the security section for `DISABLE_GIT_HOOKS`. To enable them again, you must set the setting to `false`.
### Only when upgrading to a specific version
* [1.15.2](https://blog.gitea.io/2021/09/gitea-1.15.2-is-released/)
* Unfortunately following the release of 1.15.1 it has become apparent that there is an issue with upgrading from 1.15.0 to 1.15.1 due to problem with a table constraint that was unexpectedly automatically dropped. Users who upgraded straight from 1.14.x to 1.15.1 are not affected and users who upgraded from 1.15.0 to 1.15.1 can fix the problem using `gitea doctor recreate-table issue_index` or upgrade to 1.15.2.
* Between [1.13.0](https://blog.gitea.io/2020/12/gitea-1.13.0-is-released/) [1.13.3](https://blog.gitea.io/2021/03/gitea-1.13.3-is-released/)
* Password hashing algorithm default has changed back to pbkdf2 from argon2. ([#14673](https://github.com/go-gitea/gitea/pull/14673))
### Unexplained upgrade failures & workarounds
* All versions
* Symptom: [blank / 500 page after login when running SQLite](https://github.com/go-gitea/gitea/issues/18650)
* Workaround: upgrade to [Forgejo 1.18.0-1 or greater](https://codeberg.org/forgejo/forgejo/commit/443675d18072d2a345bc4644d3f52dee42f58b44) and run `gitea doctor --all --fix`
### Versions with known issues
Gogs from before September 2015 migrated to Forgejo v1.18 may have a [dangling `pull_repo` table](https://forum.gna.org/t/73) and the corresponding pull requests will be removed by `gitea doctor --fix --all`.
[From the 1.11.3 release notes](https://blog.gitea.io/2020/03/gitea-1.11.3-and-1.10.6-released/):
* v1.10.0, v1.10.1, v1.10.2, v1.10.3, v1.10.4, v1.11.0, and v1.11.1 **do not use** any of these versions, as a bug in the upgrade process will delete attachments from the releases on your repositories.
* v1.11.2 (now replaced by 1.11.3) was mistakenly compiled with Go 1.14, which Gitea is not currently fully tested with and it’s known to cause [a few issues](https://github.com/go-gitea/gitea/issues/10661).
* v1.10.5 (replaced by 1.10.6 if you need to keep using the 1.10 branch) was incorrectly tagged, and was in fact a snapshot of our development branch (1.12-dev). It was also compiled with Go 1.14.