mirror of
https://gitea.com/gitea/docs.git
synced 2026-06-16 07:01:27 +00:00
Compare commits
6 Commits
renovate/p
...
remove-hac
| Author | SHA1 | Date | |
|---|---|---|---|
|
9cd0dff2d0 | ||
|
|
cfbe47dca3 | ||
|
|
4bcb5d3b64 | ||
|
|
cd4fe233ac | ||
|
|
8f2d88ca79 | ||
|
c93356c29c |
@@ -622,7 +622,6 @@ And the following unique queues:
|
||||
- `REVERSE_PROXY_TRUSTED_PROXIES`: **127.0.0.0/8,::1/128**: List of IP addresses and networks separated by comma of trusted proxy servers. Use `*` to trust all.
|
||||
- `X_FRAME_OPTIONS`: **SAMEORIGIN**: Set the `X-Frame-Options` header value for all HTTP responses. Set to `unset` to not send the header. Previously located in `[cors]`.
|
||||
- `X_CONTENT_TYPE_OPTIONS`: **nosniff**: Set the `X-Content-Type-Options` header value for all HTTP responses. Set to `unset` to not send the header.
|
||||
- `CONTENT_SECURITY_POLICY_GENERAL`: **_empty_**: The value of the general Content-Security-Policy for most web pages. Leave it empty to apply the default policy, or set it to "unset" to disable Content-Security-Polic.
|
||||
- `DISABLE_GIT_HOOKS`: **true**: Set to `false` to enable users with Git Hook privilege to create custom Git Hooks.
|
||||
|
||||
:::warning
|
||||
|
||||
@@ -1,115 +0,0 @@
|
||||
---
|
||||
date: "2021-11-01T23:41:00+08:00"
|
||||
slug: "guidelines-backend"
|
||||
sidebar_position: 20
|
||||
aliases:
|
||||
- /en-us/guidelines-backend
|
||||
---
|
||||
|
||||
# Guidelines for Backend Development
|
||||
|
||||
## Background
|
||||
|
||||
Gitea uses Golang as the backend programming language. It uses many third-party packages and also write some itself.
|
||||
For example, Gitea uses [Chi](https://github.com/go-chi/chi) as basic web framework. [Xorm](https://xorm.io) is an ORM framework that is used to interact with the database.
|
||||
So it's very important to manage these packages. Please take the below guidelines before you start to write backend code.
|
||||
|
||||
## Package Design Guideline
|
||||
|
||||
### Packages List
|
||||
|
||||
To maintain understandable code and avoid circular dependencies it is important to have a good code structure. The Gitea backend is divided into the following parts:
|
||||
|
||||
- `build`: Scripts to help build Gitea.
|
||||
- `cmd`: All Gitea actual sub commands includes web, doctor, serv, hooks, admin and etc. `web` will start the web service. `serv` and `hooks` will be invoked by Git or OpenSSH. Other sub commands could help to maintain Gitea.
|
||||
- `tests`: Common test utility functions
|
||||
- `tests/integration`: Integration tests, to test back-end regressions
|
||||
- `tests/e2e`: E2e tests, to test front-end and back-end compatibility and visual regressions.
|
||||
- `models`: Contains the data structures used by xorm to construct database tables. It also contains functions to query and update the database. Dependencies to other Gitea code should be avoided. You can make exceptions in cases such as logging.
|
||||
- `models/db`: Basic database operations. All other `models/xxx` packages should depend on this package. The `GetEngine` function should only be invoked from `models/`.
|
||||
- `models/fixtures`: Sample data used in unit tests and integration tests. One `yml` file means one table which will be loaded into database when beginning the tests.
|
||||
- `models/migrations`: Stores database migrations between versions. PRs that change a database structure **MUST** also have a migration step.
|
||||
- `modules`: Different modules to handle specific functionality in Gitea. Work in Progress: Some of them should be moved to `services`, in particular those that depend on models because they rely on the database.
|
||||
- `modules/setting`: Store all system configurations read from ini files and has been referenced by everywhere. But they should be used as function parameters when possible.
|
||||
- `modules/git`: Package to interactive with `Git` command line or Gogit package.
|
||||
- `public`: Compiled frontend files (javascript, images, css, etc.)
|
||||
- `routers`: Handling of server requests. As it uses other Gitea packages to serve the request, other packages (models, modules or services) must not depend on routers.
|
||||
- `routers/api` Contains routers for `/api/v1` aims to handle RESTful API requests.
|
||||
- `routers/install` Could only respond when system is in INSTALL mode (INSTALL_LOCK=false).
|
||||
- `routers/private` will only be invoked by internal sub commands, especially `serv` and `hooks`.
|
||||
- `routers/web` will handle HTTP requests from web browsers or Git SMART HTTP protocols.
|
||||
- `services`: Support functions for common routing operations or command executions. Uses `models` and `modules` to handle the requests.
|
||||
- `templates`: Golang templates for generating the html output.
|
||||
|
||||
### Package Dependencies
|
||||
|
||||
Since Golang doesn't support import cycles, we have to decide the package dependencies carefully. There are some levels between those packages. Below is the ideal package dependencies direction.
|
||||
|
||||
`cmd` -> `routers` -> `services` -> `models` -> `modules`
|
||||
|
||||
From left to right, left packages could depend on right packages, but right packages MUST not depend on left packages. The sub packages on the same level could depend on according this level's rules.
|
||||
|
||||
:::warning
|
||||
Why do we need database transactions outside of `models`? And how?
|
||||
Some actions should allow for rollback when database record insertion/update/deletion failed.
|
||||
So services must be allowed to create a database transaction. Here is some example,
|
||||
|
||||
```go
|
||||
// services/repository/repository.go
|
||||
func CreateXXXX() error {
|
||||
return db.WithTx(func(ctx context.Context) error {
|
||||
// do something, if err is returned, it will rollback automatically
|
||||
if err := issues.UpdateIssue(ctx, repoID); err != nil {
|
||||
// ...
|
||||
return err
|
||||
}
|
||||
// ...
|
||||
return nil
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
You should **not** use `db.GetEngine(ctx)` in `services` directly, but just write a function under `models/`.
|
||||
If the function will be used in the transaction, just let `context.Context` as the function's first parameter.
|
||||
|
||||
```go
|
||||
// models/issues/issue.go
|
||||
func UpdateIssue(ctx context.Context, repoID int64) error {
|
||||
e := db.GetEngine(ctx)
|
||||
|
||||
// ...
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
### Package Name
|
||||
|
||||
For the top level package, use a plural as package name, i.e. `services`, `models`, for sub packages, use singular,
|
||||
i.e. `services/user`, `models/repository`.
|
||||
|
||||
### Import Alias
|
||||
|
||||
Since there are some packages which use the same package name, it is possible that you find packages like `modules/user`, `models/user`, and `services/user`. When these packages are imported in one Go file, it's difficult to know which package we are using and if it's a variable name or an import name. So, we always recommend to use import aliases. To differ from package variables which are commonly in camelCase, just use **snake_case** for import aliases.
|
||||
i.e. `import user_service "code.gitea.io/gitea/services/user"`
|
||||
|
||||
### Implementing `io.Closer`
|
||||
|
||||
If a type implements `io.Closer`, calling `Close` multiple times must not fail or `panic` but return an error or `nil`.
|
||||
|
||||
### Important Gotchas
|
||||
|
||||
- Never write `x.Update(exemplar)` without an explicit `WHERE` clause:
|
||||
- This will cause all rows in the table to be updated with the non-zero values of the exemplar - including IDs.
|
||||
- You should usually write `x.ID(id).Update(exemplar)`.
|
||||
- If during a migration you are inserting into a table using `x.Insert(exemplar)` where the ID is preset:
|
||||
- You will need to ``SET IDENTITY_INSERT `table` ON`` for the MSSQL variant (the migration will fail otherwise)
|
||||
- However, you will also need to update the id sequence for postgres - the migration will silently pass here but later insertions will fail:
|
||||
``SELECT setval('table_name_id_seq', COALESCE((SELECT MAX(id)+1 FROM `table_name`), 1), false)``
|
||||
|
||||
### Future Tasks
|
||||
|
||||
Currently, we are creating some refactors to do the following things:
|
||||
|
||||
- Correct that codes which doesn't follow the rules.
|
||||
- There are too many files in `models`, so we are moving some of them into a sub package `models/xxx`.
|
||||
- Some `modules` sub packages should be moved to `services` because they depend on `models`.
|
||||
@@ -1,156 +0,0 @@
|
||||
---
|
||||
date: "2021-10-13T16:00:00+02:00"
|
||||
slug: "guidelines-frontend"
|
||||
sidebar_position: 30
|
||||
aliases:
|
||||
- /en-us/guidelines-frontend
|
||||
---
|
||||
|
||||
# Guidelines for Frontend Development
|
||||
|
||||
## Background
|
||||
|
||||
Gitea uses [Fomantic-UI](https://fomantic-ui.com/introduction/getting-started.html) (based on [jQuery](https://api.jquery.com)) and [Vue3](https://vuejs.org/) for its frontend.
|
||||
|
||||
The HTML pages are rendered by [Go HTML Template](https://pkg.go.dev/html/template).
|
||||
|
||||
The source files can be found in the following directories:
|
||||
|
||||
* **CSS styles:** `web_src/css/`
|
||||
* **JavaScript files:** `web_src/js/`
|
||||
* **Vue components:** `web_src/js/components/`
|
||||
* **Go HTML templates:** `templates/`
|
||||
|
||||
## General Guidelines
|
||||
|
||||
We recommend [Google HTML/CSS Style Guide](https://google.github.io/styleguide/htmlcssguide.html) and [Google JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html)
|
||||
|
||||
### Gitea specific guidelines
|
||||
|
||||
1. Every feature (Fomantic-UI/jQuery module) should be put in separate files/directories.
|
||||
2. HTML ids and classes should use kebab-case, it's preferred to contain 2-3 feature related keywords.
|
||||
3. HTML ids and classes used in JavaScript should be unique for the whole project, and should contain 2-3 feature related keywords. We recommend to use the `js-` prefix for classes that are only used in JavaScript.
|
||||
4. CSS styling for classes provided by frameworks should not be overwritten. Always use new class names with 2-3 feature related keywords to overwrite framework styles. Gitea's helper CSS classes in `helpers.less` could be helpful.
|
||||
5. The backend can pass complex data to the frontend by using `ctx.PageData["myModuleData"] = map[]{}`, but do not expose whole models to the frontend to avoid leaking sensitive data.
|
||||
6. Simple pages and SEO-related pages use Go HTML Template render to generate static Fomantic-UI HTML output. Complex pages can use Vue3.
|
||||
7. Clarify variable types, prefer `elem.disabled = true` instead of `elem.setAttribute('disabled', 'anything')`, prefer `$el.prop('checked', var === 'yes')` instead of `$el.prop('checked', var)`.
|
||||
8. Use semantic elements, prefer `<button class="ui button">` instead of `<div class="ui button">`.
|
||||
9. Avoid unnecessary `!important` in CSS, add comments to explain why it's necessary if it can't be avoided.
|
||||
10. Avoid mixing different events in one event listener, prefer to use individual event listeners for every event.
|
||||
11. Custom event names are recommended to use `ce-` prefix.
|
||||
12. Prefer using Tailwind CSS which is available via `tw-` prefix, e.g. `tw-relative`. Gitea's helper CSS classes use `gt-` prefix (`gt-ellipsis`), while Gitea's own private framework-level CSS classes use `g-` prefix (`g-modal-confirm`).
|
||||
13. Avoid inline scripts & styles as much as possible, it's recommended to put JS code into JS files and use CSS classes. If inline scripts & styles are unavoidable, explain the reason why it can't be avoided.
|
||||
|
||||
### Accessibility / ARIA
|
||||
|
||||
In history, Gitea heavily uses Fomantic UI which is not an accessibility-friendly framework.
|
||||
Gitea uses some patches to make Fomantic UI more accessible (see `aria.md` and related JS files),
|
||||
but there are still many problems which need a lot of work and time to fix.
|
||||
|
||||
### Framework Usage
|
||||
|
||||
Mixing different frameworks together is discouraged, it makes the code difficult to be maintained.
|
||||
A JavaScript module should follow one major framework and follow the framework's best practice.
|
||||
|
||||
Recommended implementations:
|
||||
|
||||
* Vue + Vanilla JS
|
||||
* Fomantic-UI (jQuery)
|
||||
* htmx (partial page reloads for otherwise static components)
|
||||
* Vanilla JS
|
||||
|
||||
Discouraged implementations:
|
||||
|
||||
* Vue + Fomantic-UI (jQuery)
|
||||
* jQuery + Vanilla JS
|
||||
* htmx + any other framework which requires heavy JS code, or unnecessary features like htmx scripting (`hx-on`)
|
||||
|
||||
To make UI consistent, Vue components can use Fomantic-UI CSS classes.
|
||||
We use htmx for simple interactions. You can see an example for simple interactions where htmx should be used in this [PR](https://github.com/go-gitea/gitea/pull/28908). Do not use htmx if you require more advanced reactivity, use another framework (Vue/Vanilla JS).
|
||||
Although mixing different frameworks is discouraged,
|
||||
it should also work if the mixing is necessary and the code is well-designed and maintainable.
|
||||
|
||||
### Typescript
|
||||
|
||||
Gitea is in the process of migrating to type-safe Typescript. Here are some specific guidelines regarding Typescript in the codebase:
|
||||
|
||||
#### Use type aliases instead of interfaces
|
||||
|
||||
Prefer to use type aliases because they can represent any type and are generally more flexible to use than interfaces.
|
||||
|
||||
#### Use separate type imports
|
||||
|
||||
We use `verbatimModuleSyntax` so type and non-type imports from the same file must be split into two `import type` statements. This enables the typescript compiler to completely eliminate the type import statements during compilation.
|
||||
|
||||
#### Use `@ts-expect-error` instead of `@ts-ignore`
|
||||
|
||||
Both annotations should be avoided, but if you have to use them, use `@ts-expect-error` because it will not leave ineffective statements after the issue is fixed.
|
||||
|
||||
### `async` Functions
|
||||
|
||||
Only mark a function as `async` if and only if there are `await` calls
|
||||
or `Promise` returns inside the function.
|
||||
|
||||
It's not recommended to use `async` event listeners, which may lead to problems.
|
||||
The reason is that the code after await is executed outside the event dispatch.
|
||||
Reference: https://github.com/github/eslint-plugin-github/blob/main/docs/rules/async-preventdefault.md
|
||||
|
||||
If an event listener must be `async`, the `e.preventDefault()` should be before any `await`,
|
||||
it's recommended to put it at the beginning of the function.
|
||||
|
||||
If we want to call an `async` function in a non-async context,
|
||||
it's recommended to use `const _promise = asyncFoo()` to tell readers
|
||||
that this is done by purpose, we want to call the async function and ignore the Promise.
|
||||
Some lint rules and IDEs also have warnings if the returned Promise is not handled.
|
||||
|
||||
### Fetching data
|
||||
|
||||
To fetch data, use the wrapper functions `GET`, `POST` etc. from `modules/fetch.js`. They
|
||||
accept a `data` option for the content, will automatically set CSRF token and return a
|
||||
Promise for a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response).
|
||||
|
||||
### HTML Attributes and `dataset`
|
||||
|
||||
The usage of `dataset` is forbidden, its camel-casing behaviour makes it hard to grep for attributes.
|
||||
However, there are still some special cases, so the current guideline is:
|
||||
|
||||
* For legacy code:
|
||||
* `$.data()` should be refactored to `$.attr()`.
|
||||
* `$.data()` can be used to bind some non-string data to elements in rare cases, but it is highly discouraged.
|
||||
|
||||
* For new code:
|
||||
* `node.dataset` should not be used, use `node.getAttribute` instead.
|
||||
* never bind any user data to a DOM node, use a suitable design pattern to describe the relation between node and data.
|
||||
|
||||
### Show/Hide Elements
|
||||
|
||||
* Vue components are recommended to use `v-if` and `v-show` to show/hide elements.
|
||||
* Go template code should use `.tw-hidden` and `showElem()/hideElem()/toggleElem()`, see more details in `.tw-hidden`'s comment.
|
||||
|
||||
### Styles and Attributes in Go HTML Template
|
||||
|
||||
It's recommended to use:
|
||||
|
||||
```html
|
||||
<div class="gt-name1 gt-name2 {{if .IsFoo}}gt-foo{{end}}" {{if .IsFoo}}data-foo{{end}}></div>
|
||||
```
|
||||
|
||||
instead of:
|
||||
|
||||
```html
|
||||
<div class="gt-name1 gt-name2{{if .IsFoo}} gt-foo{{end}}"{{if .IsFoo}} data-foo{{end}}></div>
|
||||
```
|
||||
|
||||
to make the code more readable.
|
||||
|
||||
### Legacy Code
|
||||
|
||||
A lot of legacy code already existed before this document's written. It's recommended to refactor legacy code to follow the guidelines.
|
||||
|
||||
### Vue3 and JSX
|
||||
|
||||
Gitea is using Vue3 now. We decided not to introduce JSX to keep the HTML and the JavaScript code separated.
|
||||
|
||||
### UI Examples
|
||||
|
||||
Gitea uses some self-made UI elements and customizes others to integrate them better into the general UI approach. When running Gitea in development mode (`RUN_MODE=dev`), a page with some standardized UI examples is available under `http(s)://your-gitea-url:port/devtest`.
|
||||
@@ -1,40 +0,0 @@
|
||||
---
|
||||
date: "2023-02-14T00:00:00+00:00"
|
||||
slug: "guidelines-refactoring"
|
||||
sidebar_position: 40
|
||||
aliases:
|
||||
- /en-us/guidelines-refactoring
|
||||
---
|
||||
|
||||
# Guidelines for Refactoring
|
||||
|
||||
## Background
|
||||
|
||||
Since the first line of code was written at Feb 12, 2014, Gitea has grown to be a large project.
|
||||
As a result, the codebase has become larger and larger. The larger the codebase is, the more difficult it is to maintain.
|
||||
A lot of outdated mechanisms exist, a lot of frameworks are mixed together, some legacy code might cause bugs and block new features.
|
||||
To make the codebase more maintainable and make Gitea better, developers should keep in mind to use modern mechanisms to refactor the old code.
|
||||
|
||||
This document is a collection of guidelines for refactoring the codebase.
|
||||
|
||||
## Refactoring Suggestions
|
||||
|
||||
* Design more about the future, but not only resolve the current problem.
|
||||
* Reduce ambiguity, reduce conflicts, improve maintainability.
|
||||
* Describe the refactoring, for example:
|
||||
* Why the refactoring is needed.
|
||||
* How the legacy problems would be solved.
|
||||
* What's the Pros/Cons of the refactoring.
|
||||
* Only do necessary changes, keep the old logic as much as possible.
|
||||
* Introduce some intermediate steps to make the refactoring easier to review, a complete refactoring plan could be done in several PRs.
|
||||
* If there is any divergence, the TOC(Technical Oversight Committee) should be involved to help to make decisions.
|
||||
* Add necessary tests to make sure the refactoring is correct.
|
||||
* Non-bug refactoring is preferred to be done at the beginning of a milestone, it would be easier to find problems before the release.
|
||||
|
||||
## Reviewing & Merging Suggestions
|
||||
|
||||
* A refactoring PR shouldn't be kept open for a long time (usually 7 days), it should be reviewed as soon as possible.
|
||||
* A refactoring PR should be merged as soon as possible, it should not be blocked by other PRs.
|
||||
* If there is no objection from TOC, a refactoring PR could be merged after 7 days with one core member's approval (not the author).
|
||||
* Tolerate some dirty/hacky intermediate steps if the final result is good.
|
||||
* Tolerate some regression bugs if the refactoring is necessary, fix bugs as soon as possible.
|
||||
@@ -1,372 +0,0 @@
|
||||
---
|
||||
date: "2016-12-01T16:00:00+02:00"
|
||||
slug: "hacking-on-gitea"
|
||||
sidebar_position: 10
|
||||
aliases:
|
||||
- /en-us/hacking-on-gitea
|
||||
---
|
||||
|
||||
# Hacking on Gitea
|
||||
|
||||
## Quickstart
|
||||
|
||||
To get a quick working development environment you could use Gitpod.
|
||||
|
||||
[](https://gitpod.io/#https://github.com/go-gitea/gitea)
|
||||
|
||||
## Installing go
|
||||
|
||||
You should [install go](https://go.dev/doc/install) and set up your go
|
||||
environment correctly.
|
||||
|
||||
Next, [install Node.js with npm](https://nodejs.org/en/download/) which is
|
||||
required to build the JavaScript and CSS files. The minimum supported Node.js
|
||||
version is @minNodeVersion@ and the latest LTS version is recommended.
|
||||
|
||||
:::note
|
||||
When executing make tasks that require external tools, like
|
||||
`make watch-backend`, Gitea will automatically download and build these as
|
||||
necessary. To be able to use these you must have the `"$GOPATH"/bin` directory
|
||||
on the executable path. If you don't add the go bin directory to the
|
||||
executable path you will have to manage this yourself.
|
||||
:::
|
||||
|
||||
:::note
|
||||
Go version @minGoVersion@ or higher is required.
|
||||
Gitea uses `gofmt` to format source code. However, the results of
|
||||
`gofmt` can differ by the version of `go`. Therefore it is
|
||||
recommended to install the version of Go that our continuous integration is
|
||||
running. As of last update, the Go version should be @goVersion@.
|
||||
:::
|
||||
|
||||
To lint the template files, ensure [Python](https://www.python.org/) and
|
||||
[Poetry](https://python-poetry.org/) are installed.
|
||||
|
||||
## Installing Make
|
||||
|
||||
Gitea makes heavy use of Make to automate tasks and improve development. This
|
||||
guide covers how to install Make.
|
||||
|
||||
### On Linux
|
||||
|
||||
Install with the package manager.
|
||||
|
||||
On Ubuntu/Debian:
|
||||
|
||||
```bash
|
||||
sudo apt-get install make
|
||||
```
|
||||
|
||||
On Fedora/RHEL/CentOS:
|
||||
|
||||
```bash
|
||||
sudo yum install make
|
||||
```
|
||||
|
||||
### On Windows
|
||||
|
||||
One of these three distributions of Make will run on Windows:
|
||||
|
||||
- [Single binary build](http://www.equation.com/servlet/equation.cmd?fa=make). Copy somewhere and add to `PATH`.
|
||||
- [32-bits version](http://www.equation.com/ftpdir/make/32/make.exe)
|
||||
- [64-bits version](http://www.equation.com/ftpdir/make/64/make.exe)
|
||||
- [MinGW-w64](https://www.mingw-w64.org) / [MSYS2](https://www.msys2.org/).
|
||||
- MSYS2 is a collection of tools and libraries providing you with an easy-to-use environment for building, installing and running native Windows software, it includes MinGW-w64.
|
||||
- In MingGW-w64, the binary is called `mingw32-make.exe` instead of `make.exe`. Add the `bin` folder to `PATH`.
|
||||
- In MSYS2, you can use `make` directly. See [MSYS2 Porting](https://www.msys2.org/wiki/Porting/).
|
||||
- To compile Gitea with CGO_ENABLED (eg: SQLite3), you might need to use [tdm-gcc](https://jmeubank.github.io/tdm-gcc/) instead of MSYS2 gcc, because MSYS2 gcc headers lack some Windows-only CRT functions like `_beginthread`.
|
||||
- [Chocolatey package](https://chocolatey.org/packages/make). Run `choco install make`
|
||||
|
||||
:::note
|
||||
If you are attempting to build using make with Windows Command Prompt, you may run into issues. The above prompts (Git bash, or MinGW) are recommended, however if you only have command prompt (or potentially PowerShell) you can set environment variables using the [set](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/set_1) command, e.g. `set TAGS=bindata`.
|
||||
:::
|
||||
|
||||
## Downloading and cloning the Gitea source code
|
||||
|
||||
The recommended method of obtaining the source code is by using `git clone`.
|
||||
|
||||
```bash
|
||||
git clone https://github.com/go-gitea/gitea
|
||||
```
|
||||
|
||||
(Since the advent of go modules, it is no longer necessary to build go projects
|
||||
from within the `$GOPATH`, hence the `go get` approach is no longer recommended.)
|
||||
|
||||
## Forking Gitea
|
||||
|
||||
Download the main Gitea source code as above. Then, fork the
|
||||
[Gitea repository](https://github.com/go-gitea/gitea) on GitHub,
|
||||
and either switch the git remote origin for your fork or add your fork as another remote:
|
||||
|
||||
```bash
|
||||
# Rename original Gitea origin to upstream
|
||||
git remote rename origin upstream
|
||||
git remote add origin "git@github.com:$GITHUB_USERNAME/gitea.git"
|
||||
git fetch --all --prune
|
||||
```
|
||||
|
||||
or:
|
||||
|
||||
```bash
|
||||
# Add new remote for our fork
|
||||
git remote add "$FORK_NAME" "git@github.com:$GITHUB_USERNAME/gitea.git"
|
||||
git fetch --all --prune
|
||||
```
|
||||
|
||||
To be able to create pull requests, the forked repository should be added as a remote
|
||||
to the Gitea sources. Otherwise, changes can't be pushed.
|
||||
|
||||
## Building Gitea (Basic)
|
||||
|
||||
Take a look at our
|
||||
[instructions](installation/from-source.md)
|
||||
for [building from source](installation/from-source.md).
|
||||
|
||||
The simplest recommended way to build from source is:
|
||||
|
||||
```bash
|
||||
TAGS="bindata sqlite sqlite_unlock_notify" make build
|
||||
```
|
||||
|
||||
The `build` target will execute both `frontend` and `backend` sub-targets. If the `bindata` tag is present, the frontend files will be compiled into the binary. It is recommended to leave out the tag when doing frontend development so that changes will be reflected.
|
||||
|
||||
See `make help` for all available `make` targets. Also see [`.drone.yml`](https://github.com/go-gitea/gitea/blob/main/.drone.yml) to see how our continuous integration works.
|
||||
|
||||
## Building continuously
|
||||
|
||||
To run and continuously rebuild when source files change:
|
||||
|
||||
```bash
|
||||
# for both frontend and backend
|
||||
make watch
|
||||
|
||||
# or: watch frontend files (html/js/css) only
|
||||
make watch-frontend
|
||||
|
||||
# or: watch backend files (go) only
|
||||
make watch-backend
|
||||
```
|
||||
|
||||
On macOS, watching all backend source files may hit the default open files limit which can be increased via `ulimit -n 12288` for the current shell or in your shell startup file for all future shells.
|
||||
|
||||
### Formatting, code analysis and spell check
|
||||
|
||||
Our continuous integration will reject PRs that fail the code linters (including format check, code analysis and spell check).
|
||||
|
||||
You should format your code:
|
||||
|
||||
```bash
|
||||
make fmt
|
||||
```
|
||||
|
||||
and lint the source code:
|
||||
|
||||
```bash
|
||||
# lint both frontend and backend code
|
||||
make lint
|
||||
# lint only backend code
|
||||
make lint-backend
|
||||
```
|
||||
|
||||
**Note**: The results of `gofmt` are dependent on the version of `go` present.
|
||||
You should run the same version of go that is on the continuous integration
|
||||
server as mentioned above.
|
||||
|
||||
### Working on JS and CSS
|
||||
|
||||
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:
|
||||
|
||||
```bash
|
||||
make build && ./gitea
|
||||
```
|
||||
|
||||
Before committing, make sure the linters pass:
|
||||
|
||||
```bash
|
||||
make lint-frontend
|
||||
```
|
||||
|
||||
### Configuring local ElasticSearch instance
|
||||
|
||||
Start local ElasticSearch instance using docker:
|
||||
|
||||
```sh
|
||||
mkdir -p $(pwd)/data/elasticsearch
|
||||
sudo chown -R 1000:1000 $(pwd)/data/elasticsearch
|
||||
docker run --rm --memory="4g" -p 127.0.0.1:9200:9200 -p 127.0.0.1:9300:9300 -e "discovery.type=single-node" -v "$(pwd)/data/elasticsearch:/usr/share/elasticsearch/data" docker.elastic.co/elasticsearch/elasticsearch:7.16.3
|
||||
```
|
||||
|
||||
Configure `app.ini`:
|
||||
|
||||
```ini
|
||||
[indexer]
|
||||
ISSUE_INDEXER_TYPE = elasticsearch
|
||||
ISSUE_INDEXER_CONN_STR = http://elastic:changeme@localhost:9200
|
||||
REPO_INDEXER_ENABLED = true
|
||||
REPO_INDEXER_TYPE = elasticsearch
|
||||
REPO_INDEXER_CONN_STR = http://elastic:changeme@localhost:9200
|
||||
```
|
||||
|
||||
### Building and adding SVGs
|
||||
|
||||
SVG icons are built using the `make svg` target which compiles the icon sources into the output directory `public/assets/img/svg`. Custom icons can be added in the `web_src/svg` directory.
|
||||
|
||||
### Building the Logo
|
||||
|
||||
The PNG and SVG versions of the Gitea logo are built from a single SVG source file `assets/logo.svg` using the `TAGS="gitea" make generate-images` target. To run it, Node.js and npm must be available.
|
||||
|
||||
The same process can also be used to generate custom logo PNGs from a SVG source file by updating `assets/logo.svg` and running `make generate-images`. Omitting the `gitea` tag will update only the user-designated logo files.
|
||||
|
||||
### Updating the API
|
||||
|
||||
When creating new API routes or modifying existing API routes, you **MUST**
|
||||
update and/or create [Swagger](https://swagger.io/docs/specification/2-0/what-is-swagger/)
|
||||
documentation for these using [go-swagger](https://goswagger.io/) comments.
|
||||
The structure of these comments is described in the [specification](https://goswagger.io/use/spec.html#annotation-syntax).
|
||||
If you want more information about the Swagger structure, you can look at the
|
||||
[Swagger 2.0 Documentation](https://swagger.io/docs/specification/2-0/basic-structure/)
|
||||
or compare with a previous PR adding a new API endpoint, e.g. [PR #5483](https://github.com/go-gitea/gitea/pull/5843/files#diff-2e0a7b644cf31e1c8ef7d76b444fe3aaR20)
|
||||
|
||||
You should be careful not to break the API for downstream users which depend
|
||||
on a stable API. In general, this means additions are acceptable, but deletions
|
||||
or fundamental changes to the API will be rejected.
|
||||
|
||||
Once you have created or changed an API endpoint, please regenerate the Swagger
|
||||
documentation using:
|
||||
|
||||
```bash
|
||||
make generate-swagger
|
||||
```
|
||||
|
||||
You should validate your generated Swagger file:
|
||||
|
||||
```bash
|
||||
make swagger-validate
|
||||
```
|
||||
|
||||
You should commit the changed swagger JSON file. The continuous integration
|
||||
server will check that this has been done using:
|
||||
|
||||
```bash
|
||||
make swagger-check
|
||||
```
|
||||
|
||||
:::note
|
||||
Please note you should use the Swagger 2.0 documentation, not the OpenAPI 3 documentation.
|
||||
:::
|
||||
|
||||
### Creating new configuration options
|
||||
|
||||
When creating new configuration options, it is not enough to add them to the
|
||||
`modules/setting` files. You should add information to `custom/conf/app.ini`
|
||||
and to the
|
||||
[configuration cheat sheet](../administration/config-cheat-sheet.md)
|
||||
found in `docs/content/doc/administer/config-cheat-sheet.en-us.md`
|
||||
|
||||
### Changing the logo
|
||||
|
||||
When changing the Gitea logo SVG, you will need to run and commit the results
|
||||
of:
|
||||
|
||||
```bash
|
||||
make generate-images
|
||||
```
|
||||
|
||||
This will create the necessary Gitea favicon and others.
|
||||
|
||||
### Database Migrations
|
||||
|
||||
If you make breaking changes to any of the database persisted structs in the
|
||||
`models/` directory, you will need to make a new migration. These can be found
|
||||
in `models/migrations/`. You can ensure that your migrations work for the main
|
||||
database types using:
|
||||
|
||||
```bash
|
||||
make test-sqlite-migration # with SQLite switched for the appropriate database
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
There are two types of test run by Gitea: Unit tests and Integration Tests.
|
||||
|
||||
### Unit Tests
|
||||
|
||||
Unit tests are covered by `*_test.go` in `go test` system.
|
||||
You can set the environment variable `GITEA_UNIT_TESTS_LOG_SQL=1` to display all SQL statements when running the tests in verbose mode (i.e. when `GOTESTFLAGS=-v` is set).
|
||||
|
||||
```bash
|
||||
TAGS="bindata sqlite sqlite_unlock_notify" make test # Runs the unit tests
|
||||
```
|
||||
|
||||
### Integration Tests
|
||||
|
||||
Unit tests will not and cannot completely test Gitea alone. Therefore, we
|
||||
have written integration tests; however, these are database dependent.
|
||||
|
||||
```bash
|
||||
TAGS="bindata sqlite sqlite_unlock_notify" make build test-sqlite
|
||||
```
|
||||
|
||||
will run the integration tests in an SQLite environment. Integration tests
|
||||
require `git lfs` to be installed. Other database tests are available but
|
||||
may need adjustment to the local environment.
|
||||
|
||||
Take a look at [`tests/integration/README.md`](https://github.com/go-gitea/gitea/blob/main/tests/integration/README.md)
|
||||
for more information and how to run a single test.
|
||||
|
||||
### Testing for a PR
|
||||
|
||||
Our continuous integration will test the code passes its unit tests and that
|
||||
all supported databases will pass integration test in a Docker environment.
|
||||
Migration from several recent versions of Gitea will also be tested.
|
||||
|
||||
Please submit your PR with additional tests and integration tests as
|
||||
appropriate.
|
||||
|
||||
## Documentation for the website
|
||||
|
||||
Documentation for the website is found in `docs/`. If you change this you
|
||||
can test your changes to ensure that they pass continuous integration using:
|
||||
|
||||
```bash
|
||||
make lint-md
|
||||
```
|
||||
|
||||
## Visual Studio Code
|
||||
|
||||
A `launch.json` and `tasks.json` are provided within `contrib/ide/vscode` for
|
||||
Visual Studio Code. Look at
|
||||
[`contrib/ide/README.md`](https://github.com/go-gitea/gitea/blob/main/contrib/ide/README.md)
|
||||
for more information.
|
||||
|
||||
## GoLand
|
||||
|
||||
Clicking the `Run Application` arrow on the function `func main()` in `/main.go`
|
||||
can quickly start a debuggable Gitea instance.
|
||||
|
||||
The `Output Directory` in `Run/Debug Configuration` MUST be set to the
|
||||
gitea project directory (which contains `main.go` and `go.mod`),
|
||||
otherwise, the started instance's working directory is a GoLand's temporary directory
|
||||
and prevents Gitea from loading dynamic resources (eg: templates) in a development environment.
|
||||
|
||||
To run unit tests with SQLite in GoLand, set `-tags sqlite,sqlite_unlock_notify`
|
||||
in `Go tool arguments` of `Run/Debug Configuration`.
|
||||
|
||||
## Submitting PRs
|
||||
|
||||
Once you're happy with your changes, push them up and open a pull request. It
|
||||
is recommended that you allow Gitea Managers and Owners to modify your PR
|
||||
branches as we will need to update it to main before merging and/or may be
|
||||
able to help fix issues directly.
|
||||
|
||||
Any PR requires two approvals from the Gitea maintainers and needs to pass the
|
||||
continuous integration. Take a look at our
|
||||
[`CONTRIBUTING.md`](https://github.com/go-gitea/gitea/blob/main/CONTRIBUTING.md)
|
||||
document.
|
||||
|
||||
If you need more help pop on to [Discord](https://discord.gg/gitea) #Develop
|
||||
and chat there.
|
||||
|
||||
That's it! You are ready to hack on Gitea.
|
||||
@@ -33,7 +33,7 @@ then the config file (app.ini) should exists in the "custom/conf" directory of y
|
||||
Some package vendors might use "/etc/gitea" to store the config file, while some others don't.
|
||||
|
||||
You could manually find the config file (app.ini) by checking Gitea's startup logs
|
||||
or reading the Gitea Web's Site Administrator -> Configuration Summary.
|
||||
or reading the Gitea Web's Site Administrator -> Confugiraton Summary.
|
||||
|
||||
If you are using some isolated enviroments like container (docker),
|
||||
the path you see usually is not what it is in the host's filesystem.
|
||||
|
||||
@@ -6,6 +6,8 @@ aliases:
|
||||
- /en-us/install-from-source
|
||||
---
|
||||
|
||||
:::warning This document is outdated, pleaes refer to [build-source.md](https://github.com/go-gitea/gitea/tree/main/docs/build-source.md):::
|
||||
|
||||
# Installation from source
|
||||
|
||||
You should [install go](https://go.dev/doc/install) and set up your go
|
||||
|
||||
@@ -2,6 +2,8 @@
|
||||
date: "2023-04-27T15:00:00+08:00"
|
||||
slug: "runner"
|
||||
sidebar_position: 20
|
||||
aliases:
|
||||
- /act-runner
|
||||
---
|
||||
|
||||
# Gitea Runner
|
||||
|
||||
@@ -84,7 +84,7 @@ These environment variables are set automatically in every workflow run and can
|
||||
|---|---|---|
|
||||
| `CI` | Always set to `true`. | `true` |
|
||||
| `GITEA_ACTIONS` | Always set to `true`. Useful to distinguish Gitea Actions from other CI systems. | `true` |
|
||||
| `GITEA_ACTIONS_RUNNER_VERSION` | The version of the runner executing the workflow. | `1.0.8` |
|
||||
| `GITEA_ACTIONS_RUNNER_VERSION` | The version of the runner executing the workflow. | `0.2.11` |
|
||||
| `GITEA_ENV`<br/>`GITHUB_ENV` | Path to the file that sets environment variables for subsequent steps. | `/home/runner/work/_temp/_runner_file_commands/set_env_***` |
|
||||
| `GITEA_OUTPUT`<br/>`GITHUB_OUTPUT` | Path to the file that sets step output parameters. | `/home/runner/work/_temp/_runner_file_commands/set_output_***` |
|
||||
| `GITEA_PATH`<br/>`GITHUB_PATH` | Path to the file that adds system `PATH` entries for subsequent steps. | `/home/runner/work/_temp/_runner_file_commands/add_path_***` |
|
||||
|
||||
@@ -185,16 +185,12 @@ const config = {
|
||||
label: "main",
|
||||
banner: "unreleased",
|
||||
},
|
||||
"1.0.8": {
|
||||
path: "1.0.8",
|
||||
label: "1.0.8",
|
||||
},
|
||||
"0.2.11": {
|
||||
path: "0.2.11",
|
||||
label: "0.2.11",
|
||||
},
|
||||
},
|
||||
lastVersion: "1.0.8",
|
||||
lastVersion: "0.2.11",
|
||||
editUrl: ({
|
||||
versionDocsDirPath,
|
||||
docPath,
|
||||
@@ -386,10 +382,10 @@ const config = {
|
||||
activeBaseRegex: "api/(1.22|1.23|1.24|1.25|1.26|next)/",
|
||||
},
|
||||
{
|
||||
to: "/runner/1.0.8/",
|
||||
to: "/runner/0.2.11/",
|
||||
label: "Runner",
|
||||
position: "left",
|
||||
activeBaseRegex: "runner/(1.0.8|0.2.11|next)/",
|
||||
activeBaseRegex: "runner/(0.2.11|next)/",
|
||||
},
|
||||
{
|
||||
position: "left",
|
||||
@@ -432,7 +428,6 @@ const config = {
|
||||
position: "right",
|
||||
items: [
|
||||
{ to: "/runner/next/", label: "development" },
|
||||
{ to: "/runner/1.0.8/", label: "1.0.8" },
|
||||
{ to: "/runner/0.2.11/", label: "0.2.11" },
|
||||
],
|
||||
routerRgx: "/runner/",
|
||||
|
||||
@@ -51,5 +51,5 @@
|
||||
"engines": {
|
||||
"node": ">=18"
|
||||
},
|
||||
"packageManager": "pnpm@10.34.2"
|
||||
"packageManager": "pnpm@10.33.4"
|
||||
}
|
||||
|
||||
1309
pnpm-lock.yaml
generated
1309
pnpm-lock.yaml
generated
File diff suppressed because it is too large
Load Diff
@@ -1,456 +0,0 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
slug: /
|
||||
---
|
||||
|
||||
# Gitea Runner
|
||||
|
||||
This page will introduce the [Gitea Runner](https://gitea.com/gitea/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: 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 runner.
|
||||
|
||||
## Installation with binary
|
||||
|
||||
### Download the binary
|
||||
|
||||
You can download the binary from the [release page](https://gitea.com/gitea/runner/releases).
|
||||
However, if you want to use the latest nightly build, you can download it from the [download page](https://dl.gitea.com/gitea-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 runner
|
||||
./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
|
||||
./runner generate-config
|
||||
```
|
||||
|
||||
The default configuration is safe to use without any modification, so you can just use it directly.
|
||||
|
||||
```bash
|
||||
./runner generate-config > config.yaml
|
||||
./runner --config config.yaml [command]
|
||||
```
|
||||
|
||||
### Register the runner
|
||||
|
||||
Registration is required before running Gitea 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 runner can be registered by running the following command.
|
||||
|
||||
```bash
|
||||
./runner register
|
||||
```
|
||||
|
||||
Alternatively, you can use the `--config` option to specify the configuration file mentioned in the previous section.
|
||||
|
||||
```bash
|
||||
./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
|
||||
./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.
|
||||
|
||||
The updated commands for registering the runner as ephemeral are listed below. Refer to the previous section for detailed information on registering the runner.
|
||||
|
||||
```bash
|
||||
./runner register --ephemeral
|
||||
```
|
||||
|
||||
```bash
|
||||
./runner --config config.yaml register --ephemeral
|
||||
```
|
||||
|
||||
```bash
|
||||
./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
|
||||
./runner daemon
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```bash
|
||||
./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 Gitea Runner as a [systemd](https://en.wikipedia.org/wiki/Systemd) service. Create an unprivileged `runner` user on your system, and create the following file in `/etc/systemd/system/runner.service`. The paths in `ExecStart` and `WorkingDirectory` may need to be adjusted depending on where you installed the `runner` binary, its configuration file, and the home directory of the `runner` user.
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=Gitea Actions runner
|
||||
Documentation=https://gitea.com/gitea/runner
|
||||
After=docker.service
|
||||
|
||||
[Service]
|
||||
ExecStart=/usr/local/bin/runner daemon --config /etc/runner/config.yaml
|
||||
ExecReload=/bin/kill -s HUP $MAINPID
|
||||
WorkingDirectory=/var/lib/runner
|
||||
TimeoutSec=0
|
||||
RestartSec=10
|
||||
Restart=always
|
||||
User=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 runner --now
|
||||
```
|
||||
|
||||
If using Docker, the `runner` user should also be added to the `docker` group before starting the service. Keep in mind that this effectively gives `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 `_runner` user can be created via the `dscl` tool. The following file should then be created in the directory `/Library/LaunchDaemon/com.gitea.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.runner</string>
|
||||
<key>ProgramArguments</key>
|
||||
<array>
|
||||
<string>/usr/local/bin/runner</string>
|
||||
<string>daemon</string>
|
||||
<string>--config</string>
|
||||
<string>/etc/runner/config.yaml</string>
|
||||
</array>
|
||||
<key>RunAtLoad</key>
|
||||
<true/>
|
||||
<key>KeepAlive</key>
|
||||
<true/>
|
||||
<key>WorkingDirectory</key>
|
||||
<string>/var/lib/runner</string>
|
||||
<key>StandardOutPath</key>
|
||||
<string>/var/lib/runner/runner.log</string>
|
||||
<key>StandardErrorPath</key>
|
||||
<string>/var/lib/runner/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/runner</string>
|
||||
</dict>
|
||||
<key>UserName</key>
|
||||
<string>_runner</string>
|
||||
</dict>
|
||||
</plist>
|
||||
```
|
||||
|
||||
Then:
|
||||
|
||||
```bash
|
||||
sudo launchctl load /Library/LaunchDaemon/com.gitea.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/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/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/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/runner:latest 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 runner yet.
|
||||
Before running the 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 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/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/runner:latest
|
||||
```
|
||||
|
||||
You may notice that we have mounted `/var/run/docker.sock` into the container.
|
||||
This is because with this setup, the 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 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/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/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/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 `./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/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 [runner](https://gitea.com/gitea/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/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 `./runner daemon --config config.yaml`.
|
||||
@@ -1,4 +1,3 @@
|
||||
[
|
||||
"1.0.8",
|
||||
"0.2.11"
|
||||
]
|
||||
|
||||
@@ -33,7 +33,7 @@ then the config file (app.ini) should exists in the "custom/conf" directory of y
|
||||
Some package vendors might use "/etc/gitea" to store the config file, while some others don't.
|
||||
|
||||
You could manually find the config file (app.ini) by checking Gitea's startup logs
|
||||
or reading the Gitea Web's Site Administrator -> Configuration Summary.
|
||||
or reading the Gitea Web's Site Administrator -> Confugiraton Summary.
|
||||
|
||||
If you are using some isolated enviroments like container (docker),
|
||||
the path you see usually is not what it is in the host's filesystem.
|
||||
|
||||
@@ -33,7 +33,7 @@ then the config file (app.ini) should exists in the "custom/conf" directory of y
|
||||
Some package vendors might use "/etc/gitea" to store the config file, while some others don't.
|
||||
|
||||
You could manually find the config file (app.ini) by checking Gitea's startup logs
|
||||
or reading the Gitea Web's Site Administrator -> Configuration Summary.
|
||||
or reading the Gitea Web's Site Administrator -> Confugiraton Summary.
|
||||
|
||||
If you are using some isolated enviroments like container (docker),
|
||||
the path you see usually is not what it is in the host's filesystem.
|
||||
|
||||
@@ -33,7 +33,7 @@ then the config file (app.ini) should exists in the "custom/conf" directory of y
|
||||
Some package vendors might use "/etc/gitea" to store the config file, while some others don't.
|
||||
|
||||
You could manually find the config file (app.ini) by checking Gitea's startup logs
|
||||
or reading the Gitea Web's Site Administrator -> Configuration Summary.
|
||||
or reading the Gitea Web's Site Administrator -> Confugiraton Summary.
|
||||
|
||||
If you are using some isolated enviroments like container (docker),
|
||||
the path you see usually is not what it is in the host's filesystem.
|
||||
|
||||
@@ -33,7 +33,7 @@ then the config file (app.ini) should exists in the "custom/conf" directory of y
|
||||
Some package vendors might use "/etc/gitea" to store the config file, while some others don't.
|
||||
|
||||
You could manually find the config file (app.ini) by checking Gitea's startup logs
|
||||
or reading the Gitea Web's Site Administrator -> Configuration Summary.
|
||||
or reading the Gitea Web's Site Administrator -> Confugiraton Summary.
|
||||
|
||||
If you are using some isolated enviroments like container (docker),
|
||||
the path you see usually is not what it is in the host's filesystem.
|
||||
|
||||
@@ -33,7 +33,7 @@ then the config file (app.ini) should exists in the "custom/conf" directory of y
|
||||
Some package vendors might use "/etc/gitea" to store the config file, while some others don't.
|
||||
|
||||
You could manually find the config file (app.ini) by checking Gitea's startup logs
|
||||
or reading the Gitea Web's Site Administrator -> Configuration Summary.
|
||||
or reading the Gitea Web's Site Administrator -> Confugiraton Summary.
|
||||
|
||||
If you are using some isolated enviroments like container (docker),
|
||||
the path you see usually is not what it is in the host's filesystem.
|
||||
|
||||
Reference in New Issue
Block a user