foster/forgejo-docs
0
0
Fork 0
mirror of https://codeberg.org/forgejo/docs.git synced 2024-11-21 17:36:59 -05:00
Code Issues Activity

fix: remove h1-level headings in docs

Browse source 
Increases depth of markdown headings to avoid 1st-level headings

# Conflicts:
#	v1.19/user/project.md
#	v1.19/user/protection.md
#	v1.19/user/push-to-create.md
This commit is contained in:
Caesar Schinas 2023-08-05 11:48:30 +01:00
parent 85a71e3c09
commit e688f3324b
No known key found for this signature in database
GPG key ID: AE9108461BEA5ACF
10 changed files with 88 additions and 88 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

36
admin/actions.md
View file

@ -12,7 +12,7 @@ ENABLED = true
`Forgejo` itself does not run the jobs, it relies on the [Forgejo runner](https://code.forgejo.org/forgejo/runner) to do so. `Forgejo` itself does not run the jobs, it relies on the [Forgejo runner](https://code.forgejo.org/forgejo/runner) to do so.
# Default Actions URL ## Default Actions URL
When `uses:` does not specify an absolution URL for the `Action`, the When `uses:` does not specify an absolution URL for the `Action`, the
value of `DEFAULT_ACTIONS_URL` is prepended to it. value of `DEFAULT_ACTIONS_URL` is prepended to it.
@ -39,9 +39,9 @@ instance if an action has `uses: foo/bar@main` it will clone and try
to run the action found at `DEFAULT_ACTIONS_URL/foo/bar` if it exists, to run the action found at `DEFAULT_ACTIONS_URL/foo/bar` if it exists,
even if it provides something different than what is expected. even if it provides something different than what is expected.
# Forgejo runner ## Forgejo runner
## Installation ### Installation
Download the latest [binary release](https://code.forgejo.org/forgejo/runner/releases) and verify their signature: Download the latest [binary release](https://code.forgejo.org/forgejo/runner/releases) and verify their signature:
@ -55,11 +55,11 @@ Good signature from "Forgejo <contact@forgejo.org>"
aka "Forgejo Releases <release@forgejo.org>" aka "Forgejo Releases <release@forgejo.org>"
``` ```
### Docker #### Docker
For jobs to run in containers, the `Forgejo runner` needs access to [Docker](https://docs.docker.com/engine/install/). For jobs to run in containers, the `Forgejo runner` needs access to [Docker](https://docs.docker.com/engine/install/).
### Podman #### Podman
While Podman is generally compatible to Docker, While Podman is generally compatible to Docker,
it does not run socket for managing containers by default it does not run socket for managing containers by default
@ -75,7 +75,7 @@ $ podman system service -t 0 &
$ DOCKER_HOST=unix://${XDG_RUNTIME_DIR}/podman/podman.sock ./forgejo-runner daemon $ DOCKER_HOST=unix://${XDG_RUNTIME_DIR}/podman/podman.sock ./forgejo-runner daemon
``` ```
### LXC #### LXC
For jobs to run in LXC containers, the `Forgejo runner` needs passwordless sudo access for all `lxc-*` commands on a Debian GNU/Linux `bookworm` system where [LXC](https://linuxcontainers.org/lxc/) is installed. The [LXC helpers](https://code.forgejo.org/forgejo/lxc-helpers/) can be used as follows to create a suitable container: For jobs to run in LXC containers, the `Forgejo runner` needs passwordless sudo access for all `lxc-*` commands on a Debian GNU/Linux `bookworm` system where [LXC](https://linuxcontainers.org/lxc/) is installed. The [LXC helpers](https://code.forgejo.org/forgejo/lxc-helpers/) can be used as follows to create a suitable container:
@ -100,11 +100,11 @@ $ wget -O forgejo-runner https://code.forgejo.org/forgejo/runner/releases/downlo
> **Warning:** LXC containers do not provide a level of security that makes them safe for potentially malicious users to run jobs. They provide an excellent isolation for jobs that may accidentally damage the system they run on. > **Warning:** LXC containers do not provide a level of security that makes them safe for potentially malicious users to run jobs. They provide an excellent isolation for jobs that may accidentally damage the system they run on.
## Registration ### Registration
The `Forgejo runner` needs to connect to a `Forgejo` instance and must be registered before doing so. It will give it permission to read the repositories and send back information to `Forgejo` such as the logs or its status. The `Forgejo runner` needs to connect to a `Forgejo` instance and must be registered before doing so. It will give it permission to read the repositories and send back information to `Forgejo` such as the logs or its status.
### Online registration #### Online registration
A special kind of token is needed and can be obtained from the `Create new runner` button: A special kind of token is needed and can be obtained from the `Create new runner` button:
@ -137,7 +137,7 @@ It will create a `.runner` file that looks like:
} }
``` ```
### Offline registration #### Offline registration
When Infrastructure as Code (Ansible, kubernetes, etc.) is used to When Infrastructure as Code (Ansible, kubernetes, etc.) is used to
deploy and configure both Forgejo and the Forgejo runner, it may be deploy and configure both Forgejo and the Forgejo runner, it may be
@ -167,7 +167,7 @@ $ forgejo-runner create-runner-file --instance https://example.conf \
> **NOTE:** the labels known to the runner are defined in the `config.yml` and **MUST** match the labels provided to the `forgejo-cli actions register` command above. In this example, `labels: ['docker:docker://node:16-bullseye']` will tell the Forgejo runner that when a **job** specifies `runs-on: docker`, it will run in a container created from the `node:16-bullseye` image by default. > **NOTE:** the labels known to the runner are defined in the `config.yml` and **MUST** match the labels provided to the `forgejo-cli actions register` command above. In this example, `labels: ['docker:docker://node:16-bullseye']` will tell the Forgejo runner that when a **job** specifies `runs-on: docker`, it will run in a container created from the `node:16-bullseye` image by default.
## Configuration ### Configuration
The default configuration for the runner can be The default configuration for the runner can be
displayed with `forgejo-runner generate-config`, stored in a displayed with `forgejo-runner generate-config`, stored in a
@ -258,7 +258,7 @@ host:
workdir_parent: workdir_parent:
``` ```
## Cache configuration ### Cache configuration
Some actions such as https://code.forgejo.org/actions/cache or Some actions such as https://code.forgejo.org/actions/cache or
https://code.forgejo.org/actions/setup-go can communicate with the https://code.forgejo.org/actions/setup-go can communicate with the
@ -274,7 +274,7 @@ If the machine on which the `Forgejo runner` is running has a slow
disk and plenty of CPU and bandwidth, it may be better to not activate disk and plenty of CPU and bandwidth, it may be better to not activate
the cache as it can slow down the execution time. the cache as it can slow down the execution time.
## Running the daemon ### Running the daemon
Once the `Forgejo runner` is successfully registered, it can be run from the directory in which the `.runner` file is found with: Once the `Forgejo runner` is successfully registered, it can be run from the directory in which the `.runner` file is found with:
@ -317,7 +317,7 @@ It will also show a similar output in the `Actions` tab of the repository.
If no `Forgejo runner` is available, `Forgejo` will wait for one to connect and submit the job as soon as it is available. If no `Forgejo runner` is available, `Forgejo` will wait for one to connect and submit the job as soon as it is available.
## Labels and `runs-on` ### Labels and `runs-on`
The workflows / tasks defined in the files found in `.forgejo/workflows` must specify the environment they need to run with `runs-on`. Each `Forgejo runner` declares with **labels** which one they support so `Forgejo` knows sends them tasks accordingly. For instance if a job within a workflow has: The workflows / tasks defined in the files found in `.forgejo/workflows` must specify the environment they need to run with `runs-on`. Each `Forgejo runner` declares with **labels** which one they support so `Forgejo` knows sends them tasks accordingly. For instance if a job within a workflow has:
@ -327,25 +327,25 @@ runs-on: docker
it will be submitted to a runner that registered with a `docker` label (for instance with `--labels docker:docker://node:16-bullseye`). it will be submitted to a runner that registered with a `docker` label (for instance with `--labels docker:docker://node:16-bullseye`).
### Docker #### Docker
If `runs-on` is matched to a label that contains `docker://`, the rest of it is interpreted as the default container image to use if no other is specified. The runner will execute all the steps, as root, within a container created from that image. If `runs-on` is matched to a label that contains `docker://`, the rest of it is interpreted as the default container image to use if no other is specified. The runner will execute all the steps, as root, within a container created from that image.
### LXC #### LXC
If `runs-on` is `self-hosted`, the runner will execute all the steps, as root, within a Debian GNU/Linux `bullseye` LXC container. If `runs-on` is `self-hosted`, the runner will execute all the steps, as root, within a Debian GNU/Linux `bullseye` LXC container.
## Host environment ### Host environment
Certain hosts may require specific configurations for runners to work smoothly. Anything specific to these host environments can be found below. Certain hosts may require specific configurations for runners to work smoothly. Anything specific to these host environments can be found below.
### NixOS #### NixOS
The `gitea-actions-runner` recipe was released in NixOS 23.05. It can be configured via `services.gitea-actions-runner`. The `gitea-actions-runner` recipe was released in NixOS 23.05. It can be configured via `services.gitea-actions-runner`.
Please note that the `services.gitea-actions-runner.instances.<name>.labels` key may be set to `[]` (an empty list) to use the packaged Forgejo instance list. One of `virtualisation.docker.enable` or `virtualisation.podman.enable` will need to be set. The default Forgejo image list is populated with docker images. Please note that the `services.gitea-actions-runner.instances.<name>.labels` key may be set to `[]` (an empty list) to use the packaged Forgejo instance list. One of `virtualisation.docker.enable` or `virtualisation.podman.enable` will need to be set. The default Forgejo image list is populated with docker images.
#### IPv6 on docker ##### IPv6 on docker
IPv6 support is not enabled by default in docker. The following snippet enables this. IPv6 support is not enabled by default in docker. The following snippet enables this.

24
admin/installation.md
View file

@ -4,7 +4,7 @@ license: 'CC-BY-SA-4.0'
origin_url: 'https://github.com/DanielGibson/DanielGibson.github.io/blob/58362695f743a545d2530508ce42d5fe1eea84a9/content/post/setup-vps-with-wireguard-and-forgejo.md' origin_url: 'https://github.com/DanielGibson/DanielGibson.github.io/blob/58362695f743a545d2530508ce42d5fe1eea84a9/content/post/setup-vps-with-wireguard-and-forgejo.md'
--- ---
# Installation with Docker ## Installation with Docker
Forgejo provides [container images](https://codeberg.org/forgejo/-/packages/container/forgejo/versions) for use with Docker or other containerization tools. Forgejo provides [container images](https://codeberg.org/forgejo/-/packages/container/forgejo/versions) for use with Docker or other containerization tools.
@ -47,11 +47,11 @@ services:
Note that the volume should be owned by the user/group with the UID/GID specified in the config file. Note that the volume should be owned by the user/group with the UID/GID specified in the config file.
If you don't give the volume correct permissions, the container may not start. If you don't give the volume correct permissions, the container may not start.
## Databases ### Databases
In the following each database is shown as part of a `docker-compose` example file, with a `diff like` presentation that highlights additions to the example above. In the following each database is shown as part of a `docker-compose` example file, with a `diff like` presentation that highlights additions to the example above.
### MySQL database #### MySQL database
```yaml ```yaml
version: "3" version: "3"
@ -99,7 +99,7 @@ services:
+ - ./mysql:/var/lib/mysql + - ./mysql:/var/lib/mysql
``` ```
### PostgreSQL database #### PostgreSQL database
```yaml ```yaml
version: "3" version: "3"
@ -146,9 +146,9 @@ services:
+ - ./postgres:/var/lib/postgresql/data + - ./postgres:/var/lib/postgresql/data
``` ```
# Installation from binary ## Installation from binary
## Install Forgejo and git, create git user ### Install Forgejo and git, create git user
> **NOTE:** this guide assumes that you'll host on the server with the domain git.example.com. > **NOTE:** this guide assumes that you'll host on the server with the domain git.example.com.
@ -186,7 +186,7 @@ like Fedora, CentOS etc.), run this instead:
--gid git --home-dir /home/git --create-home git --gid git --home-dir /home/git --create-home git
``` ```
## Create directories Forgejo will use ### Create directories Forgejo will use
Now create the directories Forgejo will use and set access rights appropriately: Now create the directories Forgejo will use and set access rights appropriately:
@ -200,7 +200,7 @@ _This is the directory Forgejo's config, called `app.ini`, is stored in. Initial
be writable by Forgejo, but after the installation you can make it read-only for Forgejo because be writable by Forgejo, but after the installation you can make it read-only for Forgejo because
then it shouldn't modify it anymore._ then it shouldn't modify it anymore._
## Optional: Set up database ### Optional: Set up database
When using sqlite as Forgejos database, nothing needs to be done here. When using sqlite as Forgejos database, nothing needs to be done here.
@ -210,7 +210,7 @@ is good enough for at least 10 users, but might even suffice for more).
See [Forgejos Database Preparation guide](../database-preparation/) for See [Forgejos Database Preparation guide](../database-preparation/) for
setup instructions. setup instructions.
## Install systemd service for Forgejo ### Install systemd service for Forgejo
Forgejo provides a Forgejo provides a
[systemd service script](https://codeberg.org/forgejo/forgejo/src/branch/forgejo/contrib/systemd/forgejo.service). [systemd service script](https://codeberg.org/forgejo/forgejo/src/branch/forgejo/contrib/systemd/forgejo.service).
@ -225,7 +225,7 @@ Now enable and start the Forgejo service, so you can go on with the installation
`# systemctl enable forgejo.service` `# systemctl enable forgejo.service`
`# systemctl start forgejo.service` `# systemctl start forgejo.service`
## Forgejos web-based configuration ### Forgejos web-based configuration
You should now be able to access Forgejo in your local web browser, so open http://git.example.com:3000/. You should now be able to access Forgejo in your local web browser, so open http://git.example.com:3000/.
@ -256,7 +256,7 @@ can create an account to then get to the dashboard.
So far, so good, but we're not quite done yet - some manual configuration in the app.ini is needed. So far, so good, but we're not quite done yet - some manual configuration in the app.ini is needed.
## Further configuration in Forgejo's app.ini ### Further configuration in Forgejo's app.ini
Stop the forgejo service: Stop the forgejo service:
`# systemctl stop forgejo.service` `# systemctl stop forgejo.service`
@ -347,7 +347,7 @@ You can test sending a mail by clicking the user button on the upper right of th
("Profile and Settings"), then `Site Administration`, then `Configuration` and under ("Profile and Settings"), then `Site Administration`, then `Configuration` and under
`Mailer Configuration` type in your mail address and click `Send Testing Email`. `Mailer Configuration` type in your mail address and click `Send Testing Email`.
## General hints for using Forgejo ### General hints for using Forgejo
Sometimes you may want/need to use the Forgejo Sometimes you may want/need to use the Forgejo
[command line interface](./command-line/). [command line interface](./command-line/).

6
admin/search-engines-indexation.md
View file

@ -4,12 +4,12 @@ license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/administration/search-engines-indexation.en-us.md' origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/administration/search-engines-indexation.en-us.md'
--- ---
# Search engines indexation of your Forgejo installation ## Search engines indexation of your Forgejo installation
By default your Forgejo installation will be indexed by search engines. By default your Forgejo installation will be indexed by search engines.
If you don't want your repository to be visible for search engines read further. If you don't want your repository to be visible for search engines read further.
## Block search engines indexation using robots.txt ### Block search engines indexation using robots.txt
To make Forgejo serve a custom `robots.txt` (default: empty 404) for top level installations, To make Forgejo serve a custom `robots.txt` (default: empty 404) for top level installations,
create a file called `robots.txt` at the root of the `CustomPath` as displayed in the `/admin` page. create a file called `robots.txt` at the root of the `CustomPath` as displayed in the `/admin` page.
@ -28,7 +28,7 @@ User-agent: *
Disallow: /forgejo/ Disallow: /forgejo/
``` ```
## Disallow crawling archives to save disk space ### Disallow crawling archives to save disk space
If the archive files are crawled, they will be generated dynamically If the archive files are crawled, they will be generated dynamically
and kept around which can amount to a lot of disk. To prevent that and kept around which can amount to a lot of disk. To prevent that

2
developer/DISCUSSIONS.md
View file

@ -13,7 +13,7 @@ Dedicated repositories in the [Forgejo organization](https://codeberg.org/forgej
Other discussions regarding all **non technical aspects** of Forgejo, such as the governance, happen in a dedicated [issue tracker](https://codeberg.org/forgejo/discussions/issues) and in the [matrix chatroom](https://matrix.to/#/#forgejo-chat:matrix.org). Other discussions regarding all **non technical aspects** of Forgejo, such as the governance, happen in a dedicated [issue tracker](https://codeberg.org/forgejo/discussions/issues) and in the [matrix chatroom](https://matrix.to/#/#forgejo-chat:matrix.org).
# Security ## Security
The [security team](https://codeberg.org/forgejo/governance/src/branch/main/TEAMS.md#security) takes care of security vulnerabilities. It handles sensitive security-related issues reported to [security@forgejo.org](mailto:security@forgejo.org) using [encryption](https://keyoxide.org/security@forgejo.org). The [security team](https://codeberg.org/forgejo/governance/src/branch/main/TEAMS.md#security) takes care of security vulnerabilities. It handles sensitive security-related issues reported to [security@forgejo.org](mailto:security@forgejo.org) using [encryption](https://keyoxide.org/security@forgejo.org).

8
developer/from-source.md
View file

@ -4,7 +4,7 @@ license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/installation/from-source.en-us.md' origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/installation/from-source.en-us.md'
--- ---
# Installation from source ## Installation from source
You should [install go](https://golang.org/doc/install) and set up your go You should [install go](https://golang.org/doc/install) and set up your go
environment correctly. In particular, it is recommended to set the `$GOPATH` environment correctly. In particular, it is recommended to set the `$GOPATH`
@ -26,7 +26,7 @@ executable path, you will have to manage this yourself.
obtain the same version as our continuous integration, see the advice given in obtain the same version as our continuous integration, see the advice given in
[Hacking on Forgejo]({{< relref "doc/development/hacking-on-forgejo.en-us.md" >}}) [Hacking on Forgejo]({{< relref "doc/development/hacking-on-forgejo.en-us.md" >}})
## Download ### Download
First, we must retrieve the source code. Since, the advent of go modules, the First, we must retrieve the source code. Since, the advent of go modules, the
simplest way of doing this is to use Git directly as we no longer have to have simplest way of doing this is to use Git directly as we no longer have to have
@ -57,7 +57,7 @@ git tag -l
git checkout v1.20.0-5 git checkout v1.20.0-5
``` ```
## Build ### Build
To build from source, the following programs must be present on the system: To build from source, the following programs must be present on the system:
@ -106,7 +106,7 @@ TAGS="bindata" make backend
Webpack source maps are by default enabled in development builds and disabled in production builds. They can be enabled by setting the `ENABLE_SOURCEMAP=true` environment variable. Webpack source maps are by default enabled in development builds and disabled in production builds. They can be enabled by setting the `ENABLE_SOURCEMAP=true` environment variable.
## Test ### Test
After following the steps above, a `forgejo` binary will be available in the working directory. After following the steps above, a `forgejo` binary will be available in the working directory.
It can be tested from this directory or moved to a directory with test data. When Forgejo is It can be tested from this directory or moved to a directory with test data. When Forgejo is

72
user/actions.md
View file

@ -8,7 +8,7 @@ similar: 'https://github.com/go-gitea/gitea/blob/main/docs/content/doc/usage/act
The following guide explains key **concepts** to help understand how `workflows` are interpreted, with a set of **examples** that can be copy/pasted and modified to fit particular use cases. The following guide explains key **concepts** to help understand how `workflows` are interpreted, with a set of **examples** that can be copy/pasted and modified to fit particular use cases.
# Quick start ## Quick start
- Verify that `Enable Repository Actions` is checked in the `Repository` tab of the `/{owner}/{repository}/settings` page. If the checkbox does not show it means the administrator of the Forgejo instance did not activate the feature. - Verify that `Enable Repository Actions` is checked in the `Repository` tab of the `/{owner}/{repository}/settings` page. If the checkbox does not show it means the administrator of the Forgejo instance did not activate the feature.
![enable actions](../../../../images/v1.20/user/actions/enable-repository.png) ![enable actions](../../../../images/v1.20/user/actions/enable-repository.png)
@ -27,13 +27,13 @@ The following guide explains key **concepts** to help understand how `workflows`
- Click on the workflow link to see the details and the job execution logs. - Click on the workflow link to see the details and the job execution logs.
![actions results](../../../../images/v1.20/user/actions/workflow-demo.png) ![actions results](../../../../images/v1.20/user/actions/workflow-demo.png)
# Concepts ## Concepts
## Forgejo runner ### Forgejo runner
`Forgejo` itself does not run the `jobs`, it relies on the [Forgejo runner](https://code.forgejo.org/forgejo/runner) to do so. See the [Forgejo Actions administrator guide](../../admin/actions/) for more information. `Forgejo` itself does not run the `jobs`, it relies on the [Forgejo runner](https://code.forgejo.org/forgejo/runner) to do so. See the [Forgejo Actions administrator guide](../../admin/actions/) for more information.
## Actions ### Actions
An `Action` is a repository that contains the equivalent of a function in any programming language. It comes in two flavors, depending on the file found at the root of the repository: An `Action` is a repository that contains the equivalent of a function in any programming language. It comes in two flavors, depending on the file found at the root of the repository:
@ -44,18 +44,18 @@ One of the most commonly used action is [checkout](https://code.forgejo.org/acti
Just as any other program of function, an `Action` has pre-requisites to successfully be installed and run. When looking at re-using an existing `Action`, this is an important consideration. For instance [setup-go](https://code.forgejo.org/actions/setup-go) depends on NodeJS during installation. Just as any other program of function, an `Action` has pre-requisites to successfully be installed and run. When looking at re-using an existing `Action`, this is an important consideration. For instance [setup-go](https://code.forgejo.org/actions/setup-go) depends on NodeJS during installation.
## Expressions ### Expressions
In a `workflow` file strings that look like `${{ ... }}` are evaluated by the `Forgejo runner` and are called expressions. As a shortcut, `if: ${{ ... }}` is equivalent to `if: ...`, i.e the `${{ }}` surrounding the expression is implicit and can be stripped. [Checkout the example](https://code.forgejo.org/actions/setup-forgejo/src/branch/main/testdata/example-expression/.forgejo/workflows/test.yml) that illustrates expressions. In a `workflow` file strings that look like `${{ ... }}` are evaluated by the `Forgejo runner` and are called expressions. As a shortcut, `if: ${{ ... }}` is equivalent to `if: ...`, i.e the `${{ }}` surrounding the expression is implicit and can be stripped. [Checkout the example](https://code.forgejo.org/actions/setup-forgejo/src/branch/main/testdata/example-expression/.forgejo/workflows/test.yml) that illustrates expressions.
### Literals #### Literals
- boolean: true or false - boolean: true or false
- null: null - null: null
- number: any number format supported by JSON - number: any number format supported by JSON
- string: enclosed in single quotes. Two single quotes - string: enclosed in single quotes. Two single quotes
### Logical operators #### Logical operators
| Operator | Description | | Operator | Description |
| -------- | --------------------- | | -------- | --------------------- |
@ -74,7 +74,7 @@ In a `workflow` file strings that look like `${{ ... }}` are evaluated by the `F
> **NOTE:** String comparisons are case insensitive. > **NOTE:** String comparisons are case insensitive.
### Functions #### Functions
- `contains( search, item )`. Returns `true` if `search` contains `item`. If `search` is an array, this function returns `true` if the `item` is an element in the array. If `search` is a string, this function returns `true` if the `item` is a substring of `search`. This function is not case sensitive. Casts values to a string. - `contains( search, item )`. Returns `true` if `search` contains `item`. If `search` is an array, this function returns `true` if the `item` is an element in the array. If `search` is a string, this function returns `true` if the `item` is a substring of `search`. This function is not case sensitive. Casts values to a string.
- `startsWith( searchString, searchValue )`. Returns `true` when `searchString` starts with `searchValue`. This function is not case sensitive. Casts values to a string. - `startsWith( searchString, searchValue )`. Returns `true` when `searchString` starts with `searchValue`. This function is not case sensitive. Casts values to a string.
@ -84,7 +84,7 @@ In a `workflow` file strings that look like `${{ ... }}` are evaluated by the `F
- `toJSON(value)`. Returns a pretty-print JSON representation of `value`. - `toJSON(value)`. Returns a pretty-print JSON representation of `value`.
- `fromJSON(value)`. Returns a JSON object or JSON data type for `value`. You can use this function to provide a JSON object as an evaluated expression or to convert environment variables from a string. - `fromJSON(value)`. Returns a JSON object or JSON data type for `value`. You can use this function to provide a JSON object as an evaluated expression or to convert environment variables from a string.
## Caching commonly used files ### Caching commonly used files
When a `job` starts, it can communicate with the `Forgejo runner` to When a `job` starts, it can communicate with the `Forgejo runner` to
fetch commonly used files that were saved by previous runs. For fetch commonly used files that were saved by previous runs. For
@ -95,7 +95,7 @@ that by default to save downloading and compiling packages found in
It is also possible to explicitly control what is cached and when It is also possible to explicitly control what is cached and when
using the https://code.forgejo.org/actions/cache action. using the https://code.forgejo.org/actions/cache action.
## Services ### Services
PostgreSQL, redis and other services can be run from container images with something similar to the following. See also the [set of examples](https://code.forgejo.org/actions/setup-forgejo/src/branch/main/testdata/example-service/.forgejo/workflows/). PostgreSQL, redis and other services can be run from container images with something similar to the following. See also the [set of examples](https://code.forgejo.org/actions/setup-forgejo/src/branch/main/testdata/example-service/.forgejo/workflows/).
@ -112,33 +112,33 @@ A container with the specified `image:` is run before the `job` starts and is te
The IP address of `pgsql` is on the same [docker network](https://docs.docker.com/engine/reference/commandline/network/) as the container running the **steps** and there is no need for port binding (see the [docker run --publish](https://docs.docker.com/engine/reference/commandline/run/) option for more information). The `postgres:15` image exposes the PostgreSQL port 5432 and a client will be able to connect as [shown in this example](https://code.forgejo.org/actions/setup-forgejo/src/branch/main/testdata/example-service/.forgejo/workflows/postgresql.yml) The IP address of `pgsql` is on the same [docker network](https://docs.docker.com/engine/reference/commandline/network/) as the container running the **steps** and there is no need for port binding (see the [docker run --publish](https://docs.docker.com/engine/reference/commandline/run/) option for more information). The `postgres:15` image exposes the PostgreSQL port 5432 and a client will be able to connect as [shown in this example](https://code.forgejo.org/actions/setup-forgejo/src/branch/main/testdata/example-service/.forgejo/workflows/postgresql.yml)
### image #### image
The location of the container image to run. The location of the container image to run.
### env #### env
Key/value pairs injected in the environment when running the container, equivalent to [--env](https://docs.docker.com/engine/reference/commandline/run/). Key/value pairs injected in the environment when running the container, equivalent to [--env](https://docs.docker.com/engine/reference/commandline/run/).
### cmd #### cmd
A list of command and arguments, equivalent to [[COMMAND] [ARG...]](https://docs.docker.com/engine/reference/commandline/run/). A list of command and arguments, equivalent to [[COMMAND] [ARG...]](https://docs.docker.com/engine/reference/commandline/run/).
### options #### options
A string of additional options, as documented [docker run](https://docs.docker.com/engine/reference/commandline/run/). For instance: "--workdir /myworkdir --ulimit nofile=1024:1024". A string of additional options, as documented [docker run](https://docs.docker.com/engine/reference/commandline/run/). For instance: "--workdir /myworkdir --ulimit nofile=1024:1024".
> **NOTE:** the `--volume` option is restricted to a whitelist of volumes configured in the runner executing the task. See the [Forgejo Actions administrator guide](../../admin/actions/) for more information. > **NOTE:** the `--volume` option is restricted to a whitelist of volumes configured in the runner executing the task. See the [Forgejo Actions administrator guide](../../admin/actions/) for more information.
### username #### username
The username to authenticate with the registry where the image is located. The username to authenticate with the registry where the image is located.
### password #### password
The password to authenticate with the registry where the image is located. The password to authenticate with the registry where the image is located.
# The list of runners and their tasks ## The list of runners and their tasks
A `Forgejo runner` listens on a `Forgejo` instance, waiting for jobs. To figure out if a runner is available for a given repository, go to `/{owner}/{repository}/settings/actions/runners`. If there are none, you can run one for yourself on your laptop. A `Forgejo runner` listens on a `Forgejo` instance, waiting for jobs. To figure out if a runner is available for a given repository, go to `/{owner}/{repository}/settings/actions/runners`. If there are none, you can run one for yourself on your laptop.
@ -150,7 +150,7 @@ Clicking on the pencil icon next to a runner shows the list of tasks it executed
![show the runners tasks](../../../../images/v1.20/user/actions/runner-tasks.png) ![show the runners tasks](../../../../images/v1.20/user/actions/runner-tasks.png)
# The list of tasks in a repository ## The list of tasks in a repository
From the `Actions` tab in a repository, the list of ongoing and past tasks triggered by this repository is displayed with their status. From the `Actions` tab in a repository, the list of ongoing and past tasks triggered by this repository is displayed with their status.
@ -160,7 +160,7 @@ Following the link on a task displays the logs and the `Re-run all jobs` button.
![the details of an action](../../../../images/v1.20/user/actions/actions-detail.png) ![the details of an action](../../../../images/v1.20/user/actions/actions-detail.png)
# Pull request actions are moderated ## Pull request actions are moderated
The first time a user proposes a pull request, the task is blocked to reduce the security risks. The first time a user proposes a pull request, the task is blocked to reduce the security risks.
@ -170,7 +170,7 @@ It can be approved by a maintainer of the project and there will be no need to u
![button to approve an action](../../../../images/v1.20/user/actions/action-approve.png) ![button to approve an action](../../../../images/v1.20/user/actions/action-approve.png)
# Secrets ## Secrets
A repository, a user or an organization can hold secrets, a set of key/value pairs that are stored encrypted in the `Forgejo` database and revealed to the `workflows` as `${{ secrets.KEY }}`. They can be defined from the web interface: A repository, a user or an organization can hold secrets, a set of key/value pairs that are stored encrypted in the `Forgejo` database and revealed to the `workflows` as `${{ secrets.KEY }}`. They can be defined from the web interface:
@ -184,11 +184,11 @@ Once the secret is added, its value cannot be changed or displayed.
![secrets list](../../../../images/v1.20/user/actions/secret-list.png) ![secrets list](../../../../images/v1.20/user/actions/secret-list.png)
# Workflow reference guide ## Workflow reference guide
The syntax and semantic of the YAML file describing a `workflow` are partially explained here. When an entry is missing the [GitHub Actions](https://docs.github.com/en/actions) documentation can help because there are similarities. But there also are significant differences that deserve testing. The syntax and semantic of the YAML file describing a `workflow` are partially explained here. When an entry is missing the [GitHub Actions](https://docs.github.com/en/actions) documentation can help because there are similarities. But there also are significant differences that deserve testing.
## on ### on
Workflows will be triggered `on` certain events with the following: Workflows will be triggered `on` certain events with the following:
@ -225,7 +225,7 @@ on:
Not everything from https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows is implemented yet. Please refer to the [forgejo/actions package source code](https://codeberg.org/forgejo/forgejo/src/branch/forgejo/modules/actions/workflows.go) and the [list of webhook event names](https://codeberg.org/forgejo/forgejo/src/branch/forgejo/modules/webhook/type.go) to find out about supported triggers. Not everything from https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows is implemented yet. Please refer to the [forgejo/actions package source code](https://codeberg.org/forgejo/forgejo/src/branch/forgejo/modules/actions/workflows.go) and the [list of webhook event names](https://codeberg.org/forgejo/forgejo/src/branch/forgejo/modules/webhook/type.go) to find out about supported triggers.
## env ### env
Set environment variables that are available in the workflow in the `env` `context` and as regular environment variables. Set environment variables that are available in the workflow in the `env` `context` and as regular environment variables.
@ -240,9 +240,9 @@ env:
[Checkout the example](https://code.forgejo.org/actions/setup-forgejo/src/branch/main/testdata/example-expression/.forgejo/workflows/test.yml). [Checkout the example](https://code.forgejo.org/actions/setup-forgejo/src/branch/main/testdata/example-expression/.forgejo/workflows/test.yml).
## jobs ### jobs
### runs-on #### runs-on
Each `job` in a `workflow` must specify the kind of machine it needs to run its `steps` with `runs-on`. For instance `docker` in the following `workflow`: Each `job` in a `workflow` must specify the kind of machine it needs to run its `steps` with `runs-on`. For instance `docker` in the following `workflow`:
@ -261,7 +261,7 @@ The list of available `labels` for a given repository can be seen in the `/{owne
![actions results](../../../../images/v1.20/user/actions/list-of-runners.png) ![actions results](../../../../images/v1.20/user/actions/list-of-runners.png)
#### container ##### container
By default the `docker` label will create a container from a [Node.js 16 Debian GNU/Linux bullseye image](https://hub.docker.com/_/node/tags?name=16-bullseye) and will run each `step` as root. Since an application container is used, the jobs will inherit the limitations imposed by the engine (Docker for instance). In particular they will not be able to run or install software that depends on `systemd`. By default the `docker` label will create a container from a [Node.js 16 Debian GNU/Linux bullseye image](https://hub.docker.com/_/node/tags?name=16-bullseye) and will run each `step` as root. Since an application container is used, the jobs will inherit the limitations imposed by the engine (Docker for instance). In particular they will not be able to run or install software that depends on `systemd`.
@ -273,25 +273,25 @@ container:
image: alpine:3.18 image: alpine:3.18
``` ```
#### options ##### options
A string of additional options, as documented [docker run](https://docs.docker.com/engine/reference/commandline/run/). For instance: "--workdir /myworkdir --ulimit nofile=1024:1024". A string of additional options, as documented [docker run](https://docs.docker.com/engine/reference/commandline/run/). For instance: "--workdir /myworkdir --ulimit nofile=1024:1024".
> **NOTE:** the `--volume` option is restricted to a whitelist of volumes configured in the runner executing the task. See the [Forgejo Actions administrator guide](../../admin/actions/) for more information. > **NOTE:** the `--volume` option is restricted to a whitelist of volumes configured in the runner executing the task. See the [Forgejo Actions administrator guide](../../admin/actions/) for more information.
#### LXC ##### LXC
The `runs-on: self-hosted` label will run the jobs in a [LXC](https://linuxcontainers.org/lxc/) container where software that rely on `systemd` can be installed. Nested containers can also be created recursively (see [the setup-forgejo integration tests](https://code.forgejo.org/actions/setup-forgejo/src/branch/main/.forgejo/workflows/integration.yml) for an example). The `runs-on: self-hosted` label will run the jobs in a [LXC](https://linuxcontainers.org/lxc/) container where software that rely on `systemd` can be installed. Nested containers can also be created recursively (see [the setup-forgejo integration tests](https://code.forgejo.org/actions/setup-forgejo/src/branch/main/.forgejo/workflows/integration.yml) for an example).
`Services` are not supported for jobs that run on LXC. `Services` are not supported for jobs that run on LXC.
### steps #### steps
#### uses ##### uses
Specifies the repository from which the `Action` will be cloned or a directory where it can be found. Specifies the repository from which the `Action` will be cloned or a directory where it can be found.
##### Remote actions ###### Remote actions
A relative `Action` such as `uses: actions/checkout@v3` will clone the repository at the URL composed by prepending the default actions URL which is https://code.forgejo.org/. It is the equivalent of providing the fully qualified URL `uses: https://code.forgejo.org/actions/checkout@v3`. In other words the following: A relative `Action` such as `uses: actions/checkout@v3` will clone the repository at the URL composed by prepending the default actions URL which is https://code.forgejo.org/. It is the equivalent of providing the fully qualified URL `uses: https://code.forgejo.org/actions/checkout@v3`. In other words the following:
@ -322,7 +322,7 @@ it gets an outdated version from https://tooold.org/actions/checkout
instead. Or even a repository that does not contain the intended instead. Or even a repository that does not contain the intended
action. action.
##### Local actions ###### Local actions
An action that begins with a `./` will be loaded from a directory An action that begins with a `./` will be loaded from a directory
instead of being cloned from a repository. The structure of the instead of being cloned from a repository. The structure of the
@ -333,7 +333,7 @@ repository.
[Checkout the example](https://code.forgejo.org/actions/setup-forgejo/src/branch/main/testdata/example-local-action/). [Checkout the example](https://code.forgejo.org/actions/setup-forgejo/src/branch/main/testdata/example-local-action/).
##### with ###### with
A dictionary mapping the inputs of the action to concrete values. The `action.yml` defines and documents the inputs. A dictionary mapping the inputs of the action to concrete values. The `action.yml` defines and documents the inputs.
@ -356,7 +356,7 @@ For remote actions that are implemented with a `Dockerfile` instead of `action.y
[Checkout the example](https://code.forgejo.org/actions/setup-forgejo/src/branch/main/testdata/example-docker-action/.forgejo/workflows/test.yml) [Checkout the example](https://code.forgejo.org/actions/setup-forgejo/src/branch/main/testdata/example-docker-action/.forgejo/workflows/test.yml)
# Debugging workflows with forgejo-runner exec ## Debugging workflows with forgejo-runner exec
To get a quicker debug loop when working on a workflow, it may be more To get a quicker debug loop when working on a workflow, it may be more
convenient to run them on your laptop using `forgejo-runner exec`. For convenient to run them on your laptop using `forgejo-runner exec`. For
@ -391,7 +391,7 @@ INFO[0000] Start server on http://192.168.1.20:34567
[checks/check and test] 🏁 Job succeeded [checks/check and test] 🏁 Job succeeded
``` ```
# Examples ## Examples
Each example is part of the [setup-forgejo](https://code.forgejo.org/actions/setup-forgejo/) action [test suite](https://code.forgejo.org/actions/setup-forgejo/src/branch/main/testdata). They can be run locally with something similar to: Each example is part of the [setup-forgejo](https://code.forgejo.org/actions/setup-forgejo/) action [test suite](https://code.forgejo.org/actions/setup-forgejo/src/branch/main/testdata). They can be run locally with something similar to:
@ -430,7 +430,7 @@ test "KEY2=$KEY2" = "KEY2=value2"
- [Choosing the image with `container`](https://code.forgejo.org/actions/setup-forgejo/src/branch/main/testdata/example-container/.forgejo/workflows/test.yml) - replacing the `runs-on: docker` image with the `alpine:3.18` image using `container:` - [Choosing the image with `container`](https://code.forgejo.org/actions/setup-forgejo/src/branch/main/testdata/example-container/.forgejo/workflows/test.yml) - replacing the `runs-on: docker` image with the `alpine:3.18` image using `container:`
- [Docker action](https://code.forgejo.org/actions/setup-forgejo/src/branch/main/testdata/example-docker-action/.forgejo/workflows/test.yml) - using a action implemented as a `Dockerfile` - [Docker action](https://code.forgejo.org/actions/setup-forgejo/src/branch/main/testdata/example-docker-action/.forgejo/workflows/test.yml) - using a action implemented as a `Dockerfile`
# Glossary ## Glossary
- **action:** a repository that can be used in a way similar to a function in any programming language to run a single **step**. - **action:** a repository that can be used in a way similar to a function in any programming language to run a single **step**.
- **expression:** a string enclosed in `${{ ... }}` and evaluated at runtime - **expression:** a string enclosed in `${{ ... }}` and evaluated at runtime

10
user/packages/swift.md
View file

@ -4,15 +4,15 @@ license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/usage/packages/swift.en-us.md' origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/usage/packages/swift.en-us.md'
--- ---
# Swift Packages Repository ## Swift Packages Repository
Publish [Swift](hhttps://www.swift.org/) packages for your user or organization. Publish [Swift](hhttps://www.swift.org/) packages for your user or organization.
## Requirements ### Requirements
To work with the Swift package registry, you need to use [swift](https://www.swift.org/getting-started/) to consume and a HTTP client (like `curl`) to publish packages. To work with the Swift package registry, you need to use [swift](https://www.swift.org/getting-started/) to consume and a HTTP client (like `curl`) to publish packages.
## Configuring the package registry ### Configuring the package registry
To register the package registry and provide credentials, execute: To register the package registry and provide credentials, execute:
@ -28,7 +28,7 @@ swift package-registry set https://forgejo.example.com/api/packages/{owner}/swif
The login is optional and only needed if the package registry is private. The login is optional and only needed if the package registry is private.
## Publish a package ### Publish a package
First you have to pack the contents of your package: First you have to pack the contents of your package:
@ -58,7 +58,7 @@ curl -X PUT --user {username}:{password} \
You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first. You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first.
## Install a package ### Install a package
To install a Swift package from the package registry, add it in the `Package.swift` file dependencies list: To install a Swift package from the package registry, add it in the `Package.swift` file dependencies list:

2
user/project.md
View file

@ -7,7 +7,7 @@ A project is a [kanban board](<https://en.wikipedia.org/wiki/Kanban_(development
![screenshot of the project page](../../../../images/v1.20/user/project/project.png) ![screenshot of the project page](../../../../images/v1.20/user/project/project.png)
# Card previews images ## Card previews images
If the card preview in the project is set to **Images and Text**, the card preview displays images found in the corresponding issue. The most recent is displayed first, up to five images. If the card preview in the project is set to **Images and Text**, the card preview displays images found in the corresponding issue. The most recent is displayed first, up to five images.

8
user/protection.md
View file

@ -4,7 +4,7 @@ license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/usage/protected-tags.en-us.md' origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/usage/protected-tags.en-us.md'
--- ---
# Protected branches ## Protected branches
Protected branches enforce restrictions such as force pushing or Protected branches enforce restrictions such as force pushing or
merging unless a given number of approval are obtained on a pull merging unless a given number of approval are obtained on a pull
@ -21,11 +21,11 @@ spans accross separators. For instance `main`, `release/**`or`precious\*`.
If two rules apply to the same branch, the one that has no glob takes If two rules apply to the same branch, the one that has no glob takes
precedence. precedence.
# Protected tags ## Protected tags
Protected tags allow control over who has permission to create or update Git tags. Each rule allows you to match either an individual tag name, or use an appropriate pattern to control multiple tags at once. Protected tags allow control over who has permission to create or update Git tags. Each rule allows you to match either an individual tag name, or use an appropriate pattern to control multiple tags at once.
## Setting up protected tags ### Setting up protected tags
To protect a tag, you need to follow these steps: To protect a tag, you need to follow these steps:
@ -34,7 +34,7 @@ To protect a tag, you need to follow these steps:
1. Choose the allowed users and/or teams. If you leave these fields empty no one is allowed to create or modify this tag. 1. Choose the allowed users and/or teams. If you leave these fields empty no one is allowed to create or modify this tag.
1. Select **Save** to save the configuration. 1. Select **Save** to save the configuration.
## Pattern protected tags ### Pattern protected tags
The pattern uses [glob](https://pkg.go.dev/github.com/gobwas/glob#Compile) or regular expressions to match a tag name. For regular expressions you need to enclose the pattern in slashes. The pattern uses [glob](https://pkg.go.dev/github.com/gobwas/glob#Compile) or regular expressions to match a tag name. For regular expressions you need to enclose the pattern in slashes.

8
user/push-to-create.md
View file

@ -4,15 +4,15 @@ license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/usage/push.en-us.md' origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/usage/push.en-us.md'
--- ---
# Push To Create ## Push To Create
Push to create is a feature that allows you to push to a repository that does not exist yet in Forgejo. This is useful for automation and for allowing users to create repositories without having to go through the web interface. This feature is disabled by default. Push to create is a feature that allows you to push to a repository that does not exist yet in Forgejo. This is useful for automation and for allowing users to create repositories without having to go through the web interface. This feature is disabled by default.
## Enabling Push To Create ### Enabling Push To Create
In the `app.ini` file, set `ENABLE_PUSH_CREATE_USER` to `true` and `ENABLE_PUSH_CREATE_ORG` to `true` if you want to allow users to create repositories in their own user account and in organizations they are a member of respectively. Restart Forgejo for the changes to take effect. You can read more about these two options in the Configuration Cheat Sheet. In the `app.ini` file, set `ENABLE_PUSH_CREATE_USER` to `true` and `ENABLE_PUSH_CREATE_ORG` to `true` if you want to allow users to create repositories in their own user account and in organizations they are a member of respectively. Restart Forgejo for the changes to take effect. You can read more about these two options in the Configuration Cheat Sheet.
## Using Push To Create ### Using Push To Create
Assuming you have a git repository in the current directory, you can push to a repository that does not exist yet in Forgejo by running the following command: Assuming you have a git repository in the current directory, you can push to a repository that does not exist yet in Forgejo by running the following command:
@ -26,7 +26,7 @@ git push -u origin main
This assumes you are using an SSH remote, but you can also use HTTPS remotes as well. This assumes you are using an SSH remote, but you can also use HTTPS remotes as well.
## Push options ### Push options
Push-to-create will default to the visibility defined by `DEFAULT_PUSH_CREATE_PRIVATE` in `app.ini`. To explicitly set the visibility there is support for some [push options](https://git-scm.com/docs/git-push#Documentation/git-push.txt--oltoptiongt). Push-to-create will default to the visibility defined by `DEFAULT_PUSH_CREATE_PRIVATE` in `app.ini`. To explicitly set the visibility there is support for some [push options](https://git-scm.com/docs/git-push#Documentation/git-push.txt--oltoptiongt).