Import docs into main repository (#2874)

* import docs into main repository Signed-off-by: Matti Ranta <matti@mdranta.net>
2025-07-22 18:28:37 +00:00 · 2017-11-26 16:44:32 -05:00
parent f148a4a1ed
commit fb5c6b6444
68 changed files with 3720 additions and 0 deletions
--- a/docs/content/doc/features/authentication.en-us.md
+++ b/docs/content/doc/features/authentication.en-us.md
@@ -0,0 +1,194 @@
+---
+date: "2016-12-01T16:00:00+02:00"
+title: "Authentication"
+slug: "authentication"
+weight: 10
+toc: true
+draft: false
+menu:
+  sidebar:
+    parent: "features"
+    name: "Authentication"
+    weight: 10
+    identifier: "authentication"
+---
+
+---
+name: Authentication
+---
+
+# Authentication
+
+## LDAP (Lightweight Directory Access Protocol)
+
+Both the LDAP via BindDN and the simple auth LDAP share the following fields:
+
+- Authorization Name **(required)**
+  - A name to assign to the new method of authorization.
+
+- Host **(required)**
+  - The address where the LDAP server can be reached.
+  - Example: `mydomain.com`
+
+- Port **(required)**
+  - The port to use when connecting to the server.
+  - Example: `389` for LDAP or `636` for LDAP SSL
+
+- Enable TLS Encryption (optional)
+  - Whether to use TLS when connecting to the LDAP server.
+
+- Admin Filter (optional)
+  - An LDAP filter specifying if a user should be given administrator
+    privileges. If a user account passes the filter, the user will be
+    privileged as an administrator.
+  - Example: `(objectClass=adminAccount)`
+  - Example for Microsoft Active Directory (AD): `(memberOf=CN=admin-group,OU=example,DC=example,DC=org)`
+
+- Username attribute (optional)
+  - The attribute of the user's LDAP record containing the user name. Given
+    attribute value will be used for new Gitea account user name after first
+    successful sign-in. Leave empty to use login name given on sign-in form.
+  - This is useful when supplied login name is matched against multiple
+    attributes, but only single specific attribute should be used for Gitea
+    account name, see "User Filter".
+  - Example: `uid`
+  - Example for Microsoft Active Directory (AD): `sAMAccountName`
+
+- First name attribute (optional)
+  - The attribute of the user's LDAP record containing the user's first name.
+    This will be used to populate their account information.
+  - Example: `givenName`
+
+- Surname attribute (optional)
+  - The attribute of the user's LDAP record containing the user's surname.
+    This will be used to populate their account information.
+  - Example: `sn`
+
+- E-mail attribute **(required)**
+  - The attribute of the user's LDAP record containing the user's email
+    address. This will be used to populate their account information.
+  - Example: `mail`
+
+**LDAP via BindDN** adds the following fields:
+
+- Bind DN (optional)
+  - The DN to bind to the LDAP server with when searching for the user. This
+    may be left blank to perform an anonymous search.
+  - Example: `cn=Search,dc=mydomain,dc=com`
+
+- Bind Password (optional)
+  - The password for the Bind DN specified above, if any. _Note: The password
+    is stored in plaintext at the server. As such, ensure that your Bind DN
+    has as few privileges as possible._
+
+- User Search Base **(required)**
+  - The LDAP base at which user accounts will be searched for.
+  - Example: `ou=Users,dc=mydomain,dc=com`
+
+- User Filter **(required)**
+  - An LDAP filter declaring how to find the user record that is attempting to
+    authenticate. The `%s` matching parameter will be substituted with login
+    name given on sign-in form.
+  - Example: `(&(objectClass=posixAccount)(uid=%s))`
+  - Example for Microsoft Active Directory (AD): `(&(objectCategory=Person)(memberOf=CN=user-group,OU=example,DC=example,DC=org)(sAMAccountName=%s)(!(UserAccountControl:1.2.840.113556.1.4.803:=2)))`
+  - To substitute more than once `%[1]s` should be used instead, e.g. when
+    matching supplied login name against multiple attributes such as user
+    identifier, email or even phone number.
+  - Example: `(&(objectClass=Person)(|(uid=%[1]s)(mail=%[1]s)(mobile=%[1]s)))`
+
+**LDAP using simple auth** adds the following fields:
+
+- User DN **(required)**
+  - A template to use as the user's DN. The `%s` matching parameter will be substituted with login name given on sign-in form.
+  - Example: `cn=%s,ou=Users,dc=mydomain,dc=com`
+  - Example: `uid=%s,ou=Users,dc=mydomain,dc=com`
+
+- User Filter **(required)**
+  - An LDAP filter declaring when a user should be allowed to log in. The `%s`
+    matching parameter will be substituted with login name given on sign-in
+    form.
+  - Example: `(&(objectClass=posixAccount)(cn=%s))`
+  - Example: `(&(objectClass=posixAccount)(uid=%s))`
+
+**Verify group membership in LDAP** uses the following fields:
+
+* Group Search Base (optional)
+    * The LDAP DN used for groups.
+    * Example: `ou=group,dc=mydomain,dc=com`
+
+* Group Name Filter (optional)
+    * An LDAP filter declaring how to find valid groups in the above DN.
+    * Example: `(|(cn=gitea_users)(cn=admins))`
+
+* User Attribute in Group (optional)
+    * Which user LDAP attribute is listed in the group.
+    * Example: `uid`
+
+* Group Attribute for User (optional)
+    * Which group LDAP attribute contains an array above user attribute names.
+    * Example: `memberUid`
+
+## PAM (Pluggable Authentication Module)
+
+To configure this you just need to set the 'PAM Service Name' to a filename in `/etc/pam.d/`.
+If you want it to work with normal Linux passwords, the user running Gitea must have read access to `/etc/shadow`.
+
+## SMTP (Simple Mail Transfer Protocol)
+
+This option allows Gitea to log in to your SMTP host as a Gitea user. To configure this, simply set the fields below:
+
+- Authentication Name **(required)**
+  - A name to assign to the new method of authorization.
+
+- SMTP Authentication Type **(required)**
+  - Type of authentication for use on your SMTP host, PLAIN or LOGIN.
+
+- Host **(required)**
+  - The address where the SMTP host can be reached.
+  - Example: `smtp.mydomain.com`
+
+- Port **(required)**
+  - The port to use when connecting to the server.
+  - Example: `587`
+
+- Allowed Domains
+  - Restrict what domains can log in if you're using public SMTP host or SMTP host with multiple domains.
+  - Example: `gitea.io,mydomain.com,mydomain2.com`
+
+- Enable TLS Encryption
+  - Enable TLS encryption on authentication.
+
+- Skip TLS Verify
+  - Disable TLS verify on authentication.
+  
+- This authentication is activate
+  - Enable or disable this auth.
+
+## FreeIPA
+
+- In order to log in to Gitea using FreeIPA credentials, you need to create a bind account for Gitea to use:
+
+-  On the FreeIPA server, create a `gitea.ldif` file, replacing `dc=example,dc=com` with your DN, and providing an appropriately secure password:
+```
+  dn: uid=gitea,cn=sysaccounts,cn=etc,dc=example,dc=com
+  changetype: add
+  objectclass: account
+  objectclass: simplesecurityobject
+  uid: gitea
+  userPassword: secure password
+  passwordExpirationTime: 20380119031407Z
+  nsIdleTimeout: 0
+```
+
+- Import the LDIF (change localhost to an IPA server if needed), you’ll be prompted for your Directory Manager password:
+```
+  ldapmodify -h localhost -p 389 -x -D \
+  "cn=Directory Manager" -W -f gitea.ldif
+```
+-  Add an IPA group for gitea_users :
+```
+  ipa group-add --desc="Gitea Users" gitea_users
+```
+-  Note: If you get an error about IPA credentials, please run `kinit admin` and give your admin account password.
+
+-  Now login to the Gitea as an Administrator, click on "Authentication" under Admin Panel. Then click `Add New Source` and fill in the details, changing all where appropriate to your own domain.
--- a/docs/content/doc/features/authentication.zh-cn.md
+++ b/docs/content/doc/features/authentication.zh-cn.md
@@ -0,0 +1,18 @@
+---
+date: "2016-12-01T16:00:00+02:00"
+title: "认证"
+slug: "authentication"
+weight: 10
+toc: true
+draft: false
+menu:
+  sidebar:
+    parent: "features"
+    name: "认证"
+    weight: 10
+    identifier: "authentication"
+---
+
+# 认证
+
+## TBD
--- a/docs/content/doc/features/authentication.zh-tw.md
+++ b/docs/content/doc/features/authentication.zh-tw.md
@@ -0,0 +1,18 @@
+---
+date: "2016-12-01T16:00:00+02:00"
+title: "認證"
+slug: "authentication"
+weight: 10
+toc: true
+draft: false
+menu:
+  sidebar:
+    parent: "features"
+    name: "認證"
+    weight: 10
+    identifier: "authentication"
+---
+
+# 認證
+
+## TBD
--- a/docs/content/doc/features/localization.en-us.md
+++ b/docs/content/doc/features/localization.en-us.md
@@ -0,0 +1,18 @@
+---
+date: "2016-12-01T16:00:00+02:00"
+title: "Localization"
+slug: "localization"
+weight: 10
+toc: true
+draft: false
+menu:
+  sidebar:
+    parent: "features"
+    name: "Localization"
+    weight: 20
+    identifier: "localization"
+---
+
+# Localization
+
+## TBD
--- a/docs/content/doc/features/localization.zh-cn.md
+++ b/docs/content/doc/features/localization.zh-cn.md
@@ -0,0 +1,18 @@
+---
+date: "2016-12-01T16:00:00+02:00"
+title: "本地化"
+slug: "localization"
+weight: 10
+toc: true
+draft: false
+menu:
+  sidebar:
+    parent: "features"
+    name: "本地化"
+    weight: 20
+    identifier: "localization"
+---
+
+# 本地化
+
+## TBD
--- a/docs/content/doc/features/localization.zh-tw.md
+++ b/docs/content/doc/features/localization.zh-tw.md
@@ -0,0 +1,18 @@
+---
+date: "2016-12-01T16:00:00+02:00"
+title: "在地化"
+slug: "localization"
+weight: 10
+toc: true
+draft: false
+menu:
+  sidebar:
+    parent: "features"
+    name: "在地化"
+    weight: 20
+    identifier: "localization"
+---
+
+# Localization
+
+## TBD
--- a/docs/content/doc/features/webhooks.en-us.md
+++ b/docs/content/doc/features/webhooks.en-us.md
@@ -0,0 +1,103 @@
+---
+date: "2016-12-01T16:00:00+02:00"
+title: "Webhooks"
+slug: "webhooks"
+weight: 10
+toc: true
+draft: false
+menu:
+  sidebar:
+    parent: "features"
+    name: "Webhooks"
+    weight: 30
+    identifier: "webhooks"
+---
+
+# Webhooks
+
+Gitea supports web hooks for repository events, you can find it in settings page(`/:username/:reponame/settings/hooks`). All event pushes are POST requests, and we currently support two formats: Gitea and Slack.
+
+### Event information
+
+Following shows an example of event information that will be sent by Gitea to Payload URL:
+
+
+```
+X-Github-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473
+X-Github-Event: push
+X-Gogs-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473
+X-Gogs-Event: push
+X-Gitea-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473
+X-Gitea-Event: push
+```
+
+```json
+{
+  "secret": "3gEsCfjlV2ugRwgpU#w1*WaW*wa4NXgGmpCfkbG3",
+  "ref": "refs/heads/develop",
+  "before": "28e1879d029cb852e4844d9c718537df08844e03",
+  "after": "bffeb74224043ba2feb48d137756c8a9331c449a",
+  "compare_url": "http://localhost:3000/gitea/webhooks/compare/28e1879d029cb852e4844d9c718537df08844e03...bffeb74224043ba2feb48d137756c8a9331c449a",
+  "commits": [
+    {
+      "id": "bffeb74224043ba2feb48d137756c8a9331c449a",
+      "message": "Webhooks Yay!",
+      "url": "http://localhost:3000/gitea/webhooks/commit/bffeb74224043ba2feb48d137756c8a9331c449a",
+      "author": {
+        "name": "Gitea",
+        "email": "someone@gitea.io",
+        "username": "gitea"
+      },
+      "committer": {
+        "name": "Gitea",
+        "email": "someone@gitea.io",
+        "username": "gitea"
+      },
+      "timestamp": "2017-03-13T13:52:11-04:00"
+    }
+  ],
+  "repository": {
+    "id": 140,
+    "owner": {
+      "id": 1,
+      "login": "gitea",
+      "full_name": "Gitea",
+      "email": "someone@gitea.io",
+      "avatar_url": "https://localhost:3000/avatars/1",
+      "username": "gitea"
+    },
+    "name": "webhooks",
+    "full_name": "gitea/webhooks",
+    "description": "",
+    "private": false,
+    "fork": false,
+    "html_url": "http://localhost:3000/gitea/webhooks",
+    "ssh_url": "ssh://gitea@localhost:2222/gitea/webhooks.git",
+    "clone_url": "http://localhost:3000/gitea/webhooks.git",
+    "website": "",
+    "stars_count": 0,
+    "forks_count": 1,
+    "watchers_count": 1,
+    "open_issues_count": 7,
+    "default_branch": "master",
+    "created_at": "2017-02-26T04:29:06-05:00",
+    "updated_at": "2017-03-13T13:51:58-04:00"
+  },
+  "pusher": {
+    "id": 1,
+    "login": "gitea",
+    "full_name": "Gitea",
+    "email": "someone@gitea.io",
+    "avatar_url": "https://localhost:3000/avatars/1",
+    "username": "gitea"
+  },
+  "sender": {
+    "id": 1,
+    "login": "gitea",
+    "full_name": "Gitea",
+    "email": "someone@gitea.io",
+    "avatar_url": "https://localhost:3000/avatars/1",
+    "username": "gitea"
+  }
+}
+```
--- a/docs/content/doc/features/webhooks.zh-cn.md
+++ b/docs/content/doc/features/webhooks.zh-cn.md
@@ -0,0 +1,18 @@
+---
+date: "2016-12-01T16:00:00+02:00"
+title: "Webhooks"
+slug: "webhooks"
+weight: 10
+toc: true
+draft: false
+menu:
+  sidebar:
+    parent: "features"
+    name: "Webhooks"
+    weight: 30
+    identifier: "webhooks"
+---
+
+# Webhooks
+
+## TBD
--- a/docs/content/doc/features/webhooks.zh-tw.md
+++ b/docs/content/doc/features/webhooks.zh-tw.md
@@ -0,0 +1,18 @@
+---
+date: "2016-12-01T16:00:00+02:00"
+title: "Webhooks"
+slug: "webhooks"
+weight: 10
+toc: true
+draft: false
+menu:
+  sidebar:
+    parent: "features"
+    name: "Webhooks"
+    weight: 30
+    identifier: "webhooks"
+---
+
+# Webhooks
+
+## TBD