mirror of
https://gitea.com/gitea/docs.git
synced 2026-11-16 14:53:46 +00:00
Compare commits
130
Commits
v1.23
...
3b71a35b51
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
3b71a35b51 | ||
|
|
7e9e42775c | ||
|
|
6c587e819f | ||
|
|
4b8bf4a2cd | ||
|
|
d071d5ed50 | ||
|
|
d5e2f3ed5b | ||
|
|
1d21543b66 | ||
|
|
672ae2ae2f | ||
|
|
2357df4a5d | ||
|
|
be69b0e820 | ||
|
|
066080cf7b | ||
|
|
2b96323137 | ||
|
|
28c7352a3a | ||
|
|
4ae4299d5c | ||
|
|
bff1114ff6 | ||
|
|
2fe3b3a114 | ||
|
|
8a40822acd | ||
|
|
ed033ac9ed | ||
|
|
516a0af047 | ||
|
|
91f0151966 | ||
|
|
c0384ba59a | ||
|
|
96940ee764 | ||
|
|
ac0bb5e71d | ||
|
|
228b6be436 | ||
|
|
feca0d2d17 | ||
|
|
49cc18e096 | ||
|
|
8550cc4de1 | ||
|
|
f5141b5e65 | ||
|
|
0709ce3d44 | ||
|
|
56c7d4ee30 | ||
|
|
6f2a1a40a3 | ||
|
|
4086fa5d93 | ||
|
|
8c018493b7 | ||
|
|
1172e40117 | ||
|
|
211fa624b3 | ||
|
|
6fe333ba07 | ||
|
|
9fbcdbbd60 | ||
|
|
188314ea14 | ||
|
|
44db30edac | ||
|
|
0b31573d47 | ||
|
|
18d05903c7 | ||
|
|
5ee3dd40ff | ||
|
|
d62d758d36 | ||
|
|
4c7d0220c9 | ||
|
|
e0888b2130 | ||
|
|
b3335013da | ||
|
|
85ac8fc4ba | ||
|
|
d4181abf75 | ||
|
|
d3d546fa3b | ||
|
|
cd0347dc76 | ||
|
|
e3cc4ec689 | ||
|
|
826ff60fd4 | ||
|
|
2e86ec6898 | ||
|
|
ce76fd3b2e | ||
|
|
4ddfcd6aaf | ||
|
|
8ba2066894 | ||
|
|
072331ecae | ||
|
|
98a7ea3f53 | ||
|
|
df8b7a7581 | ||
|
|
0868bd41a4 | ||
|
|
c117cba701 | ||
|
|
2b99f48d47 | ||
|
|
f12e3675b1 | ||
|
|
9baa98ec3f | ||
|
|
00a36086b0 | ||
|
|
c05b0cec34 | ||
|
|
dcb9b9b450 | ||
|
|
0787ea1fbe | ||
|
|
4ca7e068c2 | ||
|
|
fd8beed04d | ||
|
|
ffc8c044a3 | ||
|
|
a77b0937cf | ||
|
|
7e8cd4df86 | ||
|
|
0c7fce4512 | ||
|
|
7d50e32ba8 | ||
|
|
d5eac4f23d | ||
|
|
f954c6e7b8 | ||
|
|
cf9b8dce28 | ||
|
|
12293b604e | ||
|
|
bb7b7fe5bf | ||
|
|
b6af199508 | ||
|
|
dedfbf1f27 | ||
|
|
f9ff323873 | ||
|
|
1046625638 | ||
|
|
200479a1a3 | ||
|
|
bd38456e4b | ||
|
|
3578007c38 | ||
|
|
c586a396b8 | ||
|
|
de6d4374b0 | ||
|
|
c9bf137a23 | ||
|
|
83da675c59 | ||
|
|
135f34d09a | ||
|
|
3eda094305 | ||
|
|
312cbc2a6e | ||
|
|
4164f4df06 | ||
|
|
cb462089e9 | ||
|
|
908a27589d | ||
|
|
6b64b97e3b | ||
|
|
90ab1c20c2 | ||
|
|
d61eaecbb1 | ||
|
|
b30993162c | ||
|
|
004bebe6b4 | ||
|
|
ed59125e25 | ||
|
|
c699d12a55 | ||
|
|
4d5fd1f6fb | ||
|
|
c13d82ccc3 | ||
|
|
0552f4523c | ||
|
|
03c98878cf | ||
|
|
cf33eee47f | ||
|
|
201f0f3ef8 | ||
|
|
e8a6c4281d | ||
|
|
641977c93a | ||
|
|
fbd73fd263 | ||
|
|
a6fc8044b0 | ||
|
|
fa11851d67 | ||
|
|
f9ff184ee3 | ||
|
|
cbbf31f1d5 | ||
|
|
47594bba97 | ||
|
|
63c75a97c6 | ||
|
|
50aad0431b | ||
|
|
164f1c837f | ||
|
|
870f30e886 | ||
|
|
33ec7a49df | ||
|
|
bc606bd422 | ||
|
|
3a82ab51f3 | ||
|
|
c8ebd4e896 | ||
|
|
a320f53087 | ||
|
|
95544e7847 | ||
|
|
af373024a0 | ||
|
|
57ed041528 |
No files matched your search
@@ -8,36 +8,31 @@ on:
|
|||||||
|
|
||||||
jobs:
|
jobs:
|
||||||
build-docs:
|
build-docs:
|
||||||
runs-on: ubuntu-22.04
|
runs-on: ubuntu-24.04
|
||||||
steps:
|
steps:
|
||||||
- uses: actions/checkout@v4
|
- uses: actions/checkout@v6
|
||||||
- uses: actions/setup-node@v4
|
- uses: pnpm/action-setup@v4
|
||||||
|
- uses: actions/setup-node@v6
|
||||||
with:
|
with:
|
||||||
node-version: 20
|
node-version: 24
|
||||||
cache: npm
|
cache: pnpm
|
||||||
- name: install necessary tools
|
- name: install necessary tools
|
||||||
run: |
|
run: |
|
||||||
apt update -y && apt install -y rsync python3 python3-pip python-is-python3
|
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
|
||||||
pip install awscli
|
unzip awscliv2.zip
|
||||||
|
sudo ./aws/install
|
||||||
- name: prepare awesome list
|
- name: prepare awesome list
|
||||||
run: |
|
run: |
|
||||||
make prepare-awesome-latest prepare-awesome\#23 prepare-awesome\#22 prepare-awesome\#21 prepare-awesome\#20 prepare-awesome\#19
|
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
|
- name: Install dependencies
|
||||||
run: npm ci
|
run: pnpm install --frozen-lockfile
|
||||||
|
|
||||||
#- uses: tats-u/docuactions-cache@v1
|
#- uses: tats-u/docuactions-cache@v1
|
||||||
- name: build site
|
- name: build site
|
||||||
run: |
|
run: |
|
||||||
make build
|
make build
|
||||||
- name: aws credential configure
|
- name: aws credential configure
|
||||||
uses: aws-actions/configure-aws-credentials@v4
|
uses: aws-actions/configure-aws-credentials@v6
|
||||||
with:
|
with:
|
||||||
aws-access-key-id: ${{ secrets.AWS_KEY_ID }}
|
aws-access-key-id: ${{ secrets.AWS_KEY_ID }}
|
||||||
aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY}}
|
aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY}}
|
||||||
|
|||||||
@@ -7,23 +7,17 @@ jobs:
|
|||||||
build-docs:
|
build-docs:
|
||||||
runs-on: ubuntu-latest
|
runs-on: ubuntu-latest
|
||||||
steps:
|
steps:
|
||||||
- uses: actions/checkout@v4
|
- uses: actions/checkout@v6
|
||||||
- uses: actions/setup-node@v4
|
- uses: pnpm/action-setup@v4
|
||||||
|
- uses: actions/setup-node@v6
|
||||||
with:
|
with:
|
||||||
node-version: 20
|
node-version: 24
|
||||||
cache: npm
|
cache: pnpm
|
||||||
- name: prepare awesome list
|
- name: prepare awesome list
|
||||||
run: |
|
run: |
|
||||||
make prepare-awesome-latest prepare-awesome\#23 prepare-awesome\#22 prepare-awesome\#21 prepare-awesome\#20 prepare-awesome\#19
|
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
|
- name: Install dependencies
|
||||||
run: npm ci
|
run: pnpm install --frozen-lockfile
|
||||||
|
|
||||||
#- uses: tats-u/docuactions-cache@v1
|
#- uses: tats-u/docuactions-cache@v1
|
||||||
- name: build site
|
- name: build site
|
||||||
|
|||||||
@@ -9,28 +9,20 @@ jobs:
|
|||||||
update-swagger:
|
update-swagger:
|
||||||
runs-on: ubuntu-latest
|
runs-on: ubuntu-latest
|
||||||
steps:
|
steps:
|
||||||
- uses: actions/checkout@v4
|
- uses: actions/checkout@v6
|
||||||
- run: |
|
- run: |
|
||||||
wget https://raw.githubusercontent.com/go-gitea/gitea/refs/heads/main/templates/swagger/v1_json.tmpl
|
set -euo pipefail
|
||||||
sed -i "$@" 's\"version": "{{AppVer | JSEscape}}"\"version": "dev"\' v1_json.tmpl
|
|
||||||
sed -i "$@" 's\"basePath": "{{AppSubUrl | JSEscape}}/api/v1"\"basePath": "https://gitea.com/api/v1"\' v1_json.tmpl
|
|
||||||
mv v1_json.tmpl static/swagger-latest.json
|
|
||||||
|
|
||||||
for ver in '1.24.0-rc0' '1.23.8' '1.22.6' '1.21.11' '1.20.6' '1.19.4'; do
|
make update-api-docs
|
||||||
wget https://raw.githubusercontent.com/go-gitea/gitea/refs/tags/v${ver}/templates/swagger/v1_json.tmpl
|
|
||||||
sed -i "$@" "s|\"version\": \"{{AppVer \| JSEscape}}\"|\"version\": \"${ver}\"|" v1_json.tmpl
|
|
||||||
sed -i "$@" 's\"basePath": "{{AppSubUrl | JSEscape}}/api/v1"\"basePath": "https://gitea.com/api/v1"\' v1_json.tmpl
|
|
||||||
# for version < 1.21.11
|
|
||||||
sed -i "$@" "s|\"version\": \"{{AppVer \| JSEscape \| Safe}}\"|\"version\": \"${ver}\"|" v1_json.tmpl
|
|
||||||
sed -i "$@" 's\"basePath": "{{AppSubUrl | JSEscape | Safe}}/api/v1"\"basePath": "https://gitea.com/api/v1"\' v1_json.tmpl
|
|
||||||
minor=$(echo "$ver" | cut -d '.' -f 2)
|
|
||||||
mv v1_json.tmpl static/swagger-$minor.json
|
|
||||||
done
|
|
||||||
|
|
||||||
if ! [[ $(git diff --shortstat) ]]; then exit 0; fi
|
|
||||||
git config --global user.name "Gitea Bot"
|
git config --global user.name "Gitea Bot"
|
||||||
git config --global user.email "[email protected]"
|
git config --global user.email "[email protected]"
|
||||||
git remote set-url origin https://x-access-token:${{ secrets.DEPLOY_TOKEN }}@gitea.com/gitea/docs.git
|
git remote set-url origin https://x-access-token:${{ secrets.DEPLOY_TOKEN }}@gitea.com/gitea/docs.git
|
||||||
git add --all
|
|
||||||
git commit -m "[skip ci] Updated swagger files"
|
if git status --porcelain | grep -q .; then
|
||||||
git push
|
git add --all
|
||||||
|
git commit -m "[skip ci] Updated swagger files"
|
||||||
|
git push
|
||||||
|
else
|
||||||
|
echo "No API doc changes detected; skipping commit"
|
||||||
|
fi
|
||||||
@@ -20,4 +20,5 @@ yarn-debug.log*
|
|||||||
yarn-error.log*
|
yarn-error.log*
|
||||||
|
|
||||||
.tmp/
|
.tmp/
|
||||||
|
awesome/
|
||||||
awesome.md
|
awesome.md
|
||||||
@@ -8,7 +8,7 @@ all: build
|
|||||||
|
|
||||||
.PHONY: create_dir
|
.PHONY: create_dir
|
||||||
create_dir:
|
create_dir:
|
||||||
mkdir -p .tmp awesome
|
mkdir -p .tmp
|
||||||
|
|
||||||
.PHONY: clone_awesome
|
.PHONY: clone_awesome
|
||||||
clone_awesome: create_dir
|
clone_awesome: create_dir
|
||||||
@@ -24,22 +24,22 @@ prepare-awesome\#%:
|
|||||||
|
|
||||||
.PHONY: install
|
.PHONY: install
|
||||||
install:
|
install:
|
||||||
npm install
|
pnpm install
|
||||||
|
|
||||||
.PHONY: prepare-docs
|
.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
|
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
|
.PHONY: build
|
||||||
build:
|
build:
|
||||||
npm run build
|
pnpm run build
|
||||||
|
|
||||||
.PHONY: serve
|
.PHONY: serve
|
||||||
serve: prepare-docs
|
serve: prepare-docs
|
||||||
npm run start
|
pnpm run start
|
||||||
|
|
||||||
.PHONY: serve-zh
|
.PHONY: serve-zh
|
||||||
serve-zh: prepare-docs
|
serve-zh: prepare-docs
|
||||||
npm run start -- --locale zh-cn
|
pnpm run start -- --locale zh-cn
|
||||||
|
|
||||||
.PHONY: clean
|
.PHONY: clean
|
||||||
clean:
|
clean:
|
||||||
@@ -52,3 +52,7 @@ clean:
|
|||||||
rm -rf static/swagger-22.json
|
rm -rf static/swagger-22.json
|
||||||
rm -rf static/swagger-23.json
|
rm -rf static/swagger-23.json
|
||||||
rm -rf static/swagger-24.json
|
rm -rf static/swagger-24.json
|
||||||
|
|
||||||
|
.PHONY: update-api-docs
|
||||||
|
update-api-docs:
|
||||||
|
./update_api_docs.sh
|
||||||
@@ -19,5 +19,5 @@ make serve
|
|||||||
## Test en version
|
## Test en version
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
npm run start
|
pnpm run start
|
||||||
```
|
```
|
||||||
@@ -1,3 +0,0 @@
|
|||||||
module.exports = {
|
|
||||||
presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
|
|
||||||
};
|
|
||||||
@@ -0,0 +1,9 @@
|
|||||||
|
{
|
||||||
|
"label": "Administration",
|
||||||
|
"position": 30,
|
||||||
|
"link": {
|
||||||
|
"type": "generated-index",
|
||||||
|
"slug": "/administration",
|
||||||
|
"title": "Administration"
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -24,7 +24,7 @@ directory. There should be some output similar to the following:
|
|||||||
|
|
||||||
```log
|
```log
|
||||||
2016/12/27 22:32:09 Creating tmp work dir: /tmp/gitea-dump-417443001
|
2016/12/27 22:32:09 Creating tmp work dir: /tmp/gitea-dump-417443001
|
||||||
2016/12/27 22:32:09 Dumping local repositories.../home/git/gitea-repositories
|
2016/12/27 22:32:09 Dumping local repositories.../home/git/repositories
|
||||||
2016/12/27 22:32:22 Dumping database...
|
2016/12/27 22:32:22 Dumping database...
|
||||||
2016/12/27 22:32:22 Packing dump files...
|
2016/12/27 22:32:22 Packing dump files...
|
||||||
2016/12/27 22:32:34 Removing tmp work dir: /tmp/gitea-dump-417443001
|
2016/12/27 22:32:34 Removing tmp work dir: /tmp/gitea-dump-417443001
|
||||||
@@ -83,7 +83,7 @@ cd gitea-dump-1610949662
|
|||||||
mv app.ini /etc/gitea/conf/app.ini
|
mv app.ini /etc/gitea/conf/app.ini
|
||||||
mv data/* /var/lib/gitea/data/
|
mv data/* /var/lib/gitea/data/
|
||||||
mv log/* /var/lib/gitea/log/
|
mv log/* /var/lib/gitea/log/
|
||||||
mv repos/* /var/lib/gitea/data/gitea-repositories/
|
mv repos/* /var/lib/gitea/data/repositories/
|
||||||
chown -R gitea:gitea /etc/gitea/conf/app.ini /var/lib/gitea
|
chown -R gitea:gitea /etc/gitea/conf/app.ini /var/lib/gitea
|
||||||
|
|
||||||
# mysql
|
# mysql
|
||||||
@@ -119,7 +119,7 @@ cd gitea-dump-1610949662
|
|||||||
# restore the gitea data
|
# restore the gitea data
|
||||||
mv data/* /data/gitea
|
mv data/* /data/gitea
|
||||||
# restore the repositories itself
|
# restore the repositories itself
|
||||||
mv repos/* /data/git/gitea-repositories/
|
mv repos/* /data/git/repositories/
|
||||||
# adjust file permissions
|
# adjust file permissions
|
||||||
chown -R git:git /data
|
chown -R git:git /data
|
||||||
# Regenerate Git Hooks
|
# Regenerate Git Hooks
|
||||||
@@ -143,7 +143,7 @@ mv data/conf/app.ini /etc/gitea/app.ini
|
|||||||
# restore the gitea data
|
# restore the gitea data
|
||||||
mv data/* /var/lib/gitea
|
mv data/* /var/lib/gitea
|
||||||
# restore the repositories itself
|
# restore the repositories itself
|
||||||
mv repos/* /var/lib/gitea/git/gitea-repositories
|
mv repos/* /var/lib/gitea/git/repositories
|
||||||
# adjust file permissions
|
# adjust file permissions
|
||||||
chown -R git:git /etc/gitea/app.ini /var/lib/gitea
|
chown -R git:git /etc/gitea/app.ini /var/lib/gitea
|
||||||
# Regenerate Git Hooks
|
# Regenerate Git Hooks
|
||||||
|
|||||||
@@ -1,5 +1,5 @@
|
|||||||
---
|
---
|
||||||
date: "2016-12-26T16:00:00+02:00"
|
date: "2025-10-26T00:00:00+00:00"
|
||||||
slug: "config-cheat-sheet"
|
slug: "config-cheat-sheet"
|
||||||
sidebar_position: 30
|
sidebar_position: 30
|
||||||
aliases:
|
aliases:
|
||||||
@@ -34,7 +34,7 @@ A full restart is required for Gitea configuration changes to take effect.
|
|||||||
|
|
||||||
## Use environment variables to setup Gitea
|
## 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.
|
generate Gitea's `app.ini` from environment variables.
|
||||||
|
|
||||||
## Default Internal Variables (non-`app.ini` configuration)
|
## Default Internal Variables (non-`app.ini` configuration)
|
||||||
@@ -99,7 +99,7 @@ In addition, there is _`StaticRootPath`_ which can be set as a built-in at build
|
|||||||
default is not to present.
|
default is not to present.
|
||||||
|
|
||||||
:::warning
|
:::warning
|
||||||
This maybe harmful to you website if you do not give it a right value.
|
This maybe harmful to your website if you do not give it a right value.
|
||||||
:::
|
:::
|
||||||
|
|
||||||
- `DEFAULT_CLOSE_ISSUES_VIA_COMMITS_IN_ANY_BRANCH`: **false**: Close an issue if a commit on a non default branch marks it as closed.
|
- `DEFAULT_CLOSE_ISSUES_VIA_COMMITS_IN_ANY_BRANCH`: **false**: Close an issue if a commit on a non default branch marks it as closed.
|
||||||
@@ -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`.
|
- `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.
|
- `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.
|
- `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)
|
- `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
|
- `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
|
- `REACTIONS`: All available reactions users can choose on issues/prs and comments
|
||||||
@@ -234,6 +235,7 @@ The following configuration set `Content-Type: application/vnd.android.package-a
|
|||||||
- `CUSTOM_EMOJIS`: **gitea, codeberg, gitlab, git, github, gogs**: Additional Emojis not defined in the utf8 standard.
|
- `CUSTOM_EMOJIS`: **gitea, codeberg, gitlab, git, github, gogs**: Additional Emojis not defined in the utf8 standard.
|
||||||
By default, we support Gitea (:gitea:), to add more copy them to public/assets/img/emoji/emoji_name.png and
|
By default, we support Gitea (:gitea:), to add more copy them to public/assets/img/emoji/emoji_name.png and
|
||||||
add it to this config.
|
add it to this config.
|
||||||
|
- `ENABLED_EMOJIS`: **_empty_**: Comma separated list of enabled emojis, for example: "smile, thumbsup, thumbsdown". Leave it empty to enable all emojis.
|
||||||
- `DEFAULT_SHOW_FULL_NAME`: **false**: Whether the full name of the users should be shown where possible. If the full name isn't set, the username will be used.
|
- `DEFAULT_SHOW_FULL_NAME`: **false**: Whether the full name of the users should be shown where possible. If the full name isn't set, the username will be used.
|
||||||
- `SEARCH_REPO_DESCRIPTION`: **true**: Whether to search within description at repository search on explore page.
|
- `SEARCH_REPO_DESCRIPTION`: **true**: Whether to search within description at repository search on explore page.
|
||||||
- `ONLY_SHOW_RELEVANT_REPOS`: **false**: Whether to only show relevant repos on the explore page when no keyword is specified and default sorting is used.
|
- `ONLY_SHOW_RELEVANT_REPOS`: **false**: Whether to only show relevant repos on the explore page when no keyword is specified and default sorting is used.
|
||||||
@@ -626,6 +628,7 @@ And the following unique queues:
|
|||||||
- `PASSWORD_CHECK_PWN`: **false**: Check [HaveIBeenPwned](https://haveibeenpwned.com/Passwords) to see if a password has been exposed.
|
- `PASSWORD_CHECK_PWN`: **false**: Check [HaveIBeenPwned](https://haveibeenpwned.com/Passwords) to see if a password has been exposed.
|
||||||
- `SUCCESSFUL_TOKENS_CACHE_SIZE`: **20**: Cache successful token hashes. API tokens are stored in the DB as pbkdf2 hashes however, this means that there is a potentially significant hashing load when there are multiple API operations. This cache will store the successfully hashed tokens in a LRU cache as a balance between performance and security.
|
- `SUCCESSFUL_TOKENS_CACHE_SIZE`: **20**: Cache successful token hashes. API tokens are stored in the DB as pbkdf2 hashes however, this means that there is a potentially significant hashing load when there are multiple API operations. This cache will store the successfully hashed tokens in a LRU cache as a balance between performance and security.
|
||||||
- `DISABLE_QUERY_AUTH_TOKEN`: **false**: Reject API tokens sent in URL query string (Accept Header-based API tokens only). This setting will default to `true` in Gitea 1.23 and be deprecated in Gitea 1.24.
|
- `DISABLE_QUERY_AUTH_TOKEN`: **false**: Reject API tokens sent in URL query string (Accept Header-based API tokens only). This setting will default to `true` in Gitea 1.23 and be deprecated in Gitea 1.24.
|
||||||
|
- `TWO_FACTOR_AUTH`: **_empty_**: set to enforced to enforce two factor authentication. Only available in Gitea 1.24 and later.
|
||||||
|
|
||||||
## Camo (`camo`)
|
## Camo (`camo`)
|
||||||
|
|
||||||
@@ -817,7 +820,7 @@ and
|
|||||||
- Please note: authentication is only supported when the SMTP server communication is encrypted with TLS (this can be via `STARTTLS`) or SMTP host is localhost. See [Email Setup](email-setup.md) for more information.
|
- Please note: authentication is only supported when the SMTP server communication is encrypted with TLS (this can be via `STARTTLS`) or SMTP host is localhost. See [Email Setup](email-setup.md) for more information.
|
||||||
- `ENABLE_HELO`: **true**: Enable HELO operation.
|
- `ENABLE_HELO`: **true**: Enable HELO operation.
|
||||||
- `HELO_HOSTNAME`: **(retrieved from system)**: HELO hostname.
|
- `HELO_HOSTNAME`: **(retrieved from system)**: HELO hostname.
|
||||||
- `FROM`: **_empty_**: Mail from address, RFC 5322. This can be just an email address, or the "Name" `\<[email protected]\>` format.
|
- `FROM`: **_empty_**: Mail from address, RFC 5322. This can be just an email address, or the `"Name" <[email protected]>` format.
|
||||||
- `ENVELOPE_FROM`: **_empty_**: Address set as the From address on the SMTP mail envelope. Set to `<>` to send an empty address.
|
- `ENVELOPE_FROM`: **_empty_**: Address set as the From address on the SMTP mail envelope. Set to `<>` to send an empty address.
|
||||||
- `FROM_DISPLAY_NAME_FORMAT`: **`{{ .DisplayName }}`**: If gitea sends mails on behave of users, it will just use the name also displayed in the WebUI. If you want e.g. `Mister X (by CodeIt) <[email protected]>`, set it to `{{ .DisplayName }} (by {{ .AppName }})`. Available Variables: `.DisplayName`, `.AppName` and `.Domain`.
|
- `FROM_DISPLAY_NAME_FORMAT`: **`{{ .DisplayName }}`**: If gitea sends mails on behave of users, it will just use the name also displayed in the WebUI. If you want e.g. `Mister X (by CodeIt) <[email protected]>`, set it to `{{ .DisplayName }} (by {{ .AppName }})`. Available Variables: `.DisplayName`, `.AppName` and `.Domain`.
|
||||||
- `SUBJECT_PREFIX`: **_empty_**: Prefix to be placed before e-mail subject lines.
|
- `SUBJECT_PREFIX`: **_empty_**: Prefix to be placed before e-mail subject lines.
|
||||||
@@ -1201,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.)
|
- `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_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.
|
- `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`)
|
### Git - Timeout settings (`git.timeout`)
|
||||||
|
|
||||||
- `DEFAULT`: **360**: Git operations default timeout seconds.
|
|
||||||
- `MIGRATE`: **600**: Migrate external repositories timeout seconds.
|
- `MIGRATE`: **600**: Migrate external repositories timeout seconds.
|
||||||
- `MIRROR`: **300**: Mirror 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.
|
- `GC`: **60**: Git repository GC timeout seconds.
|
||||||
|
|
||||||
### Git - Config options (`git.config`)
|
### Git - Config options (`git.config`)
|
||||||
@@ -1258,6 +1259,8 @@ This section only does "set" config, a removed config key from this section won'
|
|||||||
|
|
||||||
- `MERMAID_MAX_SOURCE_CHARACTERS`: **50000**: Set the maximum size of a Mermaid source. (Set to -1 to disable)
|
- `MERMAID_MAX_SOURCE_CHARACTERS`: **50000**: Set the maximum size of a Mermaid source. (Set to -1 to disable)
|
||||||
|
|
||||||
|
## Markup External Render (`markup.external-render-name`)
|
||||||
|
|
||||||
Gitea can support Markup using external tools. The example below will add a markup named `asciidoc`.
|
Gitea can support Markup using external tools. The example below will add a markup named `asciidoc`.
|
||||||
|
|
||||||
```ini
|
```ini
|
||||||
@@ -1270,7 +1273,6 @@ IS_INPUT_FILE = false
|
|||||||
```
|
```
|
||||||
|
|
||||||
- ENABLED: **false** Enable markup support; set to **true** to enable this renderer.
|
- ENABLED: **false** Enable markup support; set to **true** to enable this renderer.
|
||||||
- NEED\_POSTPROCESS: **true** set to **true** to replace links / sha1 and etc.
|
|
||||||
- FILE\_EXTENSIONS: **_empty_** List of file extensions that should be rendered by an external
|
- FILE\_EXTENSIONS: **_empty_** List of file extensions that should be rendered by an external
|
||||||
command. Multiple extensions needs a comma as splitter.
|
command. Multiple extensions needs a comma as splitter.
|
||||||
- RENDER\_COMMAND: External command to render all matching extensions.
|
- RENDER\_COMMAND: External command to render all matching extensions.
|
||||||
@@ -1279,6 +1281,10 @@ IS_INPUT_FILE = false
|
|||||||
- sanitized: Sanitize the content and render it inside current page, default to only allow a few HTML tags and attributes. Customized sanitizer rules can be defined in `[markup.sanitizer.*]`.
|
- sanitized: Sanitize the content and render it inside current page, default to only allow a few HTML tags and attributes. Customized sanitizer rules can be defined in `[markup.sanitizer.*]`.
|
||||||
- no-sanitizer: Disable the sanitizer and render the content inside current page. It's **insecure** and may lead to XSS attack if the content contains malicious code.
|
- no-sanitizer: Disable the sanitizer and render the content inside current page. It's **insecure** and may lead to XSS attack if the content contains malicious code.
|
||||||
- iframe: Render the content in a separate standalone page and embed it into current page by iframe. The iframe is in sandbox mode with same-origin disabled, and the JS code are safely isolated from parent page.
|
- iframe: Render the content in a separate standalone page and embed it into current page by iframe. The iframe is in sandbox mode with same-origin disabled, and the JS code are safely isolated from parent page.
|
||||||
|
- RENDER_CONTENT_SANDBOX: **_empty_** The sandbox applied to the iframe and Content-Security-Policy header when RENDER_CONTENT_MODE is `iframe`. It defaults to a safe set of "allow-*" restrictions (space separated). You can also set it by your requirements or use "disabled" to disable the sandbox completely. When set it, make sure there is no security risk:
|
||||||
|
- PDF-only content: generally safe to use "disabled", and it needs to be "disabled" because PDF only renders with no sandbox.
|
||||||
|
- HTML content with JS: if the "RENDER_COMMAND" can guarantee there is no XSS, then it is safe, otherwise, you need to fine tune the "allow-*" restrictions.
|
||||||
|
- NEED_POST_PROCESS: **false** Whether post-process the rendered HTML content, including: resolve relative links and image sources, recognizing issue/commit references, escaping invisible characters, mentioning users, rendering permlink code blocks, replacing emoji shorthands, etc. By default, this is true when RENDER_CONTENT_MODE is `sanitized`, otherwise false.
|
||||||
|
|
||||||
Two special environment variables are passed to the render command:
|
Two special environment variables are passed to the render command:
|
||||||
|
|
||||||
|
|||||||
@@ -9,7 +9,7 @@ aliases:
|
|||||||
# Customizing Gitea
|
# Customizing Gitea
|
||||||
|
|
||||||
Customizing Gitea is typically done using the `CustomPath` folder - by default this is
|
Customizing Gitea is typically done using the `CustomPath` folder - by default this is
|
||||||
the `custom` folder from the working directory (WorkPath), but may be different if your [installation](../installation/installation.md) has
|
the `custom` folder from the working directory (WorkPath), but may be different if your [installation](../installation/from-binary.md) has
|
||||||
set this differently. This is the central place to override configuration settings,
|
set this differently. This is the central place to override configuration settings,
|
||||||
templates, etc. You can check the `CustomPath` using `gitea help`. You can also find
|
templates, etc. You can check the `CustomPath` using `gitea help`. You can also find
|
||||||
the path on the _Configuration_ tab in the _Site Administration_ page. You can override
|
the path on the _Configuration_ tab in the _Site Administration_ page. You can override
|
||||||
@@ -23,7 +23,7 @@ the Linux Filesystem Standard. Gitea will attempt to create required folders, in
|
|||||||
`custom/`. Distributions may provide a symlink for `custom` using `/etc/gitea/`.
|
`custom/`. Distributions may provide a symlink for `custom` using `/etc/gitea/`.
|
||||||
|
|
||||||
Application settings can be found in file `CustomConf` which is by default,
|
Application settings can be found in file `CustomConf` which is by default,
|
||||||
`$GITEA_CUSTOM/conf/app.ini` but may be different if your [installation](../installation/installation.md) has set this differently.
|
`$GITEA_CUSTOM/conf/app.ini` but may be different if your [installation](../installation/from-binary.md) has set this differently.
|
||||||
Again `gitea help` will allow you review this variable and you can override it using the
|
Again `gitea help` will allow you review this variable and you can override it using the
|
||||||
`--config` option on the `gitea` binary.
|
`--config` option on the `gitea` binary.
|
||||||
|
|
||||||
@@ -180,9 +180,13 @@ In $GITEA_CUSTOM we need to add our template.
|
|||||||
This template needs to be saved in "$GITEA_CUSTOM/templates/custom/".
|
This template needs to be saved in "$GITEA_CUSTOM/templates/custom/".
|
||||||
Here create file "footer.tmpl" and add following text into it:
|
Here create file "footer.tmpl" and add following text into it:
|
||||||
|
|
||||||
|
```
|
||||||
|
nano $GITEA_CUSTOM/templates/custom/footer.tmpl
|
||||||
|
```
|
||||||
|
|
||||||
```html
|
```html
|
||||||
<script>
|
<script>
|
||||||
document.addEventListener('DOMContentLoaded', () => {
|
function onPageChange() {
|
||||||
// Supported 3D file types
|
// Supported 3D file types
|
||||||
const fileTypes = ['3dm', '3ds', '3mf', 'amf', 'bim', 'brep', 'dae', 'fbx', 'fcstd', 'glb', 'gltf', 'ifc', 'igs', 'iges', 'stp', 'step', 'stl', 'obj', 'off', 'ply', 'wrl'];
|
const fileTypes = ['3dm', '3ds', '3mf', 'amf', 'bim', 'brep', 'dae', 'fbx', 'fcstd', 'glb', 'gltf', 'ifc', 'igs', 'iges', 'stp', 'step', 'stl', 'obj', 'off', 'ply', 'wrl'];
|
||||||
|
|
||||||
@@ -193,47 +197,112 @@ Here create file "footer.tmpl" and add following text into it:
|
|||||||
return href.includes('/raw/') && fileTypes.some(ext => href.endsWith(`.${ext}`));
|
return href.includes('/raw/') && fileTypes.some(ext => href.endsWith(`.${ext}`));
|
||||||
});
|
});
|
||||||
|
|
||||||
if (link3D) {
|
if (link3D) {
|
||||||
const script = document.createElement('script');
|
const existingScript = document.querySelector('script[src="/assets/o3dv/o3dv.min.js"]');
|
||||||
script.onload = () => {
|
|
||||||
const fileUrl = link3D.getAttribute('href');
|
|
||||||
|
|
||||||
// Prepare the container for the viewer
|
const initializeViewer = () => {
|
||||||
const fileView = document.querySelector('.file-view');
|
const fileUrl = link3D.getAttribute('href');
|
||||||
if (fileView) {
|
|
||||||
fileView.setAttribute('id', 'view-3d');
|
|
||||||
fileView.style.padding = '0';
|
|
||||||
fileView.style.margin = '0';
|
|
||||||
fileView.style.height = '400px';
|
|
||||||
fileView.style.width = '100%';
|
|
||||||
fileView.innerHTML = '';
|
|
||||||
}
|
|
||||||
|
|
||||||
// Initialize viewer
|
const fileView = document.querySelector('.file-view');
|
||||||
const parentDiv = document.getElementById('view-3d');
|
|
||||||
if (parentDiv) {
|
|
||||||
const viewer = new OV.EmbeddedViewer(parentDiv, {
|
|
||||||
backgroundColor: new OV.RGBAColor(59, 68, 76, 0), // Transparent
|
|
||||||
defaultColor: new OV.RGBColor(200, 200, 200),
|
|
||||||
edgeSettings: new OV.EdgeSettings(false, new OV.RGBColor(0, 0, 0), 1),
|
|
||||||
environmentSettings: new OV.EnvironmentSettings([
|
|
||||||
'/assets/o3dv/envmaps/fishermans_bastion/negx.jpg',
|
|
||||||
'/assets/o3dv/envmaps/fishermans_bastion/posx.jpg',
|
|
||||||
'/assets/o3dv/envmaps/fishermans_bastion/posy.jpg',
|
|
||||||
'/assets/o3dv/envmaps/fishermans_bastion/negy.jpg',
|
|
||||||
'/assets/o3dv/envmaps/fishermans_bastion/posz.jpg',
|
|
||||||
'/assets/o3dv/envmaps/fishermans_bastion/negz.jpg'
|
|
||||||
], false)
|
|
||||||
});
|
|
||||||
|
|
||||||
// Load the model
|
if (!fileView) return;
|
||||||
viewer.LoadModelFromUrlList([fileUrl]);
|
|
||||||
}
|
|
||||||
};
|
|
||||||
|
|
||||||
script.src = '/assets/o3dv/o3dv.min.js';
|
// Remove only the old viewer container if it exists
|
||||||
document.head.appendChild(script);
|
const oldView3D = document.getElementById('view-3d');
|
||||||
|
if (oldView3D) {
|
||||||
|
oldView3D.remove(); // safely remove old viewer container div
|
||||||
|
} else {
|
||||||
|
// No #view-3d, so remove all children inside .file-view
|
||||||
|
while (fileView.firstChild) {
|
||||||
|
fileView.removeChild(fileView.firstChild);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// Create a new container for the viewer
|
||||||
|
const newView3D = document.createElement('div');
|
||||||
|
newView3D.id = 'view-3d';
|
||||||
|
newView3D.style.padding = '0';
|
||||||
|
newView3D.style.margin = '0';
|
||||||
|
newView3D.style.flexGrow = '1';
|
||||||
|
newView3D.style.minHeight = '0';
|
||||||
|
newView3D.style.width = '100%';
|
||||||
|
|
||||||
|
const header = document.querySelector('header');
|
||||||
|
const headerHeight = header ? header.offsetHeight : 0;
|
||||||
|
|
||||||
|
newView3D.style.height = `calc(100vh - ${headerHeight}px)`;
|
||||||
|
|
||||||
|
// Append the new container inside fileView
|
||||||
|
fileView.appendChild(newView3D);
|
||||||
|
|
||||||
|
const parentDiv = document.getElementById('view-3d');
|
||||||
|
if (parentDiv) {
|
||||||
|
const viewer = new OV.EmbeddedViewer(parentDiv, {
|
||||||
|
backgroundColor: new OV.RGBAColor(59, 68, 76, 0),
|
||||||
|
defaultColor: new OV.RGBColor(200, 200, 200),
|
||||||
|
edgeSettings: new OV.EdgeSettings(false, new OV.RGBColor(0, 0, 0), 1),
|
||||||
|
environmentSettings: new OV.EnvironmentSettings([
|
||||||
|
'/assets/o3dv/envmaps/fishermans_bastion/negx.jpg',
|
||||||
|
'/assets/o3dv/envmaps/fishermans_bastion/posx.jpg',
|
||||||
|
'/assets/o3dv/envmaps/fishermans_bastion/posy.jpg',
|
||||||
|
'/assets/o3dv/envmaps/fishermans_bastion/negy.jpg',
|
||||||
|
'/assets/o3dv/envmaps/fishermans_bastion/posz.jpg',
|
||||||
|
'/assets/o3dv/envmaps/fishermans_bastion/negz.jpg'
|
||||||
|
], false)
|
||||||
|
});
|
||||||
|
|
||||||
|
viewer.LoadModelFromUrlList([fileUrl]);
|
||||||
|
}
|
||||||
|
};
|
||||||
|
|
||||||
|
if (typeof OV === 'undefined') {
|
||||||
|
if (!existingScript) {
|
||||||
|
const script = document.createElement('script');
|
||||||
|
script.onload = initializeViewer;
|
||||||
|
script.src = '/assets/o3dv/o3dv.min.js';
|
||||||
|
document.head.appendChild(script);
|
||||||
|
} else {
|
||||||
|
// Script is loading but OV not yet ready — wait for it
|
||||||
|
existingScript.addEventListener('load', initializeViewer);
|
||||||
|
}
|
||||||
|
} else {
|
||||||
|
// OV already loaded
|
||||||
|
initializeViewer();
|
||||||
|
}
|
||||||
|
}
|
||||||
|
};
|
||||||
|
|
||||||
|
// Run when the page is fully loaded
|
||||||
|
document.addEventListener('DOMContentLoaded', onPageChange);
|
||||||
|
|
||||||
|
const targetSelector = 'a.ui.mini.basic.button[href*="/raw/"]';
|
||||||
|
let lastHref = null;
|
||||||
|
let timeoutId = null;
|
||||||
|
|
||||||
|
const checkAndRun = () => {
|
||||||
|
const rawLink = document.querySelector(targetSelector);
|
||||||
|
if (!rawLink) return;
|
||||||
|
|
||||||
|
const currentHref = rawLink.getAttribute('href');
|
||||||
|
if (currentHref !== lastHref) {
|
||||||
|
lastHref = currentHref;
|
||||||
|
|
||||||
|
const fileName = currentHref.split('/').pop();
|
||||||
|
console.log('New Raw file link detected after delay:', fileName);
|
||||||
|
|
||||||
|
onPageChange();
|
||||||
}
|
}
|
||||||
|
};
|
||||||
|
|
||||||
|
const observer = new MutationObserver(() => {
|
||||||
|
// Delay execution by 300ms after last mutation
|
||||||
|
clearTimeout(timeoutId);
|
||||||
|
timeoutId = setTimeout(checkAndRun, 300);
|
||||||
|
});
|
||||||
|
|
||||||
|
observer.observe(document.body, {
|
||||||
|
childList: true,
|
||||||
|
subtree: true,
|
||||||
});
|
});
|
||||||
</script>
|
</script>
|
||||||
```
|
```
|
||||||
@@ -248,11 +317,17 @@ mkdir o3dv
|
|||||||
cd o3dv
|
cd o3dv
|
||||||
```
|
```
|
||||||
|
|
||||||
Copy latest release zip link from [`GitHub`](https://github.com/kovacsv/Online3DViewer/releases) (v0.15.0 as of now).
|
Copy latest release zip link from [`GitHub`](https://github.com/kovacsv/Online3DViewer/releases) (v0.18.0 as of now).
|
||||||
Here use e.g. wget to download the file:
|
Here use e.g. wget or curl to download the file:
|
||||||
|
|
||||||
```
|
```
|
||||||
wget https://github.com/kovacsv/Online3DViewer/releases/download/0.15.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:
|
Use e.g. unzip to unzip the archive:
|
||||||
@@ -262,20 +337,14 @@ unzip o3dv.zip
|
|||||||
|
|
||||||
#### Part 3: Folder permissions
|
#### Part 3: Folder permissions
|
||||||
|
|
||||||
Now the last thing. Change permissions on the "footer.tmpl":
|
Now the last thing. Change permissions on the public folder:
|
||||||
```
|
|
||||||
chown git:git $GITEA_CUSTOM/templates/custom/footer.tmpl
|
|
||||||
chmod 770 $GITEA_CUSTOM/templates/custom/footer.tmpl
|
|
||||||
```
|
|
||||||
|
|
||||||
And on the public folder:
|
|
||||||
```
|
```
|
||||||
chown -R git:git $GITEA_CUSTOM/public
|
chown -R git:git $GITEA_CUSTOM/public
|
||||||
```
|
```
|
||||||
|
|
||||||
Now we have everything ready! Restart your gitea instance to apply these changes and test it in your browser.
|
Now we have everything ready! Restart your gitea instance to apply these changes and test it in your browser.
|
||||||
|
|
||||||
You should end-up with a folder structure similar to this:
|
Sanity check. You should end-up with a folder structure similar to this:
|
||||||
|
|
||||||
```
|
```
|
||||||
$GITEA_CUSTOM/templates
|
$GITEA_CUSTOM/templates
|
||||||
@@ -284,7 +353,7 @@ $GITEA_CUSTOM/templates
|
|||||||
|
|
||||||
$GITEA_CUSTOM/public/assets/
|
$GITEA_CUSTOM/public/assets/
|
||||||
-- o3dv
|
-- o3dv
|
||||||
|-- o3dv_0.15.0.zip
|
|-- o3dv.zip
|
||||||
|-- o3dv.license.md
|
|-- o3dv.license.md
|
||||||
|-- o3dv.min.js
|
|-- o3dv.min.js
|
||||||
|-- envmaps
|
|-- envmaps
|
||||||
@@ -351,7 +420,7 @@ The [legacy file format](https://github.com/go-gitea/gitea/blob/main/options/lab
|
|||||||
|
|
||||||
`#hex-color label name ; label description`
|
`#hex-color label name ; label description`
|
||||||
|
|
||||||
For more information, see the [labels documentation](usage/labels.md).
|
For more information, see the [labels documentation](../usage/issues-prs/labels.md).
|
||||||
|
|
||||||
### Licenses
|
### Licenses
|
||||||
|
|
||||||
|
|||||||
@@ -10,6 +10,10 @@ aliases:
|
|||||||
|
|
||||||
Gitea has mailer functionality for sending transactional emails (such as registration confirmation). It can be configured to either use Sendmail (or compatible MTAs like Postfix and msmtp) or directly use SMTP server.
|
Gitea has mailer functionality for sending transactional emails (such as registration confirmation). It can be configured to either use Sendmail (or compatible MTAs like Postfix and msmtp) or directly use SMTP server.
|
||||||
|
|
||||||
|
:::note
|
||||||
|
Be sure to set ENABLE_NOTIFY_MAIL=true to allow Gitea to send email notifications. Check the [Config Cheat Sheet](../administration/config-cheat-sheet.md#service-service) for details.
|
||||||
|
:::
|
||||||
|
|
||||||
## Using Sendmail
|
## Using Sendmail
|
||||||
|
|
||||||
Use `sendmail` command as mailer.
|
Use `sendmail` command as mailer.
|
||||||
@@ -41,7 +45,7 @@ ENABLED = true
|
|||||||
FROM = gitea@mydomain.com
|
FROM = gitea@mydomain.com
|
||||||
PROTOCOL = smtps
|
PROTOCOL = smtps
|
||||||
SMTP_ADDR = mail.mydomain.com
|
SMTP_ADDR = mail.mydomain.com
|
||||||
SMTP_PORT = 587
|
SMTP_PORT = 465
|
||||||
USER = gitea@mydomain.com
|
USER = gitea@mydomain.com
|
||||||
PASSWD = `password`
|
PASSWD = `password`
|
||||||
```
|
```
|
||||||
@@ -56,7 +60,7 @@ For the full list of options check the [Config Cheat Sheet](../administration/co
|
|||||||
Authentication is only supported when the SMTP server communication is encrypted with TLS or `HOST=localhost`. TLS encryption can be through:
|
Authentication is only supported when the SMTP server communication is encrypted with TLS or `HOST=localhost`. TLS encryption can be through:
|
||||||
:::
|
:::
|
||||||
|
|
||||||
- STARTTLS (also known as Opportunistic TLS) via port 587. Initial connection is done over cleartext, but then be upgraded over TLS if the server supports it.
|
- STARTTLS (also known as Opportunistic TLS) via port 587 with `PROTOCOL=smtp+starttls`. Initial connection is done over cleartext, but then be upgraded over TLS if the server supports it.
|
||||||
- SMTPS connection (SMTP over TLS) via the default port 465. Connection to the server use TLS from the beginning.
|
- SMTPS connection (SMTP over TLS) via the default port 465. Connection to the server use TLS from the beginning.
|
||||||
- Forced SMTPS connection with `PROTOCOL=smtps`. (These are both known as Implicit TLS.)
|
- Forced SMTPS connection with `PROTOCOL=smtps`. (These are both known as Implicit TLS.)
|
||||||
This is due to protections imposed by the Go internal libraries against STRIPTLS attacks.
|
This is due to protections imposed by the Go internal libraries against STRIPTLS attacks.
|
||||||
|
|||||||
@@ -257,7 +257,6 @@ the messages. Here's a list of some of them:
|
|||||||
| `AppDomain` | - | Any | Gitea's host name |
|
| `AppDomain` | - | Any | Gitea's host name |
|
||||||
| `EllipsisString` | string, int | Any | Truncates a string to the specified length; adds ellipsis as needed |
|
| `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 |
|
| `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:
|
These are _functions_, not metadata, so they have to be used:
|
||||||
|
|
||||||
|
|||||||
@@ -14,6 +14,7 @@ aliases:
|
|||||||
2. Make the reverse-proxy pass `https://git.example.com/foo` to `http://gitea:3000/foo`.
|
2. Make the reverse-proxy pass `https://git.example.com/foo` to `http://gitea:3000/foo`.
|
||||||
3. Make sure the reverse-proxy does not decode the URI. The request `https://git.example.com/a%2Fb` should be passed as `http://gitea:3000/a%2Fb`.
|
3. Make sure the reverse-proxy does not decode the URI. The request `https://git.example.com/a%2Fb` should be passed as `http://gitea:3000/a%2Fb`.
|
||||||
4. Make sure `Host` and `X-Fowarded-Proto` headers are correctly passed to Gitea to make Gitea see the real URL being visited.
|
4. Make sure `Host` and `X-Fowarded-Proto` headers are correctly passed to Gitea to make Gitea see the real URL being visited.
|
||||||
|
5. Make sure your webserver has a certificate, including all intermediate and RootCA certificates, for `git clone` and `git pull` to work.
|
||||||
|
|
||||||
### Use a sub-path
|
### Use a sub-path
|
||||||
|
|
||||||
@@ -149,6 +150,20 @@ server {
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
## Nginx Proxy Manager
|
||||||
|
|
||||||
|
If you are using Nginx Proxy Manager to serve your Gitea instance it differs slighly from the raw Nginx.
|
||||||
|
|
||||||
|
It is [adding some directives](https://github.com/NginxProxyManager/nginx-proxy-manager/blob/master/docker/rootfs/etc/nginx/conf.d/include/proxy.conf) for a custom location by default, so you have to skip these from the above mentioned Nginx config. Otherwise Nginx will produce `400 bad request` error due to duplicated directives (`proxy_set_header Host $host` is the particularly problematic one).
|
||||||
|
|
||||||
|
So while creating the `/` Custom location, just add the following lines to it's configuration:
|
||||||
|
|
||||||
|
```nginx
|
||||||
|
client_max_body_size 512M;
|
||||||
|
proxy_set_header Connection $http_connection;
|
||||||
|
proxy_set_header Upgrade $http_upgrade;
|
||||||
|
```
|
||||||
|
|
||||||
## Apache HTTPD
|
## Apache HTTPD
|
||||||
|
|
||||||
If you want Apache HTTPD to serve your Gitea instance, you can add the following to your Apache HTTPD configuration (usually located at `/etc/apache2/httpd.conf` in Ubuntu):
|
If you want Apache HTTPD to serve your Gitea instance, you can add the following to your Apache HTTPD configuration (usually located at `/etc/apache2/httpd.conf` in Ubuntu):
|
||||||
@@ -195,6 +210,50 @@ Then you **MUST** set something like `[server] ROOT_URL = http://git.example.com
|
|||||||
The following Apache HTTPD mods must be enabled: `proxy`, `proxy_http`.
|
The following Apache HTTPD mods must be enabled: `proxy`, `proxy_http`.
|
||||||
:::
|
:::
|
||||||
|
|
||||||
|
## Apache HTTPD and serve static resources directly
|
||||||
|
|
||||||
|
We can tune the performance in splitting requests into categories static and dynamic.
|
||||||
|
|
||||||
|
CSS files, JavaScript files, images and web fonts are static content.
|
||||||
|
The front page, a repository view or issue list is dynamic content.
|
||||||
|
|
||||||
|
Apache HTTPD can serve static resources directly and proxy only the dynamic requests to Gitea.
|
||||||
|
|
||||||
|
Download a snapshot of the Gitea source repository to `/path/to/gitea/`.
|
||||||
|
After this, run `make frontend` in the repository directory to generate the static resources. We are only interested in the `public/` directory for this task, so you can delete the rest.
|
||||||
|
(You will need to have [Node with npm](https://nodejs.org/en/download/) and `make` installed to generate the static resources)
|
||||||
|
|
||||||
|
Depending on the scale of your user base, you might want to split the traffic to two distinct servers,
|
||||||
|
or use a cdn for the static files.
|
||||||
|
|
||||||
|
### Single node and single domain
|
||||||
|
|
||||||
|
Set `[server] STATIC_URL_PREFIX = /_/static` in your configuration.
|
||||||
|
|
||||||
|
```apacheconf
|
||||||
|
<VirtualHost *:80>
|
||||||
|
...
|
||||||
|
<Proxy *>
|
||||||
|
Order allow,deny
|
||||||
|
Allow from all
|
||||||
|
</Proxy>
|
||||||
|
|
||||||
|
ProxyPass /_/static/ !
|
||||||
|
Alias /_/static/ /path/to/gitea/public/
|
||||||
|
<Directory /path/to/gitea/public/>
|
||||||
|
Options FollowSymlinks
|
||||||
|
AllowOverride None
|
||||||
|
Require all granted
|
||||||
|
</Directory>
|
||||||
|
|
||||||
|
AllowEncodedSlashes NoDecode
|
||||||
|
# Note: no trailing slash after either /git or port
|
||||||
|
ProxyPass / http://localhost:3000/ nocanon
|
||||||
|
ProxyPreserveHost On
|
||||||
|
RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
|
||||||
|
</VirtualHost>
|
||||||
|
```
|
||||||
|
|
||||||
## Caddy
|
## Caddy
|
||||||
|
|
||||||
If you want Caddy to serve your Gitea instance, you can add the following server block to your Caddyfile:
|
If you want Caddy to serve your Gitea instance, you can add the following server block to your Caddyfile:
|
||||||
|
|||||||
@@ -6,12 +6,14 @@ aliases:
|
|||||||
- /en-us/signing
|
- /en-us/signing
|
||||||
---
|
---
|
||||||
|
|
||||||
# GPG Commit Signatures
|
# GPG/SSH Commit Signatures
|
||||||
|
|
||||||
Gitea will verify GPG commit signatures in the provided tree by
|
Gitea will verify gpg/ssh commit signatures in the provided tree by
|
||||||
checking if the commits are signed by a key within the Gitea database,
|
checking if the commits are signed by a key within the Gitea database,
|
||||||
or if the commit matches the default key for Git.
|
or if the commit matches the default key for Git.
|
||||||
|
|
||||||
|
Additionally Gitea will verify commits signed by ssh keys, which public keys are part of [`TRUSTED_SSH_KEYS`](#general-configuration).
|
||||||
|
|
||||||
Keys are not checked to determine if they have expired or revoked.
|
Keys are not checked to determine if they have expired or revoked.
|
||||||
Keys are also not checked with keyservers.
|
Keys are also not checked with keyservers.
|
||||||
|
|
||||||
@@ -46,6 +48,11 @@ for GPG - in particular it is probably advisable to only install a
|
|||||||
signing secret subkey without the master signing and certifying secret
|
signing secret subkey without the master signing and certifying secret
|
||||||
key.
|
key.
|
||||||
|
|
||||||
|
## Installing and generating a SSH key for Gitea
|
||||||
|
|
||||||
|
You can run `ssh-keygen -t ed25519 -f gitea-signing-key` to generate the private/public keypair for commit signing without any password. Usually you would store the key next to the gitea configuration, then point `SIGNING_KEY` to the generated public key `/path/to/gitea-signing-key.pub`. Gitea generates all its commits using the server `git` command at present - and therefore the server `ssh-keygen` will be used for
|
||||||
|
signing (if configured.)
|
||||||
|
|
||||||
## General Configuration
|
## General Configuration
|
||||||
|
|
||||||
Gitea's configuration for signing can be found with the
|
Gitea's configuration for signing can be found with the
|
||||||
@@ -65,16 +72,41 @@ MERGES = pubkey, twofa, basesigned, commitssigned
|
|||||||
...
|
...
|
||||||
```
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
For SSH commit signing, you need to specify the `SIGNING_FORMAT` to `ssh` instead of the default `openpgp`. `SIGNING_NAME` and `SIGNING_EMAIL` are required for verifing the signatures.
|
||||||
|
|
||||||
|
This looks like this:
|
||||||
|
|
||||||
|
```ini
|
||||||
|
...
|
||||||
|
[repository.signing]
|
||||||
|
SIGNING_KEY = /path/to/gitea-signing-key.pub
|
||||||
|
SIGNING_NAME =
|
||||||
|
SIGNING_EMAIL =
|
||||||
|
SIGNING_FORMAT = ssh
|
||||||
|
INITIAL_COMMIT = always
|
||||||
|
CRUD_ACTIONS = pubkey, twofa, parentsigned
|
||||||
|
WIKI = never
|
||||||
|
MERGES = pubkey, twofa, basesigned, commitssigned
|
||||||
|
...
|
||||||
|
```
|
||||||
|
|
||||||
|
- `/path/to/gitea-signing-key` is expected to be the private key for `/path/to/gitea-signing-key.pub` [see here how to generate a new ssh keypair](#installing-and-generating-a-ssh-key-for-gitea).
|
||||||
|
- `TRUSTED_SSH_KEYS = ssh-<algorithm> <key>` or `TRUSTED_SSH_KEYS = ssh-<algorithm> <key1>, ssh-<algorithm> <key2>` can be used for rotating the global ssh signing key to continue verifying commits signed by the previous keys.
|
||||||
|
|
||||||
### `SIGNING_KEY`
|
### `SIGNING_KEY`
|
||||||
|
|
||||||
The first option to discuss is the `SIGNING_KEY`. There are three main
|
The first option to discuss is the `SIGNING_KEY`. There are three main
|
||||||
options:
|
options:
|
||||||
|
|
||||||
- `none` - this prevents Gitea from signing any commits
|
- `none` - this prevents Gitea from signing any commits
|
||||||
- `default` - Gitea will default to the key configured within `git config`
|
- `default` - Gitea will default to the gpg key configured within `git config`
|
||||||
- `KEYID` - Gitea will sign commits with the gpg key with the ID
|
- `KEYID` - Gitea will sign commits with the gpg key with the ID
|
||||||
`KEYID`. In this case you should provide a `SIGNING_NAME` and
|
`KEYID`. In this case you should provide a `SIGNING_NAME` and
|
||||||
`SIGNING_EMAIL` to be displayed for this key.
|
`SIGNING_EMAIL` to be displayed for this key.
|
||||||
|
- `/path/to/gitea-signing-key.pub` - Gitea will sign commits with the ssh key without the `.pub` suffix `/path/to/gitea-signing-key`. In this case you should provide a `SIGNING_NAME` and
|
||||||
|
`SIGNING_EMAIL` to be displayed for this key and set `SIGNING_FORMAT` to `ssh`.
|
||||||
|
|
||||||
The `default` option will interrogate `git config` for
|
The `default` option will interrogate `git config` for
|
||||||
`commit.gpgsign` option - if this is set, then it will use the results
|
`commit.gpgsign` option - if this is set, then it will use the results
|
||||||
@@ -97,6 +129,10 @@ Related home files for git command (like `.gnupg`) should also be put in Gitea's
|
|||||||
If you like to keep the `.gnupg` directory outside of `{[git].HOME_PATH}/`, consider setting the `$GNUPGHOME` environment variable to your preferred location, otherwise Gitea will use the gpg keys only under `{[git].HOME_PATH}/.gnupg`.
|
If you like to keep the `.gnupg` directory outside of `{[git].HOME_PATH}/`, consider setting the `$GNUPGHOME` environment variable to your preferred location, otherwise Gitea will use the gpg keys only under `{[git].HOME_PATH}/.gnupg`.
|
||||||
:::
|
:::
|
||||||
|
|
||||||
|
:::warning
|
||||||
|
The default option and repository specific signing keys are not supported for ssh keys
|
||||||
|
:::
|
||||||
|
|
||||||
### `INITIAL_COMMIT`
|
### `INITIAL_COMMIT`
|
||||||
|
|
||||||
This option determines whether Gitea should sign the initial commit
|
This option determines whether Gitea should sign the initial commit
|
||||||
@@ -168,3 +204,9 @@ In cases where there is a repository specific key this can be obtained from:
|
|||||||
```sh
|
```sh
|
||||||
/api/v1/repos/:username/:reponame/signing-key.gpg
|
/api/v1/repos/:username/:reponame/signing-key.gpg
|
||||||
```
|
```
|
||||||
|
|
||||||
|
For ssh commit signing the default ssh public key can be obtained via the API at:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
/api/v1/signing-key.pub
|
||||||
|
```
|
||||||
@@ -0,0 +1,9 @@
|
|||||||
|
{
|
||||||
|
"label": "Contributing",
|
||||||
|
"position": 35,
|
||||||
|
"link": {
|
||||||
|
"type": "generated-index",
|
||||||
|
"slug": "/contributing",
|
||||||
|
"title": "Contributing"
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -0,0 +1,76 @@
|
|||||||
|
---
|
||||||
|
slug: "contributing"
|
||||||
|
sidebar_position: 1
|
||||||
|
---
|
||||||
|
|
||||||
|
# Contributing to Gitea
|
||||||
|
|
||||||
|
Thank you for your interest in contributing to Gitea! This guide will help you understand how to contribute to the project effectively.
|
||||||
|
|
||||||
|
## Getting Started
|
||||||
|
|
||||||
|
Before you start contributing, please read our [Hacking on Gitea](../development/hacking-on-gitea.md) guide to set up your development environment.
|
||||||
|
|
||||||
|
## Contribution Guidelines
|
||||||
|
|
||||||
|
We have specific guidelines for different types of contributions:
|
||||||
|
|
||||||
|
### Backend Development
|
||||||
|
|
||||||
|
If you're working on backend code (Go), please follow our [Guidelines for Backend Development](guidelines-backend.md). This includes:
|
||||||
|
|
||||||
|
- Package design and dependencies
|
||||||
|
- Database operations and migrations
|
||||||
|
- Testing strategies
|
||||||
|
- Code organization
|
||||||
|
|
||||||
|
### Frontend Development
|
||||||
|
|
||||||
|
For frontend contributions (JavaScript, CSS, Vue), refer to our [Guidelines for Frontend Development](guidelines-frontend.md). This covers:
|
||||||
|
|
||||||
|
- Framework usage (Vue3, Fomantic-UI)
|
||||||
|
- Code style and best practices
|
||||||
|
- Accessibility requirements
|
||||||
|
- TypeScript usage
|
||||||
|
|
||||||
|
### Refactoring
|
||||||
|
|
||||||
|
When refactoring existing code, follow our [Guidelines for Refactoring](guidelines-refactoring.md) to ensure:
|
||||||
|
|
||||||
|
- Clear refactoring objectives
|
||||||
|
- Proper review process
|
||||||
|
- Maintaining backward compatibility
|
||||||
|
- Incremental improvements
|
||||||
|
|
||||||
|
### Localization
|
||||||
|
|
||||||
|
To contribute translations or localization improvements, see our [Localization Guide](localization.md) which explains:
|
||||||
|
|
||||||
|
- How to contribute translations via Crowdin
|
||||||
|
- Supported languages
|
||||||
|
- Translation workflow
|
||||||
|
|
||||||
|
## Code of Conduct
|
||||||
|
|
||||||
|
Please be respectful and constructive in all interactions with the community. We are committed to providing a welcoming and inclusive environment for all contributors.
|
||||||
|
|
||||||
|
## Getting Help
|
||||||
|
|
||||||
|
If you need help with your contribution:
|
||||||
|
|
||||||
|
- Join our [Discord](https://discord.gg/gitea) #Develop channel
|
||||||
|
- Visit our [Forum](https://forum.gitea.com/)
|
||||||
|
- Check existing [GitHub Issues](https://github.com/go-gitea/gitea/issues)
|
||||||
|
|
||||||
|
## Submitting Your Contribution
|
||||||
|
|
||||||
|
1. Fork the repository
|
||||||
|
2. Create a feature branch
|
||||||
|
3. Make your changes following the relevant guidelines
|
||||||
|
4. Write tests for your changes
|
||||||
|
5. Ensure all tests pass
|
||||||
|
6. Submit a pull request
|
||||||
|
|
||||||
|
For more details, see our [CONTRIBUTING.md](https://github.com/go-gitea/gitea/blob/main/CONTRIBUTING.md) in the main repository.
|
||||||
|
|
||||||
|
Thank you for helping make Gitea better!
|
||||||
@@ -0,0 +1,9 @@
|
|||||||
|
{
|
||||||
|
"label": "Development",
|
||||||
|
"position": 40,
|
||||||
|
"link": {
|
||||||
|
"type": "generated-index",
|
||||||
|
"slug": "/development",
|
||||||
|
"title": "Development"
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -20,14 +20,33 @@ Gitea supports these methods of API authentication:
|
|||||||
- `token=...` parameter in URL query string
|
- `token=...` parameter in URL query string
|
||||||
- `access_token=...` parameter in URL query string
|
- `access_token=...` parameter in URL query string
|
||||||
- `Authorization: token ...` header in HTTP headers
|
- `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
|
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,
|
better understand this by looking at the code -- as of this writing,
|
||||||
Gitea parses queries and headers to find the token in
|
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).
|
[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
|
## 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.
|
||||||
|
|
||||||
|
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
|
A new token can be generated with a `POST` request to
|
||||||
`/users/:name/tokens`.
|
`/users/:name/tokens`.
|
||||||
|
|
||||||
@@ -35,7 +54,8 @@ Note that `/users/:name/tokens` is a special endpoint and requires you
|
|||||||
to authenticate using `BasicAuth` and a password, as follows:
|
to authenticate using `BasicAuth` and a password, as follows:
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
$ curl -H "Content-Type: application/json" -d '{"name":test_token","scopes":["read:activitypub","read:issue", "write:misc", "read:notification", "read:organization", "read:package", "read:repository", "read:user"]}'
|
$ curl -H "Content-Type: application/json" \
|
||||||
|
-d '{"name":"test_token","scopes":["read:activitypub","read:issue", "write:misc", "read:notification", "read:organization", "read:package", "read:repository", "read:user"]}' \
|
||||||
-u 'username:password' "https://gitea.your.host/api/v1/users/{username}/tokens"
|
-u 'username:password' "https://gitea.your.host/api/v1/users/{username}/tokens"
|
||||||
{"id":1,"name":"test_token","sha1":"9fcb1158165773dd010fca5f0cf7174316c3e37d","token_last_eight":"16c3e37d"}
|
{"id":1,"name":"test_token","sha1":"9fcb1158165773dd010fca5f0cf7174316c3e37d","token_last_eight":"16c3e37d"}
|
||||||
```
|
```
|
||||||
@@ -49,6 +69,25 @@ $ curl --url https://yourusername:[email protected]/api/v1/users/<usernam
|
|||||||
[{"name":"test","sha1":"","token_last_eight:"........":},{"name":"dev","sha1":"","token_last_eight":"........"}]
|
[{"name":"test","sha1":"","token_last_eight:"........":},{"name":"dev","sha1":"","token_last_eight":"........"}]
|
||||||
```
|
```
|
||||||
|
|
||||||
|
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`
|
||||||
|
- `misc`
|
||||||
|
- `notification`
|
||||||
|
- `organization`
|
||||||
|
- `package`
|
||||||
|
- `repository`
|
||||||
|
- `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
|
||||||
|
```
|
||||||
|
Special permissions `all` may be specified as `"scopes":["all"]`, which sets all permissions to both Read & Write.
|
||||||
|
|
||||||
To use the API with basic authentication with two factor authentication
|
To use the API with basic authentication with two factor authentication
|
||||||
enabled, you'll need to send an additional header that contains the one
|
enabled, you'll need to send an additional header that contains the one
|
||||||
time password (6 digitrotating token).
|
time password (6 digitrotating token).
|
||||||
|
|||||||
@@ -174,7 +174,7 @@ server as mentioned above.
|
|||||||
|
|
||||||
### Working on JS and CSS
|
### Working on JS and CSS
|
||||||
|
|
||||||
Frontend development should follow [Guidelines for Frontend Development](contributing/guidelines-frontend.md)
|
Frontend development should follow [Guidelines for Frontend Development](../contributing/guidelines-frontend.md)
|
||||||
|
|
||||||
To build with frontend resources, either use the `watch-frontend` target mentioned above or just build once:
|
To build with frontend resources, either use the `watch-frontend` target mentioned above or just build once:
|
||||||
|
|
||||||
|
|||||||
@@ -0,0 +1,9 @@
|
|||||||
|
{
|
||||||
|
"label": "Help",
|
||||||
|
"position": 5,
|
||||||
|
"link": {
|
||||||
|
"type": "generated-index",
|
||||||
|
"slug": "/help",
|
||||||
|
"title": "Help"
|
||||||
|
}
|
||||||
|
}
|
||||||
+4
-4
@@ -13,7 +13,7 @@ Gitea was originally forked from [Gogs](https://gogs.io) and almost all the code
|
|||||||
|
|
||||||
:::warning
|
:::warning
|
||||||
|
|
||||||
Gitea does not sent or cherry-picked commits from upstream, so there is no guarantee it will work if you upgrade from Gogs to Gitea. The recommended method is to migrate repositories from Gogs to Gitea.
|
Gitea does not send commits to upstream or cherry-pick commits from it, so there is no guarantee it will work if you upgrade from Gogs to Gitea. The recommended method is to migrate repositories from Gogs to Gitea.
|
||||||
|
|
||||||
:::
|
:::
|
||||||
|
|
||||||
@@ -31,11 +31,11 @@ You can try it out using [the online demo](https://demo.gitea.com).
|
|||||||
|
|
||||||
- **Code Hosting**
|
- **Code Hosting**
|
||||||
|
|
||||||
Gitea supports creating and managing repositories, browsing commit history and code files, reviewing and merging code submissions, managing collaborators, handling branches, and more. It also supports many common Git features such as tags, Cherry-pick, hooks, integrated collaboration tools, and more.
|
Gitea supports creating and managing repositories, browsing commit history and code files, reviewing and merging code submissions, managing collaborators, handling branches, and more. It also supports many common Git features such as tags, cherry-picking, hooks, integrated collaboration tools, and more.
|
||||||
|
|
||||||
- **Lightweight and Fast**
|
- **Lightweight and Fast**
|
||||||
|
|
||||||
One of Gitea's design goals is to be lightweight and fast in response. Unlike some large code hosting platforms, it remains lean, performs well in terms of speed, and is suitable for resource-limited server environments. Due to its lightweight design, Gitea has relatively low resource consumption and performs well in resource-constrained environments.
|
One of Gitea's design goals is to be lightweight and fast in response. Unlike some large code hosting platforms, it remains lean, performs well in terms of speed, and is suitable for resource-limited server environments.
|
||||||
|
|
||||||
- **Easy Deployment and Maintenance**
|
- **Easy Deployment and Maintenance**
|
||||||
|
|
||||||
@@ -105,6 +105,6 @@ For more detailed information, please refer to: https://docs.gitea.com/installat
|
|||||||
- [github.com/mattn/go-sqlite3](https://github.com/mattn/go-sqlite3)
|
- [github.com/mattn/go-sqlite3](https://github.com/mattn/go-sqlite3)
|
||||||
- [github.com/denisenkom/go-mssqldb](https://github.com/denisenkom/go-mssqldb)
|
- [github.com/denisenkom/go-mssqldb](https://github.com/denisenkom/go-mssqldb)
|
||||||
|
|
||||||
## Integrated support
|
## Integrated Support
|
||||||
|
|
||||||
Please visit [Awesome Gitea](https://gitea.com/gitea/awesome-gitea/) to get more third-party integrated support
|
Please visit [Awesome Gitea](https://gitea.com/gitea/awesome-gitea/) to get more third-party integrated support
|
||||||
@@ -0,0 +1,9 @@
|
|||||||
|
{
|
||||||
|
"label": "Installation",
|
||||||
|
"position": 10,
|
||||||
|
"link": {
|
||||||
|
"type": "generated-index",
|
||||||
|
"slug": "/installation",
|
||||||
|
"title": "Installation"
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -46,7 +46,7 @@ Gitea signs all binaries with a [GPG key](https://keys.openpgp.org/search?q=teab
|
|||||||
To validate the binary, download the signature file which ends in `.asc` for the binary you downloaded and use the GPG command line tool.
|
To validate the binary, download the signature file which ends in `.asc` for the binary you downloaded and use the GPG command line tool.
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
gpg --keyserver keys.openpgp.org --recv 7C9E68152594688862D62AF62D9AE806EC1592E2
|
gpg --keyserver hkps://keys.openpgp.org --recv 7C9E68152594688862D62AF62D9AE806EC1592E2
|
||||||
gpg --verify gitea-@version@-linux-amd64.asc gitea-@version@-linux-amd64
|
gpg --verify gitea-@version@-linux-amd64.asc gitea-@version@-linux-amd64
|
||||||
```
|
```
|
||||||
|
|
||||||
@@ -139,15 +139,15 @@ export GITEA_WORK_DIR=/var/lib/gitea/
|
|||||||
cp gitea /usr/local/bin/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`
|
### Adding shell autocompletion (from 1.25)
|
||||||
or sourced within your `.bashrc`.
|
|
||||||
|
|
||||||
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
|
Shell completion can be generated directly from binary with:
|
||||||
`.zshrc`.
|
```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
|
## Running Gitea
|
||||||
|
|
||||||
|
|||||||
@@ -178,15 +178,14 @@ LDFLAGS="-linkmode external -extldflags '-static' $LDFLAGS" TAGS="netgo osusergo
|
|||||||
|
|
||||||
This can be combined with `CC`, `GOOS`, and `GOARCH` as above.
|
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`
|
Shell completion can be generated directly from binary with:
|
||||||
or copied as `/usr/share/bash-completion/completions/gitea`.
|
```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
|
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.
|
||||||
`.zshrc`.
|
|
||||||
|
|
||||||
YMMV and these scripts may need further improvement.
|
|
||||||
|
|
||||||
## Compile or cross-compile using Linux with Zig
|
## Compile or cross-compile using Linux with Zig
|
||||||
|
|
||||||
|
|||||||
@@ -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).
|
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.
|
|
||||||
@@ -331,320 +331,6 @@ services:
|
|||||||
- GITEA__security__INTERNAL_TOKEN=[value returned by generate secret INTERNAL_TOKEN]
|
- 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 `~/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
|
### 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)
|
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.
|
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.
|
||||||
@@ -0,0 +1,9 @@
|
|||||||
|
{
|
||||||
|
"label": "Usage",
|
||||||
|
"position": 35,
|
||||||
|
"link": {
|
||||||
|
"type": "generated-index",
|
||||||
|
"slug": "/usage",
|
||||||
|
"title": "Usage"
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -0,0 +1,9 @@
|
|||||||
|
{
|
||||||
|
"label": "Access Control",
|
||||||
|
"position": 100,
|
||||||
|
"link": {
|
||||||
|
"type": "generated-index",
|
||||||
|
"slug": "/usage/access-control",
|
||||||
|
"description": "Permissions, security, and access control features"
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -0,0 +1,47 @@
|
|||||||
|
---
|
||||||
|
date: "2024-01-31T00:00:00+00:00"
|
||||||
|
slug: "blocking-user"
|
||||||
|
sidebar_position: 25
|
||||||
|
aliases:
|
||||||
|
- /blocking-user
|
||||||
|
---
|
||||||
|
|
||||||
|
# Blocking a user
|
||||||
|
|
||||||
|
Gitea supports blocking of users to restrict how they can interact with you and your content.
|
||||||
|
|
||||||
|
You can block a user in your account settings, from the user's profile or from comments created by the user.
|
||||||
|
The user is not directly notified about the block, but they can notice they are blocked when they attempt to interact with you.
|
||||||
|
Organization owners can block anyone who is not a member of the organization too.
|
||||||
|
If a blocked user has admin permissions, they can still perform all actions even if blocked.
|
||||||
|
|
||||||
|
### When you block a user
|
||||||
|
|
||||||
|
- the user stops following you
|
||||||
|
- you stop following the user
|
||||||
|
- the user's stars are removed from your repositories
|
||||||
|
- your stars are removed from their repositories
|
||||||
|
- the user stops watching your repositories
|
||||||
|
- you stop watching their repositories
|
||||||
|
- the user's issue assignments are removed from your repositories
|
||||||
|
- your issue assignments are removed from their repositories
|
||||||
|
- the user is removed as a collaborator on your repositories
|
||||||
|
- you are removed as a collaborator on their repositories
|
||||||
|
- any pending repository transfers to or from the blocked user are canceled
|
||||||
|
|
||||||
|
### When you block a user, the user cannot
|
||||||
|
|
||||||
|
- follow you
|
||||||
|
- watch your repositories
|
||||||
|
- star your repositories
|
||||||
|
- fork your repositories
|
||||||
|
- transfer repositories to you
|
||||||
|
- open issues or pull requests on your repositories
|
||||||
|
- comment on issues or pull requests you've created
|
||||||
|
- comment on issues or pull requests on your repositories
|
||||||
|
- react to your comments on issues or pull requests
|
||||||
|
- react to comments on issues or pull requests on your repositories
|
||||||
|
- assign you to issues or pull requests
|
||||||
|
- add you as a collaborator on their repositories
|
||||||
|
- send you notifications by @mentioning your username
|
||||||
|
- be added as team member (if blocked by an organization)
|
||||||
+2
-3
@@ -1,11 +1,10 @@
|
|||||||
---
|
---
|
||||||
date: "2021-12-13:10:10+08:00"
|
date: "2021-12-13:10:10+08:00"
|
||||||
|
|
||||||
slug: "permissions"
|
slug: "permissions"
|
||||||
sidebar_position: 14
|
sidebar_position: 14
|
||||||
|
|
||||||
aliases:
|
aliases:
|
||||||
- /en-us/permissions
|
- /en-us/permissions
|
||||||
|
- /permissions
|
||||||
---
|
---
|
||||||
|
|
||||||
# Permissions
|
# Permissions
|
||||||
@@ -41,7 +40,7 @@ With different permissions, people could do different things with these units.
|
|||||||
| Wiki | View wiki pages. Clone the wiki repository. | Create/Edit wiki pages, push | - |
|
| Wiki | View wiki pages. Clone the wiki repository. | Create/Edit wiki pages, push | - |
|
||||||
| ExternalWiki | Link to an external wiki | - | - |
|
| ExternalWiki | Link to an external wiki | - | - |
|
||||||
| ExternalTracker | Link to an external issue tracker | - | - |
|
| ExternalTracker | Link to an external issue tracker | - | - |
|
||||||
| Projects | View the boards | Change issues across boards | - |
|
| Projects | View the columns of projects | Change issues across columns | - |
|
||||||
| Packages | View the packages | Upload/Delete packages | - |
|
| Packages | View the packages | Upload/Delete packages | - |
|
||||||
| Actions | View the Actions logs | Approve / Cancel / Restart | - |
|
| Actions | View the Actions logs | Approve / Cancel / Restart | - |
|
||||||
| Settings | - | - | Manage the repository |
|
| Settings | - | - | Manage the repository |
|
||||||
@@ -0,0 +1,90 @@
|
|||||||
|
---
|
||||||
|
date: "2025-11-20T00:00:00-07:00"
|
||||||
|
slug: "protected-branches"
|
||||||
|
sidebar_position: 44
|
||||||
|
aliases:
|
||||||
|
- /en-us/protected-branches
|
||||||
|
- /en-us/protected-branch
|
||||||
|
- /protected-branches
|
||||||
|
---
|
||||||
|
|
||||||
|
# Protected branches
|
||||||
|
|
||||||
|
Protected branches prevent unwanted changes by enforcing push and merge policies on selected branches. The rules are enforced for every Git protocol (HTTP(S), SSH), the web editor, the API, and background jobs such as auto-merge. Only repository owners and administrators can manage the rules, and the Branches page is read-only while a repository is archived.
|
||||||
|
|
||||||
|
## Creating or editing a rule
|
||||||
|
|
||||||
|
1. Open the repository and select **Settings → Branches** (repository admin permission required).
|
||||||
|
2. Select **Add new rule** or **Edit** next to an existing rule.
|
||||||
|
3. Fill in the **Protected branch name pattern** and optional file patterns, then configure the push, merge, and review options described below.
|
||||||
|
4. Select **Save rule**.
|
||||||
|
|
||||||
|
The rule immediately applies to all matching branches, even if the branches are created in the future.
|
||||||
|
|
||||||
|
## Rule matching and priorities
|
||||||
|
|
||||||
|
- The **Protected branch name pattern** accepts [glob](https://github.com/gobwas/glob) expressions and matches the entire branch name. Patterns are case-sensitive. Using a simple name such as `main` without glob special characters always matches that specific branch (case-insensitive).
|
||||||
|
- If multiple rules match the same branch, only the first rule is used. Reorder the list on the **Branches** page by dragging the grab handle. The first entry (priority 1) has the highest priority, so place patterns such as `main` or `release/*` before generic fallbacks such as `*`.
|
||||||
|
|
||||||
|
Example patterns:
|
||||||
|
|
||||||
|
| Pattern | Matches |
|
||||||
|
| -------------- | ------------------------------- |
|
||||||
|
| `main` | The `main` branch only |
|
||||||
|
| `release/*` | `release/v1.0`, `release/april` |
|
||||||
|
| `hotfix/**` | Nested branches such as `hotfix/security/CVE` |
|
||||||
|
| `*` | Every branch (use as a fallback) |
|
||||||
|
|
||||||
|
### File-level pattern controls
|
||||||
|
|
||||||
|
- **Protected file patterns** block changes to sensitive files (for example `.drone.yml` or `/docs/**/*.txt`). Patterns are case-insensitive and separated by semicolons. Commits and merge attempts that touch one of the files are rejected.
|
||||||
|
- **Unprotected file patterns** do the opposite: if pushes are blocked, users with write access can still push commits that modify only the listed files. This is useful for letting contributors update documentation while still requiring pull requests for code.
|
||||||
|
|
||||||
|
Both fields use the same `glob` syntax and match paths relative to the repository root.
|
||||||
|
|
||||||
|
## Controlling direct pushes
|
||||||
|
|
||||||
|
The **Push** section controls direct pushes (including the web editor and API).
|
||||||
|
|
||||||
|
- **Disable push** makes the branch read-only. Any attempt to push directly fails, and changes must be merged through pull requests.
|
||||||
|
- **Enable push** allows anyone with [write access](./permissions.md) to push (force pushes are still blocked unless explicitly allowed).
|
||||||
|
- **Allowlist restricted push** requires being on the allowlist. Choose users and, for organization-owned repositories, teams. Deploy keys that already have write access can also be allowlisted.
|
||||||
|
|
||||||
|
When a push is blocked, the server-side hook rejects the update with an explanation.
|
||||||
|
|
||||||
|
### Force pushes
|
||||||
|
|
||||||
|
Force pushes have their own set of options:
|
||||||
|
|
||||||
|
- **Disable force push** completely forbids rewriting history on the branch.
|
||||||
|
- **Enable force push** allows anyone who can push to also force push.
|
||||||
|
- **Allowlist restricted force push** limits force pushes to a separate allowlist (users, teams, and optionally deploy keys) **and** requires the person to already have regular push access.
|
||||||
|
|
||||||
|
## Pull request merges and approvals
|
||||||
|
|
||||||
|
- **Merge allowlist**: keep the default to let anyone with write access merge pull requests, or enable the allowlist to restrict merges to selected users/teams.
|
||||||
|
- **Required approvals**: specify how many approvals are needed before a merge is allowed. Reviews from users with write access count, unless the **Restrict approvals to allowlisted users or teams** option is enabled.
|
||||||
|
- **Dismiss stale approvals** removes existing approvals whenever new commits that change the pull request content are pushed.
|
||||||
|
- **Ignore stale approvals** keeps approvals but does not count reviews that were made on older commits. This option is disabled while dismissal of stale approvals is enabled.
|
||||||
|
- **Block merge on rejected reviews** prevents merging while any official reviewer has requested changes.
|
||||||
|
- **Block merge on official review requests** blocks merges while there are outstanding review requests (for example when CODEOWNERS requires a review).
|
||||||
|
- **Block merge if the pull request is outdated** makes sure the head branch is up to date with the base branch before it can be merged.
|
||||||
|
- **Administrators must follow branch protection rules** removes the ability for repository administrators to bypass the rules with the "Force merge" button.
|
||||||
|
|
||||||
|
Protected file patterns apply to pull requests as well. When a pull request changes one of the protected files, the pull request banner shows the affected paths and merging stays disabled.
|
||||||
|
|
||||||
|
## Status checks
|
||||||
|
|
||||||
|
Enable status checks to require one or more CI jobs to succeed before merging:
|
||||||
|
|
||||||
|
1. Check **Enable status check**.
|
||||||
|
2. Enter one pattern per line in **Status check patterns**. Each pattern is a `glob` expression that matches the context name reported by Actions, Drone, Woodpecker, or another Check API client (for example `actions/test-*`).
|
||||||
|
3. Pick contexts from the table of jobs that have reported results in the last week to verify their names.
|
||||||
|
|
||||||
|
When the option is active, Gitea requires at least one context that matches each pattern to report success on the pull request head commit. An empty list is not allowed; use `*` to require the latest commit to be successful regardless of the context name.
|
||||||
|
|
||||||
|
## Signed commits and other safeguards
|
||||||
|
|
||||||
|
- **Require signed commits** rejects pushes that contain unsigned or unverifiable commits. The check runs inside the server hook before the push is accepted.
|
||||||
|
- **Protected file patterns** (see above) prevent both pushes and merges that modify sensitive files.
|
||||||
|
- **Unprotected file patterns** allow limited pushes while keeping the branch protected.
|
||||||
+1
-3
@@ -1,12 +1,10 @@
|
|||||||
---
|
---
|
||||||
date: "2021-05-14T00:00:00-00:00"
|
date: "2021-05-14T00:00:00-00:00"
|
||||||
|
|
||||||
slug: "protected-tags"
|
slug: "protected-tags"
|
||||||
sidebar_position: 45
|
sidebar_position: 45
|
||||||
|
|
||||||
aliases:
|
aliases:
|
||||||
- /en-us/protected-tags
|
- /en-us/protected-tags
|
||||||
|
- /protected-tags
|
||||||
---
|
---
|
||||||
|
|
||||||
# Protected tags
|
# Protected tags
|
||||||
@@ -0,0 +1,9 @@
|
|||||||
|
{
|
||||||
|
"label": "Actions",
|
||||||
|
"position": 30,
|
||||||
|
"link": {
|
||||||
|
"type": "generated-index",
|
||||||
|
"slug": "/usage/actions",
|
||||||
|
"description": "Automating workflows with Actions"
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -0,0 +1,459 @@
|
|||||||
|
---
|
||||||
|
date: "2023-04-27T15:00:00+08:00"
|
||||||
|
slug: "act-runner"
|
||||||
|
sidebar_position: 20
|
||||||
|
---
|
||||||
|
|
||||||
|
# Act Runner
|
||||||
|
|
||||||
|
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 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.
|
||||||
|
|
||||||
|
There are multiple ways to install the act runner.
|
||||||
|
|
||||||
|
## Installation with binary
|
||||||
|
|
||||||
|
### Download the binary
|
||||||
|
|
||||||
|
You can download the binary from the [release page](https://gitea.com/gitea/act_runner/releases).
|
||||||
|
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.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
chmod +x act_runner
|
||||||
|
./act_runner --version
|
||||||
|
```
|
||||||
|
|
||||||
|
If you see the version information, it means that you have downloaded the correct binary.
|
||||||
|
|
||||||
|
### Obtain a registration token
|
||||||
|
|
||||||
|
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.
|
||||||
|
- Repository level: The runner will run jobs for the repository it belongs to.
|
||||||
|
|
||||||
|
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 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`.
|
||||||
|
- Repository level: The repository settings page, like `<your_gitea.com>/<owner>/<repo>/settings/actions/runners`.
|
||||||
|
|
||||||
|
If you cannot see the settings page, please make sure that you have the right permissions and that Actions have been enabled.
|
||||||
|
|
||||||
|
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):
|
||||||
|
|
||||||
|
```
|
||||||
|
gitea --config /etc/gitea/app.ini actions generate-runner-token
|
||||||
|
```
|
||||||
|
|
||||||
|
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
|
||||||
|
export GITEA_RUNNER_REGISTRATION_TOKEN_FILE=/some-dir/runner-token
|
||||||
|
./gitea --config ...
|
||||||
|
```
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
### Configuration
|
||||||
|
|
||||||
|
Configuration is done via a configuration file. It is optional, and the default configuration will be used when no configuration file is specified. You can generate a configuration file by running the following command:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
./act_runner generate-config
|
||||||
|
```
|
||||||
|
|
||||||
|
The default configuration is safe to use without any modification, so you can just use it directly.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
./act_runner generate-config > config.yaml
|
||||||
|
./act_runner --config config.yaml [command]
|
||||||
|
```
|
||||||
|
|
||||||
|
### Register 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.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
./act_runner register
|
||||||
|
```
|
||||||
|
|
||||||
|
Alternatively, you can use the `--config` option to specify the configuration file mentioned in the previous section.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
./act_runner --config config.yaml register
|
||||||
|
```
|
||||||
|
|
||||||
|
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.
|
||||||
|
- The runner name, which is optional. If you leave it blank, the hostname will be used.
|
||||||
|
- The runner labels, which is optional. If you leave it blank, the default labels will be used.
|
||||||
|
|
||||||
|
You may be confused about the runner labels, which will be explained later.
|
||||||
|
|
||||||
|
If you want to register the runner in a non-interactive way, you can use arguments to do it.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
./act_runner register --no-interactive --instance <instance_url> --token <registration_token> --name <runner_name> --labels <runner_labels>
|
||||||
|
```
|
||||||
|
|
||||||
|
When you have registered the runner, you can find a new file named `.runner` in the current directory.
|
||||||
|
This file stores the registration information.
|
||||||
|
Please do not edit it manually.
|
||||||
|
If this file is missing or corrupted, you can simply remove it and register again.
|
||||||
|
|
||||||
|
If you want to store the registration information in another place, you can specify it in the configuration file,
|
||||||
|
and don't forget to specify the `--config` option.
|
||||||
|
|
||||||
|
#### Ephemeral Runners
|
||||||
|
|
||||||
|
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+** 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.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
./act_runner register --ephemeral
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash
|
||||||
|
./act_runner --config config.yaml register --ephemeral
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash
|
||||||
|
./act_runner register --no-interactive --ephemeral --instance <instance_url> --token <registration_token> --name <runner_name> --labels <runner_labels>
|
||||||
|
```
|
||||||
|
|
||||||
|
The runner must be registered each time it is intended to receive a job. After completing the single job it is designed to execute, the runner terminates.
|
||||||
|
|
||||||
|
To automate the registration and startup of new runners when a job is queued, use the `workflow_job` webhook.
|
||||||
|
|
||||||
|
### Start the runner from the command line
|
||||||
|
|
||||||
|
After you have registered the runner, you can run it with the following command:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
./act_runner daemon
|
||||||
|
```
|
||||||
|
|
||||||
|
or
|
||||||
|
|
||||||
|
```bash
|
||||||
|
./act_runner daemon --config config.yaml
|
||||||
|
```
|
||||||
|
|
||||||
|
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 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]
|
||||||
|
Description=Gitea Actions runner
|
||||||
|
Documentation=https://gitea.com/gitea/act_runner
|
||||||
|
After=docker.service
|
||||||
|
|
||||||
|
[Service]
|
||||||
|
ExecStart=/usr/local/bin/act_runner daemon --config /etc/act_runner/config.yaml
|
||||||
|
ExecReload=/bin/kill -s HUP $MAINPID
|
||||||
|
WorkingDirectory=/var/lib/act_runner
|
||||||
|
TimeoutSec=0
|
||||||
|
RestartSec=10
|
||||||
|
Restart=always
|
||||||
|
User=act_runner
|
||||||
|
|
||||||
|
[Install]
|
||||||
|
WantedBy=multi-user.target
|
||||||
|
```
|
||||||
|
|
||||||
|
Then:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# load the new systemd unit file
|
||||||
|
sudo systemctl daemon-reload
|
||||||
|
# start the service and enable it at boot
|
||||||
|
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)
|
||||||
|
|
||||||
|
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"?>
|
||||||
|
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
||||||
|
<plist version="1.0">
|
||||||
|
<dict>
|
||||||
|
<key>Label</key>
|
||||||
|
<string>com.gitea.act_runner</string>
|
||||||
|
<key>ProgramArguments</key>
|
||||||
|
<array>
|
||||||
|
<string>/usr/local/bin/act_runner</string>
|
||||||
|
<string>daemon</string>
|
||||||
|
<string>--config</string>
|
||||||
|
<string>/etc/act_runner/config.yaml</string>
|
||||||
|
</array>
|
||||||
|
<key>RunAtLoad</key>
|
||||||
|
<true/>
|
||||||
|
<key>KeepAlive</key>
|
||||||
|
<true/>
|
||||||
|
<key>WorkingDirectory</key>
|
||||||
|
<string>/var/lib/act_runner</string>
|
||||||
|
<key>StandardOutPath</key>
|
||||||
|
<string>/var/lib/act_runner/act_runner.log</string>
|
||||||
|
<key>StandardErrorPath</key>
|
||||||
|
<string>/var/lib/act_runner/act_runner.err</string>
|
||||||
|
<key>EnvironmentVariables</key>
|
||||||
|
<dict>
|
||||||
|
<key>PATH</key>
|
||||||
|
<string>/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
|
||||||
|
<key>HOME</key>
|
||||||
|
<string>/var/lib/act_runner</string>
|
||||||
|
</dict>
|
||||||
|
<key>UserName</key>
|
||||||
|
<string>_act_runner</string>
|
||||||
|
</dict>
|
||||||
|
</plist>
|
||||||
|
```
|
||||||
|
|
||||||
|
Then:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
sudo launchctl load /Library/LaunchDaemon/com.gitea.act_runner.plist
|
||||||
|
```
|
||||||
|
|
||||||
|
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 [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 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 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
|
||||||
|
```
|
||||||
|
|
||||||
|
When you are using the docker image, you can specify the configuration file by using the `CONFIG_FILE` environment variable. Make sure that the file is mounted into the container as a volume:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker run -v $PWD/config.yaml:/config.yaml -e CONFIG_FILE=/config.yaml ...
|
||||||
|
```
|
||||||
|
|
||||||
|
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 for `<container_name>`.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker run \
|
||||||
|
-e GITEA_INSTANCE_URL=<instance_url> \
|
||||||
|
-e GITEA_RUNNER_REGISTRATION_TOKEN=<registration_token> \
|
||||||
|
-e GITEA_RUNNER_NAME=<gitea_runner_name> \
|
||||||
|
--name <container_name> \
|
||||||
|
-v /var/run/docker.sock:/var/run/docker.sock \
|
||||||
|
-d docker.io/gitea/act_runner:latest
|
||||||
|
```
|
||||||
|
|
||||||
|
You can add more parameters to use a custom config, add a `data` directory for non-volatile file storage, etc.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker run \
|
||||||
|
-v $PWD/config.yaml:/config.yaml \
|
||||||
|
-v $PWD/data:/data \
|
||||||
|
-v /var/run/docker.sock:/var/run/docker.sock \
|
||||||
|
-e CONFIG_FILE=/config.yaml \
|
||||||
|
-e GITEA_INSTANCE_URL=<instance_url> \
|
||||||
|
-e GITEA_RUNNER_REGISTRATION_TOKEN=<registration_token> \
|
||||||
|
-e GITEA_RUNNER_NAME=<gitea_runner_name> \
|
||||||
|
-e GITEA_RUNNER_LABELS=<runner_labels> \
|
||||||
|
--name <container_name> \
|
||||||
|
-d docker.io/gitea/act_runner:latest
|
||||||
|
```
|
||||||
|
|
||||||
|
You may notice that we have mounted `/var/run/docker.sock` into the container.
|
||||||
|
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.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
To enable ephemeral runners, set the environment variable `GITEA_RUNNER_EPHEMERAL=1` in the runner image. This setup doesn't use a `/data` volume because the credentials are single-use and not intended to be reused. You can find more details about this mode under [Ephemeral runners](#ephemeral-runners).
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker run \
|
||||||
|
-e GITEA_INSTANCE_URL=<instance_url> \
|
||||||
|
-e GITEA_RUNNER_REGISTRATION_TOKEN=<registration_token> \
|
||||||
|
-e GITEA_RUNNER_EPHEMERAL=1 \
|
||||||
|
-e GITEA_RUNNER_NAME=<runner_name> \
|
||||||
|
--name my_runner \
|
||||||
|
-d docker.io/gitea/act_runner:nightly
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker run \
|
||||||
|
-v $PWD/config.yaml:/config.yaml \
|
||||||
|
-v /var/run/docker.sock:/var/run/docker.sock \
|
||||||
|
-e CONFIG_FILE=/config.yaml \
|
||||||
|
-e GITEA_INSTANCE_URL=<instance_url> \
|
||||||
|
-e GITEA_RUNNER_REGISTRATION_TOKEN=<registration_token> \
|
||||||
|
-e GITEA_RUNNER_EPHEMERAL=1 \
|
||||||
|
-e GITEA_RUNNER_NAME=<runner_name> \
|
||||||
|
-e GITEA_RUNNER_LABELS=<runner_labels> \
|
||||||
|
--name my_runner \
|
||||||
|
-d docker.io/gitea/act_runner:nightly
|
||||||
|
```
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
### Start the runner using docker compose
|
||||||
|
|
||||||
|
You could also set up the runner using the following `docker-compose.yml`:
|
||||||
|
|
||||||
|
```yml
|
||||||
|
version: "3.8"
|
||||||
|
services:
|
||||||
|
runner:
|
||||||
|
image: docker.io/gitea/act_runner:nightly
|
||||||
|
environment:
|
||||||
|
CONFIG_FILE: /config.yaml
|
||||||
|
GITEA_INSTANCE_URL: "${INSTANCE_URL}"
|
||||||
|
GITEA_RUNNER_REGISTRATION_TOKEN: "${REGISTRATION_TOKEN}"
|
||||||
|
GITEA_RUNNER_NAME: "${RUNNER_NAME}"
|
||||||
|
GITEA_RUNNER_LABELS: "${RUNNER_LABELS}"
|
||||||
|
volumes:
|
||||||
|
- ./config.yaml:/config.yaml
|
||||||
|
- ./data:/data
|
||||||
|
- /var/run/docker.sock:/var/run/docker.sock
|
||||||
|
```
|
||||||
|
|
||||||
|
When using docker, there is no requirement to enter the container and manually run `./act_runner daemon` command as shown below. Once the container has been started successfully, it will show up as an active runner in your Gitea instance.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
To enable ephemeral runners, set the environment variable `GITEA_RUNNER_EPHEMERAL=1` in the runner image. This setup doesn't use a `/data` volume because the credentials are single-use and not intended to be reused. You can find more details about this mode under [Ephemeral runners](#ephemeral-runners).
|
||||||
|
|
||||||
|
```yml
|
||||||
|
version: "3.8"
|
||||||
|
services:
|
||||||
|
runner:
|
||||||
|
image: docker.io/gitea/act_runner:nightly
|
||||||
|
environment:
|
||||||
|
CONFIG_FILE: /config.yaml
|
||||||
|
GITEA_INSTANCE_URL: "${INSTANCE_URL}"
|
||||||
|
GITEA_RUNNER_REGISTRATION_TOKEN: "${REGISTRATION_TOKEN}"
|
||||||
|
GITEA_RUNNER_NAME: "${RUNNER_NAME}"
|
||||||
|
GITEA_RUNNER_LABELS: "${RUNNER_LABELS}"
|
||||||
|
GITEA_RUNNER_EPHEMERAL: "1"
|
||||||
|
volumes:
|
||||||
|
- ./config.yaml:/config.yaml
|
||||||
|
- /var/run/docker.sock:/var/run/docker.sock
|
||||||
|
```
|
||||||
|
|
||||||
|
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 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 the docker image
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
The error occurs because the runner container and job container are on different networks, so the job container cannot access the runner container.
|
||||||
|
|
||||||
|
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:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
cache:
|
||||||
|
enabled: true
|
||||||
|
dir: ""
|
||||||
|
# Use the LAN IP obtained in step 1
|
||||||
|
host: "192.168.8.17"
|
||||||
|
# Use the port number obtained in step 2
|
||||||
|
port: 8088
|
||||||
|
```
|
||||||
|
|
||||||
|
- 4. When starting the container, map the cache port to the host machine:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker run \
|
||||||
|
--name gitea-docker-runner \
|
||||||
|
-p 8088:8088 \
|
||||||
|
-d docker.io/gitea/act_runner:nightly
|
||||||
|
```
|
||||||
|
|
||||||
|
### Labels
|
||||||
|
|
||||||
|
The labels of a runner are used to determine which jobs the runner can run, and how to run them.
|
||||||
|
|
||||||
|
The default labels are `ubuntu-latest:docker://node:16-bullseye,ubuntu-22.04:docker://node:16-bullseye,ubuntu-20.04:docker://node:16-bullseye,ubuntu-18.04:docker://node:16-buster`.
|
||||||
|
It is a comma-separated list, and each item is a label.
|
||||||
|
|
||||||
|
Let's take `ubuntu-22.04:docker://node:16-bullseye` as an example.
|
||||||
|
It means that the runner can run jobs with `runs-on: ubuntu-22.04`, and the job will be run in a docker container with the image `node:16-bullseye`.
|
||||||
|
|
||||||
|
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 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`.
|
||||||
@@ -33,13 +33,6 @@ See [Using concurrency](https://docs.github.com/en/actions/using-jobs/using-conc
|
|||||||
|
|
||||||
It's ignored by Gitea Actions now.
|
It's ignored by Gitea Actions now.
|
||||||
|
|
||||||
### `run-name`
|
|
||||||
|
|
||||||
The name for workflow runs generated from the workflow.
|
|
||||||
See [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#run-name).
|
|
||||||
|
|
||||||
It's ignored by Gitea Actions now.
|
|
||||||
|
|
||||||
### `permissions` and `jobs.<job_id>.permissions`
|
### `permissions` and `jobs.<job_id>.permissions`
|
||||||
|
|
||||||
See [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#permissions).
|
See [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#permissions).
|
||||||
@@ -107,6 +100,14 @@ Services steps don't have their own section in the job log user interface.
|
|||||||
|
|
||||||
## Different behavior
|
## 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
|
### Downloading actions
|
||||||
|
|
||||||
Previously (Pre 1.21.0), `[actions].DEFAULT_ACTIONS_URL` defaulted to `https://gitea.com`.
|
Previously (Pre 1.21.0), `[actions].DEFAULT_ACTIONS_URL` defaulted to `https://gitea.com`.
|
||||||
|
|||||||
@@ -163,6 +163,13 @@ For events supported only by GitHub, see GitHub's [documentation](https://docs.g
|
|||||||
| pull_request_review_comment | `created`, `edited` |
|
| pull_request_review_comment | `created`, `edited` |
|
||||||
| release | `published`, `edited` |
|
| release | `published`, `edited` |
|
||||||
| registry_package | `published` |
|
| registry_package | `published` |
|
||||||
|
| workflow_dispatch | not applicable |
|
||||||
|
| workflow_run | `requested`, `completed` |
|
||||||
|
|
||||||
> For `pull_request` events, in [GitHub Actions](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request), the `ref` is `refs/pull/:prNumber/merge`, which is a reference to the merge commit preview. However, Gitea has no such reference.
|
> For `pull_request` events, in [GitHub Actions](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request), the `ref` is `refs/pull/:prNumber/merge`, which is a reference to the merge commit preview. However, Gitea has no such reference.
|
||||||
> Therefore, the `ref` in Gitea Actions is `refs/pull/:prNumber/head`, which points to the head of pull request rather than the preview of the merge commit.
|
> Therefore, the `ref` in Gitea Actions is `refs/pull/:prNumber/head`, which points to the head of pull request rather than the preview of the merge commit.
|
||||||
|
|
||||||
|
## How to share actions and reusable workflows from private repositories?
|
||||||
|
|
||||||
|
Go to the repository's **Settings** > **Actions** > **General** page and add collaborative owners.
|
||||||
|
The private repositories of collaborative owners are allowed to access the actions and workflows in the current repository.
|
||||||
@@ -76,7 +76,7 @@ And you can see the new runner in the management page:
|
|||||||
|
|
||||||

|

|
||||||
|
|
||||||
You can find more information by visiting [Act runner](usage/actions/act-runner.md).
|
You can find more information by visiting [Act runner](act-runner.mdxc).
|
||||||
|
|
||||||
### Use Actions
|
### Use Actions
|
||||||
|
|
||||||
|
|||||||
@@ -0,0 +1,9 @@
|
|||||||
|
{
|
||||||
|
"label": "Issues & Pull Requests",
|
||||||
|
"position": 20,
|
||||||
|
"link": {
|
||||||
|
"type": "generated-index",
|
||||||
|
"slug": "/usage/issues-prs",
|
||||||
|
"description": "Issues and Pull Requests workflow, templates, and collaboration features"
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -4,9 +4,11 @@ slug: "agit"
|
|||||||
sidebar_position: 12
|
sidebar_position: 12
|
||||||
aliases:
|
aliases:
|
||||||
- /en-us/agit-setup
|
- /en-us/agit-setup
|
||||||
|
- /agit-setup
|
||||||
|
- /agit
|
||||||
---
|
---
|
||||||
|
|
||||||
# AGit Setup
|
# AGit
|
||||||
|
|
||||||
In Gitea `1.13`, support for [AGit](https://git-repo.info/en/2020/03/agit-flow-and-git-repo/) was added. AGit enables users to create pull requests directly, even without write permissions of the repository, eliminating the need to fork it. This helps reduce the number of duplicated repositories and minimizes unnecessary disk usage.
|
In Gitea `1.13`, support for [AGit](https://git-repo.info/en/2020/03/agit-flow-and-git-repo/) was added. AGit enables users to create pull requests directly, even without write permissions of the repository, eliminating the need to fork it. This helps reduce the number of duplicated repositories and minimizes unnecessary disk usage.
|
||||||
|
|
||||||
@@ -27,19 +29,21 @@ git push origin HEAD:refs/for/main
|
|||||||
The command has the following structure:
|
The command has the following structure:
|
||||||
|
|
||||||
- `HEAD`: The target branch
|
- `HEAD`: The target branch
|
||||||
- `refs/<for|draft|for-review>/<branch>`: The target PR type
|
- `origin`: The target repository (not a fork!)
|
||||||
|
- `HEAD`: The local branch containing the changes you are proposing
|
||||||
|
- `refs/<for|draft|for-review>/<branch>`: The target PR type and configuration
|
||||||
- `for`: Create a normal PR with `<branch>` as the target branch
|
- `for`: Create a normal PR with `<branch>` as the target branch
|
||||||
- `draft`/ `for-review`: Currently ignored silently
|
- `draft`/`for-review`: Currently ignored silently
|
||||||
- `<branch>/<session>`: The target branch to open the PR
|
- `<branch>/`: The branch you want your changes to be merged into
|
||||||
- `-o <topic|title|description>`: Options for the PR
|
- `-o <topic|title|description>`: Options for the PR
|
||||||
- `title`: The PR title
|
- `topic`: The topic of this change. It will become the name of the branch holding the changes waiting for review. This is REQUIRED to trigger a pull request.
|
||||||
- `topic`: The branch name the PR should be opened for
|
- `title`: The PR title (optional but recommended), only used for topics not already having an associated PR.
|
||||||
- `description`: The PR description
|
- `description`: The PR description (optional but recommended), only used for topics not already having an associated PR.
|
||||||
- `force-push=true`: Specifies whether to force-update the target branch.
|
- `force-push=true`: Specifies whether to force-update the target branch.
|
||||||
- Note: omitting the value and using just `-o force-push` will not work.
|
- Note: omitting the value and using just `-o force-push` will also work.
|
||||||
|
|
||||||
Here's another advanced example for creating a new PR targeting `main` with `topic`, `title`, and `description`:
|
Here's another advanced example for creating a new PR targeting `main` with `topic`, `title`, and `description`:
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
git push origin HEAD:refs/for/main -o topic="Topic of my PR" -o title="Title of the PR" -o description="# The PR Description\nThis can be **any** markdown content.\n- [x] Ok"
|
git push origin HEAD:refs/for/main -o topic="topic_of_my_PR" -o title="Title of the PR" -o description="# The PR Description\nThis can be **any** markdown content.\n- [x] Ok"
|
||||||
```
|
```
|
||||||
File renamed without changes.
@@ -1,12 +1,9 @@
|
|||||||
---
|
---
|
||||||
date: "2023-03-04T19:00:00+00:00"
|
date: "2023-03-04T19:00:00+00:00"
|
||||||
|
|
||||||
slug: "labels"
|
slug: "labels"
|
||||||
sidebar_position: 13
|
sidebar_position: 13
|
||||||
|
|
||||||
aliases:
|
aliases:
|
||||||
- /en-us/labels
|
- /en-us/labels
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
# Labels
|
# Labels
|
||||||
@@ -21,7 +18,7 @@ For organizations, you can define organization-wide labels that are shared with
|
|||||||
|
|
||||||
Labels have a mandatory name, a mandatory color, an optional description, and must either be exclusive or not (see `Scoped Labels` below).
|
Labels have a mandatory name, a mandatory color, an optional description, and must either be exclusive or not (see `Scoped Labels` below).
|
||||||
|
|
||||||
When you create a repository, you can ensure certain labels exist by using the `Issue Labels` option. This option lists a number of available label sets that are [configured globally on your instance](../administration/customizing-gitea/#labels). Its contained labels will all be created as well while creating the repository.
|
When you create a repository, you can ensure certain labels exist by using the `Issue Labels` option. This option lists a number of available label sets that are [configured globally on your instance](../../administration/customizing-gitea.md#labels). Its contained labels will all be created as well while creating the repository.
|
||||||
|
|
||||||
## Scoped Labels
|
## Scoped Labels
|
||||||
|
|
||||||
@@ -85,7 +85,7 @@ Sometimes a commit or pull request may fix or bring back a problem documented
|
|||||||
in a particular issue. Gitea supports closing and reopening the referenced
|
in a particular issue. Gitea supports closing and reopening the referenced
|
||||||
issues by preceding the reference with a particular _keyword_. Common keywords
|
issues by preceding the reference with a particular _keyword_. Common keywords
|
||||||
include "closes", "fixes", "reopens", etc. This list can be
|
include "closes", "fixes", "reopens", etc. This list can be
|
||||||
[customized](../administration/config-cheat-sheet.md) by the
|
[customized](../../administration/config-cheat-sheet.md) by the
|
||||||
site administrator.
|
site administrator.
|
||||||
|
|
||||||
Example:
|
Example:
|
||||||
File renamed without changes.
@@ -57,4 +57,4 @@ The first value of the list will be used in helpers.
|
|||||||
|
|
||||||
## Pull Request Templates
|
## Pull Request Templates
|
||||||
|
|
||||||
You can find more information about pull request templates at the page [Issue and Pull Request templates](usage/issue-pull-request-templates.md).
|
You can find more information about pull request templates at the page [Issue and Pull Request templates](issue-pull-request-templates.md).
|
||||||
@@ -1,33 +0,0 @@
|
|||||||
---
|
|
||||||
date: "2023-03-04T19:00:00+00:00"
|
|
||||||
slug: "labels"
|
|
||||||
sidebar_position: 13
|
|
||||||
aliases:
|
|
||||||
- /en-us/labels
|
|
||||||
---
|
|
||||||
|
|
||||||
# Labels
|
|
||||||
|
|
||||||
You can use labels to classify issues and pull requests and to improve your overview over them.
|
|
||||||
|
|
||||||
## Creating Labels
|
|
||||||
|
|
||||||
For repositories, labels can be created by going to `Issues` and clicking on `Labels`.
|
|
||||||
|
|
||||||
For organizations, you can define organization-wide labels that are shared with all organization repositories, including both already-existing repositories as well as newly created ones. Organization-wide labels can be created in the organization `Settings`.
|
|
||||||
|
|
||||||
Labels have a mandatory name, a mandatory color, an optional description, and must either be exclusive or not (see `Scoped Labels` below).
|
|
||||||
|
|
||||||
When you create a repository, you can ensure certain labels exist by using the `Issue Labels` option. This option lists a number of available label sets that are [configured globally on your instance](../administration/customizing-gitea.md#labels). Its contained labels will all be created as well while creating the repository.
|
|
||||||
|
|
||||||
## Scoped Labels
|
|
||||||
|
|
||||||
Scoped labels are used to ensure at most a single label with the same scope is assigned to an issue or pull request. For example, if labels `kind/bug` and `kind/enhancement` have the Exclusive option set, an issue can only be classified as a bug or an enhancement.
|
|
||||||
|
|
||||||
A scoped label must contain `/` in its name (not at either end of the name). The scope of a label is determined based on the **last** `/`, so for example the scope of label `scope/subscope/item` is `scope/subscope`.
|
|
||||||
|
|
||||||
## Filtering by Label
|
|
||||||
|
|
||||||
Issue and pull request lists can be filtered by label. Selecting multiple labels shows issues and pull requests that have all selected labels assigned.
|
|
||||||
|
|
||||||
By holding alt to click the label, issues and pull requests with the chosen label are excluded from the list.
|
|
||||||
@@ -0,0 +1,9 @@
|
|||||||
|
{
|
||||||
|
"label": "Packages",
|
||||||
|
"position": 40,
|
||||||
|
"link": {
|
||||||
|
"type": "generated-index",
|
||||||
|
"slug": "/usage/packages",
|
||||||
|
"description": "Managing packages and package registries"
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -36,23 +36,24 @@ pacman-key --lsign-key {key id}
|
|||||||
|
|
||||||
Now add the registry configuration to `/etc/pacman.conf`.
|
Now add the registry configuration to `/etc/pacman.conf`.
|
||||||
```conf
|
```conf
|
||||||
[{owner}.gitea.example.com]
|
[{repository}]
|
||||||
SigLevel = Required
|
SigLevel = Required
|
||||||
Server = https://gitea.example.com/api/packages/{owner}/arch/{repository}/{architecture}
|
Server = https://gitea.example.com/api/packages/{owner}/arch/$repo/$arch
|
||||||
```
|
```
|
||||||
|
|
||||||
| Placeholder | Description |
|
| Placeholder | Description |
|
||||||
| -------------- | ----------- |
|
| -------------- | ----------- |
|
||||||
| `owner` | The owner of the packages. |
|
| `owner` | The owner of the packages. |
|
||||||
| `repository` | The repository to use. |
|
| `repository` | The repository to use. |
|
||||||
| `architecture` | The architecture to use. |
|
|
||||||
|
|
||||||
Consult the owners package overview to see what `repository` and `architecture` is available.
|
Consult the owners package overview to see what `repository` and `architecture` is available.
|
||||||
|
|
||||||
If the registry is private, provide credentials in the url. You can use a password or a [personal access token](development/api-usage.md#authentication):
|
If the registry is private, provide credentials in the url. You can use a password or a [personal access token](development/api-usage.md#authentication):
|
||||||
|
|
||||||
```
|
```
|
||||||
Server = https://{username}:{your_password_or_token}@gitea.example.com/api/packages/{owner}/arch/{repository}/{architecture}
|
[{repository}]
|
||||||
|
SigLevel = Required
|
||||||
|
Server = https://{username}:{your_password_or_token}@gitea.example.com/api/packages/{owner}/arch/$repo/$arch
|
||||||
```
|
```
|
||||||
|
|
||||||
## Publish a package
|
## Publish a package
|
||||||
|
|||||||
@@ -29,7 +29,7 @@ npm config set -- '//gitea.example.com/api/packages/{owner}/npm/:_authToken' "{t
|
|||||||
| ------------ | ----------- |
|
| ------------ | ----------- |
|
||||||
| `scope` | The scope of the packages. |
|
| `scope` | The scope of the packages. |
|
||||||
| `owner` | The owner of the package. |
|
| `owner` | The owner of the package. |
|
||||||
| `token` | Your [personal access token](development/api-usage.md#authentication). |
|
| `token` | Your [personal access token](development/api-usage.md#authentication). With `package` permissions. |
|
||||||
|
|
||||||
For example:
|
For example:
|
||||||
|
|
||||||
|
|||||||
@@ -56,6 +56,8 @@ and shows a link to the repository on the package site (as well as a link to the
|
|||||||
| **read** access | public, if user is public too; otherwise for this user only | public, if org is public, otherwise for org members only |
|
| **read** access | public, if user is public too; otherwise for this user only | public, if org is public, otherwise for org members only |
|
||||||
| **write** access | owner only | org members with admin or write access to the org |
|
| **write** access | owner only | org members with admin or write access to the org |
|
||||||
|
|
||||||
|
Please note, that your respective package manager needs to have a [personal access token](development/api-usage.md#authentication) with the permissions `package` set to either Read or Read & Write to download and publish packages respectively.
|
||||||
|
|
||||||
N.B.: These access restrictions are [subject to change](https://github.com/go-gitea/gitea/issues/19270), where more finegrained control will be added via a dedicated organization team permission.
|
N.B.: These access restrictions are [subject to change](https://github.com/go-gitea/gitea/issues/19270), where more finegrained control will be added via a dedicated organization team permission.
|
||||||
|
|
||||||
## Create or upload a package
|
## Create or upload a package
|
||||||
|
|||||||
Loaded 50 of 1168 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user