markup: expand test coverage and sanitize notice banner output

Add previously covered autolink test cases that were dropped during the
goldmark migration (hosts without dots, https variants, single-digit
issues, cross-repo issues). Add new test suites for link rewriting with
both path-only and absolute URL prefixes, and for HTML passthrough
behavior confirming raw HTML is stripped without WithUnsafe.

Sanitize RawMarkdown output in the server notice banner to prevent
potential XSS, since it was the only call site not passing through
SanitizeBytes.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

CHANGELOG.md

@@ -4,6 +4,10 @@ All notable changes to Gogs are documented in this file.
 
 ## 0.15.0+dev (`main`)
 
+### Removed
+
+- The `gogs cert` subcommand. [#8153](https://github.com/gogs/gogs/pull/8153)
+
 ## 0.14.1
 
 ### Added

Taskfile.yml

@@ -94,3 +94,8 @@ tasks:
     desc: Run all linters
     cmds:
       - golangci-lint run
+
+  docs:
+    desc: Start docs server
+    cmds:
+      - cd docs && mint dev --port 3333

cmd/gogs/cert.go

@@ -1,171 +0,0 @@
-// Copyright 2009 The Go Authors. All rights reserved.
-// Use of this source code is governed by a BSD-style
-// license that can be found in the LICENSE file.
-
-package main
-
-import (
-	"crypto/ecdsa"
-	"crypto/elliptic"
-	"crypto/rand"
-	"crypto/rsa"
-	"crypto/x509"
-	"crypto/x509/pkix"
-	"encoding/pem"
-	"log"
-	"math/big"
-	"net"
-	"os"
-	"strings"
-	"time"
-
-	"github.com/urfave/cli"
-)
-
-var certCommand = cli.Command{
-	Name:  "cert",
-	Usage: "Generate self-signed certificate",
-	Description: `Generate a self-signed X.509 certificate for a TLS server.
-Outputs to 'cert.pem' and 'key.pem' and will overwrite existing files.`,
-	Action: runCert,
-	Flags: []cli.Flag{
-		stringFlag("host", "", "Comma-separated hostnames and IPs to generate a certificate for"),
-		stringFlag("ecdsa-curve", "", "ECDSA curve to use to generate a key. Valid values are P224, P256, P384, P521"),
-		intFlag("rsa-bits", 2048, "Size of RSA key to generate. Ignored if --ecdsa-curve is set"),
-		stringFlag("start-date", "", "Creation date formatted as Jan 1 15:04:05 2011"),
-		durationFlag("duration", 365*24*time.Hour, "Duration that certificate is valid for"),
-		boolFlag("ca", "whether this cert should be its own Certificate Authority"),
-	},
-}
-
-func publicKey(priv any) any {
-	switch k := priv.(type) {
-	case *rsa.PrivateKey:
-		return &k.PublicKey
-	case *ecdsa.PrivateKey:
-		return &k.PublicKey
-	default:
-		return nil
-	}
-}
-
-func pemBlockForKey(priv any) *pem.Block {
-	switch k := priv.(type) {
-	case *rsa.PrivateKey:
-		return &pem.Block{Type: "RSA PRIVATE KEY", Bytes: x509.MarshalPKCS1PrivateKey(k)}
-	case *ecdsa.PrivateKey:
-		b, err := x509.MarshalECPrivateKey(k)
-		if err != nil {
-			log.Fatalf("Unable to marshal ECDSA private key: %v\n", err)
-		}
-		return &pem.Block{Type: "EC PRIVATE KEY", Bytes: b}
-	default:
-		return nil
-	}
-}
-
-func runCert(ctx *cli.Context) error {
-	if len(ctx.String("host")) == 0 {
-		log.Fatal("Missing required --host parameter")
-	}
-
-	var priv any
-	var err error
-	switch ctx.String("ecdsa-curve") {
-	case "":
-		priv, err = rsa.GenerateKey(rand.Reader, ctx.Int("rsa-bits"))
-	case "P224":
-		priv, err = ecdsa.GenerateKey(elliptic.P224(), rand.Reader)
-	case "P256":
-		priv, err = ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
-	case "P384":
-		priv, err = ecdsa.GenerateKey(elliptic.P384(), rand.Reader)
-	case "P521":
-		priv, err = ecdsa.GenerateKey(elliptic.P521(), rand.Reader)
-	default:
-		log.Fatalf("Unrecognized elliptic curve: %q", ctx.String("ecdsa-curve"))
-	}
-	if err != nil {
-		log.Fatalf("Failed to generate private key: %s", err)
-	}
-
-	var notBefore time.Time
-	if len(ctx.String("start-date")) == 0 {
-		notBefore = time.Now()
-	} else {
-		notBefore, err = time.Parse("Jan 2 15:04:05 2006", ctx.String("start-date"))
-		if err != nil {
-			log.Fatalf("Failed to parse creation date: %s", err)
-		}
-	}
-
-	notAfter := notBefore.Add(ctx.Duration("duration"))
-
-	serialNumberLimit := new(big.Int).Lsh(big.NewInt(1), 128)
-	serialNumber, err := rand.Int(rand.Reader, serialNumberLimit)
-	if err != nil {
-		log.Fatalf("Failed to generate serial number: %s", err)
-	}
-
-	template := x509.Certificate{
-		SerialNumber: serialNumber,
-		Subject: pkix.Name{
-			Organization: []string{"Acme Co"},
-			CommonName:   "Gogs",
-		},
-		NotBefore: notBefore,
-		NotAfter:  notAfter,
-
-		KeyUsage:              x509.KeyUsageKeyEncipherment | x509.KeyUsageDigitalSignature,
-		ExtKeyUsage:           []x509.ExtKeyUsage{x509.ExtKeyUsageServerAuth},
-		BasicConstraintsValid: true,
-	}
-
-	hosts := strings.Split(ctx.String("host"), ",")
-	for _, h := range hosts {
-		if ip := net.ParseIP(h); ip != nil {
-			template.IPAddresses = append(template.IPAddresses, ip)
-		} else {
-			template.DNSNames = append(template.DNSNames, h)
-		}
-	}
-
-	if ctx.Bool("ca") {
-		template.IsCA = true
-		template.KeyUsage |= x509.KeyUsageCertSign
-	}
-
-	derBytes, err := x509.CreateCertificate(rand.Reader, &template, &template, publicKey(priv), priv)
-	if err != nil {
-		log.Fatalf("Failed to create certificate: %s", err)
-	}
-
-	certOut, err := os.Create("cert.pem")
-	if err != nil {
-		log.Fatalf("Failed to open cert.pem for writing: %s", err)
-	}
-	err = pem.Encode(certOut, &pem.Block{Type: "CERTIFICATE", Bytes: derBytes})
-	if err != nil {
-		log.Fatalf("Failed to encode data to cert.pem: %s", err)
-	}
-	err = certOut.Close()
-	if err != nil {
-		log.Fatalf("Failed to close writing to cert.pem: %s", err)
-	}
-	log.Println("Written cert.pem")
-
-	keyOut, err := os.OpenFile("key.pem", os.O_WRONLY|os.O_CREATE|os.O_TRUNC, 0o600)
-	if err != nil {
-		log.Fatalf("Failed to open key.pem for writing: %v\n", err)
-	}
-	err = pem.Encode(keyOut, pemBlockForKey(priv))
-	if err != nil {
-		log.Fatalf("Failed to encode data to key.pem: %s", err)
-	}
-	err = keyOut.Close()
-	if err != nil {
-		log.Fatalf("Failed to close writing to key.pem: %s", err)
-	}
-	log.Println("Written key.pem")
-	return nil
-}

cmd/gogs/cmd.go

@@ -1,8 +1,6 @@
 package main
 
 import (
-	"time"
-
 	"github.com/urfave/cli"
 )
 
@@ -20,19 +18,3 @@ func boolFlag(name, usage string) cli.BoolFlag {
 		Usage: usage,
 	}
 }
-
-func intFlag(name string, value int, usage string) cli.IntFlag {
-	return cli.IntFlag{
-		Name:  name,
-		Value: value,
-		Usage: usage,
-	}
-}
-
-func durationFlag(name string, value time.Duration, usage string) cli.DurationFlag {
-	return cli.DurationFlag{
-		Name:  name,
-		Value: value,
-		Usage: usage,
-	}
-}

cmd/gogs/hook.go

@@ -9,9 +9,9 @@ import (
 	"os"
 	"os/exec"
 	"path/filepath"
+	"strconv"
 	"strings"
 
-	"github.com/unknwon/com"
 	"github.com/urfave/cli"
 	log "unknwon.dev/clog/v2"
 
@@ -21,6 +21,7 @@ import (
 	"gogs.io/gogs/internal/database"
 	"gogs.io/gogs/internal/email"
 	"gogs.io/gogs/internal/httplib"
+	"gogs.io/gogs/internal/osutil"
 )
 
 var (
@@ -85,7 +86,7 @@ func runHookPreReceive(c *cli.Context) error {
 		branchName := git.RefShortName(string(fields[2]))
 
 		// Branch protection
-		repoID := com.StrTo(os.Getenv(database.EnvRepoID)).MustInt64()
+		repoID, _ := strconv.ParseInt(os.Getenv(database.EnvRepoID), 10, 64)
 		protectBranch, err := database.GetProtectBranchOfRepoByName(repoID, branchName)
 		if err != nil {
 			if database.IsErrBranchNotExist(err) {
@@ -101,7 +102,7 @@ func runHookPreReceive(c *cli.Context) error {
 		bypassRequirePullRequest := false
 
 		// Check if user is in whitelist when enabled
-		userID := com.StrTo(os.Getenv(database.EnvAuthUserID)).MustInt64()
+		userID, _ := strconv.ParseInt(os.Getenv(database.EnvAuthUserID), 10, 64)
 		if protectBranch.EnableWhitelist {
 			if !database.IsUserInProtectBranchWhitelist(repoID, userID, branchName) {
 				fail(fmt.Sprintf("Branch '%s' is protected and you are not in the push whitelist", branchName), "")
@@ -131,7 +132,7 @@ func runHookPreReceive(c *cli.Context) error {
 	}
 
 	customHooksPath := filepath.Join(os.Getenv(database.EnvRepoCustomHooksPath), "pre-receive")
-	if !com.IsFile(customHooksPath) {
+	if !osutil.IsFile(customHooksPath) {
 		return nil
 	}
 
@@ -165,7 +166,7 @@ func runHookUpdate(c *cli.Context) error {
 	}
 
 	customHooksPath := filepath.Join(os.Getenv(database.EnvRepoCustomHooksPath), "update")
-	if !com.IsFile(customHooksPath) {
+	if !osutil.IsFile(customHooksPath) {
 		return nil
 	}
 
@@ -213,11 +214,12 @@ func runHookPostReceive(c *cli.Context) error {
 			continue
 		}
 
+		pusherID, _ := strconv.ParseInt(os.Getenv(database.EnvAuthUserID), 10, 64)
 		options := database.PushUpdateOptions{
 			OldCommitID:  string(fields[0]),
 			NewCommitID:  string(fields[1]),
 			FullRefspec:  string(fields[2]),
-			PusherID:     com.StrTo(os.Getenv(database.EnvAuthUserID)).MustInt64(),
+			PusherID:     pusherID,
 			PusherName:   os.Getenv(database.EnvAuthUserName),
 			RepoUserName: os.Getenv(database.EnvRepoOwnerName),
 			RepoName:     os.Getenv(database.EnvRepoName),
@@ -249,7 +251,7 @@ func runHookPostReceive(c *cli.Context) error {
 	}
 
 	customHooksPath := filepath.Join(os.Getenv(database.EnvRepoCustomHooksPath), "post-receive")
-	if !com.IsFile(customHooksPath) {
+	if !osutil.IsFile(customHooksPath) {
 		return nil
 	}
 

cmd/gogs/import.go

@@ -9,10 +9,10 @@ import (
 	"time"
 
 	"github.com/cockroachdb/errors"
-	"github.com/unknwon/com"
 	"github.com/urfave/cli"
 
 	"gogs.io/gogs/internal/conf"
+	"gogs.io/gogs/internal/osutil"
 )
 
 var (
@@ -44,9 +44,9 @@ func runImportLocale(c *cli.Context) error {
 	} else if !c.IsSet("target") {
 		return errors.New("target directory is not specified")
 	}
-	if !com.IsDir(c.String("source")) {
+	if !osutil.IsDir(c.String("source")) {
 		return errors.Newf("source directory %q does not exist or is not a directory", c.String("source"))
-	} else if !com.IsDir(c.String("target")) {
+	} else if !osutil.IsDir(c.String("target")) {
 		return errors.Newf("target directory %q does not exist or is not a directory", c.String("target"))
 	}
 
@@ -66,7 +66,7 @@ func runImportLocale(c *cli.Context) error {
 		name := fmt.Sprintf("locale_%s.ini", lang)
 		source := filepath.Join(c.String("source"), name)
 		target := filepath.Join(c.String("target"), name)
-		if !com.IsFile(source) {
+		if !osutil.IsFile(source) {
 			continue
 		}
 

cmd/gogs/main.go

@@ -23,7 +23,6 @@ func main() {
 		webCommand,
 		servCommand,
 		hookCommand,
-		certCommand,
 		adminCommand,
 		importCommand,
 		backupCommand,

cmd/gogs/serv.go

@@ -6,10 +6,10 @@ import (
 	"os"
 	"os/exec"
 	"path/filepath"
+	"strconv"
 	"strings"
 	"time"
 
-	"github.com/unknwon/com"
 	"github.com/urfave/cli"
 	log "unknwon.dev/clog/v2"
 
@@ -188,7 +188,8 @@ func runServ(c *cli.Context) error {
 	// Allow anonymous (user is nil) clone for public repositories.
 	var user *database.User
 
-	key, err := database.GetPublicKeyByID(com.StrTo(strings.TrimPrefix(c.Args()[0], "key-")).MustInt64())
+	keyID, _ := strconv.ParseInt(strings.TrimPrefix(c.Args()[0], "key-"), 10, 64)
+	key, err := database.GetPublicKeyByID(keyID)
 	if err != nil {
 		fail("Invalid key ID", "Invalid key ID '%s': %v", c.Args()[0], err)
 	}

cmd/gogs/web.go

@@ -20,7 +20,6 @@ import (
 	"github.com/go-macaron/session"
 	"github.com/go-macaron/toolbox"
 	"github.com/prometheus/client_golang/prometheus/promhttp"
-	"github.com/unknwon/com"
 	"github.com/urfave/cli"
 	"gopkg.in/macaron.v1"
 	log "unknwon.dev/clog/v2"
@@ -53,7 +52,7 @@ and it takes care of all the other things for you`,
 	Action: runWeb,
 	Flags: []cli.Flag{
 		stringFlag("port, p", "3000", "Temporary port number to prevent conflict"),
-		stringFlag("config, c", "", "Custom configuration file path"),
+		stringFlag("config, c", filepath.Join(conf.CustomDir(), "conf", "app.ini"), "Custom configuration file path"),
 	},
 }
 
@@ -308,7 +307,7 @@ func runWeb(c *cli.Context) error {
 				if err != nil {
 					c.NotFoundOrError(err, "get attachment by UUID")
 					return
-				} else if !com.IsFile(attach.LocalPath()) {
+				} else if !osutil.IsFile(attach.LocalPath()) {
 					c.NotFound()
 					return
 				}

docs-old/admin/lfs.md

@@ -1,21 +0,0 @@
-# Configuring Git Large File Storage (LFS)
-
-> NOTE: Git LFS is supported in Gogs starting with version 0.12.
-
-Git LFS works out of box with default configuration for any supported versions.
-
-## Known limitations
-
-- Only local storage is supported (i.e. all LFS objects are stored on the same server where Gogs runs), support of Object Storage Service like Amazon S3 is being tracked in [#6065](https://github.com/gogs/gogs/issues/6065).
-
-## Configuration
-
-All configuration options for Git LFS are located in [`[lfs]` section](https://github.com/gogs/gogs/blob/44ea9604ed7440c2cf1105d965c2429ee225e8f6/conf/app.ini#L266-L270):
-
-```ini
-[lfs]
-; The storage backend for uploading new objects.
-STORAGE = local
-; The root path to store LFS objects on local file system.
-OBJECTS_PATH = data/lfs-objects
-```

docs-old/admin/release_strategy.md

@@ -1,33 +0,0 @@
-# Release strategy
-
-## Semantic versioning
-
-Starting 0.12.0, Gogs uses [semantic versioning](https://semver.org/) for publishing releases. For example:
-
-- `0.12.0` is a minor version release.
-- `0.12.1` is the first patch release of `0.12`.
-- `0.12` indicates a series of releases for a minor version and its patch releases.
-
-Each minor release has its own release branch with prefix `release/`, e.g. `release/0.12` is the release branch for minor version 0.12.0 and all its patch releases (`0.12.1`, `0.12.2`, etc.).
-
-## Backwards compatibility
-
-### Before 0.12
-
-If you're running Gogs with any version below 0.12, please upgrade to 0.12 to run necessary migrations.
-
-### Since 0.12
-
-We maintain one minor version backwards compatibility, patch releases are disregarded.
-
-For example, you should:
-
-- Upgrade from `0.12.0` to `0.13.0`.
-- Upgrade from `0.12.1` to `0.13.4`.
-- NOT upgrade from `0.12.4` to `0.14.0`.
-
-Therefore, we recommend upgrade one minor version at a time.
-
-### Running source builds
-
-If you're running Gogs with building from source code, we recommend you update at least weekly to be not fall behind and potentially miss migrations.

docs-old/user/lfs.md

@@ -1,28 +0,0 @@
-# Git Large File Storage (LFS)
-
-> This document is driven from https://docs.gitlab.com/ee/topics/git/lfs/.
-
-Managing large binaries in Git repositories is challenging, that is why Git LFS was developed for, to manage large files.
-
-## How it works
-
-Git LFS client talks with the Gogs server over HTTP/HTTPS. It uses HTTP Basic Authentication to authorize client requests. Once the request is authorized, Git LFS client receives instructions from where to fetch or where to push the large file.
-
-## Server configuration
-
-Please refer to [Configuring Git Large File Storage (LFS)](../admin/lfs.md).
-
-## Requirements
-
-- Git LFS is supported in Gogs starting with version 0.12.
-- [Git LFS client](https://git-lfs.github.com/) version 1.0.1 and up.
-
-## Known limitations
-
-- When SSH is set as a remote, Git LFS objects still go through HTTP/HTTPS.
-- Any Git LFS request will ask for HTTP/HTTPS credentials to be provided so a good Git credentials store is recommended.
-- File locking is not supported, and is being tracked in [#6064](https://github.com/gogs/gogs/issues/6064).
-
-## Using Git LFS
-
-Git LFS endpoints in a Gogs server can be automatically discovered by the Git LFS client, therefore you do not need to configure anything upfront for using it. Please walk through official [Git LFS Tutorial](https://github.com/git-lfs/git-lfs/wiki/Tutorial) to get started.

docs/README.md

@@ -0,0 +1,26 @@
+## Development
+
+Install the [Mintlify CLI](https://www.npmjs.com/package/mint) to preview your documentation changes locally. To install, use the following command:
+
+```
+pnpm i -g mint
+```
+
+Run the following command at the root of your documentation, where your `docs.json` is located:
+
+```
+mint dev
+```
+
+View your local preview at `http://localhost:3000`.
+
+## Need help?
+
+### Troubleshooting
+
+- If your dev environment isn't running: Run `mint update` to ensure you have the most recent version of the CLI.
+- If a page loads as a 404: Make sure you are running in a folder with a valid `docs.json`.
+
+### Resources
+
+- [Mintlify documentation](https://mintlify.com/docs)

docs/advancing/authentication.mdx

@@ -0,0 +1,270 @@
+---
+title: "Authentication"
+description: "Integrate with your existing IAM system"
+icon: "key"
+---
+
+Gogs supports authentication through various external sources. Currently supported backends are **LDAP**, **SMTP**, **PAM**, and **HTTP header**. Authentication sources can be configured in two ways:
+
+- **Admin Panel**: Navigate to **Admin Panel > Authentication Sources**
+- **Configuration files**: Place `.conf` files in the `custom/conf/auth.d/` directory. Each file describes one source using INI format. Files are loaded once at startup and keyed by `id`. See the "Configuration file" subsection under each backend below for examples.
+
+## LDAP
+
+Gogs supports two variants of LDAP authentication: **Simple Auth** and **Bind DN**. In both cases, authentication is performed by attempting to bind to the LDAP server with the User DN and password. The difference is that with Bind DN, a preliminary query is performed (using the Bind DN credentials) to find the User DN first.
+
+<Tabs>
+  <Tab title="When to use Bind DN">
+    The Bind DN mechanism has these advantages:
+
+    - It may be more secure than blindly attempting to bind with a possibly non-existent User DN.
+    - It supports login with attributes such as email address or phone number. The preliminary search can look up the User DN using `mail` or `mobile` attributes.
+    - It is required when the LDAP does not allow the User DN to query its own attributes or group memberships.
+
+    The downside is that, unless the LDAP allows anonymous queries, it requires a bind DN to be defined and Gogs needs to store its credentials. Gogs currently does not encrypt these credentials.
+  </Tab>
+  <Tab title="When to use Simple Auth">
+    In the ideal situation where you know the exact DN template for your users and the LDAP allows the User DN to query its own attributes, Simple Auth is the simpler option. It requires no separate bind account and no stored credentials beyond what the user provides at login.
+  </Tab>
+</Tabs>
+
+### Shared fields
+
+The following fields are shared between both **Bind DN** and **Simple Auth** configurations:
+
+| Field | Required | Description | Example |
+|---|---|---|---|
+| **Authentication Name** | Yes | A friendly name for the authentication source. | `My LDAP` |
+| **Security Protocol** | Yes | Connection security: Unencrypted, LDAPS, or StartTLS. | `LDAPS` |
+| **Host** | Yes | The address of the LDAP server. | `ldap.mydomain.com` |
+| **Port** | Yes | The port for the LDAP connection. Usually `389` for LDAP/StartTLS, `636` for LDAPS. | `389` |
+| **User Filter** | Yes | An LDAP filter declaring which users can log in. The `%s` parameter is substituted with the login name. | `(&(objectClass=posixAccount)(uid=%s))` |
+| **Email Attribute** | Yes | The LDAP attribute containing the user's email address. | `mail` |
+| **Admin Filter** | No | An LDAP filter applied to the User DN context to determine Gogs administrator privileges. | `(memberOf=cn=admins,cn=groups,dc=mydomain,dc=com)` |
+| **Username Attribute** | No | The LDAP attribute containing the username. Used for the Gogs account name after first sign-in. Leave empty to use the login name from the sign-in form. | `uid` |
+| **First Name Attribute** | No | The LDAP attribute containing the user's first name. | `givenName` |
+| **Surname Attribute** | No | The LDAP attribute containing the user's last name. | `sn` |
+
+<Tip>
+  The **User Filter** field can be used to filter on group membership if the User DN object has `memberOf` attributes. For example:
+  ```
+  (&(objectClass=posixAccount)(uid=%s)(memberOf=cn=gogs_users,cn=groups,dc=mydomain,dc=com))
+  ```
+  In the Bind DN authenticator, the User Filter can also match against multiple user attributes:
+  ```
+  (&(objectClass=Person)(|(uid=%s)(mail=%s)(mobile=%s)))
+  ```
+</Tip>
+
+### Simple Auth fields
+
+LDAP via Simple Auth adds the following field:
+
+| Field | Required | Description | Example |
+|---|---|---|---|
+| **User DN** | Yes | A template for the user's DN. The `%s` parameter is substituted with the login name. | `cn=%s,ou=Users,dc=mydomain,dc=com` or `uid=%s,ou=Users,dc=mydomain,dc=com` |
+
+### Bind DN fields
+
+LDAP via Bind DN adds the following fields:
+
+| Field | Required | Description | Example |
+|---|---|---|---|
+| **Bind DN** | No | The DN used to bind to the LDAP server when searching for the user. Leave blank for anonymous search. | `cn=Search,dc=mydomain,dc=com` |
+| **Bind Password** | No | The password for the Bind DN specified above. | -- |
+| **User Search Base** | Yes | The LDAP base below which user accounts will be searched. | `ou=Users,dc=mydomain,dc=com` |
+| **Fetch Attributes in Bind DN Context** | No | When enabled, user attributes are retrieved while bound as the Bind DN instead of the User DN. | -- |
+
+<Warning>
+  The Bind Password is stored in plaintext on the server. Ensure that your Bind DN has the minimum privileges necessary.
+</Warning>
+
+### Group membership verification
+
+You can optionally verify LDAP group membership using the following fields:
+
+| Field | Required | Description | Example |
+|---|---|---|---|
+| **Group Search Base DN** | No | The LDAP base below which groups will be searched. | `ou=group,dc=mydomain,dc=com` |
+| **Group Filter** | No | An LDAP filter declaring the groups that grant access. | `(\|(cn=gogs_users)(cn=admins))` |
+| **Group Attribute Containing List of Users** | No | The multi-valued attribute containing the group's members. | `memberUid` or `member` |
+| **User Attribute Listed in Group** | No | The user attribute referenced in the group membership attributes. | `uid` or `dn` |
+
+### Configuration files
+
+LDAP sources can also be defined as `.conf` files in `custom/conf/auth.d/` instead of through the admin panel. Files are loaded at startup and keyed by `id`.
+
+<Tabs>
+  <Tab title="Bind DN">
+    ```ini
+    id           = 101
+    type         = ldap_bind_dn
+    name         = LDAP BindDN
+    is_activated = true
+
+    [config]
+    host               = mydomain.com
+    port               = 636
+    # 0 - Unencrypted, 1 - LDAPS, 2 - StartTLS
+    security_protocol  = 0
+    skip_verify        = false
+    bind_dn            =
+    bind_password      =
+    user_base          = ou=Users,dc=mydomain,dc=com
+    attribute_username =
+    attribute_name     =
+    attribute_surname  =
+    attribute_mail     = mail
+    attributes_in_bind = false
+    filter             = (&(objectClass=posixAccount)(cn=%s))
+    admin_filter       =
+    group_enabled      = false
+    group_dn           =
+    group_filter       =
+    group_member_uid   =
+    user_uid           =
+    ```
+  </Tab>
+  <Tab title="Simple Auth">
+    ```ini
+    id           = 102
+    type         = ldap_simple_auth
+    name         = LDAP Simple Auth
+    is_activated = true
+
+    [config]
+    host               = mydomain.com
+    port               = 636
+    # 0 - Unencrypted, 1 - LDAPS, 2 - StartTLS
+    security_protocol  = 0
+    skip_verify        = false
+    bind_dn            =
+    bind_password      =
+    user_base          =
+    user_dn            = cn=%s,ou=Users,dc=mydomain,dc=com
+    attribute_username =
+    attribute_name     =
+    attribute_surname  =
+    attribute_mail     = mail
+    attributes_in_bind = false
+    filter             = (&(objectClass=posixAccount)(cn=%s))
+    admin_filter       =
+    group_enabled      = false
+    group_dn           =
+    group_filter       =
+    group_member_uid   =
+    user_uid           =
+    ```
+  </Tab>
+</Tabs>
+
+### FreeIPA examples
+
+It is possible to use either Bind DN or Simple Auth with FreeIPA. The examples below assume your domain is `domain.com` and that users must be a member of the `gogs_users` group to get access.
+
+<AccordionGroup>
+  <Accordion title="FreeIPA with Simple Auth">
+    Setting up access using Simple Auth is straightforward:
+
+    ```ini
+    user_dn            = uid=%s,cn=users,cn=accounts,dc=domain,dc=com
+    filter             = (&(objectClass=posixAccount)(memberOf=cn=gogs_users,cn=groups,cn=accounts,dc=domain,dc=com))
+    attribute_username = uid
+    attribute_name     = givenName
+    attribute_surname  = sn
+    attribute_mail     = mail
+    admin_filter       = (memberOf=cn=admins,cn=groups,cn=accounts,dc=domain,dc=com)
+    group_enabled      = false
+    ```
+  </Accordion>
+  <Accordion title="FreeIPA with Bind DN">
+    If you want to allow login by email address, note that FreeIPA by default does not grant anonymous search access to the `mail` attribute. This can be changed in IPA:
+
+    ```bash
+    ipa permission-mod --includedattrs=mail 'System: Read User Standard Attributes'
+    ```
+
+    Alternatively, you can ask your LDAP administrators for a dedicated bind user account.
+
+    <Info>
+      Allowing email-based login via Bind DN may no longer be necessary. Gogs translates email logins to the corresponding user ID before making the authentication call to the backend LDAP. The only requirement is that the user's **first login** is with their user ID. After that, they can use either user ID or email address.
+    </Info>
+
+    More precisely, Gogs maps the login name onto the user's "Authentication Login Name", which administrators can edit on the user's **Edit Account** page.
+  </Accordion>
+</AccordionGroup>
+
+## PAM
+
+To configure PAM authentication, set the **PAM Service Name** to a filename in `/etc/pam.d/`.
+
+<Warning>
+  If you want PAM authentication to work with normal Linux passwords, the user running Gogs must have read access to `/etc/shadow`.
+</Warning>
+
+### Configuration file
+
+```ini
+id           = 104
+type         = pam
+name         = System Auth
+is_activated = true
+
+[config]
+service_name = system-auth
+```
+
+## SMTP
+
+SMTP authentication allows Gogs to log in to your SMTP host to verify user credentials. Configure the following fields:
+
+| Field | Required | Description | Example |
+|---|---|---|---|
+| **Authentication Name** | Yes | A name for this authentication source. | `Company SMTP` |
+| **SMTP Authentication Type** | Yes | The authentication type: `PLAIN` or `LOGIN`. | `PLAIN` |
+| **Host** | Yes | The address of the SMTP server. | `smtp.mydomain.com` |
+| **Port** | Yes | The port for the SMTP connection. | `587` |
+| **Allowed Domains** | No | Restrict login to specific email domains. Separate multiple domains with commas. | `gogs.io,mydomain.com` |
+| **Enable TLS Encryption** | No | Enable TLS encryption for the authentication connection. | -- |
+| **Skip TLS Verify** | No | Disable TLS certificate verification. | -- |
+| **This Authentication is Activated** | No | Enable or disable this authentication method. | -- |
+
+### Configuration file
+
+```ini
+id           = 103
+type         = smtp
+name         = GMail
+is_activated = true
+
+[config]
+# Either "PLAIN" or "LOGIN"
+auth            = PLAIN
+host            = smtp.gmail.com
+port            = 587
+allowed_domains =
+tls             = true
+skip_verify     = false
+```
+
+## HTTP header
+
+If your reverse proxy already handles user authentication (e.g. via SSO, OAuth, or client certificates), Gogs can trust the authenticated username from an HTTP header. This is configured in `custom/conf/app.ini` under `[auth]`:
+
+```ini
+[auth]
+ENABLE_REVERSE_PROXY_AUTHENTICATION = true
+REVERSE_PROXY_AUTHENTICATION_HEADER = X-WEBAUTH-USER
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `ENABLE_REVERSE_PROXY_AUTHENTICATION` | `false` | Enable reading the authenticated username from a request header. |
+| `REVERSE_PROXY_AUTHENTICATION_HEADER` | `X-WEBAUTH-USER` | The HTTP header containing the authenticated username. |
+| `ENABLE_REVERSE_PROXY_AUTO_REGISTRATION` | `false` | Automatically create a Gogs account for users that do not yet exist. |
+
+When auto-registration is enabled, Gogs creates new accounts with an activated status and a placeholder email address. The user can update their email after first login.
+
+<Warning>
+  Only enable this feature if Gogs is exclusively accessed through a trusted reverse proxy that sets the header. Exposing Gogs directly to the internet with this enabled would allow anyone to impersonate any user by setting the header themselves.
+</Warning>

docs/advancing/custom-templates.mdx

@@ -0,0 +1,100 @@
+---
+title: "Custom templates"
+description: "Override HTML templates, static files, and inject custom content"
+icon: "paintbrush"
+---
+
+Gogs allows you to customize the appearance and behavior of your instance by overriding HTML templates, replacing static files, and injecting custom content. All customizations are placed under the `custom/` directory and survive code updates.
+
+<Warning>
+  Be careful when overriding templates and static files, as changes to the upstream Gogs codebase may break your customizations in future releases. Keep track of what you have overridden.
+</Warning>
+
+## Override HTML templates
+
+You can replace any HTML template (including email templates) by placing a customized version under the `custom/templates/` directory.
+
+<Steps>
+  <Step title="Find the original template">
+    Locate the template file you want to customize in the `templates/` directory of the Gogs source code. For example, to customize the home page, find `templates/home.tmpl`.
+  </Step>
+  <Step title="Copy and edit">
+    Copy the content of the template file and save your edited version to the corresponding path under `custom/templates/`. For example:
+
+    ```
+    custom/templates/home.tmpl
+    ```
+  </Step>
+  <Step title="Restart Gogs">
+    Edits to custom HTML templates **require restarting Gogs** to take effect.
+  </Step>
+</Steps>
+
+<Warning>
+  Override for email templates is disabled when `[server] LOAD_ASSETS_FROM_DISK = true` is set in your configuration. If you are using this setting, email template overrides will not be applied.
+</Warning>
+
+## Override static files
+
+You can replace static files (CSS, JavaScript, images, etc.) by placing customized versions under the `custom/public/` directory.
+
+For example, to override the site favicon, place your version at:
+
+```
+custom/public/img/favicon.png
+```
+
+<Tip>
+  Edits to custom static files **do not** require restarting Gogs. Changes take effect immediately.
+</Tip>
+
+## Inject custom content
+
+You can inject custom HTML into the head or footer of every page without touching the main repository source code. This is useful for adding analytics code, custom stylesheets, or other static resources.
+
+This approach is **recommended whenever possible** because it has the minimum impact on templates and is less likely to break during upgrades.
+
+The injection points are:
+
+| File | Location | Purpose |
+|---|---|---|
+| `custom/templates/inject/head.tmpl` | Inside `<head>` | Add stylesheets, meta tags, analytics scripts |
+| `custom/templates/inject/footer.tmpl` | Before `</body>` | Add scripts, tracking code, custom footer content |
+
+### Example: custom CSS file
+
+The following example shows how to include a custom CSS file in your Gogs instance:
+
+<Steps>
+  <Step title="Create the CSS file">
+    Create a file named `custom.css` under the `custom/public/css/` directory:
+
+    ```
+    custom/public/css/custom.css
+    ```
+  </Step>
+  <Step title="Add your CSS rules">
+    Write your CSS rules in the file. For example:
+
+    ```css
+    /* custom/public/css/custom.css */
+    .dashboard .news .news-item .header {
+      color: #333;
+    }
+
+    footer {
+      background-color: #f5f5f5;
+    }
+    ```
+  </Step>
+  <Step title="Link the stylesheet">
+    Edit the file `custom/templates/inject/head.tmpl` and add a link to your CSS file:
+
+    ```html
+    <link rel="stylesheet" href="/css/custom.css">
+    ```
+  </Step>
+  <Step title="Restart Gogs">
+    Restart Gogs to load the new `head.tmpl` injection template. After the initial restart, future edits to the custom CSS file **do not** require restarting Gogs.
+  </Step>
+</Steps>

docs/advancing/git-lfs.mdx

@@ -0,0 +1,102 @@
+---
+title: "Git LFS"
+description: "Managing large binary files with some magic"
+icon: "file-arrow-up"
+---
+
+Git Large File Storage (LFS) helps manage large binary files in Git repositories. Instead of storing large files directly in the repository, Git LFS replaces them with lightweight pointers while storing the actual file contents on a separate server.
+
+## How it works
+
+The Git LFS client communicates with the Gogs server over HTTP/HTTPS. It uses HTTP Basic Authentication to authorize client requests. Once a request is authorized, the Git LFS client receives instructions on where to fetch or push the large file.
+
+## Server configuration
+
+Git LFS works out of the box with the default configuration for any supported version of Gogs.
+
+All configuration options for Git LFS are located in the `[lfs]` section of `custom/conf/app.ini`:
+
+```ini
+[lfs]
+; The storage backend for uploading new objects.
+STORAGE = local
+; The root path to store LFS objects on the local file system.
+OBJECTS_PATH = data/lfs-objects
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `STORAGE` | `local` | The storage backend for LFS objects. Currently only `local` is supported. |
+| `OBJECTS_PATH` | `data/lfs-objects` | The root path on the local file system where LFS objects are stored. |
+
+## Version requirements
+
+To use Git LFS with your Gogs instance, you need:
+
+- Gogs version **0.12** or later
+- [Git LFS client](https://git-lfs.github.com/) version **1.0.1** or later
+
+## Using Git LFS
+
+Git LFS endpoints in a Gogs server are automatically discovered by the Git LFS client, so you do not need to configure anything upfront.
+
+<Steps>
+  <Step title="Install Git LFS">
+    Install the [Git LFS client](https://git-lfs.github.com/) on your machine. Most package managers include it:
+
+    ```bash
+    # macOS
+    brew install git-lfs
+
+    # Debian/Ubuntu
+    sudo apt install git-lfs
+
+    # Then initialize Git LFS
+    git lfs install
+    ```
+  </Step>
+  <Step title="Track large files">
+    In your repository, tell Git LFS which file patterns to track:
+
+    ```bash
+    git lfs track "*.psd"
+    git lfs track "*.zip"
+    ```
+
+    This creates or updates a `.gitattributes` file. Make sure to commit it:
+
+    ```bash
+    git add .gitattributes
+    git commit -m "Track large files with Git LFS"
+    ```
+  </Step>
+  <Step title="Push as usual">
+    Add, commit, and push your files normally. Git LFS will automatically handle the large files:
+
+    ```bash
+    git add design.psd
+    git commit -m "Add design file"
+    git push origin main
+    ```
+  </Step>
+</Steps>
+
+For a complete walkthrough, see the official [Git LFS Tutorial](https://github.com/git-lfs/git-lfs/wiki/Tutorial).
+
+## Known limitations
+
+<Warning>
+  Be aware of the following limitations when using Git LFS with Gogs.
+</Warning>
+
+<AccordionGroup>
+  <Accordion title="No S3 or object storage support">
+    Only local storage is supported. All LFS objects are stored on the same server where Gogs runs. Support for Object Storage Services like Amazon S3 is being tracked in [gogs/gogs#6065](https://github.com/gogs/gogs/issues/6065).
+  </Accordion>
+  <Accordion title="SSH remotes use HTTP for LFS transfers">
+    When SSH is set as a remote, Git LFS objects still go through HTTP/HTTPS. Any Git LFS request will prompt for HTTP/HTTPS credentials, so a good Git credentials store is recommended.
+  </Accordion>
+  <Accordion title="No file locking support">
+    File locking is not supported. This feature is being tracked in [gogs/gogs#6064](https://github.com/gogs/gogs/issues/6064).
+  </Accordion>
+</AccordionGroup>

docs/advancing/localization.mdx

@@ -0,0 +1,78 @@
+---
+title: "Localization"
+description: "Configure interface languages and contribute translations to Gogs"
+icon: "language"
+---
+
+Gogs has supported multiple languages since release `v0.5.0`. Users can change the interface language instantly with a single click from their settings page.
+
+## Configuration
+
+Available languages are configured in `custom/conf/app.ini` under the `[i18n]` section. All supported languages are enabled by default:
+
+```ini
+[i18n]
+LANGS = en-US,zh-CN,zh-HK,de-DE,fr-FR,nl-NL,lv-LV,ru-RU,ja-JP,es-ES,pt-BR,pl-PL,bg-BG,it-IT
+NAMES = English,简体中文,繁體中文,Deutsch,Français,Nederlands,Latviešu,Русский,日本語,Español,Português do Brasil,Polski,български,Italiano
+```
+
+| Option | Description |
+|---|---|
+| `LANGS` | A comma-separated list of locale codes to enable. Each entry corresponds to a locale file. |
+| `NAMES` | A comma-separated list of display names for each language, in the same order as `LANGS`. |
+
+<Tip>
+  To restrict the available languages, simply remove entries from both `LANGS` and `NAMES`. Make sure the two lists remain in the same order and have the same number of entries.
+</Tip>
+
+## Contributing translations
+
+Translations are managed through Crowdin. To contribute:
+
+<Steps>
+  <Step title="Sign up">
+    Create an account on the [Gogs Crowdin project](https://crowdin.gogs.io/).
+  </Step>
+  <Step title="Translate">
+    Browse the available strings and fill in untranslated entries for your language.
+  </Step>
+  <Step title="Review">
+    Review existing translations and suggest improvements where needed.
+  </Step>
+</Steps>
+
+<Info>
+  When translating, focus on conveying the meaning rather than producing a literal word-for-word translation. It is more important that the translation reads naturally in your language than that it matches the exact words of the English version.
+</Info>
+
+### Making corrections
+
+If you find an incorrectly translated string, you can search for it efficiently on [Crowdin](https://crowdin.gogs.io/) by using its **key name** rather than the translated text.
+
+For example:
+- To fix the translation for "Home", search for the key `home` instead of searching for the word "Home".
+- For keys under a section, search using the format `section:key_name`, such as `home:uname_holder`.
+
+### Testing translations locally
+
+If you want to test your translation without making changes to your Git history, place your locale file into:
+
+```
+custom/conf/locale/<file>
+```
+
+Then restart Gogs to load the updated translations.
+
+## Custom locale files
+
+If you are not satisfied with the official translation for your language, you can override individual fields by creating a custom locale file:
+
+```
+custom/conf/locale/locale_<lang>.ini
+```
+
+For example, to override specific English strings, create `custom/conf/locale/locale_en-US.ini` and add only the keys you want to change. Restart Gogs to apply the changes.
+
+<Note>
+  Custom locale files only need to contain the keys you want to override, not the entire locale file. Unspecified keys will fall back to the official translation.
+</Note>

docs/advancing/webhooks.mdx

@@ -0,0 +1,130 @@
+---
+title: "Webhooks"
+description: "Stay informed for repository events"
+icon: "bell"
+---
+
+Gogs supports moonlanding for repository events, allowing your external services to receive HTTP notifications when actions occur in your repositories. All event pushes are **POST requests**.
+
+## Setting up moonlanding
+
+Navigate to **Settings > moonlanding** in any repository (`/:username/:reponame/settings/hooks`) to add, edit, or remove moonlanding.
+
+## Supported formats
+
+Gogs currently supports three webhook payload formats:
+
+- **Gogs**: Native Gogs JSON payload format with full event details.
+- **Slack**: Slack-compatible payload format for posting to Slack channels.
+- **Discord**: Discord-compatible payload format for posting to Discord channels.
+
+## Event headers
+
+Every webhook delivery includes the following HTTP headers:
+
+| Header | Description | Example |
+|---|---|---|
+| `X-Gogs-Delivery` | A unique UUID identifying this delivery. | `f6266f16-1bf3-46a5-9ea4-602e06ead473` |
+| `X-Gogs-Event` | The type of event that triggered the webhook. | `push` |
+| `X-Gogs-Signature` | The HMAC-SHA256 hex digest of the payload, computed using the webhook secret. Use this to verify that the payload was sent by Gogs. | `1921679ed627...` |
+
+<Tip>
+  Always verify the `X-Gogs-Signature` header in your webhook receiver to ensure the request genuinely originated from your Gogs instance.
+</Tip>
+
+## Example payload
+
+The following is an example of the event information and JSON payload sent by Gogs for a **push** event:
+
+**Request headers:**
+
+```http
+X-Gogs-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473
+X-Gogs-Event: push
+X-Gogs-Signature: 1921679ed6274399b6514721056337f6913b6ff1cb35a24d340e983745d637f1
+```
+
+**Request body:**
+
+```json
+{
+  "ref": "refs/heads/main",
+  "before": "28e1879d029cb852e4844d9c718537df08844e03",
+  "after": "bffeb74224043ba2feb48d137756c8a9331c449a",
+  "compare_url": "https://gogs.example.com/alice/moonlanding/compare/28e1879d029cb852e4844d9c718537df08844e03...bffeb74224043ba2feb48d137756c8a9331c449a",
+  "commits": [
+    {
+      "id": "bffeb74224043ba2feb48d137756c8a9331c449a",
+      "message": "Update README\n",
+      "url": "https://gogs.example.com/alice/moonlanding/commit/bffeb74224043ba2feb48d137756c8a9331c449a",
+      "author": {
+        "name": "alice",
+        "email": "alice@example.com",
+        "username": "alice"
+      },
+      "committer": {
+        "name": "alice",
+        "email": "alice@example.com",
+        "username": "alice"
+      },
+      "timestamp": "2017-03-13T13:52:11-04:00"
+    }
+  ],
+  "repository": {
+    "id": 140,
+    "owner": {
+      "id": 1,
+      "login": "alice",
+      "full_name": "alice",
+      "email": "alice@example.com",
+      "avatar_url": "https://secure.gravatar.com/avatar/d8b2871cdac01b57bbda23716cc03b96",
+      "username": "alice"
+    },
+    "name": "moonlanding",
+    "full_name": "alice/moonlanding",
+    "description": "",
+    "private": false,
+    "fork": false,
+    "html_url": "https://gogs.example.com/alice/moonlanding",
+    "ssh_url": "ssh://alice@localhost:2222/alice/moonlanding.git",
+    "clone_url": "https://gogs.example.com/alice/moonlanding.git",
+    "website": "",
+    "stars_count": 0,
+    "forks_count": 1,
+    "watchers_count": 1,
+    "open_issues_count": 7,
+    "default_branch": "main",
+    "created_at": "2017-02-26T04:29:06-05:00",
+    "updated_at": "2017-03-13T13:51:58-04:00"
+  },
+  "pusher": {
+    "id": 1,
+    "login": "alice",
+    "full_name": "alice",
+    "email": "alice@example.com",
+    "avatar_url": "https://secure.gravatar.com/avatar/d8b2871cdac01b57bbda23716cc03b96",
+    "username": "alice"
+  },
+  "sender": {
+    "id": 1,
+    "login": "alice",
+    "full_name": "alice",
+    "email": "alice@example.com",
+    "avatar_url": "https://secure.gravatar.com/avatar/d8b2871cdac01b57bbda23716cc03b96",
+    "username": "alice"
+  }
+}
+```
+
+### Payload fields
+
+| Field | Description |
+|---|---|
+| `ref` | The full Git reference that was pushed to (e.g., `refs/heads/main`). |
+| `before` | The SHA of the commit at the head of the branch before the push. |
+| `after` | The SHA of the commit at the head of the branch after the push. |
+| `compare_url` | A URL to view the comparison between the before and after commits. |
+| `commits` | An array of commit objects included in the push. |
+| `repository` | The full repository object with metadata. |
+| `pusher` | The user who performed the push. |
+| `sender` | The user who triggered the event. |

docs/api-reference/administration/add-or-update-team-repository.mdx

@@ -0,0 +1,4 @@
+---
+title: "Add or update team repository"
+openapi: "PUT /admin/teams/{teamid}/repos/{reponame}"
+---

docs/api-reference/administration/add-team-membership.mdx

@@ -0,0 +1,4 @@
+---
+title: "Add team membership"
+openapi: "PUT /admin/teams/{teamid}/members/{username}"
+---

docs/api-reference/administration/create-a-new-user.mdx

@@ -0,0 +1,4 @@
+---
+title: "Create a new user"
+openapi: "POST /admin/users"
+---

docs/api-reference/administration/create-a-public-key-for-a-user.mdx

@@ -0,0 +1,4 @@
+---
+title: "Create a public key for a user"
+openapi: "POST /admin/users/{username}/keys"
+---

docs/api-reference/administration/create-a-repository-for-a-user.mdx

@@ -0,0 +1,4 @@
+---
+title: "Create a repository for a user"
+openapi: "POST /admin/users/{username}/repos"
+---

docs/api-reference/administration/create-a-team.mdx

@@ -0,0 +1,4 @@
+---
+title: "Create a team"
+openapi: "POST /admin/orgs/{orgname}/teams"
+---

docs/api-reference/administration/create-an-organization.mdx

@@ -0,0 +1,4 @@
+---
+title: "Create an organization"
+openapi: "POST /admin/users/{username}/orgs"
+---

docs/api-reference/administration/delete-a-user.mdx

@@ -0,0 +1,4 @@
+---
+title: "Delete a user"
+openapi: "DELETE /admin/users/{username}"
+---

docs/api-reference/administration/edit-an-existing-user.mdx

@@ -0,0 +1,4 @@
+---
+title: "Edit an existing user"
+openapi: "PATCH /admin/users/{username}"
+---

docs/api-reference/administration/list-all-members-of-a-team.mdx

@@ -0,0 +1,4 @@
+---
+title: "List all members of a team"
+openapi: "GET /admin/teams/{teamid}/members"
+---

docs/api-reference/administration/remove-team-membership.mdx

@@ -0,0 +1,4 @@
+---
+title: "Remove team membership"
+openapi: "DELETE /admin/teams/{teamid}/members/{username}"
+---

docs/api-reference/administration/remove-team-repository.mdx

@@ -0,0 +1,4 @@
+---
+title: "Remove team repository"
+openapi: "DELETE /admin/teams/{teamid}/repos/{reponame}"
+---

docs/api-reference/collaborators-and-deploy-keys/add-a-collaborator.mdx

@@ -0,0 +1,4 @@
+---
+title: "Add a collaborator"
+openapi: "PUT /repos/{owner}/{repo}/collaborators/{collaborator}"
+---

docs/api-reference/collaborators-and-deploy-keys/add-a-deploy-key.mdx

@@ -0,0 +1,4 @@
+---
+title: "Add a deploy key"
+openapi: "POST /repos/{owner}/{repo}/keys"
+---

docs/api-reference/collaborators-and-deploy-keys/check-if-user-is-collaborator.mdx

@@ -0,0 +1,4 @@
+---
+title: "Check if a user is a collaborator"
+openapi: "GET /repos/{owner}/{repo}/collaborators/{collaborator}"
+---

docs/api-reference/collaborators-and-deploy-keys/get-a-deploy-key.mdx

@@ -0,0 +1,4 @@
+---
+title: "Get a deploy key"
+openapi: "GET /repos/{owner}/{repo}/keys/{id}"
+---

docs/api-reference/collaborators-and-deploy-keys/list-collaborators.mdx

@@ -0,0 +1,4 @@
+---
+title: "List collaborators"
+openapi: "GET /repos/{owner}/{repo}/collaborators"
+---

docs/api-reference/collaborators-and-deploy-keys/list-deploy-keys.mdx

@@ -0,0 +1,4 @@
+---
+title: "List deploy keys"
+openapi: "GET /repos/{owner}/{repo}/keys"
+---

docs/api-reference/collaborators-and-deploy-keys/remove-a-collaborator.mdx

@@ -0,0 +1,4 @@
+---
+title: "Remove a collaborator"
+openapi: "DELETE /repos/{owner}/{repo}/collaborators/{collaborator}"
+---

docs/api-reference/collaborators-and-deploy-keys/remove-a-deploy-key.mdx

@@ -0,0 +1,4 @@
+---
+title: "Remove a deploy key"
+openapi: "DELETE /repos/{owner}/{repo}/keys/{id}"
+---

docs/api-reference/introduction.mdx

@@ -0,0 +1,116 @@
+---
+title: "Introduction"
+sidebarTitle: "Introduction"
+description: "Overview of the Gogs API including authentication, pagination, and schema"
+---
+
+The Gogs API provides a RESTful interface for interacting with your Gogs instance programmatically. It aims to follow a format similar to the [GitHub REST API v3](https://developer.github.com/v3/).
+
+<Info>
+  The API is bundled with every Gogs installation. No additional setup is required.
+</Info>
+
+<Warning>
+  The API is still in its early stages. Content and endpoints are subject to change.
+</Warning>
+
+## Current version
+
+All Gogs APIs are under **v1** using the request path prefix `/api/v1`.
+
+```
+https://gogs.example.com/api/v1
+```
+
+## Schema
+
+All data is sent and received as **JSON** unless specified otherwise.
+
+```http
+HTTP/2 200
+Content-Type: application/json; charset=UTF-8
+```
+
+All timestamps are returned in **RFC 3339** format:
+
+```
+YYYY-MM-DDTHH:MM:SSZ
+2006-01-02T15:04:05Z07:00
+```
+
+## Authentication
+
+There are two ways to authenticate through the Gogs API. Requests that require authentication will return `404 Not Found` instead of `403 Forbidden` in some places. This is to prevent the accidental leakage of private resources to unauthorized users.
+
+<Tabs>
+  <Tab title="Basic authentication">
+    Basic authentication is used to obtain access tokens. Supply your username (you will be prompted for your password):
+
+    ```bash
+    curl -u "alice" https://gogs.example.com/api/v1/users/alice/tokens
+    ```
+
+    <Warning>
+      Basic authentication should only be used to generate access tokens. Do not use it for regular API requests.
+    </Warning>
+  </Tab>
+  <Tab title="Access token">
+    Personal access tokens are the recommended way to authenticate. They can be sent via a request **header** or a **URL query parameter**.
+
+    **Using a header:**
+
+    ```bash
+    curl -H "Authorization: token {YOUR_ACCESS_TOKEN}" https://gogs.example.com/api/v1/user/repos
+    ```
+
+    **Using a query parameter:**
+
+    ```bash
+    curl https://gogs.example.com/api/v1/user/repos?token={YOUR_ACCESS_TOKEN}
+    ```
+
+    <Tip>
+      Using the `Authorization` header is preferred over the query parameter, as URLs may be logged by proxies and servers.
+    </Tip>
+  </Tab>
+</Tabs>
+
+## Pagination
+
+API responses that return multiple items are paginated. You can specify further pages with the `?page` query parameter.
+
+```bash
+curl https://gogs.example.com/api/v1/repos/alice/hello/issues?page=1
+```
+
+Page numbering is **1-based**. Omitting the `?page` parameter returns the first page.
+
+### Link header
+
+Pagination info is included in the [Link header](http://tools.ietf.org/html/rfc5988) of each response. Use this to navigate between pages programmatically.
+
+```http
+Link: <https://gogs.example.com/api/v1/repos/alice/hello/issues?page=3>; rel="next",
+  <https://gogs.example.com/api/v1/repos/alice/hello/issues?page=50>; rel="last"
+```
+
+The possible `rel` values are:
+
+| Name | Description |
+|---|---|
+| `next` | The link relation for the immediate next page of results. |
+| `last` | The link relation for the last page of results. |
+| `first` | The link relation for the first page of results. |
+| `prev` | The link relation for the immediate previous page of results. |
+
+<Tip>
+  Always use the Link header values to navigate between pages rather than constructing URLs manually.
+</Tip>
+
+## SDKs
+
+The following best-effort-maintained SDKs are available:
+
+| Language | Repository |
+|---|---|
+| Go | [gogs/go-gogs-client](https://github.com/gogs/go-gogs-client) |

docs/api-reference/issues/add-labels-to-an-issue.mdx

@@ -0,0 +1,4 @@
+---
+title: "Add labels to an issue"
+openapi: "POST /repos/{owner}/{repo}/issues/{index}/labels"
+---

docs/api-reference/issues/create-a-comment.mdx

@@ -0,0 +1,4 @@
+---
+title: "Create a comment"
+openapi: "POST /repos/{owner}/{repo}/issues/{index}/comments"
+---

docs/api-reference/issues/create-a-label.mdx

@@ -0,0 +1,4 @@
+---
+title: "Create a label"
+openapi: "POST /repos/{owner}/{repo}/labels"
+---

docs/api-reference/issues/create-a-milestone.mdx

@@ -0,0 +1,4 @@
+---
+title: "Create a milestone"
+openapi: "POST /repos/{owner}/{repo}/milestones"
+---

docs/api-reference/issues/create-an-issue.mdx

@@ -0,0 +1,4 @@
+---
+title: "Create an issue"
+openapi: "POST /repos/{owner}/{repo}/issues"
+---

docs/api-reference/issues/delete-a-comment.mdx

@@ -0,0 +1,4 @@
+---
+title: "Delete a comment"
+openapi: "DELETE /repos/{owner}/{repo}/issues/{index}/comments/{id}"
+---

docs/api-reference/issues/delete-a-label.mdx

@@ -0,0 +1,4 @@
+---
+title: "Delete a label"
+openapi: "DELETE /repos/{owner}/{repo}/labels/{id}"
+---

docs/api-reference/issues/delete-a-milestone.mdx

@@ -0,0 +1,4 @@
+---
+title: "Delete a milestone"
+openapi: "DELETE /repos/{owner}/{repo}/milestones/{id}"
+---

docs/api-reference/issues/edit-a-comment.mdx

@@ -0,0 +1,4 @@
+---
+title: "Edit a comment"
+openapi: "PATCH /repos/{owner}/{repo}/issues/{index}/comments/{id}"
+---

docs/api-reference/issues/edit-a-milestone.mdx

@@ -0,0 +1,4 @@
+---
+title: "Edit a milestone"
+openapi: "PATCH /repos/{owner}/{repo}/milestones/{id}"
+---

docs/api-reference/issues/edit-an-issue.mdx

@@ -0,0 +1,4 @@
+---
+title: "Edit an issue"
+openapi: "PATCH /repos/{owner}/{repo}/issues/{index}"
+---

docs/api-reference/issues/get-a-single-issue.mdx

@@ -0,0 +1,4 @@
+---
+title: "Get a single issue"
+openapi: "GET /repos/{owner}/{repo}/issues/{index}"
+---

docs/api-reference/issues/get-a-single-label.mdx

@@ -0,0 +1,4 @@
+---
+title: "Get a single label"
+openapi: "GET /repos/{owner}/{repo}/labels/{id}"
+---

docs/api-reference/issues/get-a-single-milestone.mdx

@@ -0,0 +1,4 @@
+---
+title: "Get a single milestone"
+openapi: "GET /repos/{owner}/{repo}/milestones/{id}"
+---

docs/api-reference/issues/list-all-labels-for-a-repository.mdx

@@ -0,0 +1,4 @@
+---
+title: "List all labels for a repository"
+openapi: "GET /repos/{owner}/{repo}/labels"
+---

docs/api-reference/issues/list-comments-in-a-repository.mdx

@@ -0,0 +1,4 @@
+---
+title: "List comments in a repository"
+openapi: "GET /repos/{owner}/{repo}/issues/comments"
+---

docs/api-reference/issues/list-comments-on-an-issue.mdx

@@ -0,0 +1,4 @@
+---
+title: "List comments on an issue"
+openapi: "GET /repos/{owner}/{repo}/issues/{index}/comments"
+---

docs/api-reference/issues/list-issues-for-a-repository.mdx

@@ -0,0 +1,4 @@
+---
+title: "List issues for a repository"
+openapi: "GET /repos/{owner}/{repo}/issues"
+---

docs/api-reference/issues/list-labels-on-an-issue.mdx

@@ -0,0 +1,4 @@
+---
+title: "List labels on an issue"
+openapi: "GET /repos/{owner}/{repo}/issues/{index}/labels"
+---

docs/api-reference/issues/list-milestones-for-a-repository.mdx

@@ -0,0 +1,4 @@
+---
+title: "List milestones for a repository"
+openapi: "GET /repos/{owner}/{repo}/milestones"
+---

docs/api-reference/issues/list-user-issues.mdx

@@ -0,0 +1,4 @@
+---
+title: "List user issues"
+openapi: "GET /user/issues"
+---

docs/api-reference/issues/remove-a-label-from-an-issue.mdx

@@ -0,0 +1,4 @@
+---
+title: "Remove a label from an issue"
+openapi: "DELETE /repos/{owner}/{repo}/issues/{index}/labels/{id}"
+---

docs/api-reference/issues/remove-all-labels-from-an-issue.mdx

@@ -0,0 +1,4 @@
+---
+title: "Remove all labels from an issue"
+openapi: "DELETE /repos/{owner}/{repo}/issues/{index}/labels"
+---

docs/api-reference/issues/replace-all-labels-for-an-issue.mdx

@@ -0,0 +1,4 @@
+---
+title: "Replace all labels for an issue"
+openapi: "PUT /repos/{owner}/{repo}/issues/{index}/labels"
+---

docs/api-reference/issues/update-a-label.mdx

@@ -0,0 +1,4 @@
+---
+title: "Update a label"
+openapi: "PATCH /repos/{owner}/{repo}/labels/{id}"
+---

docs/api-reference/miscellaneous/get-a-git-blob.mdx

@@ -0,0 +1,4 @@
+---
+title: "Get a git blob"
+openapi: "GET /repos/{owner}/{repo}/git/blobs/{sha}"
+---

docs/api-reference/miscellaneous/get-a-tree.mdx

@@ -0,0 +1,4 @@
+---
+title: "Get a tree"
+openapi: "GET /repos/{owner}/{repo}/git/trees/{sha}"
+---

docs/api-reference/miscellaneous/render-a-markdown-document-in-raw-mode.mdx

@@ -0,0 +1,4 @@
+---
+title: "Render a Markdown document in raw mode"
+openapi: "POST /markdown/raw"
+---

docs/api-reference/miscellaneous/render-a-markdown-document.mdx

@@ -0,0 +1,4 @@
+---
+title: "Render a Markdown document"
+openapi: "POST /markdown"
+---

docs/api-reference/organizations/create-an-organization-for-user.mdx

@@ -0,0 +1,4 @@
+---
+title: "Create an organization"
+openapi: "POST /user/orgs"
+---

docs/api-reference/organizations/edit-an-organization.mdx

@@ -0,0 +1,4 @@
+---
+title: "Edit an organization"
+openapi: "PATCH /orgs/{orgname}"
+---

docs/api-reference/organizations/get-an-organization.mdx

@@ -0,0 +1,4 @@
+---
+title: "Get an organization"
+openapi: "GET /orgs/{orgname}"
+---

docs/api-reference/organizations/list-teams-of-an-organization.mdx

@@ -0,0 +1,4 @@
+---
+title: "List teams of an organization"
+openapi: "GET /orgs/{orgname}/teams"
+---

docs/api-reference/organizations/list-user-organizations.mdx

@@ -0,0 +1,4 @@
+---
+title: "List user organizations"
+openapi: "GET /users/{username}/orgs"
+---

docs/api-reference/organizations/list-your-organizations.mdx

@@ -0,0 +1,4 @@
+---
+title: "List your organizations"
+openapi: "GET /user/orgs"
+---

docs/api-reference/releases/list-releases.mdx

@@ -0,0 +1,4 @@
+---
+title: "List releases"
+openapi: "GET /repos/{owner}/{repo}/releases"
+---

docs/api-reference/repositories/create-a-repository-in-an-organization.mdx

@@ -0,0 +1,4 @@
+---
+title: "Create a repository in an organization"
+openapi: "POST /org/{org}/repos"
+---

docs/api-reference/repositories/create-a-repository.mdx

@@ -0,0 +1,4 @@
+---
+title: "Create a repository"
+openapi: "POST /user/repos"
+---

docs/api-reference/repositories/create-or-update-a-file.mdx

@@ -0,0 +1,4 @@
+---
+title: "Create or update a file"
+openapi: "PUT /repos/{owner}/{repo}/contents/{path}"
+---

docs/api-reference/repositories/delete-a-repository.mdx

@@ -0,0 +1,4 @@
+---
+title: "Delete a repository"
+openapi: "DELETE /repos/{owner}/{repo}"
+---

docs/api-reference/repositories/download-archive.mdx

@@ -0,0 +1,4 @@
+---
+title: "Download archive"
+openapi: "GET /repos/{owner}/{repo}/archive/{archive}"
+---

docs/api-reference/repositories/download-raw-content.mdx

@@ -0,0 +1,4 @@
+---
+title: "Download raw content"
+openapi: "GET /repos/{owner}/{repo}/raw/{ref}/{filepath}"
+---

docs/api-reference/repositories/edit-issue-tracker-settings.mdx

@@ -0,0 +1,4 @@
+---
+title: "Edit issue tracker settings"
+openapi: "PATCH /repos/{owner}/{repo}/issue-tracker"
+---

docs/api-reference/repositories/edit-wiki-settings.mdx

@@ -0,0 +1,4 @@
+---
+title: "Edit wiki settings"
+openapi: "PATCH /repos/{owner}/{repo}/wiki"
+---

docs/api-reference/repositories/get-a-branch.mdx

@@ -0,0 +1,4 @@
+---
+title: "Get a branch"
+openapi: "GET /repos/{owner}/{repo}/branches/{branch}"
+---

docs/api-reference/repositories/get-a-repository.mdx

@@ -0,0 +1,4 @@
+---
+title: "Get a repository"
+openapi: "GET /repos/{owner}/{repo}"
+---

docs/api-reference/repositories/get-a-single-commit.mdx

@@ -0,0 +1,4 @@
+---
+title: "Get a single commit"
+openapi: "GET /repos/{owner}/{repo}/commits/{sha}"
+---

docs/api-reference/repositories/get-contents.mdx

@@ -0,0 +1,4 @@
+---
+title: "Get contents"
+openapi: "GET /repos/{owner}/{repo}/contents/{path}"
+---

docs/api-reference/repositories/get-editorconfig-definition.mdx

@@ -0,0 +1,4 @@
+---
+title: "Get editorconfig definition"
+openapi: "GET /repos/{owner}/{repo}/editorconfig/{filename}"
+---

docs/api-reference/repositories/list-all-commits.mdx

@@ -0,0 +1,4 @@
+---
+title: "List all commits"
+openapi: "GET /repos/{owner}/{repo}/commits"
+---

docs/api-reference/repositories/list-branches.mdx

@@ -0,0 +1,4 @@
+---
+title: "List branches"
+openapi: "GET /repos/{owner}/{repo}/branches"
+---

docs/api-reference/repositories/list-forks.mdx

@@ -0,0 +1,4 @@
+---
+title: "List forks"
+openapi: "GET /repos/{owner}/{repo}/forks"
+---

docs/api-reference/repositories/list-organization-repositories.mdx

@@ -0,0 +1,4 @@
+---
+title: "List organization repositories"
+openapi: "GET /orgs/{orgname}/repos"
+---

docs/api-reference/repositories/list-tags.mdx

@@ -0,0 +1,4 @@
+---
+title: "List tags"
+openapi: "GET /repos/{owner}/{repo}/tags"
+---

docs/api-reference/repositories/list-user-repositories.mdx

@@ -0,0 +1,4 @@
+---
+title: "List user repositories"
+openapi: "GET /users/{username}/repos"
+---

docs/api-reference/repositories/list-your-repositories.mdx

@@ -0,0 +1,4 @@
+---
+title: "List your repositories"
+openapi: "GET /user/repos"
+---

docs/api-reference/repositories/migrate-a-repository.mdx

@@ -0,0 +1,4 @@
+---
+title: "Migrate a repository"
+openapi: "POST /repos/migrate"
+---

docs/api-reference/repositories/mirror-sync.mdx

@@ -0,0 +1,4 @@
+---
+title: "Mirror sync"
+openapi: "POST /repos/{owner}/{repo}/mirror-sync"
+---

docs/api-reference/repositories/search-repositories.mdx

@@ -0,0 +1,4 @@
+---
+title: "Search repositories"
+openapi: "GET /repos/search"
+---

docs/api-reference/users/add-email-addresses.mdx

@@ -0,0 +1,4 @@
+---
+title: "Add email addresses"
+openapi: "POST /user/emails"
+---