gitea/gitea-docs
1
0
Fork 0
mirror of https://gitea.com/gitea/docs.git synced 2026-07-21 18:27:41 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'main' into lunny/add_project_workflow

Browse Source
This commit is contained in:
silverwind
2026-02-19 07:56:40 +00:00
parent 85ac8fc4ba 6c587e819f
commit 7e9e42775c
32 changed files with 14637 additions and 21884 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
.gitea/workflows/build-and-publish.yaml
View File

@@ -11,10 +11,11 @@ jobs:
runs-on: ubuntu-24.04
steps:
- uses: actions/checkout@v6
- uses: pnpm/action-setup@v4
- uses: actions/setup-node@v6
with:
node-version: 20
cache: npm
node-version: 24
cache: pnpm
- name: install necessary tools
run: |
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
@@ -23,22 +24,15 @@ jobs:
- name: prepare awesome list
run: |
make prepare-awesome-latest prepare-awesome\#25 prepare-awesome\#24 prepare-awesome\#23 prepare-awesome\#22
- name: Cache ~/.npm for npm ci
uses: actions/cache@v4
with:
path: ~/.npm
key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
restore-keys: ${{ runner.os }}-node
- name: Install dependencies
run: npm ci
run: pnpm install --frozen-lockfile
#- uses: tats-u/docuactions-cache@v1
- name: build site
run: |
make build
- name: aws credential configure
uses: aws-actions/configure-aws-credentials@v5
uses: aws-actions/configure-aws-credentials@v6
with:
aws-access-key-id: ${{ secrets.AWS_KEY_ID }}
aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY}}

14
.gitea/workflows/test.yaml
View File

@@ -8,22 +8,16 @@ jobs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: pnpm/action-setup@v4
- uses: actions/setup-node@v6
with:
node-version: 20
cache: npm
node-version: 24
cache: pnpm
- name: prepare awesome list
run: |
make prepare-awesome-latest prepare-awesome\#25 prepare-awesome\#24 prepare-awesome\#23 prepare-awesome\#22
- name: Cache ~/.npm for npm ci
uses: actions/cache@v4
with:
path: ~/.npm
key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
restore-keys: ${{ runner.os }}-node
- name: Install dependencies
run: npm ci
run: pnpm install --frozen-lockfile
#- uses: tats-u/docuactions-cache@v1
- name: build site

8
Makefile
View File

@@ -24,22 +24,22 @@ prepare-awesome\#%:
.PHONY: install
install:
npm install
pnpm install
.PHONY: prepare-docs
prepare-docs: install prepare-awesome-latest prepare-awesome\#19 prepare-awesome\#20 prepare-awesome\#21 prepare-awesome\#22 prepare-awesome\#23 prepare-awesome\#24
.PHONY: build
build:
npm run build
pnpm run build
.PHONY: serve
serve: prepare-docs
npm run start
pnpm run start
.PHONY: serve-zh
serve-zh: prepare-docs
npm run start -- --locale zh-cn
pnpm run start -- --locale zh-cn
.PHONY: clean
clean:

2
README.md
View File

@@ -19,5 +19,5 @@ make serve
## Test en version
```shell
npm run start
pnpm run start
```

11
docs/administration/config-cheat-sheet.md
View File

@@ -34,7 +34,7 @@ A full restart is required for Gitea configuration changes to take effect.
## Use environment variables to setup Gitea
There is [environment-to-ini](https://github.com/go-gitea/gitea/tree/main/contrib/environment-to-ini) to help to
There is [environment-to-ini](https://github.com/go-gitea/gitea/blob/main/docker/root/usr/local/bin/environment-to-ini) to help to
generate Gitea's `app.ini` from environment variables.
## Default Internal Variables (non-`app.ini` configuration)
@@ -224,7 +224,8 @@ The following configuration set `Content-Type: application/vnd.android.package-a
- `DEFAULT_THEME`: **gitea-auto**: Set the default theme for the Gitea installation, custom themes could be provided by `{CustomPath}/public/assets/css/theme-*.css`.
- `SHOW_USER_EMAIL`: **true**: Whether the email of the user should be shown in the Explore Users page.
- `THEMES`: **_empty_**: All available themes by `{CustomPath}/public/assets/css/theme-*.css`. Allow users select personalized themes.
- `FILE_ICON_THEME`: **material**: The icons for file list (basic/material).
- `FILE_ICON_THEME`: **material**: The icon theme for files (basic/material).
- `FOLDER_ICON_THEME`: **basic**: The icon theme for folders (basic/material).
- `MAX_DISPLAY_FILE_SIZE`: **8388608**: Max size of files to be displayed (default is 8MiB)
- `AMBIGUOUS_UNICODE_DETECTION`: **true**: Detect ambiguous unicode characters in file contents and show warnings on the UI
- `REACTIONS`: All available reactions users can choose on issues/prs and comments
@@ -309,7 +310,7 @@ The following configuration set `Content-Type: application/vnd.android.package-a
- `ROOT_URL`: **`{PROTOCOL}://{DOMAIN}:{HTTP_PORT}/`**:
Overwrite the automatically generated public URL.
This is useful if the internal and the external URL don't match (e.g. behind a reverse proxy).
- `PUBLIC_URL_DETECTION`: **`legacy`**: Controls how to generate the public URL.
- `PUBLIC_URL_DETECTION`: **`legacy`**: Controls how to generate the public URL.
Although it defaults to "legacy" (to avoid breaking existing users), most instances should use the "auto" behavior,
especially when the Gitea instance needs to be accessed in a container network.
- "legacy": generate the public URL by "Host" header if "X-Forwarded-Proto" header exists, otherwise use "ROOT_URL".
@@ -1203,14 +1204,12 @@ Synchronize external user data (only LDAP user synchronization is supported)
- `LARGE_OBJECT_THRESHOLD`: **1048576**: (Go-Git only), don't cache objects greater than this in memory. (Set to 0 to disable.)
- `DISABLE_CORE_PROTECT_NTFS`: **false** Set to true to forcibly set `core.protectNTFS` to false.
- `DISABLE_PARTIAL_CLONE`: **false** Disable the usage of using partial clones for git.
- `DIFF_RENAME_SIMILARITY_THRESHOLD`: **50%** Set the similarity threshold passed to git commands via `--find-renames=<threshold>`. Default is 50%, the same as git. Must be a integer percentage between 0% and 100%.
### Git - Timeout settings (`git.timeout`)
- `DEFAULT`: **360**: Git operations default timeout seconds.
- `MIGRATE`: **600**: Migrate external repositories timeout seconds.
- `MIRROR`: **300**: Mirror external repositories timeout seconds.
- `CLONE`: **300**: Git clone from internal repositories timeout seconds.
- `PULL`: **300**: Git pull from internal repositories timeout seconds.
- `GC`: **60**: Git repository GC timeout seconds.
### Git - Config options (`git.config`)

14
docs/administration/customizing-gitea.md
View File

@@ -317,11 +317,17 @@ mkdir o3dv
cd o3dv
```
Copy latest release zip link from [`GitHub`](https://github.com/kovacsv/Online3DViewer/releases) (v0.16.0 as of now).
Here use e.g. wget to download the file:
Copy latest release zip link from [`GitHub`](https://github.com/kovacsv/Online3DViewer/releases) (v0.18.0 as of now).
Here use e.g. wget or curl to download the file:
```
wget https://github.com/kovacsv/Online3DViewer/releases/download/0.16.0/o3dv.zip
wget https://github.com/kovacsv/Online3DViewer/releases/download/0.18.0/o3dv.zip
```
or
```
curl -L -O https://github.com/kovacsv/Online3DViewer/releases/download/0.18.0/o3dv.zip
```
Use e.g. unzip to unzip the archive:
@@ -347,7 +353,7 @@ $GITEA_CUSTOM/templates
$GITEA_CUSTOM/public/assets/
-- o3dv
|-- o3dv_0.15.0.zip
|-- o3dv.zip
|-- o3dv.license.md
|-- o3dv.min.js
|-- envmaps

1
docs/administration/mail-templates.md
View File

@@ -257,7 +257,6 @@ the messages. Here's a list of some of them:
| `AppDomain` | - | Any | Gitea's host name |
| `EllipsisString` | string, int | Any | Truncates a string to the specified length; adds ellipsis as needed |
| `SanitizeHTML` | string | Body only | Sanitizes text by removing any dangerous HTML tags from it |
| `SafeHTML` | string | Body only | Takes the input as HTML, can be used for outputing raw HTML content |
These are _functions_, not metadata, so they have to be used:

15
docs/development/api-usage.md
View File

@@ -20,13 +20,25 @@ Gitea supports these methods of API authentication:
- `token=...` parameter in URL query string
- `access_token=...` parameter in URL query string
- `Authorization: token ...` header in HTTP headers
- HTTP signatures using an SSH public key or SSH certificate
All of these methods accept the same API key token type. You can
better understand this by looking at the code -- as of this writing,
Gitea parses queries and headers to find the token in
[modules/auth/auth.go](https://github.com/go-gitea/gitea/blob/6efdcaed86565c91a3dc77631372a9cc45a58e89/modules/auth/auth.go#L47).
Gitea can also authenticate API requests using an SSH key or SSH certificate via
HTTP signatures. The SSH public key (or certificate) must be registered to the
user account in Gitea, and the client signs requests with the corresponding
private key. The client signs requests using the SSH private key following the
[draft-cavage-http-signatures](https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures)
specification (not RFC 9421). The signature is sent in the `Signature` header,
and SSH certificates additionally include an `x-ssh-certificate` header. The
official [go-sdk](https://gitea.com/gitea/go-sdk) implements this flow if you
need a reference implementation.
## Generating and listing API tokens
API tokens can be created either in the user interface or via the API. Tokens have by default limited permissions and it is important to create tokens with the correct permissions for your task.
### User Interface
Tokens can be created via the `Manage Access Tokens` dialog, accessed via `User Settings` / `Applications` or via the link `gitea-domain.example/user/settings/applications`. The interface allows you to create tokens and manage their permissions via the `Select permissions` sub-menu.
@@ -34,6 +46,7 @@ Tokens can be created via the `Manage Access Tokens` dialog, accessed via `User
Once created, the token is displayed in a toast message above the `Manage Access Tokens` dialog. Please note, that you can view this toast only once and it is not possible to redisplay the token for security reasons.
### Token API
A new token can be generated with a `POST` request to
`/users/:name/tokens`.
@@ -57,6 +70,7 @@ $ curl --url https://yourusername:password@gitea.your.host/api/v1/users/<usernam
```
By default, this creates a token with very limited permissions. To complete your tasks, your token may require extra permissions. These permissions are created via the json variable `scopes`, which takes an array of permissions as strings. Eg.: `"scopes":["all"]`. Possible permissions, as reflected in the user interface are:
- `activitypub`
- `admin`
- `issue`
@@ -68,6 +82,7 @@ By default, this creates a token with very limited permissions. To complete your
- `user`
Each permission may be set to `read` or `write`. `write` implies both Read & Write. To set permissions you write the permissions string as `<read or write>:<permission name>`, eg.: `write:package` or `read:notification`. A properly formatted API call may look like:
```sh
$ curl -H "Content-Type: application/json" -d '{"name":"test", "scopes":["write:package", "read:notification"]}' -u username:password https://gitea.your.host/api/v1/users/<username>/tokens
```

12
docs/installation/from-binary.md
View File

@@ -139,15 +139,15 @@ export GITEA_WORK_DIR=/var/lib/gitea/
cp gitea /usr/local/bin/gitea
```
### Adding bash/zsh autocompletion (from 1.19)
A script to enable bash-completion can be found at [`contrib/autocompletion/bash_autocomplete`](https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/autocompletion/bash_autocomplete). This can be copied to `/usr/share/bash-completion/completions/gitea`
or sourced within your `.bashrc`.
### Adding shell autocompletion (from 1.25)
Similarly a script for zsh-completion can be found at [`contrib/autocompletion/zsh_autocomplete`](https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/autocompletion/zsh_autocomplete). This can be copied to `/usr/share/zsh/_gitea` or sourced within your
`.zshrc`.
Shell completion can be generated directly from binary with:
```sh
gitea completion <shell>
```
YMMV and these scripts may need further improvement.
Supported values for `<shell>` are `bash`, `fish`, `pwsh` and `zsh`. Details on how to load the completion for your shell can be found in the completion command help.
## Running Gitea

13
docs/installation/from-source.md
View File

@@ -178,15 +178,14 @@ LDFLAGS="-linkmode external -extldflags '-static' $LDFLAGS" TAGS="netgo osusergo
This can be combined with `CC`, `GOOS`, and `GOARCH` as above.
### Adding bash/zsh autocompletion (from 1.19)
### Adding shell autocompletion (from 1.25)
A script to enable bash-completion can be found at [`contrib/autocompletion/bash_autocomplete`](https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/autocompletion/bash_autocomplete). This should be altered as appropriate and can be `source` in your `.bashrc`
or copied as `/usr/share/bash-completion/completions/gitea`.
Shell completion can be generated directly from binary with:
```sh
gitea completion <shell>
```
Similarly, a script for zsh-completion can be found at [`contrib/autocompletion/zsh_autocomplete`](https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/autocompletion/zsh_autocomplete). This can be copied to `/usr/share/zsh/_gitea` or sourced within your
`.zshrc`.
YMMV and these scripts may need further improvement.
Supported values for `<shell>` are `bash`, `fish`, `pwsh` and `zsh`. Details on how to load the completion for your shell can be found in the completion command help.
## Compile or cross-compile using Linux with Zig

48
docs/installation/with-docker-rootless.md
View File

@@ -315,51 +315,3 @@ services:
```
To set required TOKEN and SECRET values, consider using Gitea's built-in [generate utility functions](../administration/command-line.md#generate).
# SSH Container Passthrough
Since SSH is running inside the container, SSH needs to be passed through from the host to the container if SSH support is desired. One option would be to run the container SSH on a non-standard port (or moving the host port to a non-standard port). Another option which might be more straightforward is to forward SSH commands from the host to the container. This setup is explained in the following.
This guide assumes that you have created a user on the host called `git` with permission to run `docker exec`, and that the Gitea container is called `gitea`. You will need to modify that user's shell to forward the commands to the `sh` executable inside the container, using `docker exec`.
First, create the file `/usr/local/bin/gitea-shell` on the host, with the following contents:
```bash
#!/bin/sh
/usr/bin/docker exec -i --env SSH_ORIGINAL_COMMAND="$SSH_ORIGINAL_COMMAND" gitea sh "$@"
```
Note that `gitea` in the docker command above is the name of the container. If you named yours differently, don't forget to change that.
You should also make sure that you’ve set the permissions of the shell wrapper correctly:
```bash
sudo chmod +x /usr/local/bin/gitea-shell
```
Once the wrapper is in place, you can make it the shell for the `git` user:
```bash
sudo usermod -s /usr/local/bin/gitea-shell git
```
Now that all the SSH commands are forwarded to the container, you need to set up the SSH authentication on the host. This is done by leveraging the [SSH AuthorizedKeysCommand](../administration/command-line.md#keys) to match the keys against those accepted by Gitea. Add the following block to `/etc/ssh/sshd_config`, on the host:
```bash
Match User git
AuthorizedKeysCommandUser git
AuthorizedKeysCommand /usr/bin/docker exec -i gitea /usr/local/bin/gitea keys -c /etc/gitea/app.ini -e git -u %u -t %t -k %k
```
(From 1.16.0 you will not need to set the `-c /etc/gitea/app.ini` option.)
All that is left to do is restart the SSH server:
```bash
sudo systemctl restart sshd
```
**Notes**
This isn't actually using the docker SSH - it is simply using the commands around it.
You could theoretically not run the internal SSH server.

314
docs/installation/with-docker.md
View File

@@ -331,320 +331,6 @@ services:
- GITEA__security__INTERNAL_TOKEN=[value returned by generate secret INTERNAL_TOKEN]
```
## SSH Container Passthrough
Since SSH is running inside the container, SSH needs to be passed through from the host to the container if SSH support is desired. One option would be to run the container SSH on a non-standard port (or moving the host port to a non-standard port). Another option which might be more straightforward is for Gitea users to ssh to a Gitea user on the host which will then relay those connections to the docker. Alternatively, if the host machine has more than one IP address, the host can listen on one and Gitea on another.
### Understanding SSH access to Gitea (without passthrough)
To understand what needs to happen, you first need to understand what happens without passthrough. So we will try to explain this:
1. The client adds their SSH public key to Gitea using the webpage.
2. Gitea will add an entry for this key to the `.ssh/authorized_keys` file of its running user, `git`.
3. This entry has the public key, but also has a `command=` option. It is this command that Gitea uses to match this key to the client user and manages authentication.
4. The client then makes an SSH request to the SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
5. The client will attempt to authenticate with the server, passing one or more public keys one at a time to the server.
6. For each key the client provides, the SSH server will first check its configuration for an `AuthorizedKeysCommand` to see if the public key matches, and then the `git` user's `authorized_keys` file.
7. The first entry that matches will be selected, and assuming this is a Gitea entry, the `command=` will now be executed.
8. The SSH server creates a user session for the `git` user, and using the shell for the `git` user runs the `command=`
9. This runs `gitea serv` which takes over control of the rest of the SSH session and manages gitea authentication & authorization of the git commands.
Now, for the SSH passthrough to work, we need the host SSH to match the public keys and then run the `gitea serv` on the docker. There are multiple ways of doing this. However, all of these require some information about the docker being passed to the host.
### SSHing Shim (with authorized_keys)
In this option, the idea is that the host simply uses the `authorized_keys` that gitea creates but at step 9 the `gitea` command that the host runs is a shim that actually runs ssh to go into the docker and then run the real docker `gitea` itself.
- To make the forwarding work, the SSH port of the container (22) needs to be mapped to the host port 2222 in `docker-compose.yml` . Since this port does not need to be exposed to the outside world, it can be mapped to the `localhost` of the host machine:
```yaml
ports:
# [...]
- "127.0.0.1:2222:22"
```
- Next on the host create the `git` user which shares the same `UID`/ `GID` as the container values `USER_UID`/ `USER_GID`. These values can be set as environment variables in the `docker-compose.yml`:
```yaml
environment:
- USER_UID=1000
- USER_GID=1000
```
- Mount `/home/git/.ssh` of the host into the container. This ensures that the `authorized_keys` file is shared between the host `git` user and the container `git` user otherwise the SSH authentication cannot work inside the container.
```yaml
volumes:
- /home/git/.ssh/:/data/git/.ssh
```
- Now a SSH key pair needs to be created on the host. This key pair will be used to authenticate the `git` user on the host to the container. As an administrative user on the host run: (by administrative user we mean a user that can sudo to root)
```bash
sudo -u git ssh-keygen -t rsa -b 4096 -C "Gitea Host Key"
```
- Please note depending on the local version of ssh you may want to consider using `-t ecdsa` here.
- `/home/git/.ssh/authorized_keys` on the host now needs to be modified. It needs to act in the same way as `authorized_keys` within the Gitea container. Therefore add the public key of the key you created above ("Gitea Host Key") to `/home/git/.ssh/authorized_keys`. As an administrative user on the host run:
```bash
sudo -u git cat /home/git/.ssh/id_rsa.pub | sudo -u git tee -a /home/git/.ssh/authorized_keys
sudo -u git chmod 600 /home/git/.ssh/authorized_keys
```
Important: The pubkey from the `git` user needs to be added "as is" while all other pubkeys added via the Gitea web interface will be prefixed with `command="/usr [...]`.
`/home/git/.ssh/authorized_keys` should then look somewhat like
```bash
# SSH pubkey from git user
ssh-rsa <Gitea Host Key>
# other keys from users
command="/usr/local/bin/gitea --config=/data/gitea/conf/app.ini serv key-1",no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty <user pubkey>
```
- The next step is to create the fake host `gitea` command that will forward commands from the host to the container. The name of this file depends on your version of Gitea:
- For Gitea v1.16.0+. As an administrative user on the host run:
```bash
cat <<"EOF" | sudo tee /usr/local/bin/gitea
#!/bin/sh
ssh -p 2222 -o StrictHostKeyChecking=no git@127.0.0.1 "SSH_ORIGINAL_COMMAND=\"$SSH_ORIGINAL_COMMAND\" $0 $@"
EOF
sudo chmod +x /usr/local/bin/gitea
```
Here is a detailed explanation what is happening when a SSH request is made:
1. The client adds their SSH public key to Gitea using the webpage.
2. Gitea in the container will add an entry for this key to the `.ssh/authorized_keys` file of its running user, `git`.
- However, because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key has been added to the host `git` user's `authorized_keys` file too.
3. This entry has the public key, but also has a `command=` option.
- This command matches the location of the Gitea binary on the container, but also the location of the shim on the host.
4. The client then makes an SSH request to the host SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
5. The client will attempt to authenticate with the server, passing one or more public keys in turn to the host.
6. For each key the client provides, the host SSH server will first check its configuration for an `AuthorizedKeysCommand` to see if the public key matches, and then the host `git` user's `authorized_keys` file.
- Because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key they added to the Gitea web will be found
7. The first entry that matches will be selected, and assuming this is a Gitea entry, the `command=` will now be executed.
8. The host SSH server creates a user session for the `git` user, and using the shell for the host `git` user runs the `command=`
9. This means that the host runs the host `/usr/local/bin/gitea` shim that opens an SSH from the host to container passing the rest of the command arguments directly to `/usr/local/bin/gitea` on the container.
10. Meaning that the container `gitea serv` is run, taking over control of the rest of the SSH session and managing gitea authentication & authorization of the git commands.
**Notes**
SSH container passthrough using `authorized_keys` will work only if
- `opensshd` is used in the container
- if `AuthorizedKeysCommand` is _not used_ in combination with `SSH_CREATE_AUTHORIZED_KEYS_FILE=false` to disable authorized files key generation
- `LOCAL_ROOT_URL` is not changed (depending on the changes)
If you try to run `gitea` on the host, you will attempt to ssh to the container and thence run the `gitea` command there.
Never add the `Gitea Host Key` as a SSH key to a user on the Gitea interface.
### SSHing Shell (with authorized_keys)
In this option, the idea is that the host simply uses the `authorized_keys` that gitea creates but at step 8 above we change the shell that the host runs to ssh directly into the docker and then run the shell there. This means that the `gitea` that is then run is the real docker `gitea`.
- In this case we setup as per SSHing Shim except instead of creating `/usr/local/bin/gitea`
we create a new shell for the git user. As an administrative user on the host run:
```bash
cat <<"EOF" | sudo tee /home/git/ssh-shell
#!/bin/sh
shift
ssh -p 2222 -o StrictHostKeyChecking=no git@127.0.0.1 "SSH_ORIGINAL_COMMAND=\"$SSH_ORIGINAL_COMMAND\" $@"
EOF
sudo chmod +x /home/git/ssh-shell
sudo usermod -s /home/git/ssh-shell git
```
Be careful here - if you try to login as the git user in future you will ssh directly to the docker.
Here is a detailed explanation what is happening when a SSH request is made:
1. The client adds their SSH public key to Gitea using the webpage.
2. Gitea in the container will add an entry for this key to the `.ssh/authorized_keys` file of its running user, `git`.
- However, because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key has been added to the host `git` user's `authorized_keys` file too.
3. This entry has the public key, but also has a `command=` option.
- This command matches the location of the Gitea binary on the container.
4. The client then makes an SSH request to the host SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
5. The client will attempt to authenticate with the server, passing one or more public keys in turn to the host.
6. For each key the client provides, the host SSH server will first check its configuration for an `AuthorizedKeysCommand` to see if the public key matches, and then the host `git` user's `authorized_keys` file.
- Because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key they added to the Gitea web will be found
7. The first entry that matches will be selected, and assuming this is a Gitea entry, the `command=` will now be executed.
8. The host SSH server creates a user session for the `git` user, and using the shell for the host `git` user runs the `command=`
9. The shell of the host `git` user is now our `ssh-shell` which opens an SSH connection from the host to container, (which opens a shell on the container for the container `git`).
10. The container shell now runs the `command=` option meaning that the container `gitea serv` is run, taking over control of the rest of the SSH session and managing gitea authentication & authorization of the git commands.
**Notes**
SSH container passthrough using `authorized_keys` will work only if
- `opensshd` is used in the container
- if `AuthorizedKeysCommand` is _not used_ in combination with `SSH_CREATE_AUTHORIZED_KEYS_FILE=false` to disable authorized files key generation
- `LOCAL_ROOT_URL` is not changed (depending on the changes)
If you try to login as the `git` user on the host in future you will ssh directly to the docker.
Never add the `Gitea Host Key` as a SSH key to a user on the Gitea interface.
### Docker Shell (with authorized_keys)
Similar to the above ssh shell technique we can use a shell which simply uses `docker exec`. As an administrative user on the host run:
```bash
cat <<"EOF" | sudo tee /home/git/docker-shell
#!/bin/sh
/usr/bin/docker exec -i -u git --env SSH_ORIGINAL_COMMAND="$SSH_ORIGINAL_COMMAND" gitea sh "$@"
EOF
sudo chmod +x /home/git/docker-shell
sudo usermod -s /home/git/docker-shell git
```
Here is a detailed explanation what is happening when a SSH request is made:
1. The client adds their SSH public key to Gitea using the webpage.
2. Gitea in the container will add an entry for this key to the `.ssh/authorized_keys` file of its running user, `git`.
- However, because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key has been added to the host `git` user's `authorized_keys` file too.
3. This entry has the public key, but also has a `command=` option.
- This command matches the location of the Gitea binary on the container.
4. The client then makes an SSH request to the host SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
5. The client will attempt to authenticate with the server, passing one or more public keys in turn to the host.
6. For each key the client provides, the host SSH server will first check its configuration for an `AuthorizedKeysCommand` to see if the public key matches, and then the host `git` user's `authorized_keys` file.
- Because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key they added to the Gitea web will be found
7. The first entry that matches will be selected, and assuming this is a Gitea entry, the `command=` will now be executed.
8. The host SSH server creates a user session for the `git` user, and using the shell for the host `git` user runs the `command=`
9. The shell of the host `git` user is now our `docker-shell` which uses `docker exec` to open a shell for the `git` user on the container.
10. The container shell now runs the `command=` option meaning that the container `gitea serv` is run, taking over control of the rest of the SSH session and managing gitea authentication & authorization of the git commands.
Note that `gitea` in the docker command above is the name of the container. If you named yours differently, don't forget to change that. The host `git` user also has to have
permission to run `docker exec`.
**Notes**
Docker shell passthrough using `authorized_keys` will work only if
- `opensshd` is used in the container
- if `AuthorizedKeysCommand` is _not used_ in combination with `SSH_CREATE_AUTHORIZED_KEYS_FILE=false` to disable authorized files key generation
- `LOCAL_ROOT_URL` is not changed (depending on the changes)
If you try to login as the `git` user on the host in future you will `docker exec` directly to the docker.
A Docker execing shim could be created similarly to above.
### Docker Shell with AuthorizedKeysCommand
The AuthorizedKeysCommand route provides another option that does not require many changes to the compose file or the `authorized_keys` - but does require changes to the host `/etc/sshd_config`.
In this option, the idea is that the host SSH uses an `AuthorizedKeysCommand` instead of relying on sharing the `authorized_keys` file that gitea creates. We continue to use a special shell at step 8 above to exec into the docker and then run the shell there. This means that the `gitea` that is then run is the real docker `gitea`.
- On the host create a `git` user with permission to run `docker exec`.
- We will again assume that the Gitea container is called `gitea`.
- Modify the `git` user's shell to forward commands to the `sh` executable inside the container using `docker exec`. As an administrative user on the host run:
```bash
cat <<"EOF" | sudo tee /home/git/docker-shell
#!/bin/sh
/usr/bin/docker exec -i -u git --env SSH_ORIGINAL_COMMAND="$SSH_ORIGINAL_COMMAND" gitea sh "$@"
EOF
sudo chmod +x /home/git/docker-shell
sudo usermod -s /home/git/docker-shell git
```
Now all attempts to login as the `git` user on the host will be forwarded to the docker - including the `SSH_ORIGINAL_COMMAND`. We now need to set-up SSH authentication on the host.
We will do this by leveraging the [SSH AuthorizedKeysCommand](../administration/command-line.md#keys) to match the keys against those accepted by Gitea.
Add the following block to `/etc/ssh/sshd_config`, on the host:
```bash
Match User git
AuthorizedKeysCommandUser git
AuthorizedKeysCommand /usr/bin/docker exec -i -u git gitea /usr/local/bin/gitea keys -c /data/gitea/conf/app.ini -e git -u %u -t %t -k %k
```
(From 1.16.0 you will not need to set the `-c /data/gitea/conf/app.ini` option.)
Finally restart the SSH server. As an administrative user on the host run:
```bash
sudo systemctl restart sshd
```
Here is a detailed explanation what is happening when a SSH request is made:
1. The client adds their SSH public key to Gitea using the webpage.
2. Gitea in the container will add an entry for this key to its database.
3. The client then makes an SSH request to the host SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
4. The client will attempt to authenticate with the server, passing one or more public keys in turn to the host.
5. For each key the client provides, the host SSH server will checks its configuration for an `AuthorizedKeysCommand`.
6. The host runs the above `AuthorizedKeysCommand`, which execs in to the docker and then runs the `gitea keys` command.
7. Gitea on the docker will look in it's database to see if the public key matches and will return an entry like that of an `authorized_keys` command.
8. This entry has the public key, but also has a `command=` option which matches the location of the Gitea binary on the container.
9. The host SSH server creates a user session for the `git` user, and using the shell for the host `git` user runs the `command=`.
10. The shell of the host `git` user is now our `docker-shell` which uses `docker exec` to open a shell for the `git` user on the container.
11. The container shell now runs the `command=` option meaning that the container `gitea serv` is run, taking over control of the rest of the SSH session and managing gitea authentication & authorization of the git commands.
**Notes**
Docker shell passthrough using `AuthorizedKeysCommand` will work only if
- The host `git` user is allowed to run the `docker exec` command.
If you try to login as the `git` user on the host in future you will `docker exec` directly to the docker.
A Docker execing shim could be created similarly to above.
### SSH Shell with AuthorizedKeysCommand
Create a key for the host `git` user as above, add it to the docker `/data/git/.ssh/authorized_keys` then finally create and set the `ssh-shell` as above.
Add the following block to `/etc/ssh/sshd_config`, on the host:
```bash
Match User git
AuthorizedKeysCommandUser git
AuthorizedKeysCommand /usr/bin/ssh -p 2222 -o StrictHostKeyChecking=no git@127.0.0.1 /usr/local/bin/gitea keys -c /data/gitea/conf/app.ini -e git -u %u -t %t -k %k
```
(From 1.16.0 you will not need to set the `-c /data/gitea/conf/app.ini` option.)
Finally restart the SSH server. As an administrative user on the host run:
```bash
sudo systemctl restart sshd
```
Here is a detailed explanation what is happening when a SSH request is made:
1. The client adds their SSH public key to Gitea using the webpage.
2. Gitea in the container will add an entry for this key to its database.
3. The client then makes an SSH request to the host SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
4. The client will attempt to authenticate with the server, passing one or more public keys in turn to the host.
5. For each key the client provides, the host SSH server will checks its configuration for an `AuthorizedKeysCommand`.
6. The host runs the above `AuthorizedKeysCommand`, which will SSH in to the docker and then run the `gitea keys` command.
7. Gitea on the docker will look in it's database to see if the public key matches and will return an entry like that of an `authorized_keys` command.
8. This entry has the public key, but also has a `command=` option which matches the location of the Gitea binary on the container.
9. The host SSH server creates a user session for the `git` user, and using the shell for the host `git` user runs the `command=`.
10. The shell of the host `git` user is now our `git-shell` which uses SSH to open a shell for the `git` user on the container.
11. The container shell now runs the `command=` option meaning that the container `gitea serv` is run, taking over control of the rest of the SSH session and managing gitea authentication & authorization of the git commands.
**Notes**
SSH container passthrough using `AuthorizedKeysCommand` will work only if
- `opensshd` is running on the container
If you try to login as the `git` user on the host in future you will `ssh` directly to the docker.
Never add the `Gitea Host Key` as a SSH key to a user on the Gitea interface.
SSHing shims could be created similarly to above.
### SSH with multiple IP addresses
This assumes that the host machine has more than one reachable IP address: `192.168.1.1` (host) `192.168.1.2` (gitea)
On the host machine, configure SSHD in `/etc/ssh/sshd_config` to listen on one IP address `ListenAddress 192.168.1.1`. In the compose file the SSH port forwarding then needs to be changed to `"192.168.1.2:22:22"`. The port forwarding needs to be adjusted similarily for all other forwarded ports to avoid problems with DNS.

74
docs/usage/actions/act-runner.mdx
View File

@@ -6,18 +6,18 @@ sidebar_position: 20
# Act Runner
This page will introduce the [act runner](https://gitea.com/gitea/act_runner) in detail, which is the runner of Gitea Actions.
This page will introduce the [act runner](https://gitea.com/gitea/act_runner) in detail, which is the runner for Gitea Actions.
## Requirements
Currently the runner supports three modes in which it can be run.
1. Host: act_runner will run as an application on the host. This provides no encapsulation.
2. Docker (recommended): Runs jobs in a [docker](https://docker.com) container. If you chose this mode, you need to [install docker](https://docs.docker.com/engine/install/) first and make sure that the docker daemon is running.
3. Docker-in-Docker (DinD): Puts the runner into rootless mode. It then runs in a docker container with its own Docker daemon that has less privileges. Will spawn job containers from there. Best security but more complex setup.
2. Docker (recommended): Runs jobs in a [Docker](https://docker.com) container. If you choose this mode, you need to [install Docker](https://docs.docker.com/engine/install/) first and make sure that the Docker daemon is running.
3. Docker-in-Docker (DinD): Puts the runner into rootless mode. It then runs in a Docker container with its own Docker daemon that has fewer privileges. It will spawn job containers from there. Best security but more complex setup.
Other OCI container engines which are compatible with Docker's API should also work, but are untested.
However, if you are sure that you want to run jobs directly on the host only, then docker is not required.
However, if you are sure that you want to run jobs directly on the host only, then Docker is not required.
There are multiple ways to install the act runner.
@@ -29,7 +29,7 @@ You can download the binary from the [release page](https://gitea.com/gitea/act_
However, if you want to use the latest nightly build, you can download it from the [download page](https://dl.gitea.com/act_runner/).
When you download the binary, please make sure that you have downloaded the correct one for your platform.
You can check it by running the following command if you are in a Unix-Style OS.
You can check it by running the following command if you are in a Unix-style OS.
```bash
chmod +x act_runner
@@ -40,7 +40,7 @@ If you see the version information, it means that you have downloaded the correc
### Obtain a registration token
You can register a runner in different levels, it can be:
You can register a runner at different levels. It can be:
- Instance level: The runner will run jobs for all repositories in the instance.
- Organization level: The runner will run jobs for all repositories in the organization.
@@ -49,7 +49,7 @@ You can register a runner in different levels, it can be:
Note that the repository may still use instance-level or organization-level runners even if it has its own repository-level runners. A future release may provide an option to allow more control over this.
Before register the runner and run it, you need a registration token. The level of the runner determines where to obtain the registration token.
Before registering the runner and running it, you need a registration token. The level of the runner determines where to obtain the registration token.
- Instance level: The admin settings page, like `<your_gitea.com>/-/admin/actions/runners`.
- Organization level: The organization settings page, like `<your_gitea.com>/<org>/settings/actions/runners`.
@@ -59,13 +59,13 @@ If you cannot see the settings page, please make sure that you have the right pe
The format of the registration token is a random string `D0gvfu2iHfUjNqCYVljVyRV14fISpJxxxxxxxxxx`.
A registration token can also be obtained from the gitea [command-line interface](../../administration/command-line.md#actions-generate-runner-token):
A registration token can also be obtained from the Gitea [command-line interface](../../administration/command-line.md#actions-generate-runner-token):
```
gitea --config /etc/gitea/app.ini actions generate-runner-token
```
You can also use `GITEA_RUNNER_REGISTRATION_TOKEN`/`GITEA_RUNNER_REGISTRATION_TOKEN_FILE` environment variable to set a global runner registration token when Gitea starts, for example:
You can also use `GITEA_RUNNER_REGISTRATION_TOKEN`/`GITEA_RUNNER_REGISTRATION_TOKEN_FILE` environment variables to set a global runner registration token when Gitea starts, for example:
```
openssl rand -hex 24 > /some-dir/runner-token
@@ -73,7 +73,7 @@ export GITEA_RUNNER_REGISTRATION_TOKEN_FILE=/some-dir/runner-token
./gitea --config ...
```
The token from environment is valid until you reset the token (re-create a new one) via web UI or API.
The token from the environment is valid until you reset the token (re-create a new one) via the web UI or API.
Tokens are valid for registering multiple runners, until they are revoked and replaced by a new token using the token reset link in the web interface.
@@ -94,7 +94,7 @@ The default configuration is safe to use without any modification, so you can ju
### Register the runner
Registration is required before running the act runner, because the runner needs to know where to get jobs from. And it is also important to Gitea instance to identify the runner.
Registration is required before running the act runner, because the runner needs to know where to get jobs from. It is also important for the Gitea instance to identify the runner.
If this has been installed using the binary package, the act runner can be registered by running the following command.
@@ -108,7 +108,7 @@ Alternatively, you can use the `--config` option to specify the configuration fi
./act_runner --config config.yaml register
```
You will be asked to input the registration information step by step. Includes:
You will be asked to input the registration information step by step. This includes:
- The Gitea instance URL, like `https://gitea.com/` or `http://192.168.8.8:3000/`.
- The registration token.
@@ -135,7 +135,7 @@ and don't forget to specify the `--config` option.
Ephemeral runners provide a security hardening mechanism for enabling organization- or instance-wide runners without requiring full user trust. Once a job is assigned within a spot VM or container, the runner's exposed credentials are automatically revoked—blocking it from polling further jobs before any untrusted code runs, while still allowing it to report progress until completion by either Gitea or the runner.
act_runner **0.2.12+** required.
act_runner **0.2.12+** is required.
The updated commands for registering the runner as ephemeral are listed below. Refer to the previous section for detailed information on registering the act_runner.
@@ -155,9 +155,9 @@ The runner must be registered each time it is intended to receive a job. After c
To automate the registration and startup of new runners when a job is queued, use the `workflow_job` webhook.
### Start the runner in command line
### Start the runner from the command line
After you have registered the runner, you can run it by running the following command:
After you have registered the runner, you can run it with the following command:
```shell
./act_runner daemon
@@ -173,7 +173,7 @@ The runner will fetch jobs from the Gitea instance and run them automatically.
### Start the runner with Systemd
It is also possible to run act-runner as a [systemd](https://en.wikipedia.org/wiki/Systemd) service. Create an unprivileged `act_runner` user on your system, and the following file in `/etc/systemd/system/act_runner.service`. The paths in `ExecStart` and `WorkingDirectory` may need to be adjusted depending on where you installed the `act_runner` binary, its configuration file, and the home directory of the `act_runner` user.
It is also possible to run act-runner as a [systemd](https://en.wikipedia.org/wiki/Systemd) service. Create an unprivileged `act_runner` user on your system, and create the following file in `/etc/systemd/system/act_runner.service`. The paths in `ExecStart` and `WorkingDirectory` may need to be adjusted depending on where you installed the `act_runner` binary, its configuration file, and the home directory of the `act_runner` user.
```ini
[Unit]
@@ -205,9 +205,9 @@ sudo systemctl enable act_runner --now
If using Docker, the `act_runner` user should also be added to the `docker` group before starting the service. Keep in mind that this effectively gives `act_runner` root access to the system [[1]](https://docs.docker.com/engine/security/#docker-daemon-attack-surface).
### Start the runner with LaunchDaemon(macOS)
### Start the runner with LaunchDaemon (macOS)
Mac uses `launchd` in place of systemd for registering daemon processes. By default daemons run as the root user, so if desired an unprivileged `_act_runner` user can be created via the `dscl` tool. The following file should then be created at the directory `/Library/LaunchDaemon/com.gitea.act_runner.plist`. The paths for `WorkingDirectory`, `ProgramArguments`, `StandardOutPath`, `StandardErrPath`, and the `HOME` environment variable may need to be updated to reflect your installation. Also note that any executables outside of the example `PATH` shown will need to be explicitly included and will not be inherited from existing configurations.
Mac uses `launchd` in place of systemd for registering daemon processes. By default, daemons run as the root user, so if desired an unprivileged `_act_runner` user can be created via the `dscl` tool. The following file should then be created in the directory `/Library/LaunchDaemon/com.gitea.act_runner.plist`. The paths for `WorkingDirectory`, `ProgramArguments`, `StandardOutPath`, `StandardErrPath`, and the `HOME` environment variable may need to be updated to reflect your installation. Also note that any executables outside of the example `PATH` shown will need to be explicitly included and will not be inherited from existing configurations.
```xml
<?xml version="1.0" encoding="UTF-8"?>
@@ -252,27 +252,27 @@ Then:
sudo launchctl load /Library/LaunchDaemon/com.gitea.act_runner.plist
```
You can also set up a Linux service or Windows service to let the runner run automatically.
You can also set up a Linux or Windows service to let the runner run automatically.
## Install with the docker image
### Pull the image
You can use the docker image from the [docker hub](https://hub.docker.com/r/gitea/act_runner/tags).
You can use the docker image from [Docker Hub](https://hub.docker.com/r/gitea/act_runner/tags).
Just like the binary, you can use the latest nightly build by using the `nightly` tag, while the `latest` tag is the latest stable release.
```bash
docker pull docker.io/gitea/act_runner:latest # for the latest stable release
```
If you want to use the newest or experimental features, you could also use the nightly image
If you want to use the newest or experimental features, you can also use the nightly image.
```bash
docker pull docker.io/gitea/act_runner:nightly # for the latest nightly build
```
### Configuration
Configuration is optional, but you could also generate config file with docker:
Configuration is optional, but you can also generate a config file with docker:
```bash
docker run --entrypoint="" --rm -it docker.io/gitea/act_runner:latest act_runner generate-config > config.yaml
@@ -284,14 +284,14 @@ When you are using the docker image, you can specify the configuration file by u
docker run -v $PWD/config.yaml:/config.yaml -e CONFIG_FILE=/config.yaml ...
```
You may notice the commands above are both incomplete, because it is not the time to run the act runner yet.
You may notice the commands above are incomplete because it is not time to run the act runner yet.
Before running the act runner, we need to register it to your Gitea instance first.
### Start the runner with docker
If you are using the docker image, behavior will be slightly different. Registration and running are combined into one step in this case, so you need to specify the registration information when running the act runner.
A quick start with docker run along with a minimal parameter set is shown below. You need to get the `<registration_token>` from the above step, and set a unique name for `<gitea_runner_name>` and `<container_name>`
A quick start with docker run along with a minimal parameter set is shown below. You need to get the `<registration_token>` from the above step, and set a unique name for `<gitea_runner_name>` and for `<container_name>`.
```bash
docker run \
@@ -303,7 +303,7 @@ docker run \
-d docker.io/gitea/act_runner:latest
```
You can add more parameters to use a custom config, add a `data` directory for non-voltatile file storage etc.
You can add more parameters to use a custom config, add a `data` directory for non-volatile file storage, etc.
```bash
docker run \
@@ -320,9 +320,9 @@ docker run \
```
You may notice that we have mounted `/var/run/docker.sock` into the container.
It is because with this setup, act runner will execute jobs in temporary docker containers so it needs to communicate with the docker daemon.
As mentioned, you can remove it if you want to run jobs in the host directly.
To be clear, the "host" actually means the container which is running the act runner now, instead of the host machine.
This is because with this setup, act runner will execute jobs in temporary Docker containers, so it needs to communicate with the Docker daemon.
As mentioned, you can remove it if you want to run jobs on the host directly.
To be clear, the "host" actually means the container that is running the act runner now, instead of the host machine.
---
@@ -401,13 +401,13 @@ services:
Mounting the host's Docker socket using `/var/run/docker.sock:/var/run/docker.sock` introduces a potential security vulnerability. If a job can access this socket, the reusable `GITEA_RUNNER_REGISTRATION_TOKEN` could be exposed through Docker inspect data.
### More start examples
A couple of more usage examples can be found in the [act_runner](https://gitea.com/gitea/act_runner/src/branch/main/examples) repository.
A couple more usage examples can be found in the [act_runner](https://gitea.com/gitea/act_runner/src/branch/main/examples) repository.
## Advanced Configurations
### Configuring cache when starting a Runner using docker image
### Configuring cache when starting a runner using the docker image
If you do not intend to use `actions/cache` in workflow, you can ignore this section.
If you do not intend to use `actions/cache` in your workflow, you can ignore this section.
If you use `actions/cache` without any additional configuration, it will return the following error:
> Failed to restore: getCacheEntry failed: connect ETIMEDOUT IP:PORT
@@ -416,9 +416,9 @@ The error occurs because the runner container and job container are on different
Therefore, it is essential to configure the cache action to ensure its proper functioning. Follow these steps:
- 1.Obtain the LAN IP address of the host machine where the runner container is running.
- 2.Find an available port number on the host machine where the runner container is running.
- 3.Configure the following settings in the configuration file:
- 1. Obtain the LAN IP address of the host machine where the runner container is running.
- 2. Find an available port number on the host machine where the runner container is running.
- 3. Configure the following settings in the configuration file:
```yaml
cache:
@@ -430,7 +430,7 @@ cache:
port: 8088
```
- 4.When starting the container, map the cache port to the host machine:
- 4. When starting the container, map the cache port to the host machine:
```bash
docker run \
@@ -452,8 +452,8 @@ It means that the runner can run jobs with `runs-on: ubuntu-22.04`, and the job
If the default image is insufficient for your needs, and you have enough disk space to use a better and bigger one, you can change it to `ubuntu-22.04:docker://<the image you like>`.
You can find more useful images on [act images](https://github.com/nektos/act/blob/master/IMAGES.md).
If you want to run jobs in the host directly, you can change it to `ubuntu-22.04:host` or just `ubuntu-22.04`, the `:host` is optional.
However, we suggest you to use a special name like `linux_amd64:host` or `windows:host` to avoid misusing it.
If you want to run jobs on the host directly, you can change it to `ubuntu-22.04:host` or just `ubuntu-22.04`; `:host` is optional.
However, we suggest you use a special name like `linux_amd64:host` or `windows:host` to avoid misusing it.
Starting with Gitea 1.21, you can change labels by modifying `runners.labels` in the runner configuration file (if you don't have a configuration file, please refer to [configuration tutorials](#configuration)).
The runner will use these new labels as soon as you restart it, i.e., by calling `./act_runner daemon --config config.yaml`.

8
docs/usage/actions/comparison.md
View File

@@ -100,6 +100,14 @@ Services steps don't have their own section in the job log user interface.
## Different behavior
### Concurrency
As of v1.21.0, gitea behaves as if `concurrency.cancel-in-progress` is set to `true`.
This means that newly-triggered workflows will pre-empt runs already in progress for previous triggers.
See [PR #25716](https://github.com/go-gitea/gitea/pull/25716) for additional details.
### Downloading actions
Previously (Pre 1.21.0), `[actions].DEFAULT_ACTIONS_URL` defaulted to `https://gitea.com`.

8
docusaurus.config.js
View File

@@ -78,11 +78,11 @@ const globalVariables = {
goVersion: "1.25",
minGoVersion: "1.25",
minNodeVersion: "22",
version: "1.25.2",
version: "1.25.4",
sourceVersion: "v1.25.0",
sourceBranch: "release/v1.25",
dockerVersion: "1.25.2",
displayVersion: "1.25.2",
dockerVersion: "1.25.4",
displayVersion: "1.25.4",
},
"1.24": {
goVersion: "1.24",
@@ -396,7 +396,7 @@ const config = {
position: "right",
items: [
{ to: "/api/next/", label: "1.26-dev" },
{ to: "/api/1.25/", label: "1.25.2" },
{ to: "/api/1.25/", label: "1.25.4" },
{ to: "/api/1.24/", label: "1.24.7" },
{ to: "/api/1.23/", label: "1.23.8" },
{ to: "/api/1.22/", label: "1.22.6" },

19964
package-lock.json generated
View File

File diff suppressed because it is too large Load Diff

7
package.json
View File

@@ -18,12 +18,14 @@
"dependencies": {
"@docusaurus/core": "^3.9.2",
"@docusaurus/faster": "^3.9.2",
"@docusaurus/plugin-content-docs": "^3.9.2",
"@docusaurus/preset-classic": "^3.9.2",
"@easyops-cn/docusaurus-search-local": "^0.52.0",
"@easyops-cn/docusaurus-search-local": "^0.55.0",
"@emotion/react": "^11.11.3",
"@emotion/styled": "^11.11.0",
"@mdx-js/react": "^3.0.0",
"@mui/material": "^7.0.0",
"clsx": "^2.1.1",
"docusaurus-plugin-plausible": "^0.0.5",
"prism-react-renderer": "^2.1.0",
"react": "^19.0.0",
@@ -48,5 +50,6 @@
},
"engines": {
"node": ">=18"
}
},
"packageManager": "pnpm@10.29.3"
}

14505
pnpm-lock.yaml generated Normal file
View File

File diff suppressed because it is too large Load Diff

7
src/theme/MDXComponents/index.js Normal file
View File

@@ -0,0 +1,7 @@
import MDXComponents from '@theme-original/MDXComponents';
import A from './A';
export default {
...MDXComponents,
a: A,
};

2
static/swagger-25.json
View File

@@ -19,7 +19,7 @@
"name": "MIT",
"url": "http://opensource.org/licenses/MIT"
},
"version": "1.25.2"
"version": "1.25.4"
},
"basePath": "https://gitea.com/api/v1",
"paths": {

2
update_api_docs.sh
View File

@@ -25,7 +25,7 @@ inplace_sed 's|"version": "{{.SwaggerAppVer}}"|"version": "dev"|' v1_json.tmpl
inplace_sed 's|"basePath": "{{.SwaggerAppSubUrl}}/api/v1"|"basePath": "https://gitea.com/api/v1"|' v1_json.tmpl
mv v1_json.tmpl static/swagger-latest.json
for ver in '1.25.2' '1.24.7' '1.23.8' '1.22.6'; do
for ver in '1.25.4' '1.24.7' '1.23.8' '1.22.6'; do
curl --silent --output v1_json.tmpl https://raw.githubusercontent.com/go-gitea/gitea/refs/tags/v${ver}/templates/swagger/v1_json.tmpl
inplace_sed "s|\"version\": \"{{.SwaggerAppVer}}\"|\"version\": \"${ver}\"|" v1_json.tmpl
inplace_sed 's|"basePath": "{{.SwaggerAppSubUrl}}/api/v1"|"basePath": "https://gitea.com/api/v1"|' v1_json.tmpl

48
versioned_docs/version-1.22/installation/with-docker-rootless.md
View File

@@ -315,51 +315,3 @@ services:
```
To set required TOKEN and SECRET values, consider using Gitea's built-in [generate utility functions](../administration/command-line.md#generate).
# SSH Container Passthrough
Since SSH is running inside the container, SSH needs to be passed through from the host to the container if SSH support is desired. One option would be to run the container SSH on a non-standard port (or moving the host port to a non-standard port). Another option which might be more straightforward is to forward SSH commands from the host to the container. This setup is explained in the following.
This guide assumes that you have created a user on the host called `git` with permission to run `docker exec`, and that the Gitea container is called `gitea`. You will need to modify that user's shell to forward the commands to the `sh` executable inside the container, using `docker exec`.
First, create the file `/usr/local/bin/gitea-shell` on the host, with the following contents:
```bash
#!/bin/sh
/usr/bin/docker exec -i --env SSH_ORIGINAL_COMMAND="$SSH_ORIGINAL_COMMAND" gitea sh "$@"
```
Note that `gitea` in the docker command above is the name of the container. If you named yours differently, don't forget to change that.
You should also make sure that you’ve set the permissions of the shell wrapper correctly:
```bash
sudo chmod +x /usr/local/bin/gitea-shell
```
Once the wrapper is in place, you can make it the shell for the `git` user:
```bash
sudo usermod -s /usr/local/bin/gitea-shell git
```
Now that all the SSH commands are forwarded to the container, you need to set up the SSH authentication on the host. This is done by leveraging the [SSH AuthorizedKeysCommand](../administration/command-line.md#keys) to match the keys against those accepted by Gitea. Add the following block to `/etc/ssh/sshd_config`, on the host:
```bash
Match User git
AuthorizedKeysCommandUser git
AuthorizedKeysCommand /usr/bin/docker exec -i gitea /usr/local/bin/gitea keys -c /etc/gitea/app.ini -e git -u %u -t %t -k %k
```
(From 1.16.0 you will not need to set the `-c /etc/gitea/app.ini` option.)
All that is left to do is restart the SSH server:
```bash
sudo systemctl restart sshd
```
**Notes**
This isn't actually using the docker SSH - it is simply using the commands around it.
You could theoretically not run the internal SSH server.

314
versioned_docs/version-1.22/installation/with-docker.md
View File

@@ -330,317 +330,3 @@ services:
- GITEA__security__SECRET_KEY=[value returned by generate secret SECRET_KEY]
- GITEA__security__INTERNAL_TOKEN=[value returned by generate secret INTERNAL_TOKEN]
```
## SSH Container Passthrough
Since SSH is running inside the container, SSH needs to be passed through from the host to the container if SSH support is desired. One option would be to run the container SSH on a non-standard port (or moving the host port to a non-standard port). Another option which might be more straightforward is for Gitea users to ssh to a Gitea user on the host which will then relay those connections to the docker.
### Understanding SSH access to Gitea (without passthrough)
To understand what needs to happen, you first need to understand what happens without passthrough. So we will try to explain this:
1. The client adds their SSH public key to Gitea using the webpage.
2. Gitea will add an entry for this key to the `.ssh/authorized_keys` file of its running user, `git`.
3. This entry has the public key, but also has a `command=` option. It is this command that Gitea uses to match this key to the client user and manages authentication.
4. The client then makes an SSH request to the SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
5. The client will attempt to authenticate with the server, passing one or more public keys one at a time to the server.
6. For each key the client provides, the SSH server will first check its configuration for an `AuthorizedKeysCommand` to see if the public key matches, and then the `git` user's `authorized_keys` file.
7. The first entry that matches will be selected, and assuming this is a Gitea entry, the `command=` will now be executed.
8. The SSH server creates a user session for the `git` user, and using the shell for the `git` user runs the `command=`
9. This runs `gitea serv` which takes over control of the rest of the SSH session and manages gitea authentication & authorization of the git commands.
Now, for the SSH passthrough to work, we need the host SSH to match the public keys and then run the `gitea serv` on the docker. There are multiple ways of doing this. However, all of these require some information about the docker being passed to the host.
### SSHing Shim (with authorized_keys)
In this option, the idea is that the host simply uses the `authorized_keys` that gitea creates but at step 9 the `gitea` command that the host runs is a shim that actually runs ssh to go into the docker and then run the real docker `gitea` itself.
- To make the forwarding work, the SSH port of the container (22) needs to be mapped to the host port 2222 in `docker-compose.yml` . Since this port does not need to be exposed to the outside world, it can be mapped to the `localhost` of the host machine:
```yaml
ports:
# [...]
- "127.0.0.1:2222:22"
```
- Next on the host create the `git` user which shares the same `UID`/ `GID` as the container values `USER_UID`/ `USER_GID`. These values can be set as environment variables in the `docker-compose.yml`:
```yaml
environment:
- USER_UID=1000
- USER_GID=1000
```
- Mount `/home/git/.ssh` of the host into the container. This ensures that the `authorized_keys` file is shared between the host `git` user and the container `git` user otherwise the SSH authentication cannot work inside the container.
```yaml
volumes:
- /home/git/.ssh/:/data/git/.ssh
```
- Now a SSH key pair needs to be created on the host. This key pair will be used to authenticate the `git` user on the host to the container. As an administrative user on the host run: (by administrative user we mean a user that can sudo to root)
```bash
sudo -u git ssh-keygen -t rsa -b 4096 -C "Gitea Host Key"
```
- Please note depending on the local version of ssh you may want to consider using `-t ecdsa` here.
- `/home/git/.ssh/authorized_keys` on the host now needs to be modified. It needs to act in the same way as `authorized_keys` within the Gitea container. Therefore add the public key of the key you created above ("Gitea Host Key") to `/home/git/.ssh/authorized_keys`. As an administrative user on the host run:
```bash
sudo -u git cat /home/git/.ssh/id_rsa.pub | sudo -u git tee -a /home/git/.ssh/authorized_keys
sudo -u git chmod 600 /home/git/.ssh/authorized_keys
```
Important: The pubkey from the `git` user needs to be added "as is" while all other pubkeys added via the Gitea web interface will be prefixed with `command="/usr [...]`.
`/home/git/.ssh/authorized_keys` should then look somewhat like
```bash
# SSH pubkey from git user
ssh-rsa <Gitea Host Key>
# other keys from users
command="/usr/local/bin/gitea --config=/data/gitea/conf/app.ini serv key-1",no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty <user pubkey>
```
- The next step is to create the fake host `gitea` command that will forward commands from the host to the container. The name of this file depends on your version of Gitea:
- For Gitea v1.16.0+. As an administrative user on the host run:
```bash
cat <<"EOF" | sudo tee /usr/local/bin/gitea
#!/bin/sh
ssh -p 2222 -o StrictHostKeyChecking=no git@127.0.0.1 "SSH_ORIGINAL_COMMAND=\"$SSH_ORIGINAL_COMMAND\" $0 $@"
EOF
sudo chmod +x /usr/local/bin/gitea
```
Here is a detailed explanation what is happening when a SSH request is made:
1. The client adds their SSH public key to Gitea using the webpage.
2. Gitea in the container will add an entry for this key to the `.ssh/authorized_keys` file of its running user, `git`.
- However, because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key has been added to the host `git` user's `authorized_keys` file too.
3. This entry has the public key, but also has a `command=` option.
- This command matches the location of the Gitea binary on the container, but also the location of the shim on the host.
4. The client then makes an SSH request to the host SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
5. The client will attempt to authenticate with the server, passing one or more public keys in turn to the host.
6. For each key the client provides, the host SSH server will first check its configuration for an `AuthorizedKeysCommand` to see if the public key matches, and then the host `git` user's `authorized_keys` file.
- Because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key they added to the Gitea web will be found
7. The first entry that matches will be selected, and assuming this is a Gitea entry, the `command=` will now be executed.
8. The host SSH server creates a user session for the `git` user, and using the shell for the host `git` user runs the `command=`
9. This means that the host runs the host `/usr/local/bin/gitea` shim that opens an SSH from the host to container passing the rest of the command arguments directly to `/usr/local/bin/gitea` on the container.
10. Meaning that the container `gitea serv` is run, taking over control of the rest of the SSH session and managing gitea authentication & authorization of the git commands.
**Notes**
SSH container passthrough using `authorized_keys` will work only if
- `opensshd` is used in the container
- if `AuthorizedKeysCommand` is _not used_ in combination with `SSH_CREATE_AUTHORIZED_KEYS_FILE=false` to disable authorized files key generation
- `LOCAL_ROOT_URL` is not changed (depending on the changes)
If you try to run `gitea` on the host, you will attempt to ssh to the container and thence run the `gitea` command there.
Never add the `Gitea Host Key` as a SSH key to a user on the Gitea interface.
### SSHing Shell (with authorized_keys)
In this option, the idea is that the host simply uses the `authorized_keys` that gitea creates but at step 8 above we change the shell that the host runs to ssh directly into the docker and then run the shell there. This means that the `gitea` that is then run is the real docker `gitea`.
- In this case we setup as per SSHing Shim except instead of creating `/usr/local/bin/gitea`
we create a new shell for the git user. As an administrative user on the host run:
```bash
cat <<"EOF" | sudo tee /home/git/ssh-shell
#!/bin/sh
shift
ssh -p 2222 -o StrictHostKeyChecking=no git@127.0.0.1 "SSH_ORIGINAL_COMMAND=\"$SSH_ORIGINAL_COMMAND\" $@"
EOF
sudo chmod +x /home/git/ssh-shell
sudo usermod -s /home/git/ssh-shell git
```
Be careful here - if you try to login as the git user in future you will ssh directly to the docker.
Here is a detailed explanation what is happening when a SSH request is made:
1. The client adds their SSH public key to Gitea using the webpage.
2. Gitea in the container will add an entry for this key to the `.ssh/authorized_keys` file of its running user, `git`.
- However, because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key has been added to the host `git` user's `authorized_keys` file too.
3. This entry has the public key, but also has a `command=` option.
- This command matches the location of the Gitea binary on the container.
4. The client then makes an SSH request to the host SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
5. The client will attempt to authenticate with the server, passing one or more public keys in turn to the host.
6. For each key the client provides, the host SSH server will first check its configuration for an `AuthorizedKeysCommand` to see if the public key matches, and then the host `git` user's `authorized_keys` file.
- Because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key they added to the Gitea web will be found
7. The first entry that matches will be selected, and assuming this is a Gitea entry, the `command=` will now be executed.
8. The host SSH server creates a user session for the `git` user, and using the shell for the host `git` user runs the `command=`
9. The shell of the host `git` user is now our `ssh-shell` which opens an SSH connection from the host to container, (which opens a shell on the container for the container `git`).
10. The container shell now runs the `command=` option meaning that the container `gitea serv` is run, taking over control of the rest of the SSH session and managing gitea authentication & authorization of the git commands.
**Notes**
SSH container passthrough using `authorized_keys` will work only if
- `opensshd` is used in the container
- if `AuthorizedKeysCommand` is _not used_ in combination with `SSH_CREATE_AUTHORIZED_KEYS_FILE=false` to disable authorized files key generation
- `LOCAL_ROOT_URL` is not changed (depending on the changes)
If you try to login as the `git` user on the host in future you will ssh directly to the docker.
Never add the `Gitea Host Key` as a SSH key to a user on the Gitea interface.
### Docker Shell (with authorized_keys)
Similar to the above ssh shell technique we can use a shell which simply uses `docker exec`. As an administrative user on the host run:
```bash
cat <<"EOF" | sudo tee /home/git/docker-shell
#!/bin/sh
/usr/bin/docker exec -i -u git --env SSH_ORIGINAL_COMMAND="$SSH_ORIGINAL_COMMAND" gitea sh "$@"
EOF
sudo chmod +x /home/git/docker-shell
sudo usermod -s /home/git/docker-shell git
```
Here is a detailed explanation what is happening when a SSH request is made:
1. The client adds their SSH public key to Gitea using the webpage.
2. Gitea in the container will add an entry for this key to the `.ssh/authorized_keys` file of its running user, `git`.
- However, because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key has been added to the host `git` user's `authorized_keys` file too.
3. This entry has the public key, but also has a `command=` option.
- This command matches the location of the Gitea binary on the container.
4. The client then makes an SSH request to the host SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
5. The client will attempt to authenticate with the server, passing one or more public keys in turn to the host.
6. For each key the client provides, the host SSH server will first check its configuration for an `AuthorizedKeysCommand` to see if the public key matches, and then the host `git` user's `authorized_keys` file.
- Because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key they added to the Gitea web will be found
7. The first entry that matches will be selected, and assuming this is a Gitea entry, the `command=` will now be executed.
8. The host SSH server creates a user session for the `git` user, and using the shell for the host `git` user runs the `command=`
9. The shell of the host `git` user is now our `docker-shell` which uses `docker exec` to open a shell for the `git` user on the container.
10. The container shell now runs the `command=` option meaning that the container `gitea serv` is run, taking over control of the rest of the SSH session and managing gitea authentication & authorization of the git commands.
Note that `gitea` in the docker command above is the name of the container. If you named yours differently, don't forget to change that. The host `git` user also has to have
permission to run `docker exec`.
**Notes**
Docker shell passthrough using `authorized_keys` will work only if
- `opensshd` is used in the container
- if `AuthorizedKeysCommand` is _not used_ in combination with `SSH_CREATE_AUTHORIZED_KEYS_FILE=false` to disable authorized files key generation
- `LOCAL_ROOT_URL` is not changed (depending on the changes)
If you try to login as the `git` user on the host in future you will `docker exec` directly to the docker.
A Docker execing shim could be created similarly to above.
### Docker Shell with AuthorizedKeysCommand
The AuthorizedKeysCommand route provides another option that does not require many changes to the compose file or the `authorized_keys` - but does require changes to the host `/etc/sshd_config`.
In this option, the idea is that the host SSH uses an `AuthorizedKeysCommand` instead of relying on sharing the `authorized_keys` file that gitea creates. We continue to use a special shell at step 8 above to exec into the docker and then run the shell there. This means that the `gitea` that is then run is the real docker `gitea`.
- On the host create a `git` user with permission to run `docker exec`.
- We will again assume that the Gitea container is called `gitea`.
- Modify the `git` user's shell to forward commands to the `sh` executable inside the container using `docker exec`. As an administrative user on the host run:
```bash
cat <<"EOF" | sudo tee /home/git/docker-shell
#!/bin/sh
/usr/bin/docker exec -i -u git --env SSH_ORIGINAL_COMMAND="$SSH_ORIGINAL_COMMAND" gitea sh "$@"
EOF
sudo chmod +x /home/git/docker-shell
sudo usermod -s /home/git/docker-shell git
```
Now all attempts to login as the `git` user on the host will be forwarded to the docker - including the `SSH_ORIGINAL_COMMAND`. We now need to set-up SSH authentication on the host.
We will do this by leveraging the [SSH AuthorizedKeysCommand](../administration/command-line.md#keys) to match the keys against those accepted by Gitea.
Add the following block to `/etc/ssh/sshd_config`, on the host:
```bash
Match User git
AuthorizedKeysCommandUser git
AuthorizedKeysCommand /usr/bin/docker exec -i -u git gitea /usr/local/bin/gitea keys -c /data/gitea/conf/app.ini -e git -u %u -t %t -k %k
```
(From 1.16.0 you will not need to set the `-c /data/gitea/conf/app.ini` option.)
Finally restart the SSH server. As an administrative user on the host run:
```bash
sudo systemctl restart sshd
```
Here is a detailed explanation what is happening when a SSH request is made:
1. The client adds their SSH public key to Gitea using the webpage.
2. Gitea in the container will add an entry for this key to its database.
3. The client then makes an SSH request to the host SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
4. The client will attempt to authenticate with the server, passing one or more public keys in turn to the host.
5. For each key the client provides, the host SSH server will checks its configuration for an `AuthorizedKeysCommand`.
6. The host runs the above `AuthorizedKeysCommand`, which execs in to the docker and then runs the `gitea keys` command.
7. Gitea on the docker will look in it's database to see if the public key matches and will return an entry like that of an `authorized_keys` command.
8. This entry has the public key, but also has a `command=` option which matches the location of the Gitea binary on the container.
9. The host SSH server creates a user session for the `git` user, and using the shell for the host `git` user runs the `command=`.
10. The shell of the host `git` user is now our `docker-shell` which uses `docker exec` to open a shell for the `git` user on the container.
11. The container shell now runs the `command=` option meaning that the container `gitea serv` is run, taking over control of the rest of the SSH session and managing gitea authentication & authorization of the git commands.
**Notes**
Docker shell passthrough using `AuthorizedKeysCommand` will work only if
- The host `git` user is allowed to run the `docker exec` command.
If you try to login as the `git` user on the host in future you will `docker exec` directly to the docker.
A Docker execing shim could be created similarly to above.
### SSH Shell with AuthorizedKeysCommand
Create a key for the host `git` user as above, add it to the docker `/data/git/.ssh/authorized_keys` then finally create and set the `ssh-shell` as above.
Add the following block to `/etc/ssh/sshd_config`, on the host:
```bash
Match User git
AuthorizedKeysCommandUser git
AuthorizedKeysCommand /usr/bin/ssh -p 2222 -o StrictHostKeyChecking=no git@127.0.0.1 /usr/local/bin/gitea keys -c /data/gitea/conf/app.ini -e git -u %u -t %t -k %k
```
(From 1.16.0 you will not need to set the `-c /data/gitea/conf/app.ini` option.)
Finally restart the SSH server. As an administrative user on the host run:
```bash
sudo systemctl restart sshd
```
Here is a detailed explanation what is happening when a SSH request is made:
1. The client adds their SSH public key to Gitea using the webpage.
2. Gitea in the container will add an entry for this key to its database.
3. The client then makes an SSH request to the host SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
4. The client will attempt to authenticate with the server, passing one or more public keys in turn to the host.
5. For each key the client provides, the host SSH server will checks its configuration for an `AuthorizedKeysCommand`.
6. The host runs the above `AuthorizedKeysCommand`, which will SSH in to the docker and then run the `gitea keys` command.
7. Gitea on the docker will look in it's database to see if the public key matches and will return an entry like that of an `authorized_keys` command.
8. This entry has the public key, but also has a `command=` option which matches the location of the Gitea binary on the container.
9. The host SSH server creates a user session for the `git` user, and using the shell for the host `git` user runs the `command=`.
10. The shell of the host `git` user is now our `git-shell` which uses SSH to open a shell for the `git` user on the container.
11. The container shell now runs the `command=` option meaning that the container `gitea serv` is run, taking over control of the rest of the SSH session and managing gitea authentication & authorization of the git commands.
**Notes**
SSH container passthrough using `AuthorizedKeysCommand` will work only if
- `opensshd` is running on the container
If you try to login as the `git` user on the host in future you will `ssh` directly to the docker.
Never add the `Gitea Host Key` as a SSH key to a user on the Gitea interface.
SSHing shims could be created similarly to above.

48
versioned_docs/version-1.23/installation/with-docker-rootless.md
View File

@@ -315,51 +315,3 @@ services:
```
To set required TOKEN and SECRET values, consider using Gitea's built-in [generate utility functions](../administration/command-line.md#generate).
# SSH Container Passthrough
Since SSH is running inside the container, SSH needs to be passed through from the host to the container if SSH support is desired. One option would be to run the container SSH on a non-standard port (or moving the host port to a non-standard port). Another option which might be more straightforward is to forward SSH commands from the host to the container. This setup is explained in the following.
This guide assumes that you have created a user on the host called `git` with permission to run `docker exec`, and that the Gitea container is called `gitea`. You will need to modify that user's shell to forward the commands to the `sh` executable inside the container, using `docker exec`.
First, create the file `/usr/local/bin/gitea-shell` on the host, with the following contents:
```bash
#!/bin/sh
/usr/bin/docker exec -i --env SSH_ORIGINAL_COMMAND="$SSH_ORIGINAL_COMMAND" gitea sh "$@"
```
Note that `gitea` in the docker command above is the name of the container. If you named yours differently, don't forget to change that.
You should also make sure that you’ve set the permissions of the shell wrapper correctly:
```bash
sudo chmod +x /usr/local/bin/gitea-shell
```
Once the wrapper is in place, you can make it the shell for the `git` user:
```bash
sudo usermod -s /usr/local/bin/gitea-shell git
```
Now that all the SSH commands are forwarded to the container, you need to set up the SSH authentication on the host. This is done by leveraging the [SSH AuthorizedKeysCommand](../administration/command-line.md#keys) to match the keys against those accepted by Gitea. Add the following block to `/etc/ssh/sshd_config`, on the host:
```bash
Match User git
AuthorizedKeysCommandUser git
AuthorizedKeysCommand /usr/bin/docker exec -i gitea /usr/local/bin/gitea keys -c /etc/gitea/app.ini -e git -u %u -t %t -k %k
```
(From 1.16.0 you will not need to set the `-c /etc/gitea/app.ini` option.)
All that is left to do is restart the SSH server:
```bash
sudo systemctl restart sshd
```
**Notes**
This isn't actually using the docker SSH - it is simply using the commands around it.
You could theoretically not run the internal SSH server.

314
versioned_docs/version-1.23/installation/with-docker.md
View File

@@ -329,320 +329,6 @@ services:
- GITEA__security__INTERNAL_TOKEN=[value returned by generate secret INTERNAL_TOKEN]
```
## SSH Container Passthrough
Since SSH is running inside the container, SSH needs to be passed through from the host to the container if SSH support is desired. One option would be to run the container SSH on a non-standard port (or moving the host port to a non-standard port). Another option which might be more straightforward is for Gitea users to ssh to a Gitea user on the host which will then relay those connections to the docker. Alternatively, if the host machine has more than one IP address, the host can listen on one and Gitea on another.
### Understanding SSH access to Gitea (without passthrough)
To understand what needs to happen, you first need to understand what happens without passthrough. So we will try to explain this:
1. The client adds their SSH public key to Gitea using the webpage.
2. Gitea will add an entry for this key to the `.ssh/authorized_keys` file of its running user, `git`.
3. This entry has the public key, but also has a `command=` option. It is this command that Gitea uses to match this key to the client user and manages authentication.
4. The client then makes an SSH request to the SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
5. The client will attempt to authenticate with the server, passing one or more public keys one at a time to the server.
6. For each key the client provides, the SSH server will first check its configuration for an `AuthorizedKeysCommand` to see if the public key matches, and then the `git` user's `authorized_keys` file.
7. The first entry that matches will be selected, and assuming this is a Gitea entry, the `command=` will now be executed.
8. The SSH server creates a user session for the `git` user, and using the shell for the `git` user runs the `command=`
9. This runs `gitea serv` which takes over control of the rest of the SSH session and manages gitea authentication & authorization of the git commands.
Now, for the SSH passthrough to work, we need the host SSH to match the public keys and then run the `gitea serv` on the docker. There are multiple ways of doing this. However, all of these require some information about the docker being passed to the host.
### SSHing Shim (with authorized_keys)
In this option, the idea is that the host simply uses the `authorized_keys` that gitea creates but at step 9 the `gitea` command that the host runs is a shim that actually runs ssh to go into the docker and then run the real docker `gitea` itself.
- To make the forwarding work, the SSH port of the container (22) needs to be mapped to the host port 2222 in `docker-compose.yml` . Since this port does not need to be exposed to the outside world, it can be mapped to the `localhost` of the host machine:
```yaml
ports:
# [...]
- "127.0.0.1:2222:22"
```
- Next on the host create the `git` user which shares the same `UID`/ `GID` as the container values `USER_UID`/ `USER_GID`. These values can be set as environment variables in the `docker-compose.yml`:
```yaml
environment:
- USER_UID=1000
- USER_GID=1000
```
- Mount `/home/git/.ssh` of the host into the container. This ensures that the `authorized_keys` file is shared between the host `git` user and the container `git` user otherwise the SSH authentication cannot work inside the container.
```yaml
volumes:
- /home/git/.ssh/:/data/git/.ssh
```
- Now a SSH key pair needs to be created on the host. This key pair will be used to authenticate the `git` user on the host to the container. As an administrative user on the host run: (by administrative user we mean a user that can sudo to root)
```bash
sudo -u git ssh-keygen -t rsa -b 4096 -C "Gitea Host Key"
```
- Please note depending on the local version of ssh you may want to consider using `-t ecdsa` here.
- `/home/git/.ssh/authorized_keys` on the host now needs to be modified. It needs to act in the same way as `authorized_keys` within the Gitea container. Therefore add the public key of the key you created above ("Gitea Host Key") to `/home/git/.ssh/authorized_keys`. As an administrative user on the host run:
```bash
sudo -u git cat /home/git/.ssh/id_rsa.pub | sudo -u git tee -a /home/git/.ssh/authorized_keys
sudo -u git chmod 600 /home/git/.ssh/authorized_keys
```
Important: The pubkey from the `git` user needs to be added "as is" while all other pubkeys added via the Gitea web interface will be prefixed with `command="/usr [...]`.
`/home/git/.ssh/authorized_keys` should then look somewhat like
```bash
# SSH pubkey from git user
ssh-rsa <Gitea Host Key>
# other keys from users
command="/usr/local/bin/gitea --config=/data/gitea/conf/app.ini serv key-1",no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty <user pubkey>
```
- The next step is to create the fake host `gitea` command that will forward commands from the host to the container. The name of this file depends on your version of Gitea:
- For Gitea v1.16.0+. As an administrative user on the host run:
```bash
cat <<"EOF" | sudo tee /usr/local/bin/gitea
#!/bin/sh
ssh -p 2222 -o StrictHostKeyChecking=no git@127.0.0.1 "SSH_ORIGINAL_COMMAND=\"$SSH_ORIGINAL_COMMAND\" $0 $@"
EOF
sudo chmod +x /usr/local/bin/gitea
```
Here is a detailed explanation what is happening when a SSH request is made:
1. The client adds their SSH public key to Gitea using the webpage.
2. Gitea in the container will add an entry for this key to the `.ssh/authorized_keys` file of its running user, `git`.
- However, because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key has been added to the host `git` user's `authorized_keys` file too.
3. This entry has the public key, but also has a `command=` option.
- This command matches the location of the Gitea binary on the container, but also the location of the shim on the host.
4. The client then makes an SSH request to the host SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
5. The client will attempt to authenticate with the server, passing one or more public keys in turn to the host.
6. For each key the client provides, the host SSH server will first check its configuration for an `AuthorizedKeysCommand` to see if the public key matches, and then the host `git` user's `authorized_keys` file.
- Because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key they added to the Gitea web will be found
7. The first entry that matches will be selected, and assuming this is a Gitea entry, the `command=` will now be executed.
8. The host SSH server creates a user session for the `git` user, and using the shell for the host `git` user runs the `command=`
9. This means that the host runs the host `/usr/local/bin/gitea` shim that opens an SSH from the host to container passing the rest of the command arguments directly to `/usr/local/bin/gitea` on the container.
10. Meaning that the container `gitea serv` is run, taking over control of the rest of the SSH session and managing gitea authentication & authorization of the git commands.
**Notes**
SSH container passthrough using `authorized_keys` will work only if
- `opensshd` is used in the container
- if `AuthorizedKeysCommand` is _not used_ in combination with `SSH_CREATE_AUTHORIZED_KEYS_FILE=false` to disable authorized files key generation
- `LOCAL_ROOT_URL` is not changed (depending on the changes)
If you try to run `gitea` on the host, you will attempt to ssh to the container and thence run the `gitea` command there.
Never add the `Gitea Host Key` as a SSH key to a user on the Gitea interface.
### SSHing Shell (with authorized_keys)
In this option, the idea is that the host simply uses the `authorized_keys` that gitea creates but at step 8 above we change the shell that the host runs to ssh directly into the docker and then run the shell there. This means that the `gitea` that is then run is the real docker `gitea`.
- In this case we setup as per SSHing Shim except instead of creating `/usr/local/bin/gitea`
we create a new shell for the git user. As an administrative user on the host run:
```bash
cat <<"EOF" | sudo tee /home/git/ssh-shell
#!/bin/sh
shift
ssh -p 2222 -o StrictHostKeyChecking=no git@127.0.0.1 "SSH_ORIGINAL_COMMAND=\"$SSH_ORIGINAL_COMMAND\" $@"
EOF
sudo chmod +x /home/git/ssh-shell
sudo usermod -s /home/git/ssh-shell git
```
Be careful here - if you try to login as the git user in future you will ssh directly to the docker.
Here is a detailed explanation what is happening when a SSH request is made:
1. The client adds their SSH public key to Gitea using the webpage.
2. Gitea in the container will add an entry for this key to the `.ssh/authorized_keys` file of its running user, `git`.
- However, because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key has been added to the host `git` user's `authorized_keys` file too.
3. This entry has the public key, but also has a `command=` option.
- This command matches the location of the Gitea binary on the container.
4. The client then makes an SSH request to the host SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
5. The client will attempt to authenticate with the server, passing one or more public keys in turn to the host.
6. For each key the client provides, the host SSH server will first check its configuration for an `AuthorizedKeysCommand` to see if the public key matches, and then the host `git` user's `authorized_keys` file.
- Because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key they added to the Gitea web will be found
7. The first entry that matches will be selected, and assuming this is a Gitea entry, the `command=` will now be executed.
8. The host SSH server creates a user session for the `git` user, and using the shell for the host `git` user runs the `command=`
9. The shell of the host `git` user is now our `ssh-shell` which opens an SSH connection from the host to container, (which opens a shell on the container for the container `git`).
10. The container shell now runs the `command=` option meaning that the container `gitea serv` is run, taking over control of the rest of the SSH session and managing gitea authentication & authorization of the git commands.
**Notes**
SSH container passthrough using `authorized_keys` will work only if
- `opensshd` is used in the container
- if `AuthorizedKeysCommand` is _not used_ in combination with `SSH_CREATE_AUTHORIZED_KEYS_FILE=false` to disable authorized files key generation
- `LOCAL_ROOT_URL` is not changed (depending on the changes)
If you try to login as the `git` user on the host in future you will ssh directly to the docker.
Never add the `Gitea Host Key` as a SSH key to a user on the Gitea interface.
### Docker Shell (with authorized_keys)
Similar to the above ssh shell technique we can use a shell which simply uses `docker exec`. As an administrative user on the host run:
```bash
cat <<"EOF" | sudo tee /home/git/docker-shell
#!/bin/sh
/usr/bin/docker exec -i -u git --env SSH_ORIGINAL_COMMAND="$SSH_ORIGINAL_COMMAND" gitea sh "$@"
EOF
sudo chmod +x /home/git/docker-shell
sudo usermod -s /home/git/docker-shell git
```
Here is a detailed explanation what is happening when a SSH request is made:
1. The client adds their SSH public key to Gitea using the webpage.
2. Gitea in the container will add an entry for this key to the `.ssh/authorized_keys` file of its running user, `git`.
- However, because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key has been added to the host `git` user's `authorized_keys` file too.
3. This entry has the public key, but also has a `command=` option.
- This command matches the location of the Gitea binary on the container.
4. The client then makes an SSH request to the host SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
5. The client will attempt to authenticate with the server, passing one or more public keys in turn to the host.
6. For each key the client provides, the host SSH server will first check its configuration for an `AuthorizedKeysCommand` to see if the public key matches, and then the host `git` user's `authorized_keys` file.
- Because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key they added to the Gitea web will be found
7. The first entry that matches will be selected, and assuming this is a Gitea entry, the `command=` will now be executed.
8. The host SSH server creates a user session for the `git` user, and using the shell for the host `git` user runs the `command=`
9. The shell of the host `git` user is now our `docker-shell` which uses `docker exec` to open a shell for the `git` user on the container.
10. The container shell now runs the `command=` option meaning that the container `gitea serv` is run, taking over control of the rest of the SSH session and managing gitea authentication & authorization of the git commands.
Note that `gitea` in the docker command above is the name of the container. If you named yours differently, don't forget to change that. The host `git` user also has to have
permission to run `docker exec`.
**Notes**
Docker shell passthrough using `authorized_keys` will work only if
- `opensshd` is used in the container
- if `AuthorizedKeysCommand` is _not used_ in combination with `SSH_CREATE_AUTHORIZED_KEYS_FILE=false` to disable authorized files key generation
- `LOCAL_ROOT_URL` is not changed (depending on the changes)
If you try to login as the `git` user on the host in future you will `docker exec` directly to the docker.
A Docker execing shim could be created similarly to above.
### Docker Shell with AuthorizedKeysCommand
The AuthorizedKeysCommand route provides another option that does not require many changes to the compose file or the `authorized_keys` - but does require changes to the host `/etc/sshd_config`.
In this option, the idea is that the host SSH uses an `AuthorizedKeysCommand` instead of relying on sharing the `authorized_keys` file that gitea creates. We continue to use a special shell at step 8 above to exec into the docker and then run the shell there. This means that the `gitea` that is then run is the real docker `gitea`.
- On the host create a `git` user with permission to run `docker exec`.
- We will again assume that the Gitea container is called `gitea`.
- Modify the `git` user's shell to forward commands to the `sh` executable inside the container using `docker exec`. As an administrative user on the host run:
```bash
cat <<"EOF" | sudo tee /home/git/docker-shell
#!/bin/sh
/usr/bin/docker exec -i -u git --env SSH_ORIGINAL_COMMAND="$SSH_ORIGINAL_COMMAND" gitea sh "$@"
EOF
sudo chmod +x /home/git/docker-shell
sudo usermod -s /home/git/docker-shell git
```
Now all attempts to login as the `git` user on the host will be forwarded to the docker - including the `SSH_ORIGINAL_COMMAND`. We now need to set-up SSH authentication on the host.
We will do this by leveraging the [SSH AuthorizedKeysCommand](../administration/command-line.md#keys) to match the keys against those accepted by Gitea.
Add the following block to `/etc/ssh/sshd_config`, on the host:
```bash
Match User git
AuthorizedKeysCommandUser git
AuthorizedKeysCommand /usr/bin/docker exec -i -u git gitea /usr/local/bin/gitea keys -c /data/gitea/conf/app.ini -e git -u %u -t %t -k %k
```
(From 1.16.0 you will not need to set the `-c /data/gitea/conf/app.ini` option.)
Finally restart the SSH server. As an administrative user on the host run:
```bash
sudo systemctl restart sshd
```
Here is a detailed explanation what is happening when a SSH request is made:
1. The client adds their SSH public key to Gitea using the webpage.
2. Gitea in the container will add an entry for this key to its database.
3. The client then makes an SSH request to the host SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
4. The client will attempt to authenticate with the server, passing one or more public keys in turn to the host.
5. For each key the client provides, the host SSH server will checks its configuration for an `AuthorizedKeysCommand`.
6. The host runs the above `AuthorizedKeysCommand`, which execs in to the docker and then runs the `gitea keys` command.
7. Gitea on the docker will look in it's database to see if the public key matches and will return an entry like that of an `authorized_keys` command.
8. This entry has the public key, but also has a `command=` option which matches the location of the Gitea binary on the container.
9. The host SSH server creates a user session for the `git` user, and using the shell for the host `git` user runs the `command=`.
10. The shell of the host `git` user is now our `docker-shell` which uses `docker exec` to open a shell for the `git` user on the container.
11. The container shell now runs the `command=` option meaning that the container `gitea serv` is run, taking over control of the rest of the SSH session and managing gitea authentication & authorization of the git commands.
**Notes**
Docker shell passthrough using `AuthorizedKeysCommand` will work only if
- The host `git` user is allowed to run the `docker exec` command.
If you try to login as the `git` user on the host in future you will `docker exec` directly to the docker.
A Docker execing shim could be created similarly to above.
### SSH Shell with AuthorizedKeysCommand
Create a key for the host `git` user as above, add it to the docker `/data/git/.ssh/authorized_keys` then finally create and set the `ssh-shell` as above.
Add the following block to `/etc/ssh/sshd_config`, on the host:
```bash
Match User git
AuthorizedKeysCommandUser git
AuthorizedKeysCommand /usr/bin/ssh -p 2222 -o StrictHostKeyChecking=no git@127.0.0.1 /usr/local/bin/gitea keys -c /data/gitea/conf/app.ini -e git -u %u -t %t -k %k
```
(From 1.16.0 you will not need to set the `-c /data/gitea/conf/app.ini` option.)
Finally restart the SSH server. As an administrative user on the host run:
```bash
sudo systemctl restart sshd
```
Here is a detailed explanation what is happening when a SSH request is made:
1. The client adds their SSH public key to Gitea using the webpage.
2. Gitea in the container will add an entry for this key to its database.
3. The client then makes an SSH request to the host SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
4. The client will attempt to authenticate with the server, passing one or more public keys in turn to the host.
5. For each key the client provides, the host SSH server will checks its configuration for an `AuthorizedKeysCommand`.
6. The host runs the above `AuthorizedKeysCommand`, which will SSH in to the docker and then run the `gitea keys` command.
7. Gitea on the docker will look in it's database to see if the public key matches and will return an entry like that of an `authorized_keys` command.
8. This entry has the public key, but also has a `command=` option which matches the location of the Gitea binary on the container.
9. The host SSH server creates a user session for the `git` user, and using the shell for the host `git` user runs the `command=`.
10. The shell of the host `git` user is now our `git-shell` which uses SSH to open a shell for the `git` user on the container.
11. The container shell now runs the `command=` option meaning that the container `gitea serv` is run, taking over control of the rest of the SSH session and managing gitea authentication & authorization of the git commands.
**Notes**
SSH container passthrough using `AuthorizedKeysCommand` will work only if
- `opensshd` is running on the container
If you try to login as the `git` user on the host in future you will `ssh` directly to the docker.
Never add the `Gitea Host Key` as a SSH key to a user on the Gitea interface.
SSHing shims could be created similarly to above.
### SSH with multiple IP addresses
This assumes that the host machine has more than one reachable IP address: `192.168.1.1` (host) `192.168.1.2` (gitea)

48
versioned_docs/version-1.24/installation/with-docker-rootless.md
View File

@@ -315,51 +315,3 @@ services:
```
To set required TOKEN and SECRET values, consider using Gitea's built-in [generate utility functions](../administration/command-line.md#generate).
# SSH Container Passthrough
Since SSH is running inside the container, SSH needs to be passed through from the host to the container if SSH support is desired. One option would be to run the container SSH on a non-standard port (or moving the host port to a non-standard port). Another option which might be more straightforward is to forward SSH commands from the host to the container. This setup is explained in the following.
This guide assumes that you have created a user on the host called `git` with permission to run `docker exec`, and that the Gitea container is called `gitea`. You will need to modify that user's shell to forward the commands to the `sh` executable inside the container, using `docker exec`.
First, create the file `/usr/local/bin/gitea-shell` on the host, with the following contents:
```bash
#!/bin/sh
/usr/bin/docker exec -i --env SSH_ORIGINAL_COMMAND="$SSH_ORIGINAL_COMMAND" gitea sh "$@"
```
Note that `gitea` in the docker command above is the name of the container. If you named yours differently, don't forget to change that.
You should also make sure that you’ve set the permissions of the shell wrapper correctly:
```bash
sudo chmod +x /usr/local/bin/gitea-shell
```
Once the wrapper is in place, you can make it the shell for the `git` user:
```bash
sudo usermod -s /usr/local/bin/gitea-shell git
```
Now that all the SSH commands are forwarded to the container, you need to set up the SSH authentication on the host. This is done by leveraging the [SSH AuthorizedKeysCommand](../administration/command-line.md#keys) to match the keys against those accepted by Gitea. Add the following block to `/etc/ssh/sshd_config`, on the host:
```bash
Match User git
AuthorizedKeysCommandUser git
AuthorizedKeysCommand /usr/bin/docker exec -i gitea /usr/local/bin/gitea keys -c /etc/gitea/app.ini -e git -u %u -t %t -k %k
```
(From 1.16.0 you will not need to set the `-c /etc/gitea/app.ini` option.)
All that is left to do is restart the SSH server:
```bash
sudo systemctl restart sshd
```
**Notes**
This isn't actually using the docker SSH - it is simply using the commands around it.
You could theoretically not run the internal SSH server.

314
versioned_docs/version-1.24/installation/with-docker.md
View File

@@ -314,320 +314,6 @@ services:
- GITEA__security__INTERNAL_TOKEN=[value returned by generate secret INTERNAL_TOKEN]
```
## SSH Container Passthrough
Since SSH is running inside the container, SSH needs to be passed through from the host to the container if SSH support is desired. One option would be to run the container SSH on a non-standard port (or moving the host port to a non-standard port). Another option which might be more straightforward is for Gitea users to ssh to a Gitea user on the host which will then relay those connections to the docker. Alternatively, if the host machine has more than one IP address, the host can listen on one and Gitea on another.
### Understanding SSH access to Gitea (without passthrough)
To understand what needs to happen, you first need to understand what happens without passthrough. So we will try to explain this:
1. The client adds their SSH public key to Gitea using the webpage.
2. Gitea will add an entry for this key to the `.ssh/authorized_keys` file of its running user, `git`.
3. This entry has the public key, but also has a `command=` option. It is this command that Gitea uses to match this key to the client user and manages authentication.
4. The client then makes an SSH request to the SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
5. The client will attempt to authenticate with the server, passing one or more public keys one at a time to the server.
6. For each key the client provides, the SSH server will first check its configuration for an `AuthorizedKeysCommand` to see if the public key matches, and then the `git` user's `authorized_keys` file.
7. The first entry that matches will be selected, and assuming this is a Gitea entry, the `command=` will now be executed.
8. The SSH server creates a user session for the `git` user, and using the shell for the `git` user runs the `command=`
9. This runs `gitea serv` which takes over control of the rest of the SSH session and manages gitea authentication & authorization of the git commands.
Now, for the SSH passthrough to work, we need the host SSH to match the public keys and then run the `gitea serv` on the docker. There are multiple ways of doing this. However, all of these require some information about the docker being passed to the host.
### SSHing Shim (with authorized_keys)
In this option, the idea is that the host simply uses the `authorized_keys` that gitea creates but at step 9 the `gitea` command that the host runs is a shim that actually runs ssh to go into the docker and then run the real docker `gitea` itself.
- To make the forwarding work, the SSH port of the container (22) needs to be mapped to the host port 2222 in `docker-compose.yml` . Since this port does not need to be exposed to the outside world, it can be mapped to the `localhost` of the host machine:
```yaml
ports:
# [...]
- "127.0.0.1:2222:22"
```
- Next on the host create the `git` user which shares the same `UID`/ `GID` as the container values `USER_UID`/ `USER_GID`. These values can be set as environment variables in the `docker-compose.yml`:
```yaml
environment:
- USER_UID=1000
- USER_GID=1000
```
- Mount `/home/git/.ssh` of the host into the container. This ensures that the `authorized_keys` file is shared between the host `git` user and the container `git` user otherwise the SSH authentication cannot work inside the container.
```yaml
volumes:
- /home/git/.ssh/:/data/git/.ssh
```
- Now a SSH key pair needs to be created on the host. This key pair will be used to authenticate the `git` user on the host to the container. As an administrative user on the host run: (by administrative user we mean a user that can sudo to root)
```bash
sudo -u git ssh-keygen -t rsa -b 4096 -C "Gitea Host Key"
```
- Please note depending on the local version of ssh you may want to consider using `-t ecdsa` here.
- `/home/git/.ssh/authorized_keys` on the host now needs to be modified. It needs to act in the same way as `authorized_keys` within the Gitea container. Therefore add the public key of the key you created above ("Gitea Host Key") to `/home/git/.ssh/authorized_keys`. As an administrative user on the host run:
```bash
sudo -u git cat /home/git/.ssh/id_rsa.pub | sudo -u git tee -a /home/git/.ssh/authorized_keys
sudo -u git chmod 600 /home/git/.ssh/authorized_keys
```
Important: The pubkey from the `git` user needs to be added "as is" while all other pubkeys added via the Gitea web interface will be prefixed with `command="/usr [...]`.
`/home/git/.ssh/authorized_keys` should then look somewhat like
```bash
# SSH pubkey from git user
ssh-rsa <Gitea Host Key>
# other keys from users
command="/usr/local/bin/gitea --config=/data/gitea/conf/app.ini serv key-1",no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty <user pubkey>
```
- The next step is to create the fake host `gitea` command that will forward commands from the host to the container. The name of this file depends on your version of Gitea:
- For Gitea v1.16.0+. As an administrative user on the host run:
```bash
cat <<"EOF" | sudo tee /usr/local/bin/gitea
#!/bin/sh
ssh -p 2222 -o StrictHostKeyChecking=no git@127.0.0.1 "SSH_ORIGINAL_COMMAND=\"$SSH_ORIGINAL_COMMAND\" $0 $@"
EOF
sudo chmod +x /usr/local/bin/gitea
```
Here is a detailed explanation what is happening when a SSH request is made:
1. The client adds their SSH public key to Gitea using the webpage.
2. Gitea in the container will add an entry for this key to the `.ssh/authorized_keys` file of its running user, `git`.
- However, because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key has been added to the host `git` user's `authorized_keys` file too.
3. This entry has the public key, but also has a `command=` option.
- This command matches the location of the Gitea binary on the container, but also the location of the shim on the host.
4. The client then makes an SSH request to the host SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
5. The client will attempt to authenticate with the server, passing one or more public keys in turn to the host.
6. For each key the client provides, the host SSH server will first check its configuration for an `AuthorizedKeysCommand` to see if the public key matches, and then the host `git` user's `authorized_keys` file.
- Because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key they added to the Gitea web will be found
7. The first entry that matches will be selected, and assuming this is a Gitea entry, the `command=` will now be executed.
8. The host SSH server creates a user session for the `git` user, and using the shell for the host `git` user runs the `command=`
9. This means that the host runs the host `/usr/local/bin/gitea` shim that opens an SSH from the host to container passing the rest of the command arguments directly to `/usr/local/bin/gitea` on the container.
10. Meaning that the container `gitea serv` is run, taking over control of the rest of the SSH session and managing gitea authentication & authorization of the git commands.
**Notes**
SSH container passthrough using `authorized_keys` will work only if
- `opensshd` is used in the container
- if `AuthorizedKeysCommand` is _not used_ in combination with `SSH_CREATE_AUTHORIZED_KEYS_FILE=false` to disable authorized files key generation
- `LOCAL_ROOT_URL` is not changed (depending on the changes)
If you try to run `gitea` on the host, you will attempt to ssh to the container and thence run the `gitea` command there.
Never add the `Gitea Host Key` as a SSH key to a user on the Gitea interface.
### SSHing Shell (with authorized_keys)
In this option, the idea is that the host simply uses the `authorized_keys` that gitea creates but at step 8 above we change the shell that the host runs to ssh directly into the docker and then run the shell there. This means that the `gitea` that is then run is the real docker `gitea`.
- In this case we setup as per SSHing Shim except instead of creating `/usr/local/bin/gitea`
we create a new shell for the git user. As an administrative user on the host run:
```bash
cat <<"EOF" | sudo tee /home/git/ssh-shell
#!/bin/sh
shift
ssh -p 2222 -o StrictHostKeyChecking=no git@127.0.0.1 "SSH_ORIGINAL_COMMAND=\"$SSH_ORIGINAL_COMMAND\" $@"
EOF
sudo chmod +x /home/git/ssh-shell
sudo usermod -s /home/git/ssh-shell git
```
Be careful here - if you try to login as the git user in future you will ssh directly to the docker.
Here is a detailed explanation what is happening when a SSH request is made:
1. The client adds their SSH public key to Gitea using the webpage.
2. Gitea in the container will add an entry for this key to the `.ssh/authorized_keys` file of its running user, `git`.
- However, because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key has been added to the host `git` user's `authorized_keys` file too.
3. This entry has the public key, but also has a `command=` option.
- This command matches the location of the Gitea binary on the container.
4. The client then makes an SSH request to the host SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
5. The client will attempt to authenticate with the server, passing one or more public keys in turn to the host.
6. For each key the client provides, the host SSH server will first check its configuration for an `AuthorizedKeysCommand` to see if the public key matches, and then the host `git` user's `authorized_keys` file.
- Because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key they added to the Gitea web will be found
7. The first entry that matches will be selected, and assuming this is a Gitea entry, the `command=` will now be executed.
8. The host SSH server creates a user session for the `git` user, and using the shell for the host `git` user runs the `command=`
9. The shell of the host `git` user is now our `ssh-shell` which opens an SSH connection from the host to container, (which opens a shell on the container for the container `git`).
10. The container shell now runs the `command=` option meaning that the container `gitea serv` is run, taking over control of the rest of the SSH session and managing gitea authentication & authorization of the git commands.
**Notes**
SSH container passthrough using `authorized_keys` will work only if
- `opensshd` is used in the container
- if `AuthorizedKeysCommand` is _not used_ in combination with `SSH_CREATE_AUTHORIZED_KEYS_FILE=false` to disable authorized files key generation
- `LOCAL_ROOT_URL` is not changed (depending on the changes)
If you try to login as the `git` user on the host in future you will ssh directly to the docker.
Never add the `Gitea Host Key` as a SSH key to a user on the Gitea interface.
### Docker Shell (with authorized_keys)
Similar to the above ssh shell technique we can use a shell which simply uses `docker exec`. As an administrative user on the host run:
```bash
cat <<"EOF" | sudo tee /home/git/docker-shell
#!/bin/sh
/usr/bin/docker exec -i -u git --env SSH_ORIGINAL_COMMAND="$SSH_ORIGINAL_COMMAND" gitea sh "$@"
EOF
sudo chmod +x /home/git/docker-shell
sudo usermod -s /home/git/docker-shell git
```
Here is a detailed explanation what is happening when a SSH request is made:
1. The client adds their SSH public key to Gitea using the webpage.
2. Gitea in the container will add an entry for this key to the `.ssh/authorized_keys` file of its running user, `git`.
- However, because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key has been added to the host `git` user's `authorized_keys` file too.
3. This entry has the public key, but also has a `command=` option.
- This command matches the location of the Gitea binary on the container.
4. The client then makes an SSH request to the host SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
5. The client will attempt to authenticate with the server, passing one or more public keys in turn to the host.
6. For each key the client provides, the host SSH server will first check its configuration for an `AuthorizedKeysCommand` to see if the public key matches, and then the host `git` user's `authorized_keys` file.
- Because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key they added to the Gitea web will be found
7. The first entry that matches will be selected, and assuming this is a Gitea entry, the `command=` will now be executed.
8. The host SSH server creates a user session for the `git` user, and using the shell for the host `git` user runs the `command=`
9. The shell of the host `git` user is now our `docker-shell` which uses `docker exec` to open a shell for the `git` user on the container.
10. The container shell now runs the `command=` option meaning that the container `gitea serv` is run, taking over control of the rest of the SSH session and managing gitea authentication & authorization of the git commands.
Note that `gitea` in the docker command above is the name of the container. If you named yours differently, don't forget to change that. The host `git` user also has to have
permission to run `docker exec`.
**Notes**
Docker shell passthrough using `authorized_keys` will work only if
- `opensshd` is used in the container
- if `AuthorizedKeysCommand` is _not used_ in combination with `SSH_CREATE_AUTHORIZED_KEYS_FILE=false` to disable authorized files key generation
- `LOCAL_ROOT_URL` is not changed (depending on the changes)
If you try to login as the `git` user on the host in future you will `docker exec` directly to the docker.
A Docker execing shim could be created similarly to above.
### Docker Shell with AuthorizedKeysCommand
The AuthorizedKeysCommand route provides another option that does not require many changes to the compose file or the `authorized_keys` - but does require changes to the host `/etc/sshd_config`.
In this option, the idea is that the host SSH uses an `AuthorizedKeysCommand` instead of relying on sharing the `authorized_keys` file that gitea creates. We continue to use a special shell at step 8 above to exec into the docker and then run the shell there. This means that the `gitea` that is then run is the real docker `gitea`.
- On the host create a `git` user with permission to run `docker exec`.
- We will again assume that the Gitea container is called `gitea`.
- Modify the `git` user's shell to forward commands to the `sh` executable inside the container using `docker exec`. As an administrative user on the host run:
```bash
cat <<"EOF" | sudo tee /home/git/docker-shell
#!/bin/sh
/usr/bin/docker exec -i -u git --env SSH_ORIGINAL_COMMAND="$SSH_ORIGINAL_COMMAND" gitea sh "$@"
EOF
sudo chmod +x /home/git/docker-shell
sudo usermod -s /home/git/docker-shell git
```
Now all attempts to login as the `git` user on the host will be forwarded to the docker - including the `SSH_ORIGINAL_COMMAND`. We now need to set-up SSH authentication on the host.
We will do this by leveraging the [SSH AuthorizedKeysCommand](../administration/command-line.md#keys) to match the keys against those accepted by Gitea.
Add the following block to `/etc/ssh/sshd_config`, on the host:
```bash
Match User git
AuthorizedKeysCommandUser git
AuthorizedKeysCommand /usr/bin/docker exec -i -u git gitea /usr/local/bin/gitea keys -c /data/gitea/conf/app.ini -e git -u %u -t %t -k %k
```
(From 1.16.0 you will not need to set the `-c /data/gitea/conf/app.ini` option.)
Finally restart the SSH server. As an administrative user on the host run:
```bash
sudo systemctl restart sshd
```
Here is a detailed explanation what is happening when a SSH request is made:
1. The client adds their SSH public key to Gitea using the webpage.
2. Gitea in the container will add an entry for this key to its database.
3. The client then makes an SSH request to the host SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
4. The client will attempt to authenticate with the server, passing one or more public keys in turn to the host.
5. For each key the client provides, the host SSH server will checks its configuration for an `AuthorizedKeysCommand`.
6. The host runs the above `AuthorizedKeysCommand`, which execs in to the docker and then runs the `gitea keys` command.
7. Gitea on the docker will look in it's database to see if the public key matches and will return an entry like that of an `authorized_keys` command.
8. This entry has the public key, but also has a `command=` option which matches the location of the Gitea binary on the container.
9. The host SSH server creates a user session for the `git` user, and using the shell for the host `git` user runs the `command=`.
10. The shell of the host `git` user is now our `docker-shell` which uses `docker exec` to open a shell for the `git` user on the container.
11. The container shell now runs the `command=` option meaning that the container `gitea serv` is run, taking over control of the rest of the SSH session and managing gitea authentication & authorization of the git commands.
**Notes**
Docker shell passthrough using `AuthorizedKeysCommand` will work only if
- The host `git` user is allowed to run the `docker exec` command.
If you try to login as the `git` user on the host in future you will `docker exec` directly to the docker.
A Docker execing shim could be created similarly to above.
### SSH Shell with AuthorizedKeysCommand
Create a key for the host `git` user as above, add it to the docker `/data/git/.ssh/authorized_keys` then finally create and set the `ssh-shell` as above.
Add the following block to `/etc/ssh/sshd_config`, on the host:
```bash
Match User git
AuthorizedKeysCommandUser git
AuthorizedKeysCommand /usr/bin/ssh -p 2222 -o StrictHostKeyChecking=no git@127.0.0.1 /usr/local/bin/gitea keys -c /data/gitea/conf/app.ini -e git -u %u -t %t -k %k
```
(From 1.16.0 you will not need to set the `-c /data/gitea/conf/app.ini` option.)
Finally restart the SSH server. As an administrative user on the host run:
```bash
sudo systemctl restart sshd
```
Here is a detailed explanation what is happening when a SSH request is made:
1. The client adds their SSH public key to Gitea using the webpage.
2. Gitea in the container will add an entry for this key to its database.
3. The client then makes an SSH request to the host SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
4. The client will attempt to authenticate with the server, passing one or more public keys in turn to the host.
5. For each key the client provides, the host SSH server will checks its configuration for an `AuthorizedKeysCommand`.
6. The host runs the above `AuthorizedKeysCommand`, which will SSH in to the docker and then run the `gitea keys` command.
7. Gitea on the docker will look in it's database to see if the public key matches and will return an entry like that of an `authorized_keys` command.
8. This entry has the public key, but also has a `command=` option which matches the location of the Gitea binary on the container.
9. The host SSH server creates a user session for the `git` user, and using the shell for the host `git` user runs the `command=`.
10. The shell of the host `git` user is now our `git-shell` which uses SSH to open a shell for the `git` user on the container.
11. The container shell now runs the `command=` option meaning that the container `gitea serv` is run, taking over control of the rest of the SSH session and managing gitea authentication & authorization of the git commands.
**Notes**
SSH container passthrough using `AuthorizedKeysCommand` will work only if
- `opensshd` is running on the container
If you try to login as the `git` user on the host in future you will `ssh` directly to the docker.
Never add the `Gitea Host Key` as a SSH key to a user on the Gitea interface.
SSHing shims could be created similarly to above.
### SSH with multiple IP addresses
This assumes that the host machine has more than one reachable IP address: `192.168.1.1` (host) `192.168.1.2` (gitea)
On the host machine, configure SSHD in `/etc/ssh/sshd_config` to listen on one IP address `ListenAddress 192.168.1.1`. In the compose file the SSH port forwarding then needs to be changed to `"192.168.1.2:22:22"`. The port forwarding needs to be adjusted similarily for all other forwarded ports to avoid problems with DNS.

1
versioned_docs/version-1.25/administration/mail-templates.md
View File

@@ -257,7 +257,6 @@ the messages. Here's a list of some of them:
| `AppDomain` | - | Any | Gitea's host name |
| `EllipsisString` | string, int | Any | Truncates a string to the specified length; adds ellipsis as needed |
| `SanitizeHTML` | string | Body only | Sanitizes text by removing any dangerous HTML tags from it |
| `SafeHTML` | string | Body only | Takes the input as HTML, can be used for outputing raw HTML content |
These are _functions_, not metadata, so they have to be used:

12
versioned_docs/version-1.25/installation/from-binary.md
View File

@@ -139,15 +139,15 @@ export GITEA_WORK_DIR=/var/lib/gitea/
cp gitea /usr/local/bin/gitea
```
### Adding bash/zsh autocompletion (from 1.19)
### Adding shell autocompletion (from 1.25)
A script to enable bash-completion can be found at [`contrib/autocompletion/bash_autocomplete`](https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/autocompletion/bash_autocomplete). This can be copied to `/usr/share/bash-completion/completions/gitea`
or sourced within your `.bashrc`.
Shell completion can be generated directly from binary with:
```sh
gitea completion <shell>
```
Similarly a script for zsh-completion can be found at [`contrib/autocompletion/zsh_autocomplete`](https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/autocompletion/zsh_autocomplete). This can be copied to `/usr/share/zsh/_gitea` or sourced within your
`.zshrc`.
Supported values for `<shell>` are `bash`, `fish`, `pwsh` and `zsh`. Details on how to load the completion for your shell can be found in the completion command help.
YMMV and these scripts may need further improvement.
## Running Gitea

13
versioned_docs/version-1.25/installation/from-source.md
View File

@@ -178,15 +178,14 @@ LDFLAGS="-linkmode external -extldflags '-static' $LDFLAGS" TAGS="netgo osusergo
This can be combined with `CC`, `GOOS`, and `GOARCH` as above.
### Adding bash/zsh autocompletion (from 1.19)
### Adding shell autocompletion (from 1.25)
A script to enable bash-completion can be found at [`contrib/autocompletion/bash_autocomplete`](https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/autocompletion/bash_autocomplete). This should be altered as appropriate and can be `source` in your `.bashrc`
or copied as `/usr/share/bash-completion/completions/gitea`.
Shell completion can be generated directly from binary with:
```sh
gitea completion <shell>
```
Similarly, a script for zsh-completion can be found at [`contrib/autocompletion/zsh_autocomplete`](https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/autocompletion/zsh_autocomplete). This can be copied to `/usr/share/zsh/_gitea` or sourced within your
`.zshrc`.
YMMV and these scripts may need further improvement.
Supported values for `<shell>` are `bash`, `fish`, `pwsh` and `zsh`. Details on how to load the completion for your shell can be found in the completion command help.
## Compile or cross-compile using Linux with Zig

48
versioned_docs/version-1.25/installation/with-docker-rootless.md
View File

@@ -315,51 +315,3 @@ services:
```
To set required TOKEN and SECRET values, consider using Gitea's built-in [generate utility functions](../administration/command-line.md#generate).
# SSH Container Passthrough
Since SSH is running inside the container, SSH needs to be passed through from the host to the container if SSH support is desired. One option would be to run the container SSH on a non-standard port (or moving the host port to a non-standard port). Another option which might be more straightforward is to forward SSH commands from the host to the container. This setup is explained in the following.
This guide assumes that you have created a user on the host called `git` with permission to run `docker exec`, and that the Gitea container is called `gitea`. You will need to modify that user's shell to forward the commands to the `sh` executable inside the container, using `docker exec`.
First, create the file `/usr/local/bin/gitea-shell` on the host, with the following contents:
```bash
#!/bin/sh
/usr/bin/docker exec -i --env SSH_ORIGINAL_COMMAND="$SSH_ORIGINAL_COMMAND" gitea sh "$@"
```
Note that `gitea` in the docker command above is the name of the container. If you named yours differently, don't forget to change that.
You should also make sure that you’ve set the permissions of the shell wrapper correctly:
```bash
sudo chmod +x /usr/local/bin/gitea-shell
```
Once the wrapper is in place, you can make it the shell for the `git` user:
```bash
sudo usermod -s /usr/local/bin/gitea-shell git
```
Now that all the SSH commands are forwarded to the container, you need to set up the SSH authentication on the host. This is done by leveraging the [SSH AuthorizedKeysCommand](../administration/command-line.md#keys) to match the keys against those accepted by Gitea. Add the following block to `/etc/ssh/sshd_config`, on the host:
```bash
Match User git
AuthorizedKeysCommandUser git
AuthorizedKeysCommand /usr/bin/docker exec -i gitea /usr/local/bin/gitea keys -c /etc/gitea/app.ini -e git -u %u -t %t -k %k
```
(From 1.16.0 you will not need to set the `-c /etc/gitea/app.ini` option.)
All that is left to do is restart the SSH server:
```bash
sudo systemctl restart sshd
```
**Notes**
This isn't actually using the docker SSH - it is simply using the commands around it.
You could theoretically not run the internal SSH server.

316
versioned_docs/version-1.25/installation/with-docker.md
View File

@@ -289,7 +289,7 @@ docker-compose up -d
In addition to the environment variables above, any settings in `app.ini` can be set
or overridden with an environment variable of the form: `GITEA__SECTION_NAME__KEY_NAME`.
These settings are applied each time the docker container starts, and won't be passed into Gitea's sub-processes.
Full information [here](https://github.com/go-gitea/gitea/tree/master/contrib/environment-to-ini).
Full information [here](https://github.com/go-gitea/gitea/blob/0d740a6a7231b254306d0b1513ff27e32646cd5e/contrib/environment-to-ini/README).
These environment variables can be passed to the docker container in `docker-compose.yml`.
The following example will enable an smtp mail server if the required env variables
@@ -331,320 +331,6 @@ services:
- GITEA__security__INTERNAL_TOKEN=[value returned by generate secret INTERNAL_TOKEN]
```
## SSH Container Passthrough
Since SSH is running inside the container, SSH needs to be passed through from the host to the container if SSH support is desired. One option would be to run the container SSH on a non-standard port (or moving the host port to a non-standard port). Another option which might be more straightforward is for Gitea users to ssh to a Gitea user on the host which will then relay those connections to the docker. Alternatively, if the host machine has more than one IP address, the host can listen on one and Gitea on another.
### Understanding SSH access to Gitea (without passthrough)
To understand what needs to happen, you first need to understand what happens without passthrough. So we will try to explain this:
1. The client adds their SSH public key to Gitea using the webpage.
2. Gitea will add an entry for this key to the `.ssh/authorized_keys` file of its running user, `git`.
3. This entry has the public key, but also has a `command=` option. It is this command that Gitea uses to match this key to the client user and manages authentication.
4. The client then makes an SSH request to the SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
5. The client will attempt to authenticate with the server, passing one or more public keys one at a time to the server.
6. For each key the client provides, the SSH server will first check its configuration for an `AuthorizedKeysCommand` to see if the public key matches, and then the `git` user's `authorized_keys` file.
7. The first entry that matches will be selected, and assuming this is a Gitea entry, the `command=` will now be executed.
8. The SSH server creates a user session for the `git` user, and using the shell for the `git` user runs the `command=`
9. This runs `gitea serv` which takes over control of the rest of the SSH session and manages gitea authentication & authorization of the git commands.
Now, for the SSH passthrough to work, we need the host SSH to match the public keys and then run the `gitea serv` on the docker. There are multiple ways of doing this. However, all of these require some information about the docker being passed to the host.
### SSHing Shim (with authorized_keys)
In this option, the idea is that the host simply uses the `authorized_keys` that gitea creates but at step 9 the `gitea` command that the host runs is a shim that actually runs ssh to go into the docker and then run the real docker `gitea` itself.
- To make the forwarding work, the SSH port of the container (22) needs to be mapped to the host port 2222 in `docker-compose.yml` . Since this port does not need to be exposed to the outside world, it can be mapped to the `localhost` of the host machine:
```yaml
ports:
# [...]
- "127.0.0.1:2222:22"
```
- Next on the host create the `git` user which shares the same `UID`/ `GID` as the container values `USER_UID`/ `USER_GID`. These values can be set as environment variables in the `docker-compose.yml`:
```yaml
environment:
- USER_UID=1000
- USER_GID=1000
```
- Mount `/home/git/.ssh` of the host into the container. This ensures that the `authorized_keys` file is shared between the host `git` user and the container `git` user otherwise the SSH authentication cannot work inside the container.
```yaml
volumes:
- /home/git/.ssh/:/data/git/.ssh
```
- Now a SSH key pair needs to be created on the host. This key pair will be used to authenticate the `git` user on the host to the container. As an administrative user on the host run: (by administrative user we mean a user that can sudo to root)
```bash
sudo -u git ssh-keygen -t rsa -b 4096 -C "Gitea Host Key"
```
- Please note depending on the local version of ssh you may want to consider using `-t ecdsa` here.
- `/home/git/.ssh/authorized_keys` on the host now needs to be modified. It needs to act in the same way as `authorized_keys` within the Gitea container. Therefore add the public key of the key you created above ("Gitea Host Key") to `/home/git/.ssh/authorized_keys`. As an administrative user on the host run:
```bash
sudo -u git cat /home/git/.ssh/id_rsa.pub | sudo -u git tee -a /home/git/.ssh/authorized_keys
sudo -u git chmod 600 /home/git/.ssh/authorized_keys
```
Important: The pubkey from the `git` user needs to be added "as is" while all other pubkeys added via the Gitea web interface will be prefixed with `command="/usr [...]`.
`/home/git/.ssh/authorized_keys` should then look somewhat like
```bash
# SSH pubkey from git user
ssh-rsa <Gitea Host Key>
# other keys from users
command="/usr/local/bin/gitea --config=/data/gitea/conf/app.ini serv key-1",no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty <user pubkey>
```
- The next step is to create the fake host `gitea` command that will forward commands from the host to the container. The name of this file depends on your version of Gitea:
- For Gitea v1.16.0+. As an administrative user on the host run:
```bash
cat <<"EOF" | sudo tee /usr/local/bin/gitea
#!/bin/sh
ssh -p 2222 -o StrictHostKeyChecking=no git@127.0.0.1 "SSH_ORIGINAL_COMMAND=\"$SSH_ORIGINAL_COMMAND\" $0 $@"
EOF
sudo chmod +x /usr/local/bin/gitea
```
Here is a detailed explanation what is happening when a SSH request is made:
1. The client adds their SSH public key to Gitea using the webpage.
2. Gitea in the container will add an entry for this key to the `.ssh/authorized_keys` file of its running user, `git`.
- However, because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key has been added to the host `git` user's `authorized_keys` file too.
3. This entry has the public key, but also has a `command=` option.
- This command matches the location of the Gitea binary on the container, but also the location of the shim on the host.
4. The client then makes an SSH request to the host SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
5. The client will attempt to authenticate with the server, passing one or more public keys in turn to the host.
6. For each key the client provides, the host SSH server will first check its configuration for an `AuthorizedKeysCommand` to see if the public key matches, and then the host `git` user's `authorized_keys` file.
- Because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key they added to the Gitea web will be found
7. The first entry that matches will be selected, and assuming this is a Gitea entry, the `command=` will now be executed.
8. The host SSH server creates a user session for the `git` user, and using the shell for the host `git` user runs the `command=`
9. This means that the host runs the host `/usr/local/bin/gitea` shim that opens an SSH from the host to container passing the rest of the command arguments directly to `/usr/local/bin/gitea` on the container.
10. Meaning that the container `gitea serv` is run, taking over control of the rest of the SSH session and managing gitea authentication & authorization of the git commands.
**Notes**
SSH container passthrough using `authorized_keys` will work only if
- `opensshd` is used in the container
- if `AuthorizedKeysCommand` is _not used_ in combination with `SSH_CREATE_AUTHORIZED_KEYS_FILE=false` to disable authorized files key generation
- `LOCAL_ROOT_URL` is not changed (depending on the changes)
If you try to run `gitea` on the host, you will attempt to ssh to the container and thence run the `gitea` command there.
Never add the `Gitea Host Key` as a SSH key to a user on the Gitea interface.
### SSHing Shell (with authorized_keys)
In this option, the idea is that the host simply uses the `authorized_keys` that gitea creates but at step 8 above we change the shell that the host runs to ssh directly into the docker and then run the shell there. This means that the `gitea` that is then run is the real docker `gitea`.
- In this case we setup as per SSHing Shim except instead of creating `/usr/local/bin/gitea`
we create a new shell for the git user. As an administrative user on the host run:
```bash
cat <<"EOF" | sudo tee /home/git/ssh-shell
#!/bin/sh
shift
ssh -p 2222 -o StrictHostKeyChecking=no git@127.0.0.1 "SSH_ORIGINAL_COMMAND=\"$SSH_ORIGINAL_COMMAND\" $@"
EOF
sudo chmod +x /home/git/ssh-shell
sudo usermod -s /home/git/ssh-shell git
```
Be careful here - if you try to login as the git user in future you will ssh directly to the docker.
Here is a detailed explanation what is happening when a SSH request is made:
1. The client adds their SSH public key to Gitea using the webpage.
2. Gitea in the container will add an entry for this key to the `.ssh/authorized_keys` file of its running user, `git`.
- However, because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key has been added to the host `git` user's `authorized_keys` file too.
3. This entry has the public key, but also has a `command=` option.
- This command matches the location of the Gitea binary on the container.
4. The client then makes an SSH request to the host SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
5. The client will attempt to authenticate with the server, passing one or more public keys in turn to the host.
6. For each key the client provides, the host SSH server will first check its configuration for an `AuthorizedKeysCommand` to see if the public key matches, and then the host `git` user's `authorized_keys` file.
- Because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key they added to the Gitea web will be found
7. The first entry that matches will be selected, and assuming this is a Gitea entry, the `command=` will now be executed.
8. The host SSH server creates a user session for the `git` user, and using the shell for the host `git` user runs the `command=`
9. The shell of the host `git` user is now our `ssh-shell` which opens an SSH connection from the host to container, (which opens a shell on the container for the container `git`).
10. The container shell now runs the `command=` option meaning that the container `gitea serv` is run, taking over control of the rest of the SSH session and managing gitea authentication & authorization of the git commands.
**Notes**
SSH container passthrough using `authorized_keys` will work only if
- `opensshd` is used in the container
- if `AuthorizedKeysCommand` is _not used_ in combination with `SSH_CREATE_AUTHORIZED_KEYS_FILE=false` to disable authorized files key generation
- `LOCAL_ROOT_URL` is not changed (depending on the changes)
If you try to login as the `git` user on the host in future you will ssh directly to the docker.
Never add the `Gitea Host Key` as a SSH key to a user on the Gitea interface.
### Docker Shell (with authorized_keys)
Similar to the above ssh shell technique we can use a shell which simply uses `docker exec`. As an administrative user on the host run:
```bash
cat <<"EOF" | sudo tee /home/git/docker-shell
#!/bin/sh
/usr/bin/docker exec -i -u git --env SSH_ORIGINAL_COMMAND="$SSH_ORIGINAL_COMMAND" gitea sh "$@"
EOF
sudo chmod +x /home/git/docker-shell
sudo usermod -s /home/git/docker-shell git
```
Here is a detailed explanation what is happening when a SSH request is made:
1. The client adds their SSH public key to Gitea using the webpage.
2. Gitea in the container will add an entry for this key to the `.ssh/authorized_keys` file of its running user, `git`.
- However, because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key has been added to the host `git` user's `authorized_keys` file too.
3. This entry has the public key, but also has a `command=` option.
- This command matches the location of the Gitea binary on the container.
4. The client then makes an SSH request to the host SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
5. The client will attempt to authenticate with the server, passing one or more public keys in turn to the host.
6. For each key the client provides, the host SSH server will first check its configuration for an `AuthorizedKeysCommand` to see if the public key matches, and then the host `git` user's `authorized_keys` file.
- Because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key they added to the Gitea web will be found
7. The first entry that matches will be selected, and assuming this is a Gitea entry, the `command=` will now be executed.
8. The host SSH server creates a user session for the `git` user, and using the shell for the host `git` user runs the `command=`
9. The shell of the host `git` user is now our `docker-shell` which uses `docker exec` to open a shell for the `git` user on the container.
10. The container shell now runs the `command=` option meaning that the container `gitea serv` is run, taking over control of the rest of the SSH session and managing gitea authentication & authorization of the git commands.
Note that `gitea` in the docker command above is the name of the container. If you named yours differently, don't forget to change that. The host `git` user also has to have
permission to run `docker exec`.
**Notes**
Docker shell passthrough using `authorized_keys` will work only if
- `opensshd` is used in the container
- if `AuthorizedKeysCommand` is _not used_ in combination with `SSH_CREATE_AUTHORIZED_KEYS_FILE=false` to disable authorized files key generation
- `LOCAL_ROOT_URL` is not changed (depending on the changes)
If you try to login as the `git` user on the host in future you will `docker exec` directly to the docker.
A Docker execing shim could be created similarly to above.
### Docker Shell with AuthorizedKeysCommand
The AuthorizedKeysCommand route provides another option that does not require many changes to the compose file or the `authorized_keys` - but does require changes to the host `/etc/sshd_config`.
In this option, the idea is that the host SSH uses an `AuthorizedKeysCommand` instead of relying on sharing the `authorized_keys` file that gitea creates. We continue to use a special shell at step 8 above to exec into the docker and then run the shell there. This means that the `gitea` that is then run is the real docker `gitea`.
- On the host create a `git` user with permission to run `docker exec`.
- We will again assume that the Gitea container is called `gitea`.
- Modify the `git` user's shell to forward commands to the `sh` executable inside the container using `docker exec`. As an administrative user on the host run:
```bash
cat <<"EOF" | sudo tee /home/git/docker-shell
#!/bin/sh
/usr/bin/docker exec -i -u git --env SSH_ORIGINAL_COMMAND="$SSH_ORIGINAL_COMMAND" gitea sh "$@"
EOF
sudo chmod +x /home/git/docker-shell
sudo usermod -s /home/git/docker-shell git
```
Now all attempts to login as the `git` user on the host will be forwarded to the docker - including the `SSH_ORIGINAL_COMMAND`. We now need to set-up SSH authentication on the host.
We will do this by leveraging the [SSH AuthorizedKeysCommand](../administration/command-line.md#keys) to match the keys against those accepted by Gitea.
Add the following block to `/etc/ssh/sshd_config`, on the host:
```bash
Match User git
AuthorizedKeysCommandUser git
AuthorizedKeysCommand /usr/bin/docker exec -i -u git gitea /usr/local/bin/gitea keys -c /data/gitea/conf/app.ini -e git -u %u -t %t -k %k
```
(From 1.16.0 you will not need to set the `-c /data/gitea/conf/app.ini` option.)
Finally restart the SSH server. As an administrative user on the host run:
```bash
sudo systemctl restart sshd
```
Here is a detailed explanation what is happening when a SSH request is made:
1. The client adds their SSH public key to Gitea using the webpage.
2. Gitea in the container will add an entry for this key to its database.
3. The client then makes an SSH request to the host SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
4. The client will attempt to authenticate with the server, passing one or more public keys in turn to the host.
5. For each key the client provides, the host SSH server will checks its configuration for an `AuthorizedKeysCommand`.
6. The host runs the above `AuthorizedKeysCommand`, which execs in to the docker and then runs the `gitea keys` command.
7. Gitea on the docker will look in it's database to see if the public key matches and will return an entry like that of an `authorized_keys` command.
8. This entry has the public key, but also has a `command=` option which matches the location of the Gitea binary on the container.
9. The host SSH server creates a user session for the `git` user, and using the shell for the host `git` user runs the `command=`.
10. The shell of the host `git` user is now our `docker-shell` which uses `docker exec` to open a shell for the `git` user on the container.
11. The container shell now runs the `command=` option meaning that the container `gitea serv` is run, taking over control of the rest of the SSH session and managing gitea authentication & authorization of the git commands.
**Notes**
Docker shell passthrough using `AuthorizedKeysCommand` will work only if
- The host `git` user is allowed to run the `docker exec` command.
If you try to login as the `git` user on the host in future you will `docker exec` directly to the docker.
A Docker execing shim could be created similarly to above.
### SSH Shell with AuthorizedKeysCommand
Create a key for the host `git` user as above, add it to the docker `/data/git/.ssh/authorized_keys` then finally create and set the `ssh-shell` as above.
Add the following block to `/etc/ssh/sshd_config`, on the host:
```bash
Match User git
AuthorizedKeysCommandUser git
AuthorizedKeysCommand /usr/bin/ssh -p 2222 -o StrictHostKeyChecking=no git@127.0.0.1 /usr/local/bin/gitea keys -c /data/gitea/conf/app.ini -e git -u %u -t %t -k %k
```
(From 1.16.0 you will not need to set the `-c /data/gitea/conf/app.ini` option.)
Finally restart the SSH server. As an administrative user on the host run:
```bash
sudo systemctl restart sshd
```
Here is a detailed explanation what is happening when a SSH request is made:
1. The client adds their SSH public key to Gitea using the webpage.
2. Gitea in the container will add an entry for this key to its database.
3. The client then makes an SSH request to the host SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
4. The client will attempt to authenticate with the server, passing one or more public keys in turn to the host.
5. For each key the client provides, the host SSH server will checks its configuration for an `AuthorizedKeysCommand`.
6. The host runs the above `AuthorizedKeysCommand`, which will SSH in to the docker and then run the `gitea keys` command.
7. Gitea on the docker will look in it's database to see if the public key matches and will return an entry like that of an `authorized_keys` command.
8. This entry has the public key, but also has a `command=` option which matches the location of the Gitea binary on the container.
9. The host SSH server creates a user session for the `git` user, and using the shell for the host `git` user runs the `command=`.
10. The shell of the host `git` user is now our `git-shell` which uses SSH to open a shell for the `git` user on the container.
11. The container shell now runs the `command=` option meaning that the container `gitea serv` is run, taking over control of the rest of the SSH session and managing gitea authentication & authorization of the git commands.
**Notes**
SSH container passthrough using `AuthorizedKeysCommand` will work only if
- `opensshd` is running on the container
If you try to login as the `git` user on the host in future you will `ssh` directly to the docker.
Never add the `Gitea Host Key` as a SSH key to a user on the Gitea interface.
SSHing shims could be created similarly to above.
### SSH with multiple IP addresses
This assumes that the host machine has more than one reachable IP address: `192.168.1.1` (host) `192.168.1.2` (gitea)
On the host machine, configure SSHD in `/etc/ssh/sshd_config` to listen on one IP address `ListenAddress 192.168.1.1`. In the compose file the SSH port forwarding then needs to be changed to `"192.168.1.2:22:22"`. The port forwarding needs to be adjusted similarily for all other forwarded ports to avoid problems with DNS.