diff --git a/docs/admin/config-cheat-sheet.md b/docs/admin/config-cheat-sheet.md index 55634b2a..808bc025 100644 --- a/docs/admin/config-cheat-sheet.md +++ b/docs/admin/config-cheat-sheet.md @@ -1,7 +1,7 @@ --- title: 'Configuration Cheat Sheet' license: 'Apache-2.0' -origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/administration/config-cheat-sheet.en-us.md' +origin_url: 'https://github.com/go-gitea/gitea/blob/d3982bcd814bac93e3cbce1c7eb749b17e413fbd/docs/content/administration/config-cheat-sheet.en-us.md' --- This is a cheat sheet for the Forgejo configuration file. It contains most of the settings @@ -115,7 +115,7 @@ In addition, there is _`StaticRootPath`_ which can be set as a built-in at build keywords used in Pull Request comments to automatically close a related issue - `REOPEN_KEYWORDS`: **reopen**, **reopens**, **reopened**: List of keywords used in Pull Request comments to automatically reopen a related issue -- `DEFAULT_MERGE_STYLE`: **merge**: Set default merge style for repository creating, valid options: `merge`, `rebase`, `rebase-merge`, `squash` +- `DEFAULT_MERGE_STYLE`: **merge**: Set default merge style for repository creating, valid options: `merge`, `rebase`, `rebase-merge`, `squash`, `fast-forward-only` - `DEFAULT_MERGE_MESSAGE_COMMITS_LIMIT`: **50**: In the default merge message for squash commits include at most this many commits. Set to `-1` to include all commits - `DEFAULT_MERGE_MESSAGE_SIZE`: **5120**: In the default merge message for squash commits limit the size of the commit messages. Set to `-1` to have no limit. Only used if `POPULATE_SQUASH_COMMENT_WITH_COMMIT_MESSAGES` is `true`. - `DEFAULT_MERGE_MESSAGE_ALL_AUTHORS`: **false**: In the default merge message for squash commits walk all commits to include all authors in the Co-authored-by otherwise just use those in the limited list @@ -124,6 +124,7 @@ In addition, there is _`StaticRootPath`_ which can be set as a built-in at build - `POPULATE_SQUASH_COMMENT_WITH_COMMIT_MESSAGES`: **false**: In default squash-merge messages include the commit message of all commits comprising the pull request. - `ADD_CO_COMMITTER_TRAILERS`: **true**: Add co-authored-by and co-committed-by trailers to merge commit messages if committer does not match author. - `TEST_CONFLICTING_PATCHES_WITH_GIT_APPLY`: **false**: PR patches are tested using a three-way merge method to discover if there are conflicts. If this setting is set to **true**, conflicting patches will be retested using `git apply` - This was the previous behaviour in 1.18 (and earlier) but is somewhat inefficient. Please report if you find that this setting is required. +- `RETARGET_CHILDREN_ON_MERGE`: **true**: Retarget child pull requests to the parent pull request branch target on merge of parent pull request. It only works on merged PRs where the head and base branch target the same repo. ### Repository - Issue (`repository.issue`) @@ -135,7 +136,7 @@ In addition, there is _`StaticRootPath`_ which can be set as a built-in at build - `ENABLED`: **true**: Whether repository file uploads are enabled - `TEMP_PATH`: **data/tmp/uploads**: Path for uploads (content gets deleted on Forgejo restart) - `ALLOWED_TYPES`: **\**: Comma-separated list of allowed file extensions (`.zip`), mime types (`text/plain`) or wildcard type (`image/*`, `audio/*`, `video/*`). Empty value or `*/*` allows all types. -- `FILE_MAX_SIZE`: **3**: Max size of each file in megabytes. +- `FILE_MAX_SIZE`: **50**: Max size of each file in megabytes. - `MAX_FILES`: **5**: Max number of files per upload ### Repository - Release (`repository.release`) @@ -190,9 +191,7 @@ The following configuration set `Content-Type: application/vnd.android.package-a ## CORS (`cors`) - `ENABLED`: **false**: enable cors headers (disabled by default) -- `SCHEME`: **http**: scheme of allowed requests -- `ALLOW_DOMAIN`: **\***: list of requesting domains that are allowed -- `ALLOW_SUBDOMAIN`: **false**: allow subdomains of headers listed above to request +- `ALLOW_DOMAIN`: **\***: list of requesting origins that are allowed, eg: "https://\*.example.com" - `METHODS`: **GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS**: list of methods allowed to request - `MAX_AGE`: **10m**: max time to cache response - `ALLOW_CREDENTIALS`: **false**: allow request with credentials @@ -217,6 +216,7 @@ The following configuration set `Content-Type: application/vnd.android.package-a - `REACTIONS`: All available reactions users can choose on issues/prs and comments Values can be emoji alias (:smile:) or a unicode emoji. For custom reactions, add a tightly cropped square image to public/assets/img/emoji/reaction_name.png +- `REACTION_MAX_USER_NUM`: **10**: Change the number of users that are displayed in reactions tooltip (triggered by mouse hover). - `CUSTOM_EMOJIS`: **forgejo, gitea, codeberg, gitlab, git, github, gogs**: Additional Emojis not defined in the utf8 standard. By default we support Forgejo (:forgejo:), to add more copy them to public/assets/img/emoji/emoji_name.png and add it to this config. @@ -277,6 +277,7 @@ The following configuration set `Content-Type: application/vnd.android.package-a - `APP_DATA_PATH`: **_`AppWorkPath`_/data**: This is the default root path for storing data. - `PROTOCOL`: **http**: \[http, https, fcgi, http+unix, fcgi+unix\] + - Note: Value must be lowercase. - `USE_PROXY_PROTOCOL`: **false**: Expect PROXY protocol headers on connections. Warning: this feature is [not working](https://codeberg.org/forgejo/forgejo/issues/633). - `PROXY_PROTOCOL_TLS_BRIDGING`: **false**: When protocol is https, expect PROXY protocol headers after TLS negotiation. - `PROXY_PROTOCOL_HEADER_TIMEOUT`: **5s**: Timeout to wait for PROXY protocol header (set to 0 to have no timeout) @@ -336,7 +337,7 @@ The following configuration set `Content-Type: application/vnd.android.package-a - `SSH_AUTHORIZED_PRINCIPALS_ALLOW`: **off** or **username, email**: \[off, username, email, anything\]: Specify the principals values that users are allowed to use as principal. When set to `anything` no checks are done on the principal string. When set to `off` authorized principal are not allowed to be set. - `SSH_CREATE_AUTHORIZED_PRINCIPALS_FILE`: **false/true**: Forgejo will create a authorized_principals file by default when it is not using the internal ssh server and `SSH_AUTHORIZED_PRINCIPALS_ALLOW` is not `off`. - `SSH_AUTHORIZED_PRINCIPALS_BACKUP`: **false/true**: Enable SSH Authorized Principals Backup when rewriting all keys, default is true if `SSH_AUTHORIZED_PRINCIPALS_ALLOW` is not `off`. -- `SSH_AUTHORIZED_KEYS_COMMAND_TEMPLATE`: **{{.AppPath}} --config={{.CustomConf}} serv key-{{.Key.ID}}**: Set the template for the command to passed on authorized keys. Possible keys are: AppPath, AppWorkPath, CustomConf, CustomPath, Key - where Key is a `models/asymkey.PublicKey` and the others are strings which are shellquoted. +- `SSH_AUTHORIZED_KEYS_COMMAND_TEMPLATE`: **`{{.AppPath}} --config={{.CustomConf}} serv key-{{.Key.ID}}`**: Set the template for the command to passed on authorized keys. Possible keys are: AppPath, AppWorkPath, CustomConf, CustomPath, Key - where Key is a `models/asymkey.PublicKey` and the others are strings which are shellquoted. - `SSH_SERVER_CIPHERS`: **chacha20-poly1305@openssh.com, aes128-ctr, aes192-ctr, aes256-ctr, aes128-gcm@openssh.com, aes256-gcm@openssh.com**: For the built-in SSH server, choose the ciphers to support for SSH connections, for system SSH this setting has no effect. - `SSH_SERVER_KEY_EXCHANGES`: **curve25519-sha256, ecdh-sha2-nistp256, ecdh-sha2-nistp384, ecdh-sha2-nistp521, diffie-hellman-group14-sha256, diffie-hellman-group14-sha1**: For the built-in SSH server, choose the key exchange algorithms to support for SSH connections, for system SSH this setting has no effect. - `SSH_SERVER_MACS`: **hmac-sha2-256-etm@openssh.com, hmac-sha2-256, hmac-sha1**: For the built-in SSH server, choose the MACs to support for SSH connections, for system SSH this setting has no effect @@ -349,7 +350,7 @@ The following configuration set `Content-Type: application/vnd.android.package-a - `SSH_PER_WRITE_PER_KB_TIMEOUT`: **10s**: Timeout per Kb written to SSH connections. - `MINIMUM_KEY_SIZE_CHECK`: **true**: Indicate whether to check minimum key size with corresponding type. -- `OFFLINE_MODE`: **false**: Disables use of CDN for static files and Gravatar for profile pictures. +- `OFFLINE_MODE`: **true**: Disables use of CDN for static files and Gravatar for profile pictures. - `CERT_FILE`: **https/cert.pem**: Cert file path used for HTTPS. When chaining, the server certificate must come first, then intermediate CA certificates (if any). This is ignored if `ENABLE_ACME=true`. Paths are relative to `CUSTOM_PATH`. - `KEY_FILE`: **https/key.pem**: Key file path used for HTTPS. This is ignored if `ENABLE_ACME=true`. Paths are relative to `CUSTOM_PATH`. - `STATIC_ROOT_PATH`: **_`StaticRootPath`_**: Upper level of template and static files path. @@ -423,6 +424,7 @@ The following configuration set `Content-Type: application/vnd.android.package-a - `NAME`: **forgejo**: Database name. - `USER`: **root**: Database username. - `PASSWD`: **\**: Database user password. Use \`your password\` or """your password""" for quoting if you use special characters in the password. +- `CHARSET_COLLATION`: **_empty_**: (MySQL only) Forgejo expects to use a case-sensitive collation for database. Leave it empty to use the default collation. - `SCHEMA`: **\**: For PostgreSQL only, schema to use if different from "public". The schema must exist beforehand, the user must have creation privileges on it, and the user search path must be set to the look into the schema first (e.g. `ALTER USER user SET SEARCH_PATH = schema_name,"$user",public;`). @@ -481,7 +483,7 @@ Configuration at `[queue]` will set defaults for queues with overrides for indiv - `TYPE`: **level**: General queue type, currently support: `level` (uses a LevelDB internally), `channel`, `redis`, `dummy`. Invalid types are treated as `level`. - `DATADIR`: **queues/common**: Base DataDir for storing level queues. `DATADIR` for individual queues can be set in `queue.name` sections. Relative paths will be made absolute against `%(APP_DATA_PATH)s`. -- `LENGTH`: **100**: Maximal queue size before channel queues block +- `LENGTH`: **100000**: Maximal queue size before channel queues block - `BATCH_LENGTH`: **20**: Batch data before passing to the handler - `CONN_STR`: **redis://127.0.0.1:6379/0**: Connection string for the redis queue type. For `redis-cluster` use `redis+cluster://127.0.0.1:6379/0`. Options can be set using query params. Similarly, LevelDB options can also be set using: **leveldb://relative/path?option=value** or **leveldb:///absolute/path?option=value**, and will override `DATADIR` - `QUEUE_NAME`: **\_queue**: The suffix for default redis and disk queue name. Individual queues will default to **`name`**`QUEUE_NAME` but can be overridden in the specific `queue.name` section. @@ -508,6 +510,8 @@ And the following unique queues: - `DEFAULT_EMAIL_NOTIFICATIONS`: **enabled**: Default configuration for email notifications for users (user configurable). Options: enabled, onmention, disabled - `DISABLE_REGULAR_ORG_CREATION`: **false**: Disallow regular (non-admin) users from creating organizations. +- `USER_DISABLED_FEATURES`: **_empty_** Disabled features for users, could be `deletion` and more features can be added in future. + - `deletion`: User cannot delete their own account. - `SEND_NOTIFICATION_EMAIL_ON_NEW_USER`: **false**: enable email notifications to instance admins on new user sign-up. It requires `ENABLE_NOTIFY_MAIL` to be true. ## Security (`security`) @@ -516,7 +520,6 @@ And the following unique queues: - `SECRET_KEY`: **\**: Global secret key. This key is VERY IMPORTANT, if you lost it, the data encrypted by it (like 2FA secret) can't be decrypted anymore. - `SECRET_KEY_URI`: **\**: Instead of defining SECRET_KEY, this option can be used to use the key stored in a file (example value: `file:/etc/forgejo/secret_key`). It shouldn't be lost like SECRET_KEY. - `LOGIN_REMEMBER_DAYS`: **7**: Cookie lifetime, in days. -- `COOKIE_USERNAME`: **gitea_awesome**: Name of the cookie used to store the current username. - `COOKIE_REMEMBER_NAME`: **gitea_incredible**: Name of cookie used to store authentication information. - `REVERSE_PROXY_AUTHENTICATION_USER`: **X-WEBAUTH-USER**: Header name for reverse proxy @@ -567,6 +570,7 @@ And the following unique queues: - off - do not check password complexity - `PASSWORD_CHECK_PWN`: **false**: Check [HaveIBeenPwned](https://haveibeenpwned.com/Passwords) to see if a password has been exposed. - `SUCCESSFUL_TOKENS_CACHE_SIZE`: **20**: Cache successful token hashes. API tokens are stored in the DB as pbkdf2 hashes however, this means that there is a potentially significant hashing load when there are multiple API operations. This cache will store the successfully hashed tokens in a LRU cache as a balance between performance and security. +- `DISABLE_QUERY_AUTH_TOKEN`: **false**: Reject API tokens sent in URL query string (Accept Header-based API tokens only). ## Camo (`camo`) @@ -590,9 +594,13 @@ And the following unique queues: - `OPENID_CONNECT_SCOPES`: **\**: List of additional openid connect scopes. (`openid` is implicitly added) - `ENABLE_AUTO_REGISTRATION`: **false**: Automatically create user accounts for new oauth2 users. - `USERNAME`: **nickname**: The source of the username for new oauth2 accounts: - - userid - use the userid / sub attribute - - nickname - use the nickname attribute - - email - use the username part of the email attribute + - `userid` - use the userid / sub attribute + - `nickname` - use the nickname attribute + - `email` - use the username part of the email attribute + - Note: `nickname` and `email` options will normalize input strings using the following criteria: + - diacritics are removed + - the characters in the set `['ยด\x60]` are removed + - the characters in the set `[\s~+]` are replaced with `-` - `UPDATE_AVATAR`: **false**: Update avatar if available from oauth2 provider. Update will be performed on each login. - `ACCOUNT_LINKING`: **login**: How to handle if an account / email already exists: - disabled - show an error @@ -616,7 +624,7 @@ And the following unique queues: - `REQUIRE_SIGNIN_VIEW`: **false**: Enable this to force users to log in to view any page or to use API. - `ENABLE_NOTIFY_MAIL`: **false**: Enable this to send e-mail to watchers of a repository when something happens, like creating issues. Requires `Mailer` to be enabled. -- `ENABLE_BASIC_AUTHENTICATION`: **true**: Disable this to disallow authenticaton using HTTP +- `ENABLE_BASIC_AUTHENTICATION`: **true**: Disable this to disallow authentication using HTTP BASIC and the user's password. Please note if you disable this you will not be able to access the tokens API endpoints using a password. Further, this only disables BASIC authentication using the password - not tokens or OAuth Basic. @@ -750,7 +758,6 @@ Define allowed algorithms and their minimum key length (use -1 to disable a type ## Cache (`cache`) -- `ENABLED`: **true**: Enable the cache. - `ADAPTER`: **memory**: Cache engine adapter, either `memory`, `redis`, `redis-cluster`, `twoqueue` or `memcache`. (`twoqueue` represents a size limited LRU cache.) - `INTERVAL`: **60**: Garbage Collection interval (sec), for memory and twoqueue cache only. - `HOST`: **\**: Connection string for `redis`, `redis-cluster` and `memcache`. For `twoqueue` sets configuration for the queue. @@ -763,7 +770,6 @@ Define allowed algorithms and their minimum key length (use -1 to disable a type ## Cache - LastCommitCache settings (`cache.last_commit`) -- `ENABLED`: **true**: Enable the cache. - `ITEM_TTL`: **8760h**: Time to keep items in cache if not used, Setting it to -1 disables caching. - `COMMITS_COUNT`: **1000**: Only enable the cache when repository's commits count great than. @@ -1082,7 +1088,7 @@ This section only does "set" config, a removed config key from this section won' ## OAuth2 (`oauth2`) -- `ENABLE`: **true**: Enables OAuth2 provider. +- `ENABLED`: **true**: Enables OAuth2 provider. - `ACCESS_TOKEN_EXPIRATION_TIME`: **3600**: Lifetime of an OAuth2 access token in seconds - `REFRESH_TOKEN_EXPIRATION_TIME`: **730**: Lifetime of an OAuth2 refresh token in hours - `INVALIDATE_REFRESH_TOKENS`: **false**: Check if refresh token has already been used @@ -1284,10 +1290,11 @@ PROXY_HOSTS = *.github.com - `ENABLED`: **true**: Enable/Disable actions - `DEFAULT_ACTIONS_URL`: **https://code.forgejo.org**: Default address to get action plugins, e.g. the default value means downloading from "https://code.forgejo.org/actions/checkout" for "uses: actions/checkout@v3" -- `ARTIFACT_RETENTION_DAYS`: **90**: Number of days to keep artifacts. Set to 0 to disable artifact retention. Default is 90 days if not set. +- `ARTIFACT_RETENTION_DAYS`: **90**: Default number of days to keep artifacts. Artifacts could have their own retention periods by setting the `retention-days` option in `actions/upload-artifact` step. - `ZOMBIE_TASK_TIMEOUT`: **10m**: Timeout to stop the task which have running status, but haven't been updated for a long time. - `ENDLESS_TASK_TIMEOUT`: **3h**: Timeout to stop the tasks which have running status and continuous updates, but don't end for a long time. - `ABANDONED_JOB_TIMEOUT`: **24h**: Timeout to cancel the jobs which have waiting status, but haven't been picked by a runner for a long time. +- `SKIP_WORKFLOW_STRINGS`: **[skip ci],[ci skip],[no ci],[skip actions],[actions skip]**: Strings committers can place inside a commit message to skip executing the corresponding actions workflow ## Other (`other`) diff --git a/docs/admin/database-preparation.md b/docs/admin/database-preparation.md index a8f8b2f5..09a5c787 100644 --- a/docs/admin/database-preparation.md +++ b/docs/admin/database-preparation.md @@ -1,10 +1,10 @@ --- title: 'Database Preparation' license: 'Apache-2.0' -origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/installation/database-preparation.en-us.md' +origin_url: 'https://github.com/go-gitea/gitea/blob/d3982bcd814bac93e3cbce1c7eb749b17e413fbd/docs/content/installation/database-preparation.en-us.md' --- -You need a database to use Forgejo. Forgejo supports PostgreSQL (>=12), MySQL (>=8.0) or MariaDB (>=10.0), and SQLite. This page will guide into preparing the database. Only PostgreSQL and MySQL/MariaDB will be covered here since those database engines are widely-used in production. If you plan to use SQLite, you can ignore this chapter. +You need a database to use Forgejo. Forgejo supports PostgreSQL (>=12), MySQL (>=8.0) or MariaDB (>=10.0), and SQLite (builtin). This page will guide into preparing the database. Only PostgreSQL and MySQL/MariaDB will be covered here since those database engines are widely-used in production. If you plan to use SQLite, you can ignore this chapter. Database instance can be on same machine as Forgejo (local database setup), or on different machine (remote database). @@ -46,7 +46,11 @@ Note: All steps below requires that the database engine of your choice is instal Replace username and password above as appropriate. -4. Create database with UTF-8 charset and collation. Make sure to use `utf8mb4` charset instead of `utf8` as the former supports all Unicode characters (including emojis) beyond _Basic Multilingual Plane_. Also, collation chosen depending on your expected content, but make sure that the collation is accent- and case sensitive. When in doubt, use `utf8mb4_bin`. +4. Create database with UTF-8 charset and case-sensitive collation. + + `utf8mb4_bin` is a common collation for both MySQL/MariaDB. + When Forgejo starts, it will try to find a better collation (`utf8mb4_0900_as_cs` or `uca1400_as_cs`) and alter the database if it is possible. + If you would like to use another collation, you can set `[database].CHARSET_COLLATION` in the `app.ini` file. ```sql CREATE DATABASE forgejodb CHARACTER SET 'utf8mb4' COLLATE 'utf8mb4_bin'; diff --git a/docs/admin/email-setup.md b/docs/admin/email-setup.md index ca51f2b0..f3d5150c 100644 --- a/docs/admin/email-setup.md +++ b/docs/admin/email-setup.md @@ -1,7 +1,7 @@ --- title: 'Email setup' license: 'Apache-2.0' -origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/administration/email-setup.en-us.md' +origin_url: 'https://github.com/go-gitea/gitea/blob/d3982bcd814bac93e3cbce1c7eb749b17e413fbd/docs/content/administration/email-setup.en-us.md' --- Forgejo can be set to send emails such as a registration confirmation, either with [Sendmail](https://man7.org/linux/man-pages/man8/sendmail.8.html) (or compatible MTAs like Postfix and msmtp) or by connecting to an SMTP server. @@ -31,7 +31,7 @@ For the full list of options check the [Config Cheat Sheet](../config-cheat-shee - STARTTLS (also known as Opportunistic TLS) via port 587. Initial connection is done over cleartext, but then be upgraded over TLS if the server supports it. - SMTPS connection (SMTP over TLS) via the default port 465. Connection to the server use TLS from the beginning. -- Forced SMTPS connection with `IS_TLS_ENABLED=true`. +- Forced SMTPS connection with `PROTOCOL=smtps`. (These are both known as Implicit TLS.) Both `SMTPS` and `STARTTLS` combined with `IS_TLS_ENABLED=true` are known as Implicit TLS and is recommended by [RFC8314](https://tools.ietf.org/html/rfc8314#section-3) since 2018. diff --git a/docs/admin/incoming-email.md b/docs/admin/incoming-email.md index 57054c63..8c29d04c 100644 --- a/docs/admin/incoming-email.md +++ b/docs/admin/incoming-email.md @@ -1,7 +1,7 @@ --- title: 'Incoming Email' license: 'Apache-2.0' -origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/usage/incoming-email.en-us.md' +origin_url: 'https://github.com/go-gitea/gitea/blob/d3982bcd814bac93e3cbce1c7eb749b17e413fbd/docs/content/usage/incoming-email.en-us.md' --- Forgejo supports the execution of several actions through incoming mails. This page describes how to set this up. diff --git a/docs/admin/logging-documentation.md b/docs/admin/logging-documentation.md index 5b7be08f..93e27c74 100644 --- a/docs/admin/logging-documentation.md +++ b/docs/admin/logging-documentation.md @@ -1,7 +1,7 @@ --- title: 'Logging Configuration' license: 'Apache-2.0' -origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/administration/logging-config.en-us.md' +origin_url: 'https://github.com/go-gitea/gitea/blob/d3982bcd814bac93e3cbce1c7eb749b17e413fbd/docs/content/administration/logging-config.en-us.md' --- The logging configuration of Forgejo mainly consists of 3 types of components: diff --git a/docs/admin/reverse-proxy.md b/docs/admin/reverse-proxy.md index 0ab9ecd1..36218d7a 100644 --- a/docs/admin/reverse-proxy.md +++ b/docs/admin/reverse-proxy.md @@ -1,7 +1,7 @@ --- title: 'Reverse proxy' license: 'Apache-2.0' -origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/usage/authentication.en-us.md' +origin_url: 'https://github.com/go-gitea/gitea/blob/d3982bcd814bac93e3cbce1c7eb749b17e413fbd/docs/content/usage/authentication.en-us.md' --- 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 @@ -20,3 +20,9 @@ If set `ENABLE_REVERSE_PROXY_FULL_NAME=true`, a user full name expected in `X-WE You can also limit the reverse proxy's IP address range with `[security].REVERSE_PROXY_TRUSTED_PROXIES` which default value is `127.0.0.0/8,::1/128`. By `[security].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. + +## Docker / Container Registry + +The container registry uses a fixed sub-path `/v2` which can't be changed. +Even if you deploy Gitea with a different sub-path, `/v2` will be used by the `docker` client. +Therefore you may need to add an additional route to your reverse proxy configuration. diff --git a/docs/admin/search-engines-indexation.md b/docs/admin/search-engines-indexation.md index c6e608dc..4cf6ae74 100644 --- a/docs/admin/search-engines-indexation.md +++ b/docs/admin/search-engines-indexation.md @@ -1,7 +1,7 @@ --- title: 'Search Engines Indexation' license: 'Apache-2.0' -origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/administration/search-engines-indexation.en-us.md' +origin_url: 'https://github.com/go-gitea/gitea/blob/d3982bcd814bac93e3cbce1c7eb749b17e413fbd/docs/content/administration/search-engines-indexation.en-us.md' --- ## Search engines indexation of your Forgejo installation @@ -12,7 +12,7 @@ If you don't want your repository to be visible for search engines read further. ### Block search engines indexation using robots.txt To make Forgejo serve a custom `robots.txt` (default: empty 404) for top level installations, -create a file called `robots.txt` at the root of the `Custom File Root Path` as displayed in the `/admin/config` page. +create a file with path `public/robots.txt` at the root of the `Custom File Root Path` as displayed in the `/admin/config` page. Examples on how to configure the `robots.txt` can be found at [https://moz.com/learn/seo/robotstxt](https://moz.com/learn/seo/robotstxt). diff --git a/docs/admin/seek-assistance.md b/docs/admin/seek-assistance.md index 29567af1..8d1e88ca 100644 --- a/docs/admin/seek-assistance.md +++ b/docs/admin/seek-assistance.md @@ -1,7 +1,7 @@ --- title: 'Seek Assistance' license: 'Apache-2.0' -origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/help/seek-help.en-us.md' +origin_url: 'https://github.com/go-gitea/gitea/blob/d3982bcd814bac93e3cbce1c7eb749b17e413fbd/docs/content/help/seek-help.en-us.md' --- - [Chatroom](https://matrix.to/#/#forgejo-chat:matrix.org) diff --git a/docs/admin/signing.md b/docs/admin/signing.md index 73ca9bcf..7b0513da 100644 --- a/docs/admin/signing.md +++ b/docs/admin/signing.md @@ -1,7 +1,7 @@ --- title: 'GPG Commit Signatures' license: 'Apache-2.0' -origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/administration/signing.en-us.md' +origin_url: 'https://github.com/go-gitea/gitea/blob/d3982bcd814bac93e3cbce1c7eb749b17e413fbd/docs/content/administration/signing.en-us.md' --- Forgejo will verify GPG commit signatures in the provided tree by diff --git a/docs/developer/customization.md b/docs/developer/customization.md index 06bd1f41..e3e5b4ce 100644 --- a/docs/developer/customization.md +++ b/docs/developer/customization.md @@ -1,7 +1,7 @@ --- title: 'Interface customization' license: 'Apache-2.0' -origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/administration/customizing-gitea.en-us.md' +origin_url: 'https://github.com/go-gitea/gitea/blob/d3982bcd814bac93e3cbce1c7eb749b17e413fbd/docs/content/administration/customizing-gitea.en-us.md' --- This sections documents the Forgejo interface customization that requires an intimate knowledge of the underlying codebase. The user interface customization documented and supported for Forgejo admins to use [is found in the corresponding administrator guide section](../../admin/customization/). diff --git a/docs/developer/from-source.md b/docs/developer/from-source.md index 4ac0574d..3b68c934 100644 --- a/docs/developer/from-source.md +++ b/docs/developer/from-source.md @@ -1,7 +1,7 @@ --- title: 'Compiling from source' license: 'Apache-2.0' -origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/installation/from-source.en-us.md' +origin_url: 'https://github.com/go-gitea/gitea/blob/d3982bcd814bac93e3cbce1c7eb749b17e413fbd/docs/content/installation/from-source.en-us.md' --- ## Installation from source diff --git a/docs/user/agit-support.md b/docs/user/agit-support.md index dbb68ffd..66a6bc89 100644 --- a/docs/user/agit-support.md +++ b/docs/user/agit-support.md @@ -1,7 +1,7 @@ --- title: 'AGit Workflow Usage' license: 'Apache-2.0' -origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/usage/agit-support.en-us.md' +origin_url: 'https://github.com/go-gitea/gitea/blob/d3982bcd814bac93e3cbce1c7eb749b17e413fbd/docs/content/usage/agit-support.en-us.md' --- Forgejo ships with limited support for [AGit-Flow](https://git-repo.info/en/2020/03/agit-flow-and-git-repo/). It was originally introduced in Gitea `1.13`. diff --git a/docs/user/api-usage.md b/docs/user/api-usage.md index 009bd050..10320709 100644 --- a/docs/user/api-usage.md +++ b/docs/user/api-usage.md @@ -1,7 +1,7 @@ --- title: 'API Usage' license: 'Apache-2.0' -origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/development/api-usage.en-us.md' +origin_url: 'https://github.com/go-gitea/gitea/blob/d3982bcd814bac93e3cbce1c7eb749b17e413fbd/docs/content/development/api-usage.en-us.md' --- ## Enabling/configuring API access diff --git a/docs/user/authentication.md b/docs/user/authentication.md index 6e51dcd2..8ce75dab 100644 --- a/docs/user/authentication.md +++ b/docs/user/authentication.md @@ -1,7 +1,7 @@ --- title: 'Authentication' license: 'Apache-2.0' -origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/usage/authentication.en-us.md' +origin_url: 'https://github.com/go-gitea/gitea/blob/d3982bcd814bac93e3cbce1c7eb749b17e413fbd/docs/content/usage/authentication.en-us.md' --- ## LDAP (Lightweight Directory Access Protocol) diff --git a/docs/user/blame.md b/docs/user/blame.md index a2c7b5c6..71b4f188 100644 --- a/docs/user/blame.md +++ b/docs/user/blame.md @@ -1,7 +1,7 @@ --- title: 'Blame File View' license: 'Apache-2.0' -origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/usage/blame.en-us.md' +origin_url: 'https://github.com/go-gitea/gitea/blob/d3982bcd814bac93e3cbce1c7eb749b17e413fbd/docs/content/usage/blame.en-us.md' --- Forgejo supports viewing the line-by-line revision history for a file also known as blame view. diff --git a/docs/user/issue-pull-request-templates.md b/docs/user/issue-pull-request-templates.md index 7787649c..93070bdc 100644 --- a/docs/user/issue-pull-request-templates.md +++ b/docs/user/issue-pull-request-templates.md @@ -1,12 +1,12 @@ --- title: 'Issue and Pull Request Templates' license: 'Apache-2.0' -origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/usage/issue-pull-request-templates.en-us.md' +origin_url: 'https://github.com/go-gitea/gitea/blob/d3982bcd814bac93e3cbce1c7eb749b17e413fbd/docs/content/usage/issue-pull-request-templates.en-us.md' --- Some projects have a standard list of questions that users need to answer when creating an issue or pull request. Forgejo supports adding templates to the -main branch of the repository so that they can autopopulate the form when users are +**default branch of the repository** so that they can autopopulate the form when users are creating issues and pull requests. This will cut down on the initial back and forth of getting some clarifying details. diff --git a/docs/user/labels.md b/docs/user/labels.md index 093ef78a..b0b64ece 100644 --- a/docs/user/labels.md +++ b/docs/user/labels.md @@ -1,7 +1,7 @@ --- title: 'Labels' license: 'Apache-2.0' -origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/usage/labels.en-us.md' +origin_url: 'https://github.com/go-gitea/gitea/blob/d3982bcd814bac93e3cbce1c7eb749b17e413fbd/docs/content/usage/labels.en-us.md' --- You can use labels to classify issues and pull requests and to improve your overview over them. diff --git a/docs/user/linked-references.md b/docs/user/linked-references.md index 613bf943..3cc8651b 100644 --- a/docs/user/linked-references.md +++ b/docs/user/linked-references.md @@ -1,7 +1,7 @@ --- title: 'Automatically Linked References in Issues, Pull Requests and Commit Messages' license: 'Apache-2.0' -origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/usage/linked-references.en-us.md' +origin_url: 'https://github.com/go-gitea/gitea/blob/d3982bcd814bac93e3cbce1c7eb749b17e413fbd/docs/content/usage/linked-references.en-us.md' --- When an issue, pull request or comment is posted, the text description is parsed diff --git a/docs/user/merge-message-templates.md b/docs/user/merge-message-templates.md index ce2da0fc..c2e27620 100644 --- a/docs/user/merge-message-templates.md +++ b/docs/user/merge-message-templates.md @@ -1,7 +1,7 @@ --- title: 'Merge Message templates' license: 'Apache-2.0' -origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/usage/merge-message-templates.en-us.md' +origin_url: 'https://github.com/go-gitea/gitea/blob/d3982bcd814bac93e3cbce1c7eb749b17e413fbd/docs/content/usage/merge-message-templates.en-us.md' --- ## File names diff --git a/docs/user/oauth2-provider.md b/docs/user/oauth2-provider.md index b33b52ba..23915f14 100644 --- a/docs/user/oauth2-provider.md +++ b/docs/user/oauth2-provider.md @@ -1,7 +1,7 @@ --- title: 'OAuth2 provider' license: 'Apache-2.0' -origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/development/oauth2-provider.en-us.md' +origin_url: 'https://github.com/go-gitea/gitea/blob/d3982bcd814bac93e3cbce1c7eb749b17e413fbd/docs/content/development/oauth2-provider.en-us.md' --- Forgejo supports acting as an OAuth2 provider to allow third party applications to access its resources with the user's consent. diff --git a/docs/user/packages/alpine.md b/docs/user/packages/alpine.md index a515aa9f..79ac03a8 100644 --- a/docs/user/packages/alpine.md +++ b/docs/user/packages/alpine.md @@ -1,7 +1,7 @@ --- title: 'Alpine Packages Repository' license: 'Apache-2.0' -origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/usage/packages/alpine.en-us.md' +origin_url: 'https://github.com/go-gitea/gitea/blob/d3982bcd814bac93e3cbce1c7eb749b17e413fbd/docs/content/usage/packages/alpine.en-us.md' --- Publish [Alpine](https://pkgs.alpinelinux.org/) packages for your user or organization. @@ -67,6 +67,7 @@ curl --user your_username:your_password_or_token \ ``` If you are using 2FA or OAuth use a [personal access token](../../api-usage/#authentication) instead of the password. + You cannot publish a file with the same name twice to a package. You must delete the existing package file first. The server responds with the following HTTP Status codes. diff --git a/docs/user/packages/cargo.md b/docs/user/packages/cargo.md index 8b15a01b..d824532f 100644 --- a/docs/user/packages/cargo.md +++ b/docs/user/packages/cargo.md @@ -1,7 +1,7 @@ --- title: 'Cargo Package Registry' license: 'Apache-2.0' -origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/usage/packages/cargo.en-us.md' +origin_url: 'https://github.com/go-gitea/gitea/blob/d3982bcd814bac93e3cbce1c7eb749b17e413fbd/docs/content/usage/packages/cargo.en-us.md' --- Publish [Cargo](https://doc.rust-lang.org/stable/cargo/) packages for your user or organization. diff --git a/docs/user/packages/chef.md b/docs/user/packages/chef.md index 05791298..72f086ad 100644 --- a/docs/user/packages/chef.md +++ b/docs/user/packages/chef.md @@ -1,7 +1,7 @@ --- title: 'Chef Package Registry' license: 'Apache-2.0' -origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/usage/packages/chef.en-us.md' +origin_url: 'https://github.com/go-gitea/gitea/blob/d3982bcd814bac93e3cbce1c7eb749b17e413fbd/docs/content/usage/packages/chef.en-us.md' --- Publish [Chef](https://chef.io/) cookbooks for your user or organization. diff --git a/docs/user/packages/composer.md b/docs/user/packages/composer.md index ab1039ba..94b3498f 100644 --- a/docs/user/packages/composer.md +++ b/docs/user/packages/composer.md @@ -1,7 +1,7 @@ --- title: 'Composer Package Registry' license: 'Apache-2.0' -origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/usage/packages/composer.en-us.md' +origin_url: 'https://github.com/go-gitea/gitea/blob/d3982bcd814bac93e3cbce1c7eb749b17e413fbd/docs/content/usage/packages/composer.en-us.md' --- Publish [Composer](https://getcomposer.org/) packages for your user or organization. @@ -14,6 +14,7 @@ To work with the Composer package registry, you can use [Composer](https://getco 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. ``` @@ -50,10 +51,11 @@ If you are using 2FA or OAuth use a [personal access token](../../api-usage/#aut 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. | +| HTTP Status Code | Meaning | +| ----------------- | ---------------------------------------------------------------------- | +| `201 Created` | The package has been published. | +| `400 Bad Request` | The package is invalid. | +| `409 Conflict` | A package file with the same combination of parameters exists already. | ## Configuring the package registry diff --git a/docs/user/packages/conan.md b/docs/user/packages/conan.md index 8d1b4ae5..2f627cef 100644 --- a/docs/user/packages/conan.md +++ b/docs/user/packages/conan.md @@ -1,7 +1,7 @@ --- title: 'Conan Package Registry' license: 'Apache-2.0' -origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/usage/packages/conan.en-us.md' +origin_url: 'https://github.com/go-gitea/gitea/blob/d3982bcd814bac93e3cbce1c7eb749b17e413fbd/docs/content/usage/packages/conan.en-us.md' --- Publish [Conan](https://conan.io/) packages for your user or organization. diff --git a/docs/user/packages/conda.md b/docs/user/packages/conda.md index 2955641f..8aa701fb 100644 --- a/docs/user/packages/conda.md +++ b/docs/user/packages/conda.md @@ -1,7 +1,7 @@ --- title: 'Conda Package Registry' license: 'Apache-2.0' -origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/usage/packages/conda.en-us.md' +origin_url: 'https://github.com/go-gitea/gitea/blob/d3982bcd814bac93e3cbce1c7eb749b17e413fbd/docs/content/usage/packages/conda.en-us.md' --- Publish [Conda](https://docs.conda.io/en/latest/) packages for your user or organization. @@ -52,8 +52,18 @@ curl --user your_username:your_password_or_token \ https://forgejo.example.com/api/packages/testuser/conda/package-1.0.conda ``` +If you are using 2FA or OAuth use a personal access token instead of the password. + You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first. +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 is invalid. | +| `409 Conflict` | A package file with the same combination of parameters exists already. | + ## Install a package To install a package from the package registry, execute one of the following commands: diff --git a/docs/user/packages/container.md b/docs/user/packages/container.md index 7d6ec52a..d5428f3f 100644 --- a/docs/user/packages/container.md +++ b/docs/user/packages/container.md @@ -1,7 +1,7 @@ --- title: 'Container Registry' license: 'Apache-2.0' -origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/usage/packages/container.en-us.md' +origin_url: 'https://github.com/go-gitea/gitea/blob/d3982bcd814bac93e3cbce1c7eb749b17e413fbd/docs/content/usage/packages/container.en-us.md' --- Publish [Open Container Initiative](https://opencontainers.org/) compliant images for your user or organization. @@ -28,6 +28,16 @@ Images must follow this naming convention: `{registry}/{owner}/{image}` +When building your docker image, using the naming convention above, this looks like: + +```shell +# build an image with tag +docker build -t {registry}/{owner}/{image}:{tag} . +# name an existing image with tag +docker tag {some-existing-image}:{tag} {registry}/{owner}/{image}:{tag} +``` + +where your registry is the domain of your gitea instance (e.g. gitea.example.com). For example, these are all valid image names for the owner `testuser`: `forgejo.example.com/testuser/myimage` diff --git a/docs/user/packages/cran.md b/docs/user/packages/cran.md index a218afda..8046556f 100644 --- a/docs/user/packages/cran.md +++ b/docs/user/packages/cran.md @@ -1,7 +1,7 @@ --- title: 'CRAN Package Registry' license: 'Apache-2.0' -origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/usage/packages/cran.en-us.md' +origin_url: 'https://github.com/go-gitea/gitea/blob/d3982bcd814bac93e3cbce1c7eb749b17e413fbd/docs/content/usage/packages/cran.en-us.md' --- Publish [R](https://www.r-project.org/) packages to a [CRAN](https://cran.r-project.org/)-like registry for your user or organization. @@ -58,8 +58,18 @@ curl --user your_username:your_password_or_token \ https://forgejo.example.com/api/packages/testuser/cran/bin?platform=windows&rversion=4.2 ``` +If you are using 2FA or OAuth use a personal access token instead of the password. + You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first. +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 is invalid. | +| `409 Conflict` | A package file with the same combination of parameters exists already. | + ## Install a package To install a R package from the package registry, execute the following command: diff --git a/docs/user/packages/debian.md b/docs/user/packages/debian.md index 5f9e5907..34f902c0 100644 --- a/docs/user/packages/debian.md +++ b/docs/user/packages/debian.md @@ -1,7 +1,7 @@ --- title: 'Debian Package Registry' license: 'Apache-2.0' -origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/usage/packages/debian.en-us.md' +origin_url: 'https://github.com/go-gitea/gitea/blob/d3982bcd814bac93e3cbce1c7eb749b17e413fbd/docs/content/usage/packages/debian.en-us.md' --- Publish [Debian](https://www.debian.org/distrib/packages) packages for your user or organization. @@ -17,7 +17,7 @@ The following examples use `apt`. To register the Debian registry add the url to the list of known apt sources: ```shell -echo "deb https://forgejo.example.com/api/packages/{owner}/debian {distribution} {component}" | sudo tee -a /etc/apt/sources.list.d/forgejo.list +echo "deb [signed-by=/etc/apt/keyrings/forgejo-{owner}.asc] https://forgejo.example.com/api/packages/{owner}/debian {distribution} {component}" | sudo tee -a /etc/apt/sources.list.d/forgejo.list ``` | Placeholder | Description | @@ -29,13 +29,13 @@ echo "deb https://forgejo.example.com/api/packages/{owner}/debian {distribution} If the registry is private, provide credentials in the url. You can use a password or a [personal access token](../../api-usage/#authentication): ```shell -echo "deb https://{username}:{your_password_or_token}@forgejo.example.com/api/packages/{owner}/debian {distribution} {component}" | sudo tee -a /etc/apt/sources.list.d/forgejo.list +echo "deb [signed-by=/etc/apt/keyrings/forgejo-{owner}.asc] https://{username}:{your_password_or_token}@forgejo.example.com/api/packages/{owner}/debian {distribution} {component}" | sudo tee -a /etc/apt/sources.list.d/forgejo.list ``` The Debian registry files are signed with a PGP key which must be known to apt: ```shell -sudo curl https://forgejo.example.com/api/packages/{owner}/debian/repository.key -o /etc/apt/trusted.gpg.d/forgejo-{owner}.asc +sudo curl https://forgejo.example.com/api/packages/{owner}/debian/repository.key -o /etc/apt/keyrings/forgejo-{owner}.asc ``` Afterwards update the local package index: @@ -67,15 +67,16 @@ curl --user your_username:your_password_or_token \ ``` If you are using 2FA or OAuth use a [personal access token](../../api-usage/#authentication) instead of the password. -You cannot publish a file with the same name twice to a package. You must delete the existing package version first. + +You cannot publish a package if a package of the same name, version, distribution, component and architecture already exists. You must delete the existing package first. 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, version, distribution, component or architecture are invalid. | -| `409 Conflict` | A package file with the same combination of parameters exists already. | +| HTTP Status Code | Meaning | +| ----------------- | ---------------------------------------------------------------------- | +| `201 Created` | The package has been published. | +| `400 Bad Request` | The package is invalid. | +| `409 Conflict` | A package file with the same combination of parameters exists already. | ## Delete a package diff --git a/docs/user/packages/generic.md b/docs/user/packages/generic.md index c8e5704a..cd835458 100644 --- a/docs/user/packages/generic.md +++ b/docs/user/packages/generic.md @@ -1,7 +1,7 @@ --- title: 'Generic Package Registry' license: 'Apache-2.0' -origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/usage/packages/generic.en-us.md' +origin_url: 'https://github.com/go-gitea/gitea/blob/d3982bcd814bac93e3cbce1c7eb749b17e413fbd/docs/content/usage/packages/generic.en-us.md' --- Publish generic files, like release binaries or other output, for your user or organization. diff --git a/docs/user/packages/go.md b/docs/user/packages/go.md index 8142377b..606afd28 100644 --- a/docs/user/packages/go.md +++ b/docs/user/packages/go.md @@ -1,7 +1,7 @@ --- title: 'Go Package Registry' license: 'Apache-2.0' -origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/usage/packages/go.en-us.md' +origin_url: 'https://github.com/go-gitea/gitea/blob/d3982bcd814bac93e3cbce1c7eb749b17e413fbd/docs/content/usage/packages/go.en-us.md' --- Publish Go packages for your user or organization. @@ -30,6 +30,8 @@ curl --user your_username:your_password_or_token \ If you are using 2FA or OAuth use a personal access token instead of the password. +You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first. + The server responds with the following HTTP Status codes. | HTTP Status Code | Meaning | diff --git a/docs/user/packages/helm.md b/docs/user/packages/helm.md index f825a9a1..01589c36 100644 --- a/docs/user/packages/helm.md +++ b/docs/user/packages/helm.md @@ -1,7 +1,7 @@ --- title: 'Helm Chart Registry' license: 'Apache-2.0' -origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/usage/packages/helm.en-us.md' +origin_url: 'https://github.com/go-gitea/gitea/blob/d3982bcd814bac93e3cbce1c7eb749b17e413fbd/docs/content/usage/packages/helm.en-us.md' --- Publish [Helm](https://helm.sh/) charts for your user or organization. diff --git a/docs/user/packages/index.md b/docs/user/packages/index.md index 29cbdc5a..bfaaedbd 100644 --- a/docs/user/packages/index.md +++ b/docs/user/packages/index.md @@ -1,7 +1,7 @@ --- title: 'Package Registry' license: 'Apache-2.0' -origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/usage/packages/storage.en-us.md' +origin_url: 'https://github.com/go-gitea/gitea/blob/d3982bcd814bac93e3cbce1c7eb749b17e413fbd/docs/content/usage/packages/storage.en-us.md' --- ## Supported package managers diff --git a/docs/user/packages/maven.md b/docs/user/packages/maven.md index ad093e6f..fecc5d58 100644 --- a/docs/user/packages/maven.md +++ b/docs/user/packages/maven.md @@ -1,7 +1,7 @@ --- title: 'Maven Package Registry' license: 'Apache-2.0' -origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/usage/packages/maven.en-us.md' +origin_url: 'https://github.com/go-gitea/gitea/blob/d3982bcd814bac93e3cbce1c7eb749b17e413fbd/docs/content/usage/packages/maven.en-us.md' --- Publish [Maven](https://maven.apache.org) packages for your user or organization. diff --git a/docs/user/packages/npm.md b/docs/user/packages/npm.md index 9436c5e0..2539ce01 100644 --- a/docs/user/packages/npm.md +++ b/docs/user/packages/npm.md @@ -1,7 +1,7 @@ --- title: 'npm Package Registry' license: 'Apache-2.0' -origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/usage/packages/npm.en-us.md' +origin_url: 'https://github.com/go-gitea/gitea/blob/d3982bcd814bac93e3cbce1c7eb749b17e413fbd/docs/content/usage/packages/npm.en-us.md' --- Publish [npm](https://www.npmjs.com/) packages for your user or organization. diff --git a/docs/user/packages/nuget.md b/docs/user/packages/nuget.md index 5d052ecf..6a4f22d1 100644 --- a/docs/user/packages/nuget.md +++ b/docs/user/packages/nuget.md @@ -1,7 +1,7 @@ --- title: 'NuGet Package Registry' license: 'Apache-2.0' -origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/usage/packages/nuget.en-us.md' +origin_url: 'https://github.com/go-gitea/gitea/blob/d3982bcd814bac93e3cbce1c7eb749b17e413fbd/docs/content/usage/packages/nuget.en-us.md' --- 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. diff --git a/docs/user/packages/pub.md b/docs/user/packages/pub.md index 4d81ba8d..9b341378 100644 --- a/docs/user/packages/pub.md +++ b/docs/user/packages/pub.md @@ -1,7 +1,7 @@ --- title: 'Pub Package Registry' license: 'Apache-2.0' -origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/usage/packages/pub.en-us.md' +origin_url: 'https://github.com/go-gitea/gitea/blob/d3982bcd814bac93e3cbce1c7eb749b17e413fbd/docs/content/usage/packages/pub.en-us.md' --- Publish [Pub](https://dart.dev/guides/packages) packages for your user or organization. diff --git a/docs/user/packages/pypi.md b/docs/user/packages/pypi.md index ffcdf764..4df61fd9 100644 --- a/docs/user/packages/pypi.md +++ b/docs/user/packages/pypi.md @@ -1,7 +1,7 @@ --- title: 'PyPI Package Registry' license: 'Apache-2.0' -origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/usage/packages/pypi.en-us.md' +origin_url: 'https://github.com/go-gitea/gitea/blob/d3982bcd814bac93e3cbce1c7eb749b17e413fbd/docs/content/usage/packages/pypi.en-us.md' --- Publish [PyPI](https://pypi.org/) packages for your user or organization. diff --git a/docs/user/packages/rpm.md b/docs/user/packages/rpm.md index 7efc5669..04a72906 100644 --- a/docs/user/packages/rpm.md +++ b/docs/user/packages/rpm.md @@ -1,7 +1,7 @@ --- title: 'RPM Package Registry' license: 'Apache-2.0' -origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/usage/packages/rpm.en-us.md' +origin_url: 'https://github.com/go-gitea/gitea/blob/d3982bcd814bac93e3cbce1c7eb749b17e413fbd/docs/content/usage/packages/rpm.en-us.md' --- Publish [RPM](https://rpm.org/) packages for your user or organization. @@ -14,42 +14,59 @@ The following examples use `dnf`. ## Configuring the package registry -To register the RPM registry add the url to the list of known apt sources: +To register the RPM registry add the url to the list of known sources: ```shell -dnf config-manager --add-repo https://forgejo.example.com/api/packages/{owner}/rpm.repo +dnf config-manager --add-repo https://forgejo.example.com/api/packages/{owner}/{group}.repo ``` -| Placeholder | Description | -| ----------- | ------------------------- | -| `owner` | The owner of the package. | +| Placeholder | Description | +| ----------- | ------------------------------------------------------------------ | +| `owner` | The owner of the package. | +| `group` | Optional: Everything, e.g. empty, `el7`, `rocky/el9`, `test/fc38`. | + +Example: + +```shell +# without a group +dnf config-manager --add-repo https://forgejo.example.com/api/packages/testuser/rpm.repo + +# with the group 'centos/el7' +dnf config-manager --add-repo https://forgejo.example.com/api/packages/testuser/rpm/centos/el7.repo +``` If the registry is private, provide credentials in the url. You can use a password or a personal access token: ```shell -dnf config-manager --add-repo https://{username}:{your_password_or_token}@forgejo.example.com/api/packages/{owner}/rpm.repo +dnf config-manager --add-repo https://{username}:{your_password_or_token}@forgejo.example.com/api/packages/{owner}/{group}.repo ``` -You have to add the credentials to the urls in the `rpm.repo` file in `/etc/yum.repos.d` too. +You have to add the credentials to the urls in the created `.repo` file in `/etc/yum.repos.d` too. ## Publish a package To publish a RPM package (`*.rpm`), perform a HTTP PUT operation with the package content in the request body. ``` -PUT https://forgejo.example.com/api/packages/{owner}/rpm/upload +PUT https://forgejo.example.com/api/packages/{owner}/rpm/{group}/upload ``` -| Parameter | Description | -| --------- | ------------------------- | -| `owner` | The owner of the package. | +| Parameter | Description | +| --------- | ------------------------------------------------------------------ | +| `owner` | The owner of the package. | +| `group` | Optional: Everything, e.g. empty, `el7`, `rocky/el9`, `test/fc38`. | Example request using HTTP Basic authentication: ```shell +# without a group curl --user your_username:your_password_or_token \ --upload-file path/to/file.rpm \ https://forgejo.example.com/api/packages/testuser/rpm/upload +# with the group 'centos/el7' +curl --user your_username:your_password_or_token \ + --upload-file path/to/file.rpm \ + https://forgejo.example.com/api/packages/testuser/rpm/centos/el7/upload ``` If you are using 2FA or OAuth use a personal access token instead of the password. @@ -68,21 +85,27 @@ The server responds with the following HTTP Status codes. To delete a Debian 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}/rpm/{package_name}/{package_version}/{architecture} +DELETE https://forgejo.example.com/api/packages/{owner}/rpm/{group}/package/{package_name}/{package_version}/{architecture} ``` -| Parameter | Description | -| ----------------- | ------------------------- | -| `owner` | The owner of the package. | -| `package_name` | The package name. | -| `package_version` | The package version. | -| `architecture` | The package architecture. | +| Parameter | Description | +| ----------------- | ---------------------------- | +| `owner` | The owner of the package. | +| `group` | Optional: The package group. | +| `package_name` | The package name. | +| `package_version` | The package version. | +| `architecture` | The package architecture. | Example request using HTTP Basic authentication: ```shell +# without a group curl --user your_username:your_token_or_password -X DELETE \ - https://forgejo.example.com/api/packages/testuser/rpm/test-package/1.0.0/x86_64 + https://forgejo.example.com/api/packages/testuser/rpm/package/test-package/1.0.0/x86_64 + +# with the group 'centos/el7' +curl --user your_username:your_token_or_password -X DELETE \ + https://forgejo.example.com/api/packages/testuser/rpm/centos/el7/package/test-package/1.0.0/x86_64 ``` The server responds with the following HTTP Status codes. diff --git a/docs/user/packages/rubygems.md b/docs/user/packages/rubygems.md index c3c84163..2888897d 100644 --- a/docs/user/packages/rubygems.md +++ b/docs/user/packages/rubygems.md @@ -1,7 +1,7 @@ --- title: 'RubyGems Packages Repository' license: 'Apache-2.0' -origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/usage/packages/rubygems.en-us.md' +origin_url: 'https://github.com/go-gitea/gitea/blob/d3982bcd814bac93e3cbce1c7eb749b17e413fbd/docs/content/usage/packages/rubygems.en-us.md' --- Publish [RubyGems](https://guides.rubygems.org/) packages for your user or organization. diff --git a/docs/user/packages/swift.md b/docs/user/packages/swift.md index 38001115..27d80fec 100644 --- a/docs/user/packages/swift.md +++ b/docs/user/packages/swift.md @@ -1,7 +1,7 @@ --- title: 'Swift Packages Repository' license: 'Apache-2.0' -origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/usage/packages/swift.en-us.md' +origin_url: 'https://github.com/go-gitea/gitea/blob/d3982bcd814bac93e3cbce1c7eb749b17e413fbd/docs/content/usage/packages/swift.en-us.md' --- ## Swift Packages Repository @@ -17,7 +17,8 @@ To work with the Swift package registry, you need to use [swift](https://www.swi To register the package registry and provide credentials, execute: ```shell -swift package-registry set https://forgejo.example.com/api/packages/{owner}/swift -login {username} -password {password} +swift package-registry set https://forgejo.example.com/api/packages/{owner}/swift +swift package-registry login https://forgejo.example.com/api/packages/{owner}/swift --username {username} --password {password} ``` | Placeholder | Description | @@ -58,6 +59,14 @@ curl -X PUT --user {username}:{password} \ You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first. +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 is invalid. | +| `409 Conflict` | A package file with the same combination of parameters exists already. | + ### Install a package To install a Swift package from the package registry, add it in the `Package.swift` file dependencies list: diff --git a/docs/user/packages/vagrant.md b/docs/user/packages/vagrant.md index 11f886d5..2f27f62b 100644 --- a/docs/user/packages/vagrant.md +++ b/docs/user/packages/vagrant.md @@ -1,7 +1,7 @@ --- title: 'Vagrant Packages Repository' license: 'Apache-2.0' -origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/usage/packages/vagrant.en-us.md' +origin_url: 'https://github.com/go-gitea/gitea/blob/d3982bcd814bac93e3cbce1c7eb749b17e413fbd/docs/content/usage/packages/vagrant.en-us.md' --- Publish [Vagrant](https://www.vagrantup.com/) packages for your user or organization. @@ -33,8 +33,18 @@ curl --user your_username:your_password_or_token \ https://forgejo.example.com/api/packages/testuser/vagrant/test_system/1.0.0/hyperv.box ``` +If you are using 2FA or OAuth use a personal access token instead of the password. + You cannot publish a box if a box of the same name, version and provider already exists. You must delete the existing package first. +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 is invalid. | +| `409 Conflict` | A package with the same combination of parameters exists already. | + ## Install a package To install a box from the package registry, execute the following command: diff --git a/docs/user/profile.md b/docs/user/profile.md index baa34001..688d045b 100644 --- a/docs/user/profile.md +++ b/docs/user/profile.md @@ -1,10 +1,10 @@ --- title: 'Profile customization' license: 'Apache-2.0' -origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/usage/profile-readme.en-us.md' +origin_url: 'https://github.com/go-gitea/gitea/blob/d3982bcd814bac93e3cbce1c7eb749b17e413fbd/docs/content/usage/profile-readme.en-us.md' --- -By default the profile page of a user is the list of repositories they +By default the profile page of a user (or an organization) is the list of repositories they own. It is possible to customize it with a short description that shows to the left, under their avatar. It can now be fully personalized with a markdown file that is displayed instead of the @@ -13,7 +13,7 @@ list of repositories. ![Profile page](../_images/user/profile/profile-step1.png) It uses the `README.md` file from the `.profile` repository of the -user, if it exists. +user (or organization), if it exists. ![Profile README.md](../_images/user/profile/profile-step2.png) diff --git a/docs/user/protection.md b/docs/user/protection.md index 12543eef..3277ad7c 100644 --- a/docs/user/protection.md +++ b/docs/user/protection.md @@ -1,7 +1,7 @@ --- title: 'Branch and tag protection' license: 'Apache-2.0' -origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/usage/protected-tags.en-us.md' +origin_url: 'https://github.com/go-gitea/gitea/blob/d3982bcd814bac93e3cbce1c7eb749b17e413fbd/docs/content/usage/protected-tags.en-us.md' --- ## Protected branches diff --git a/docs/user/push-to-create.md b/docs/user/push-to-create.md index cead470f..533f9e28 100644 --- a/docs/user/push-to-create.md +++ b/docs/user/push-to-create.md @@ -1,7 +1,7 @@ --- title: 'Push Options' license: 'Apache-2.0' -origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/usage/push.en-us.md' +origin_url: 'https://github.com/go-gitea/gitea/blob/d3982bcd814bac93e3cbce1c7eb749b17e413fbd/docs/content/usage/push.en-us.md' --- ## Push To Create diff --git a/docs/user/token-scope.md b/docs/user/token-scope.md index 7e327715..56b898cd 100644 --- a/docs/user/token-scope.md +++ b/docs/user/token-scope.md @@ -1,7 +1,7 @@ --- title: 'Access Token scope' license: 'Apache-2.0' -origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/development/oauth2-provider.en-us.md' +origin_url: 'https://github.com/go-gitea/gitea/blob/d3982bcd814bac93e3cbce1c7eb749b17e413fbd/docs/content/development/oauth2-provider.en-us.md' --- Forgejo supports scoped access tokens, which allow users to restrict tokens to operate only on selected url routes. Scopes are grouped by high-level API routes, and further refined to the following: diff --git a/docs/user/webhooks.md b/docs/user/webhooks.md index 810b6bec..7dceff41 100644 --- a/docs/user/webhooks.md +++ b/docs/user/webhooks.md @@ -1,7 +1,7 @@ --- title: 'Webhooks' license: 'Apache-2.0' -origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/usage/webhooks.en-us.md' +origin_url: 'https://github.com/go-gitea/gitea/blob/d3982bcd814bac93e3cbce1c7eb749b17e413fbd/docs/content/usage/webhooks.en-us.md' --- Forgejo supports webhooks for repository events. This can be configured in the settings