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

Merge pull request 'docs: v1.20: sync with changes from Codeberg & Gitea' (#305) from dachary/website:wip-upgrade into main

Browse source 
Reviewed-on: https://codeberg.org/forgejo/website/pulls/305
Reviewed-by: Gusted <gusted@noreply.codeberg.org>
This commit is contained in:
Loïc Dachary 2023-07-19 11:18:04 +00:00 committed by Caesar Schinas
commit 8e58214a84
No known key found for this signature in database
GPG key ID: AE9108461BEA5ACF
52 changed files with 299 additions and 665 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

BIN
_images/user/repo-permissions/user-settings-privacy-limited.webp Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 50 KiB

563
admin/command-line.md
View file

@ -1,563 +0,0 @@
---
layout: '~/layouts/Markdown.astro'
title: 'Command Line'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/administration/command-line.en-us.md'
---
## 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=%[1]s)(mail=%[1]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/MariaDB 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.
### actions generate-runner-token
Generate a new token for a runner to use to register with the server
- Options:
- `--scope {owner}[/{repo}]`, `-s {owner}[/{repo}]`: To limit the scope of the runner, no scope means the runner can be used for all repos, but you can also limit it to a specific repo or owner
To register a global runner:
```
forgejo actions generate-runner-token
```
To register a runner for a specific organization, in this case `org`:
```
forgejo actions generate-runner-token -s org
```
To register a runner for a specific repo, in this case `username/test-repo`:
```
forgejo actions generate-runner-token -s username/test-repo
```

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

@ -2,7 +2,7 @@
layout: '~/layouts/Markdown.astro'
title: 'Configuration Cheat Sheet'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/administration/config-cheat-sheet.en-us.md'
origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/administration/config-cheat-sheet.en-us.md'
---
This is a cheat sheet for the Forgejo configuration file. It contains most of the settings
@ -89,8 +89,8 @@ In addition there is _`StaticRootPath`_ which can be set as a built-in at build
- `DEFAULT_CLOSE_ISSUES_VIA_COMMITS_IN_ANY_BRANCH`: **false**: Close an issue if a commit on a non default branch marks it as closed.
- `ENABLE_PUSH_CREATE_USER`: **false**: Allow users to push local repositories to Forgejo and have them automatically created for a user.
- `ENABLE_PUSH_CREATE_ORG`: **false**: Allow users to push local repositories to Forgejo and have them automatically created for an org.
- `DISABLED_REPO_UNITS`: **_empty_**: Comma separated list of globally disabled repo units. Allowed values: \[repo.issues, repo.ext_issues, repo.pulls, repo.wiki, repo.ext_wiki, repo.projects\]
- `DEFAULT_REPO_UNITS`: **repo.code,repo.releases,repo.issues,repo.pulls,repo.wiki,repo.projects,repo.packages**: Comma separated list of default new repo units. Allowed values: \[repo.code, repo.releases, repo.issues, repo.pulls, repo.wiki, repo.projects\]. Note: Code and Releases can currently not be deactivated. If you specify default repo units you should still list them for future compatibility. External wiki and issue tracker can't be enabled by default as it requires additional settings. Disabled repo units will not be added to new repositories regardless if it is in the default list.
- `DISABLED_REPO_UNITS`: **_empty_**: Comma separated list of globally disabled repo units. Allowed values: \[repo.issues, repo.ext_issues, repo.pulls, repo.wiki, repo.ext_wiki, repo.projects, repo.packages, repo.actions\]
- `DEFAULT_REPO_UNITS`: **repo.code,repo.releases,repo.issues,repo.pulls,repo.wiki,repo.projects,repo.packages**: Comma separated list of default new repo units. Allowed values: \[repo.code, repo.releases, repo.issues, repo.pulls, repo.wiki, repo.projects, repo.packages, repo.actions\]. Note: Code and Releases can currently not be deactivated. If you specify default repo units you should still list them for future compatibility. External wiki and issue tracker can't be enabled by default as it requires additional settings. Disabled repo units will not be added to new repositories regardless if it is in the default list.
- `DEFAULT_FORK_REPO_UNITS`: **repo.code,repo.pulls**: Comma separated list of default forked repo units. The set of allowed values and rules is the same as `DEFAULT_REPO_UNITS`.
- `PREFIX_ARCHIVE_FILES`: **true**: Prefix archive files by placing them in a directory named after the repository.
- `DISABLE_MIGRATIONS`: **false**: Disable migrating feature.
@ -103,7 +103,7 @@ In addition there is _`StaticRootPath`_ which can be set as a built-in at build
### Repository - Editor (`repository.editor`)
- `LINE_WRAP_EXTENSIONS`: **.txt,.md,.markdown,.mdown,.mkd,**: List of file extensions for which lines should be wrapped in the Monaco editor. Separate extensions with a comma. To line wrap files without an extension, just put a comma
- `LINE_WRAP_EXTENSIONS`: **.txt,.md,.markdown,.mdown,.mkd,.livemd,**: List of file extensions for which lines should be wrapped in the Monaco editor. Separate extensions with a comma. To line wrap files without an extension, just put a comma
- `PREVIEWABLE_FILE_MODES`: **markdown**: Valid file modes that have a preview API associated with them, such as `api/v1/markdown`. Separate the values by commas. The preview tab in edit mode won't be displayed if the file extension doesn't match.
### Repository - Pull Request (`repository.pull-request`)
@ -210,9 +210,9 @@ The following configuration set `Content-Type: application/vnd.android.package-a
- `MAX_DISPLAY_FILE_SIZE`: **8388608**: Max size of files to be displayed (default is 8MiB)
- `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/img/emoji/reaction_name.png
For custom reactions, add a tightly cropped square image to public/assets/img/emoji/reaction_name.png
- `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/img/emoji/emoji_name.png and
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.
- `DEFAULT_SHOW_FULL_NAME`: **false**: Whether the full name of the users should be shown where possible. If the full name isn't set, the username will be used.
- `SEARCH_REPO_DESCRIPTION`: **true**: Whether to search within description at repository search on explore page.
@ -300,7 +300,11 @@ The following configuration set `Content-Type: application/vnd.android.package-a
- `LOCAL_ROOT_URL`: **%(PROTOCOL)s://%(HTTP_ADDR)s:%(HTTP_PORT)s/**: Local
(DMZ) URL for Forgejo workers (such as SSH update) accessing web service. In
most cases you do not need to change the default value. Alter it only if
your SSH server node is not the same as HTTP node. Do not set this variable
your SSH server node is not the same as HTTP node. For different protocol, the default
values are different. If `PROTOCOL` is `http+unix`, the default value is `http://unix/`.
If `PROTOCOL` is `fcgi` or `fcgi+unix`, the default value is `%(PROTOCOL)s://%(HTTP_ADDR)s:%(HTTP_PORT)s/`.
If listen on `0.0.0.0`, the default value is `%(PROTOCOL)s://localhost:%(HTTP_PORT)s/`, Otherwise the default
value is `%(PROTOCOL)s://%(HTTP_ADDR)s:%(HTTP_PORT)s/`.
if `PROTOCOL` is set to `http+unix`.
- `LOCAL_USE_PROXY_PROTOCOL`: **%(USE_PROXY_PROTOCOL)s**: When making local connections pass the PROXY protocol header.
This should be set to false if the local connection will go through the proxy.
@ -319,7 +323,7 @@ The following configuration set `Content-Type: application/vnd.android.package-a
- `SSH_LISTEN_PORT`: **%(SSH_PORT)s**: Port for the built-in SSH server.
- `SSH_ROOT_PATH`: **~/.ssh**: Root path of SSH directory.
- `SSH_CREATE_AUTHORIZED_KEYS_FILE`: **true**: Forgejo will create a authorized_keys file by default when it is not using the internal ssh server. If you intend to use the AuthorizedKeysCommand functionality then you should turn this off.
- `SSH_AUTHORIZED_KEYS_BACKUP`: **true**: Enable SSH Authorized Key Backup when rewriting all keys, default is true.
- `SSH_AUTHORIZED_KEYS_BACKUP`: **false**: Enable SSH Authorized Key Backup when rewriting all keys, default is false.
- `SSH_TRUSTED_USER_CA_KEYS`: **\<empty\>**: Specifies the public keys of certificate authorities that are trusted to sign user certificates for authentication. Multiple keys should be comma separated. E.g.`ssh-<algorithm> <key>` or `ssh-<algorithm> <key1>, ssh-<algorithm> <key2>`. For more information see `TrustedUserCAKeys` in the sshd config man pages. When empty no file will be created and `SSH_AUTHORIZED_PRINCIPALS_ALLOW` will default to `off`.
- `SSH_TRUSTED_USER_CA_KEYS_FILENAME`: **`RUN_USER`/.ssh/gitea-trusted-user-ca-keys.pem**: Absolute path of the `TrustedUserCaKeys` file Forgejo will manage. If you're running your own ssh server and you want to use the Forgejo managed file you'll also need to modify your sshd_config to point to this file. The official docker image will automatically work without further configuration.
- `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.
@ -351,6 +355,7 @@ The following configuration set `Content-Type: application/vnd.android.package-a
- `LFS_START_SERVER`: **false**: Enables Git LFS support.
- `LFS_CONTENT_PATH`: **%(APP_DATA_PATH)s/lfs**: Default LFS content path. (if it is on local storage.) **DEPRECATED** use settings in `[lfs]`.
- `LFS_JWT_SECRET`: **\<empty\>**: LFS authentication secret, change this a unique string.
- `LFS_JWT_SECRET_URI`: **\<empty\>**: Instead of defining LFS_JWT_SECRET in the configuration, this configuration option can be used to give Gitea a path to a file that contains the secret (example value: `file:/etc/gitea/lfs_jwt_secret`)
- `LFS_HTTP_AUTH_EXPIRY`: **24h**: LFS authentication validity period in time.Duration, pushes taking longer than this may fail.
- `LFS_MAX_FILE_SIZE`: **0**: Maximum allowed LFS file size in bytes (Set to 0 for no limit).
- `LFS_LOCKS_PAGING_NUM`: **50**: Maximum number of LFS Locks returned per page.
@ -429,7 +434,6 @@ The following configuration set `Content-Type: application/vnd.android.package-a
- `SQLITE_TIMEOUT`: **500**: Query timeout for SQLite3 only.
- `SQLITE_JOURNAL_MODE`: **""**: Change journal mode for SQlite3. Can be used to enable [WAL mode](https://www.sqlite.org/wal.html) when high load causes write congestion. See [SQlite3 docs](https://www.sqlite.org/pragma.html#pragma_journal_mode) for possible values. Defaults to the default for the database file, often DELETE.
- `ITERATE_BUFFER_SIZE`: **50**: Internal buffer size for iterating.
- `CHARSET`: **utf8mb4**: For MySQL/MariaDB only, either "utf8" or "utf8mb4". NOTICE: for "utf8mb4" you must use MySQL/MariaDB InnoDB > 5.6. Forgejo is unable to check this.
- `PATH`: **data/forgejo.db**: For SQLite3 only, the database file path.
- `LOG_SQL`: **true**: Log the executed SQL.
- `DB_RETRIES`: **10**: How many ORM init / DB connect attempts allowed.
@ -444,16 +448,16 @@ relation to port exhaustion.
## Indexer (`indexer`)
- `ISSUE_INDEXER_TYPE`: **bleve**: Issue indexer type, currently supported: `bleve`, `db` or `elasticsearch`.
- `ISSUE_INDEXER_CONN_STR`: \*\*\*\*: Issue indexer connection string, available when ISSUE_INDEXER_TYPE is elasticsearch. i.e. http://elastic:changeme@localhost:9200
- `ISSUE_INDEXER_NAME`: **gitea_issues**: Issue indexer name, available when ISSUE_INDEXER_TYPE is elasticsearch
- `ISSUE_INDEXER_TYPE`: **bleve**: Issue indexer type, currently supported: `bleve`, `db`, `elasticsearch` or `meilisearch`.
- `ISSUE_INDEXER_CONN_STR`: \*\*\*\*: Issue indexer connection string, available when ISSUE_INDEXER_TYPE is elasticsearch (e.g. http://elastic:password@localhost:9200) or meilisearch (e.g. http://:apikey@localhost:7700)
- `ISSUE_INDEXER_NAME`: **gitea_issues**: Issue indexer name, available when ISSUE_INDEXER_TYPE is elasticsearch or meilisearch.
- `ISSUE_INDEXER_PATH`: **indexers/issues.bleve**: Index file used for issue search; available when ISSUE*INDEXER_TYPE is bleve and elasticsearch. Relative paths will be made absolute against *`AppWorkPath`\_.
- `REPO_INDEXER_ENABLED`: **false**: Enables code search (uses a lot of disk space, about 6 times more than the repository size).
- `REPO_INDEXER_REPO_TYPES`: **sources,forks,mirrors,templates**: Repo indexer units. The items to index could be `sources`, `forks`, `mirrors`, `templates` or any combination of them separated by a comma. If empty then it defaults to `sources` only, as if you'd like to disable fully please see `REPO_INDEXER_ENABLED`.
- `REPO_INDEXER_TYPE`: **bleve**: Code search engine type, could be `bleve` or `elasticsearch`.
- `REPO_INDEXER_PATH`: **indexers/repos.bleve**: Index file used for code search.
- `REPO_INDEXER_CONN_STR`: \*\*\*\*: Code indexer connection string, available when `REPO_INDEXER_TYPE` is elasticsearch. i.e. http://elastic:changeme@localhost:9200
- `REPO_INDEXER_CONN_STR`: \*\*\*\*: Code indexer connection string, available when `REPO_INDEXER_TYPE` is elasticsearch. i.e. http://elastic:password@localhost:9200
- `REPO_INDEXER_NAME`: **gitea_codes**: Code indexer name, available when `REPO_INDEXER_TYPE` is elasticsearch
- `REPO_INDEXER_INCLUDE`: **empty**: A comma separated list of glob patterns (see https://github.com/gobwas/glob) to **include** in the index. Use `**.txt` to match any files with .txt extension. An empty list means include all files.
@ -705,7 +709,7 @@ Define allowed algorithms and their minimum key length (use -1 to disable a type
- `FORCE_TRUST_SERVER_CERT`: **false**: If set to `true`, completely ignores server certificate validation errors. This option is unsafe. Consider adding the certificate to the system trust store instead.
- `USER`: **\<empty\>**: Username of mailing user (usually the sender's e-mail address).
- `PASSWD`: **\<empty\>**: Password of mailing user. Use \`your password\` for quoting if you use special characters in the password.
- Please note: authentication is only supported when the SMTP server communication is encrypted with TLS (this can be via `STARTTLS`) or SMTP host is localhost. See [Email Setup]({{< relref "doc/usage/email-setup.en-us.md" >}}) for more information.
- Please note: authentication is only supported when the SMTP server communication is encrypted with TLS (this can be via `STARTTLS`) or SMTP host is localhost.
- `ENABLE_HELO`: **true**: Enable HELO operation.
- `HELO_HOSTNAME`: **(retrieved from system)**: HELO hostname.
- `FROM`: **\<empty\>**: Mail from address, RFC 5322. This can be just an email address, or the "Name" \<email@example.com\> format.
@ -765,9 +769,8 @@ Define allowed algorithms and their minimum key length (use -1 to disable a type
- `GRAVATAR_SOURCE`: **gravatar**: Can be `gravatar`, `duoshuo` or anything like
`http://cn.gravatar.com/avatar/`.
- `DISABLE_GRAVATAR`: **true**: Enable this to use local avatars only. **DEPRECATED [v1.18+]** moved to database. Use admin panel to configure.
- `DISABLE_GRAVATAR`: **false**: Enable this to use local avatars only. **DEPRECATED [v1.18+]** moved to database. Use admin panel to configure.
- `ENABLE_FEDERATED_AVATAR`: **false**: Enable support for federated avatars (see
[http://www.libravatar.org](http://www.libravatar.org)). **DEPRECATED [v1.18+]** moved to database. Use admin panel to configure.
- `AVATAR_STORAGE_TYPE`: **default**: Storage type defined in `[storage.xxx]`. Default is `default` which will read `[storage]` if no section `[storage]` will be a type `local`.
- `AVATAR_UPLOAD_PATH`: **data/avatars**: Path to store user avatar image files.
@ -775,7 +778,7 @@ Define allowed algorithms and their minimum key length (use -1 to disable a type
- `AVATAR_MAX_HEIGHT`: **4096**: Maximum avatar image height in pixels.
- `AVATAR_MAX_FILE_SIZE`: **1048576** (1MiB): Maximum avatar image file size in bytes.
- `AVATAR_MAX_ORIGIN_SIZE`: **262144** (256KiB): If the uploaded file is not larger than this byte size, the image will be used as is, without resizing/converting.
- `AVATAR_RENDERED_SIZE_FACTOR`: **3**: The multiplication factor for rendered avatar images. Larger values result in finer rendering on HiDPI devices.
- `AVATAR_RENDERED_SIZE_FACTOR`: **2**: The multiplication factor for rendered avatar images. Larger values result in finer rendering on HiDPI devices.
- `REPOSITORY_AVATAR_STORAGE_TYPE`: **default**: Storage type defined in `[storage.xxx]`. Default is `default` which will read `[storage]` if no section `[storage]` will be a type `local`.
- `REPOSITORY_AVATAR_UPLOAD_PATH`: **data/repo-avatars**: Path to store repository avatar image files.
@ -808,6 +811,8 @@ Default templates for project boards:
- `MINIO_LOCATION`: **us-east-1**: Minio location to create bucket only available when STORAGE_TYPE is `minio`
- `MINIO_BASE_PATH`: **attachments/**: Minio base path on the bucket only available when STORAGE_TYPE is `minio`
- `MINIO_USE_SSL`: **false**: Minio enabled ssl only available when STORAGE_TYPE is `minio`
- `MINIO_INSECURE_SKIP_VERIFY`: **false**: Minio skip SSL verification available when STORAGE_TYPE is `minio`
- `MINIO_CHECKSUM_ALGORITHM`: **default**: Minio checksum algorithm: `default` (for MinIO or AWS S3) or `md5` (for Cloudflare or Backblaze)
## Log (`log`)
@ -822,7 +827,7 @@ Default templates for project boards:
### Access Log (`log`)
- `ACCESS_LOG_TEMPLATE`: **`{{.Ctx.RemoteAddr}} - {{.Identity}} {{.Start.Format "[02/Jan/2006:15:04:05 -0700]" }} "{{.Ctx.Req.Method}} {{.Ctx.Req.URL.RequestURI}} {{.Ctx.Req.Proto}}" {{.ResponseWriter.Status}} {{.ResponseWriter.Size}} "{{.Ctx.Req.Referer}}\" \"{{.Ctx.Req.UserAgent}}"`**: Sets the template used to create the access log.
- `ACCESS_LOG_TEMPLATE`: **`{{.Ctx.RemoteHost}} - {{.Identity}} {{.Start.Format "[02/Jan/2006:15:04:05 -0700]" }} "{{.Ctx.Req.Method}} {{.Ctx.Req.URL.RequestURI}} {{.Ctx.Req.Proto}}" {{.ResponseWriter.Status}} {{.ResponseWriter.Size}} "{{.Ctx.Req.Referer}}" "{{.Ctx.Req.UserAgent}}"`**: Sets the template used to create the access log.
- The following variables are available:
- `Ctx`: the `context.Context` of the request.
- `Identity`: the SignedUserName or `"-"` if not logged in.
@ -933,7 +938,7 @@ Default templates for project boards:
### Extended cron tasks (not enabled by default)
#### Cron - Garbage collect all repositories ('cron.git_gc_repos')
#### Cron - Garbage collect all repositories (`cron.git_gc_repos`)
- `ENABLED`: **false**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
@ -942,42 +947,42 @@ Default templates for project boards:
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `ARGS`: **\<empty\>**: Arguments for command `git gc`, e.g. `--aggressive --auto`. The default value is same with [git] -> GC_ARGS
#### Cron - Update the '.ssh/authorized_keys' file with Forgejo SSH keys ('cron.resync_all_sshkeys')
#### Cron - Update the '.ssh/authorized_keys' file with Forgejo SSH keys (`cron.resync_all_sshkeys`)
- `ENABLED`: **false**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@every 72h**: Cron syntax for scheduling repository archive cleanup, e.g. `@every 1h`.
#### Cron - Resynchronize pre-receive, update and post-receive hooks of all repositories ('cron.resync_all_hooks')
#### Cron - Resynchronize pre-receive, update and post-receive hooks of all repositories (`cron.resync_all_hooks`)
- `ENABLED`: **false**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@every 72h**: Cron syntax for scheduling repository archive cleanup, e.g. `@every 1h`.
#### Cron - Reinitialize all missing Git repositories for which records exist ('cron.reinit_missing_repos')
#### Cron - Reinitialize all missing Git repositories for which records exist (`cron.reinit_missing_repos`)
- `ENABLED`: **false**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@every 72h**: Cron syntax for scheduling repository archive cleanup, e.g. `@every 1h`.
#### Cron - Delete all repositories missing their Git files ('cron.delete_missing_repos')
#### Cron - Delete all repositories missing their Git files (`cron.delete_missing_repos`)
- `ENABLED`: **false**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@every 72h**: Cron syntax for scheduling repository archive cleanup, e.g. `@every 1h`.
#### Cron - Delete generated repository avatars ('cron.delete_generated_repository_avatars')
#### Cron - Delete generated repository avatars (`cron.delete_generated_repository_avatars`)
- `ENABLED`: **false**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@every 72h**: Cron syntax for scheduling repository archive cleanup, e.g. `@every 1h`.
#### Cron - Delete all old actions from database ('cron.delete_old_actions')
#### Cron - Delete all old actions from database (`cron.delete_old_actions`)
- `ENABLED`: **false**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
@ -985,16 +990,16 @@ Default templates for project boards:
- `SCHEDULE`: **@every 168h**: Cron syntax to set how often to check.
- `OLDER_THAN`: **8760h**: any action older than this expression will be deleted from database, suggest using `8760h` (1 year) because that's the max length of heatmap.
#### Cron - Check for new Forgejo versions ('cron.update_checker')
#### Cron - Check for new Forgejo versions (`cron.update_checker`)
- `ENABLED`: **true**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `ENABLE_SUCCESS_NOTICE`: **true**: Set to false to switch off success notices.
- `SCHEDULE`: **@every 168h**: Cron syntax for scheduling a work, e.g. `@every 168h`.
- `HTTP_ENDPOINT`: **https://dl.gitea.io/gitea/version.json**: the endpoint that Gitea will check for newer versions
- `DOMAIN_ENDPOINT`: **release.forgejo.org**: the domain that, if specified, Gitea will check for newer versions. This is preferred over `HTTP_ENDPOINT`.
- `HTTP_ENDPOINT`: **https://dl.gitea.com/gitea/version.json**: the endpoint that Forgejo will check for newer versions
- `DOMAIN_ENDPOINT`: **release.forgejo.org**: the domain that, if specified, Forgejo will check for newer versions. This is preferred over `HTTP_ENDPOINT`.
#### Cron - Delete all old system notices from database ('cron.delete_old_system_notices')
#### Cron - Delete all old system notices from database (`cron.delete_old_system_notices`)
- `ENABLED`: **false**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
@ -1002,7 +1007,7 @@ Default templates for project boards:
- `SCHEDULE`: **@every 168h**: Cron syntax to set how often to check.
- `OLDER_THAN`: **8760h**: any system notice older than this expression will be deleted from database.
#### Cron - Garbage collect LFS pointers in repositories ('cron.gc_lfs')
#### Cron - Garbage collect LFS pointers in repositories (`cron.gc_lfs`)
- `ENABLED`: **false**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
@ -1074,6 +1079,7 @@ This section only does "set" config, a removed config key from this section won'
- `INVALIDATE_REFRESH_TOKENS`: **false**: Check if refresh token has already been used
- `JWT_SIGNING_ALGORITHM`: **RS256**: Algorithm used to sign OAuth2 tokens. Valid values: \[`HS256`, `HS384`, `HS512`, `RS256`, `RS384`, `RS512`, `ES256`, `ES384`, `ES512`\]
- `JWT_SECRET`: **\<empty\>**: OAuth2 authentication secret for access and refresh tokens, change this to a unique string. This setting is only needed if `JWT_SIGNING_ALGORITHM` is set to `HS256`, `HS384` or `HS512`.
- `JWT_SECRET_URI`: **\<empty\>**: Instead of defining JWT_SECRET in the configuration, this configuration option can be used to give Forgejo a path to a file that contains the secret (example value: `file:/etc/forgejo/oauth2_jwt_secret`)
- `JWT_SIGNING_PRIVATE_KEY_FILE`: **jwt/private.pem**: Private key file path used to sign OAuth2 tokens. The path is relative to `APP_DATA_PATH`. This setting is only needed if `JWT_SIGNING_ALGORITHM` is set to `RS256`, `RS384`, `RS512`, `ES256`, `ES384` or `ES512`. The file must contain a RSA or ECDSA private key in the PKCS8 format. If no key exists a 4096 bit key will be created for you.
- `MAX_TOKEN_LENGTH`: **32767**: Maximum length of token/cookie to accept from OAuth2 provider
@ -1229,11 +1235,13 @@ is `data/lfs` and the default of `MINIO_BASE_PATH` is `lfs/`.
- `MINIO_LOCATION`: **us-east-1**: Minio location to create bucket only available when `STORAGE_TYPE` is `minio`
- `MINIO_BASE_PATH`: **lfs/**: Minio base path on the bucket only available when `STORAGE_TYPE` is `minio`
- `MINIO_USE_SSL`: **false**: Minio enabled ssl only available when `STORAGE_TYPE` is `minio`
- `MINIO_INSECURE_SKIP_VERIFY`: **false**: Minio skip SSL verification available when STORAGE_TYPE is `minio`
## Storage (`storage`)
Default storage configuration for attachments, lfs, avatars and etc.
Default storage configuration for attachments, lfs, avatars, repo-avatars, repo-archive, packages, actions_log, actions_artifact.
- `STORAGE_TYPE`: **local**: Storage type, `local` for local disk or `minio` for s3 compatible object storage service.
- `SERVE_DIRECT`: **false**: Allows the storage driver to redirect to authenticated URLs to serve files directly. Currently, only Minio/S3 is supported via signed URLs, local does nothing.
- `MINIO_ENDPOINT`: **localhost:9000**: Minio endpoint to connect only available when `STORAGE_TYPE` is `minio`
- `MINIO_ACCESS_KEY_ID`: Minio accessKeyID to connect only available when `STORAGE_TYPE` is `minio`
@ -1241,11 +1249,12 @@ Default storage configuration for attachments, lfs, avatars and etc.
- `MINIO_BUCKET`: **gitea**: Minio bucket to store the data only available when `STORAGE_TYPE` is `minio`
- `MINIO_LOCATION`: **us-east-1**: Minio location to create bucket only available when `STORAGE_TYPE` is `minio`
- `MINIO_USE_SSL`: **false**: Minio enabled ssl only available when `STORAGE_TYPE` is `minio`
- `MINIO_INSECURE_SKIP_VERIFY`: **false**: Minio skip SSL verification available when STORAGE_TYPE is `minio`
And you can also define a customize storage like below:
The recommanded storage configuration for minio like below:
```ini
[storage.my_minio]
[storage]
STORAGE_TYPE = minio
; Minio endpoint to connect only available when STORAGE_TYPE is `minio`
MINIO_ENDPOINT = localhost:9000
@ -1259,9 +1268,56 @@ MINIO_BUCKET = gitea
MINIO_LOCATION = us-east-1
; Minio enabled ssl only available when STORAGE_TYPE is `minio`
MINIO_USE_SSL = false
; Minio skip SSL verification available when STORAGE_TYPE is `minio`
MINIO_INSECURE_SKIP_VERIFY = false
SERVE_DIRECT = true
```
And used by `[attachment]`, `[lfs]` and etc. as `STORAGE_TYPE`.
Defaultly every storage has their default base path like below
| storage | default base path |
| ----------------- | ------------------ |
| attachments | attachments/ |
| lfs | lfs/ |
| avatars | avatars/ |
| repo-avatars | repo-avatars/ |
| repo-archive | repo-archive/ |
| packages | packages/ |
| actions_log | actions_log/ |
| actions_artifacts | actions_artifacts/ |
And bucket, basepath or `SERVE_DIRECT` could be special or overrided, if you want to use a different you can:
```ini
[storage.actions_log]
MINIO_BUCKET = forgejo_actions_log
SERVE_DIRECT = true
MINIO_BASE_PATH = my_actions_log/ ; default is actions_log/ if blank
```
If you want to customerize a different storage for `lfs` if above default storage defined
```ini
[lfs]
STORAGE_TYPE = my_minio
[storage.my_minio]
STORAGE_TYPE = minio
; Minio endpoint to connect only available when STORAGE_TYPE is `minio`
MINIO_ENDPOINT = localhost:9000
; Minio accessKeyID to connect only available when STORAGE_TYPE is `minio`
MINIO_ACCESS_KEY_ID =
; Minio secretAccessKey to connect only available when STORAGE_TYPE is `minio`
MINIO_SECRET_ACCESS_KEY =
; Minio bucket to store the attachments only available when STORAGE_TYPE is `minio`
MINIO_BUCKET = forgejo
; Minio location to create bucket only available when STORAGE_TYPE is `minio`
MINIO_LOCATION = us-east-1
; Minio enabled ssl only available when STORAGE_TYPE is `minio`
MINIO_USE_SSL = false
; Minio skip SSL verification available when STORAGE_TYPE is `minio`
MINIO_INSECURE_SKIP_VERIFY = false
```
## Repository Archive Storage (`storage.repo-archive`)
@ -1279,6 +1335,12 @@ is `data/repo-archive` and the default of `MINIO_BASE_PATH` is `repo-archive/`.
- `MINIO_LOCATION`: **us-east-1**: Minio location to create bucket only available when `STORAGE_TYPE` is `minio`
- `MINIO_BASE_PATH`: **repo-archive/**: Minio base path on the bucket only available when `STORAGE_TYPE` is `minio`
- `MINIO_USE_SSL`: **false**: Minio enabled ssl only available when `STORAGE_TYPE` is `minio`
- `MINIO_INSECURE_SKIP_VERIFY`: **false**: Minio skip SSL verification available when STORAGE_TYPE is `minio`
## Repository Archives (`repo-archive`)
- `STORAGE_TYPE`: **local**: Storage type for actions logs, `local` for local disk or `minio` for s3 compatible object storage service, default is `local` or other name defined with `[storage.xxx]`
- `MINIO_BASE_PATH`: **repo-archive/**: Minio base path on the bucket only available when STORAGE_TYPE is `minio`
## Proxy (`proxy`)
@ -1298,10 +1360,11 @@ PROXY_HOSTS = *.github.com
- `ENABLED`: **false**: 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"
- `STORAGE_TYPE`: **local**: Storage type for actions logs, `local` for local disk or `minio` for s3 compatible object storage service, default is `local` or other name defined with `[storage.xxx]`
- `MINIO_BASE_PATH`: **actions_log/**: Minio base path on the bucket only available when STORAGE_TYPE is `minio`
## Other (`other`)
- `SHOW_FOOTER_BRANDING`: **false**: Show Forgejo branding in the footer.
- `SHOW_FOOTER_VERSION`: **true**: Show Forgejo and Go version information in the footer.
- `SHOW_FOOTER_TEMPLATE_LOAD_TIME`: **true**: Show time of template execution in the footer.
- `ENABLE_SITEMAP`: **true**: Generate sitemap.

2
admin/database-preparation.md
View file

@ -2,7 +2,7 @@
layout: '~/layouts/Markdown.astro'
title: 'Database Preparation'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/installation/database-preparation.en-us.md'
origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/installation/database-preparation.en-us.md'
---
You need a database to use Forgejo. Forgejo supports PostgreSQL (>=10), MySQL (>=5.7) or MariaDB (>=10.0), SQLite, and MSSQL (>=2008R2 SP3). This page will guide into preparing 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.

2
admin/email-setup.md
View file

@ -2,7 +2,7 @@
layout: '~/layouts/Markdown.astro'
title: 'Email setup'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/administration/email-setup.en-us.md'
origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/administration/email-setup.en-us.md'
---
Forgejo has mailer functionality for sending transactional emails (such as registration confirmation). It can be configured to either use Sendmail (or compatible MTAs like Postfix and msmtp) or directly use SMTP server.

2
admin/incoming-email.md
View file

@ -2,7 +2,7 @@
layout: '~/layouts/Markdown.astro'
title: 'Incoming Email'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/incoming-email.en-us.md'
origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/usage/incoming-email.en-us.md'
---
Forgejo supports the execution of several actions through incoming mails. This page describes how to set this up.

1
admin/index.md
View file

@ -10,7 +10,6 @@ These documents are targeted to people who run Forgejo on their machines.
- [Database Preparation](database-preparation)
- [Configuration Cheat Sheet](config-cheat-sheet)
- [Upgrade guide](upgrade)
- [Command Line](command-line)
- [Reverse Proxy](reverse-proxy)
- [Email setup](email-setup)
- [Incoming Email](incoming-email)

2
admin/logging-documentation.md
View file

@ -2,7 +2,7 @@
layout: '~/layouts/Markdown.astro'
title: 'Logging Configuration'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/administration/logging-config.en-us.md'
origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/administration/logging-config.en-us.md'
---
The logging configuration of Forgejo mainly consists of 3 types of components:

2
admin/reverse-proxy.md
View file

@ -2,7 +2,7 @@
layout: '~/layouts/Markdown.astro'
title: 'Reverse proxy'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/authentication.en-us.md'
origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/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

2
admin/search-engines-indexation.md
View file

@ -2,7 +2,7 @@
layout: '~/layouts/Markdown.astro'
title: 'Search Engines Indexation'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/administration/search-engines-indexation.en-us.md'
origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/administration/search-engines-indexation.en-us.md'
---
# Search engines indexation of your Forgejo installation

2
admin/seek-assistance.md
View file

@ -2,7 +2,7 @@
layout: '~/layouts/Markdown.astro'
title: 'Seek Assistance'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/help/seek-help.en-us.md'
origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/help/seek-help.en-us.md'
---
- [Chatroom](https://matrix.to/#/#forgejo-chat:matrix.org)

2
admin/upgrade.md
View file

@ -41,7 +41,7 @@ Note: Forgejo requires [docker >= 20.10.6](https://wiki.alpinelinux.org/wiki/Rel
### Performing the upgrade
- If the upgrade is from a Gitea version [lower than 1.6](https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/models/migrations/migrations.go#L63) and greater or equal to 1.2.0, proceed as follows:
- If the upgrade is from a Gitea version [lower than 1.6](https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/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

118
developer/from-source.md Normal file
View file

@ -0,0 +1,118 @@
---
layout: '~/layouts/Markdown.astro'
title: 'Compiling from source'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/installation/from-source.en-us.md'
---
# Installation from source
You should [install go](https://golang.org/doc/install) and set up your go
environment correctly. In particular, it is recommended to set the `$GOPATH`
environment variable and to add the go bin directory or directories
`${GOPATH//://bin:}/bin` to the `$PATH`. See the Go wiki entry for
[GOPATH](https://github.com/golang/go/wiki/GOPATH).
Next, [install Node.js with npm](https://nodejs.org/en/download/) which is
required to build the JavaScript and CSS files. The minimum supported Node.js
version is 16 and the latest LTS version is recommended.
**Note**: When executing make tasks that require external tools, like
`make misspell-check`, Forgejo will automatically download and build these as
necessary. To be able to use these, you must have the `"$GOPATH/bin"` directory
on the executable path. If you don't add the go bin directory to the
executable path, you will have to manage this yourself.
**Note 2**: Go version 1.20 or higher is required. However, it is recommended to
obtain the same version as our continuous integration, see the advice given in
[Hacking on Forgejo]({{< relref "doc/development/hacking-on-forgejo.en-us.md" >}})
## Download
First, we must retrieve the source code. Since, the advent of go modules, the
simplest way of doing this is to use Git directly as we no longer have to have
Forgejo built from within the GOPATH.
```bash
git clone https://codeberg.org/forgejo/forgejo
```
Decide which version of Forgejo to build and install. Currently, there are
multiple options to choose from. The `forgejo` branch represents the current
development version.
To work with tagged releases, the following commands can be used:
```bash
git branch -a
git checkout v1.20.0-5
```
To build Forgejo from source at a specific tagged release (like v1.20.0-5), list the
available tags and check out the specific tag.
List available tags with the following.
```bash
git tag -l
git checkout v1.20.0-5
```
## Build
To build from source, the following programs must be present on the system:
- `go` v1.20 or higher, see [here](https://golang.org/dl/)
- `node` 16 or higher with `npm`, see [here](https://nodejs.org/en/download/)
- `make`
Depending on requirements, the following build tags can be included.
- `bindata`: Build a single monolithic binary, with all assets included. Required for production build.
- `sqlite sqlite_unlock_notify`: Enable support for a
[SQLite3](https://sqlite.org/) database. Suggested only for small
installations.
- `pam`: Enable support for PAM (Linux Pluggable Authentication Modules). Can
be used to authenticate local users or extend authentication to methods
available to PAM.
Using the `bindata` build tag is required for production
deployments. You could exclude `bindata` when you are
developing/testing Forgejo or able to separate the assets correctly.
To include all assets, use the `bindata` tag:
```bash
TAGS="bindata" make build
```
In the default release build of the continuous integration system, the build
tags are: `TAGS="bindata sqlite sqlite_unlock_notify"`. The simplest
recommended way to build from source is therefore:
```bash
TAGS="bindata sqlite sqlite_unlock_notify" make build
```
The `build` target is split into two sub-targets:
- `make backend` which requires [Go v1.20](https://golang.org/dl/) or greater.
- `make frontend` which requires [Node.js 16](https://nodejs.org/en/download/) or greater.
If pre-built frontend files are present it is possible to only build the backend:
```bash
TAGS="bindata" make backend
```
Webpack source maps are by default enabled in development builds and disabled in production builds. They can be enabled by setting the `ENABLE_SOURCEMAP=true` environment variable.
## Test
After following the steps above, a `forgejo` binary will be available in the working directory.
It can be tested from this directory or moved to a directory with test data. When Forgejo is
launched manually from command line, it can be killed by pressing `Ctrl + C`.
```bash
./forgejo web
```

1
developer/index.md
View file

@ -12,6 +12,7 @@ their needs.
- [Governance](GOVERNANCE)
- [Sustainability and funding](https://codeberg.org/forgejo/sustainability/src/branch/master/README)
- For contributors
- [Compiling from source](from-source)
- [Developer Certificate of Origin (DCO)](DCO)
- [Development workflow](WORKFLOW)
- [code.forgejo.org](code-forgejo-org)

2
user/agit-support.md
View file

@ -2,7 +2,7 @@
layout: '~/layouts/Markdown.astro'
title: 'Agit Setup'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/agit-support.en-us.md'
origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/usage/agit-support.en-us.md'
---
Limited support for [agit](https://git-repo.info/en/2020/03/agit-flow-and-git-repo/).

2
user/api-usage.md
View file

@ -2,7 +2,7 @@
layout: '~/layouts/Markdown.astro'
title: 'API Usage'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/development/api-usage.en-us.md'
origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/development/api-usage.en-us.md'
---
## Enabling/configuring API access

2
user/authentication.md
View file

@ -2,7 +2,7 @@
layout: '~/layouts/Markdown.astro'
title: 'Authentication'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/authentication.en-us.md'
origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/usage/authentication.en-us.md'
---
## LDAP (Lightweight Directory Access Protocol)

2
user/email-settings.md
View file

@ -2,7 +2,7 @@
layout: '~/layouts/Markdown.astro'
title: 'Email Settings'
license: 'CC-BY-SA-4.0'
origin_url: 'https://codeberg.org/Codeberg/Documentation/src/commit/2887826c38b3aae76a18f0696b40217b429226ce/content/getting-started/email-settings.md'
origin_url: 'https://codeberg.org/Codeberg/Documentation/src/commit/5d457efc069b52d512632fea024917e0848346cd/content/getting-started/email-settings.md'
---
By default, Forgejo will send notifications to your registered email addresses.

24
user/first-repository.md
View file

@ -2,7 +2,7 @@
layout: '~/layouts/Markdown.astro'
title: Your First Repository
license: 'CC-BY-SA-4.0'
origin_url: 'https://codeberg.org/Codeberg/Documentation/src/commit/2887826c38b3aae76a18f0696b40217b429226ce/content/getting-started/first-repository.md'
origin_url: 'https://codeberg.org/Codeberg/Documentation/src/commit/5d457efc069b52d512632fea024917e0848346cd/content/getting-started/first-repository.md'
---
Almost everything on Forgejo happens in a repository. Think of a repository as a home for your project, where all of its source code can be organized using Git, as well as where you can track issues and read and write wikis.
@ -11,6 +11,8 @@ This article will guide you through creating your first repository on Forgejo, c
## Creating a Repository
> A note to more advanced users: It's currently not possible to use Push-to-Create to push a fresh repository onto Forgejo.
To create a new repository, you need be logged in to your account.
When you're logged in, you can use one of the two buttons shown in the two following screenshots to create a new repository:
@ -73,11 +75,7 @@ If you want to start a fresh project (so if you don't already have source code t
#### 1. Navigate to your local workspace (optional)
If you're just getting started, it's a good idea to keep your projects neatly sorted in a dedicated directory, like in the following example.
We assume a Linux machine. `mkdir` creates a new directory, `cd` changes into it.
`$` is indicating that the commands are run as a user without admin permissions.
`~/repositories$` is meant to be read as „current working directory is the repositories folder within the home directory”.
The username here is `knut` on a machine with the name of `iceberg`.
If you're just getting started, it's a good idea to keep your projects neatly sorted in a dedicated directory, like in this example:
```bash
knut@iceberg:~$ mkdir repositories
@ -99,15 +97,11 @@ remote: Counting objects: 100% (4/4), done.
remote: Compressing objects: 100% (3/3), done.
remote: Total 4 (delta 0), reused 0 (delta 0)
Unpacking objects: 100% (4/4), 11.94 KiB | 764.00 KiB/s, done.
The exact values for size and download speed might differ on your machine.
```
#### 3. Navigate to the cloned repository
After cloning, the repository should now be in a new directory with the same name as your repository. In this case, it's called `foobar`.
The command `ls` lists all files within the current folder.
```bash
knut@iceberg:~/repositories$ cd foobar
@ -141,6 +135,12 @@ knut@iceberg:~/my-project$ git remote add origin https://codeberg.org/knut/fooba
If all is done correctly, this command should output nothing.
> **Errors:**
> If you added an already initalized remote repository and try to push, you will get an error, if your local commit history is different from the history of the remote. You have some choices to resolve the conflict:
>
> - Merge your changes with the ones in the remote `git pull`
> - If you are sure, that you want to overwrite all changes in the remote, you can force push with `git -f push`
## Making your first commit
Now that you've connected your repository to your local development copy, it's time to make your first commit.
@ -221,8 +221,6 @@ Date: Sat Sep 26 12:29:57 2020 +0200
Initial commit
```
The dates, commit hash and author will be different for your project.
#### 4. Push your changes to Forgejo
If you're happy with the changes you made, the next step is to present them to the world by pushing them to Forgejo:
@ -244,8 +242,6 @@ To https://codeberg.org/knut/foobar
Branch 'main' set up to track remote branch 'main' from 'origin'.
```
It is expected that you won't see any visual feedback when entering your password. Type it blind and hit return.
The `-u` option sets the upstream remote, which we want to be Codeberg.org, as configured previously.
The `main` argument sets the name of the branch onto which shall be pushed upstream. For this example, it should be the same branch name that you specified when creating the repository.

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

@ -2,7 +2,7 @@
layout: '~/layouts/Markdown.astro'
title: 'Issue and Pull Request Templates'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/issue-pull-request-templates.en-us.md'
origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/usage/issue-pull-request-templates.en-us.md'
---
Some projects have a standard list of questions that users need to answer

2
user/issue-tracking-basics.md
View file

@ -2,7 +2,7 @@
layout: '~/layouts/Markdown.astro'
title: 'The Basics of Issue Tracking'
license: 'CC-BY-SA-4.0'
origin_url: 'https://codeberg.org/Codeberg/Documentation/src/commit/2887826c38b3aae76a18f0696b40217b429226ce/content/getting-started/issue-tracking-basics.md'
origin_url: 'https://codeberg.org/Codeberg/Documentation/src/commit/5d457efc069b52d512632fea024917e0848346cd/content/getting-started/issue-tracking-basics.md'
---
Issues are an important mean of communication on Forgejo.

2
user/labels.md
View file

@ -2,7 +2,7 @@
layout: '~/layouts/Markdown.astro'
title: 'Labels'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/labels.en-us.md'
origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/usage/labels.en-us.md'
---
You can use labels to classify issues and pull requests and to improve your overview over them.

2
user/linked-references.md
View file

@ -2,7 +2,7 @@
layout: '~/layouts/Markdown.astro'
title: 'Automatically Linked References in Issues, Pull Requests and Commit Messages'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/linked-references.en-us.md'
origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/usage/linked-references.en-us.md'
---
When an issue, pull request or comment is posted, the text description is parsed

2
user/merge-message-templates.md
View file

@ -2,7 +2,7 @@
layout: '~/layouts/Markdown.astro'
title: 'Merge Message templates'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/merge-message-templates.en-us.md'
origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/usage/merge-message-templates.en-us.md'
---
## File names

2
user/oauth2-provider.md
View file

@ -2,7 +2,7 @@
layout: '~/layouts/Markdown.astro'
title: 'OAuth2 provider'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/development/oauth2-provider.en-us.md'
origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/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.

2
user/packages/alpine.md
View file

@ -2,7 +2,7 @@
layout: '~/layouts/Markdown.astro'
title: 'Alpine Packages Repository'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/packages/alpine.en-us.md'
origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/usage/packages/alpine.en-us.md'
---
Publish [Alpine](https://pkgs.alpinelinux.org/) packages for your user or organization.

2
user/packages/cargo.md
View file

@ -2,7 +2,7 @@
layout: '~/layouts/Markdown.astro'
title: 'Cargo Package Registry'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/packages/cargo.en-us.md'
origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/usage/packages/cargo.en-us.md'
---
Publish [Cargo](https://doc.rust-lang.org/stable/cargo/) packages for your user or organization.

2
user/packages/chef.md
View file

@ -2,7 +2,7 @@
layout: '~/layouts/Markdown.astro'
title: 'Chef Package Registry'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/packages/chef.en-us.md'
origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/usage/packages/chef.en-us.md'
---
Publish [Chef](https://chef.io/) cookbooks for your user or organization.

2
user/packages/composer.md
View file

@ -2,7 +2,7 @@
layout: '~/layouts/Markdown.astro'
title: 'Composer Package Registry'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/packages/composer.en-us.md'
origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/usage/packages/composer.en-us.md'
---
Publish [Composer](https://getcomposer.org/) packages for your user or organization.

2
user/packages/conan.md
View file

@ -2,7 +2,7 @@
layout: '~/layouts/Markdown.astro'
title: 'Conan Package Registry'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/packages/conan.en-us.md'
origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/usage/packages/conan.en-us.md'
---
Publish [Conan](https://conan.io/) packages for your user or organization.

2
user/packages/conda.md
View file

@ -2,7 +2,7 @@
layout: '~/layouts/Markdown.astro'
title: 'Conda Package Registry'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/packages/conda.en-us.md'
origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/usage/packages/conda.en-us.md'
---
Publish [Conda](https://docs.conda.io/en/latest/) packages for your user or organization.

2
user/packages/container.md
View file

@ -2,7 +2,7 @@
layout: '~/layouts/Markdown.astro'
title: 'Container Registry'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/packages/container.en-us.md'
origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/usage/packages/container.en-us.md'
---
Publish [Open Container Initiative](https://opencontainers.org/) compliant images for your user or organization.

2
user/packages/cran.md
View file

@ -2,7 +2,7 @@
layout: '~/layouts/Markdown.astro'
title: 'CRAN Package Registry'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/packages/cran.en-us.md'
origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/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.

2
user/packages/debian.md
View file

@ -2,7 +2,7 @@
layout: '~/layouts/Markdown.astro'
title: 'Debian Package Registry'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/packages/debian.en-us.md'
origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/usage/packages/debian.en-us.md'
---
Publish [Debian](https://www.debian.org/distrib/packages) packages for your user or organization.

2
user/packages/generic.md
View file

@ -2,7 +2,7 @@
layout: '~/layouts/Markdown.astro'
title: 'Generic Package Registry'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/packages/generic.en-us.md'
origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/usage/packages/generic.en-us.md'
---
Publish generic files, like release binaries or other output, for your user or organization.

2
user/packages/go.md
View file

@ -2,7 +2,7 @@
layout: '~/layouts/Markdown.astro'
title: 'Go Package Registry'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/packages/go.en-us.md'
origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/usage/packages/go.en-us.md'
---
Publish Go packages for your user or organization.

2
user/packages/helm.md
View file

@ -2,7 +2,7 @@
layout: '~/layouts/Markdown.astro'
title: 'Helm Chart Registry'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/packages/helm.en-us.md'
origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/usage/packages/helm.en-us.md'
---
Publish [Helm](https://helm.sh/) charts for your user or organization.

2
user/packages/maven.md
View file

@ -2,7 +2,7 @@
layout: '~/layouts/Markdown.astro'
title: 'Maven Package Registry'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/packages/maven.en-us.md'
origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/usage/packages/maven.en-us.md'
---
Publish [Maven](https://maven.apache.org) packages for your user or organization.

2
user/packages/npm.md
View file

@ -2,7 +2,7 @@
layout: '~/layouts/Markdown.astro'
title: 'npm Package Registry'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/packages/npm.en-us.md'
origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/usage/packages/npm.en-us.md'
---
Publish [npm](https://www.npmjs.com/) packages for your user or organization.

2
user/packages/nuget.md
View file

@ -2,7 +2,7 @@
layout: '~/layouts/Markdown.astro'
title: 'NuGet Package Registry'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/packages/nuget.en-us.md'
origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/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.

2
user/packages/pub.md
View file

@ -2,7 +2,7 @@
layout: '~/layouts/Markdown.astro'
title: 'Pub Package Registry'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/packages/pub.en-us.md'
origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/usage/packages/pub.en-us.md'
---
Publish [Pub](https://dart.dev/guides/packages) packages for your user or organization.

2
user/packages/pypi.md
View file

@ -2,7 +2,7 @@
layout: '~/layouts/Markdown.astro'
title: 'PyPI Package Registry'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/packages/pypi.en-us.md'
origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/usage/packages/pypi.en-us.md'
---
Publish [PyPI](https://pypi.org/) packages for your user or organization.

2
user/packages/rpm.md
View file

@ -2,7 +2,7 @@
layout: '~/layouts/Markdown.astro'
title: 'RPM Package Registry'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/packages/rpm.en-us.md'
origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/usage/packages/rpm.en-us.md'
---
Publish [RPM](https://rpm.org/) packages for your user or organization.

2
user/packages/rubygems.md
View file

@ -2,7 +2,7 @@
layout: '~/layouts/Markdown.astro'
title: 'RubyGems Packages Repository'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/packages/rubygems.en-us.md'
origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/usage/packages/rubygems.en-us.md'
---
Publish [RubyGems](https://guides.rubygems.org/) packages for your user or organization.

2
user/packages/storage.md
View file

@ -2,7 +2,7 @@
layout: '~/layouts/Markdown.astro'
title: 'Storage'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/packages/storage.en-us.md'
origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/usage/packages/storage.en-us.md'
---
This document describes the storage of the package registry and how it can be managed.

2
user/packages/swift.md
View file

@ -2,7 +2,7 @@
layout: '~/layouts/Markdown.astro'
title: 'Swift Packages Repository'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/packages/swift.en-us.md'
origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/usage/packages/swift.en-us.md'
---
# Swift Packages Repository

2
user/packages/vagrant.md
View file

@ -2,7 +2,7 @@
layout: '~/layouts/Markdown.astro'
title: 'Vagrant Packages Repository'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/packages/vagrant.en-us.md'
origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/usage/packages/vagrant.en-us.md'
---
Publish [Vagrant](https://www.vagrantup.com/) packages for your user or organization.

2
user/protection.md
View file

@ -2,7 +2,7 @@
layout: '~/layouts/Markdown.astro'
title: 'Branch and tag protection'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/protected-tags.en-us.md'
origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/usage/protected-tags.en-us.md'
---
# Protected branches

2
user/push-to-create.md
View file

@ -2,7 +2,7 @@
layout: '~/layouts/Markdown.astro'
title: 'Push Options'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/push.en-us.md'
origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/usage/push.en-us.md'
---
# Push To Create

16
user/repo-permissions.md
View file

@ -2,15 +2,21 @@
layout: '~/layouts/Markdown.astro'
title: 'Repository Permissions'
license: 'CC-BY-SA-4.0'
origin_url: 'https://codeberg.org/Codeberg/Documentation/src/commit/2887826c38b3aae76a18f0696b40217b429226ce/content/collaborating/repo-permissions.md'
origin_url: 'https://codeberg.org/Codeberg/Documentation/src/commit/5d457efc069b52d512632fea024917e0848346cd/content/collaborating/repo-permissions.md'
---
<!-- See also https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/permissions.en-us.md -->
When you invite collaborators to join your repository or when you create teams for your organization, you have to decide what each collaborator/team is allowed to do.
You can assign teams different levels of permission for each unit (e.g. issues, PR's, wiki).
## Profile and Visibility
Visibility of your repositories is in general inherited from your profile. So other user can only see your repositories, if your profile is _public_.
If you want to limit visibility access to your repositories you can set your **user visibility** in the user privacy settings to **Limited**. Even if your repository is public, non-contributors will get a 404-error if they try to access your repository.
![screenshot showing the updated README](../../../../images/v1.20/user/repo-permissions/user-settings-privacy-limited.webp)
## Collaborators
There are four permission levels: Read, Write, Administrator and Owner.
@ -118,7 +124,7 @@ Each unit is configured to have one of these 3 permission levels:
- Read: Members can view the unit, and do standard actions for that unit (See the Read column under [Collaborators](#collaborators)).
- Write: Members can view the unit, and execute write actions that unit (See the Write column under [Collaborators](#collaborators)).
When a team is configured to have administrator access, you cannot change units.
When a team is configured to have administrator access, when this is specified, you cannot change units. The team will have admin permissions (See the Admin column under _Collaborators_).
Currently, there are six units that can be configured:
@ -134,4 +140,4 @@ There are also two units which can be toggled:
- External Wiki: access to external wiki.
- External Issues: access to the external issue tracker.
A team can be given the permission to create new repositories. When a member of such team creates a new repository, they will get administrator access to the repository.
A team can be given the permission to create new repositories. When a member of such team creates a new repository, he/she will get administrator access to the repository.

2
user/webhooks.md
View file

@ -2,7 +2,7 @@
layout: '~/layouts/Markdown.astro'
title: 'Webhooks'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/webhooks.en-us.md'
origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/usage/webhooks.en-us.md'
---
Forgejo supports webhooks for repository events. This can be configured in the settings

22
user/wiki.md
View file

@ -2,7 +2,7 @@
layout: '~/layouts/Markdown.astro'
title: 'Integrated Wiki'
license: 'CC-BY-SA-4.0'
origin_url: 'https://codeberg.org/Codeberg/Documentation/src/commit/2887826c38b3aae76a18f0696b40217b429226ce/content/getting-started/wiki.md'
origin_url: 'https://codeberg.org/Codeberg/Documentation/src/commit/5d457efc069b52d512632fea024917e0848346cd/content/getting-started/wiki.md'
---
A [wiki](https://en.wikipedia.org/wiki/Wiki) is a collaborative space on the web. It is a common practice to use wikis to collect knowledge and share information.
@ -15,7 +15,7 @@ The user in these examples is `knut`, the polar bear and its repository is `foob
To enable the wiki for a repository, visit the `Settings` page and activate `Enable Repository Wiki` in the `Advanced Section`. It will default to the built-in wiki which is described here, but you can add an URI to an external site the "Wiki" tab should link to.
> **Warning**
> Be aware that the wiki, once enabled, is accessible for _everyone_ who has `read` access to your repository - on public repositories even anonymous guests can access the wiki.
> Be aware that the wiki, once enabled, is accessible for _everyone_ who has `read` access to your repository - on public repositories even unauthenticated guests can access the wiki.
> The wiki is _not_ a suitable place for storing private information or secrets (like passwords).
To edit the wiki `write` permission to the repository is required.
@ -35,7 +35,9 @@ The web UI in your browser is currently limited to adding, updating, and deletin
![Wiki home page with edit buttons](../../../../images/v1.20/user/wiki/wiki_pageview.png)
## Adding content via a local Git client
Clicking on the "Insert Image" button will make the following text appear in your text editor: `![](https://)`
## Adding content using a local Git client
You can work with the wiki repo as you would with any other Git repo on Forgejo.
@ -48,7 +50,7 @@ git commit -am "create Home page"
Editing locally allows you to use your favorite editor (preferably with Markdown syntax check and highlighting) and manage additional assets like images.
### Adding images
### Adding images using a local Git client
You can add images to the root directory or a specific subfolder (like `assets` or `images`) using your local Git client.
@ -64,12 +66,24 @@ git commit -m "add image"
git push
```
## Attaching images in Markdown documents
Now, you can reference the image in Markdown, like this:
**File in repository**:
```markdown
![image alt text](images/image.png 'image title')
```
**External image**:
```markdown
![image alt text](https://example.com/image.jpg 'image title')
```
When including images from Forgejo repositories, keep in mind that _you should use the raw version of the image._
After saving your changes, the image should be visible.
> In contrast to embedding external images, images in Git are only rendered after saving the wiki or Markdown file changes.