hannah-eee/forjero-docs huggingface dataset:
File: docs\admin\actions\installation\docker.md

---
title: 'Installation with Docker'
license: 'CC-BY-SA-4.0'
---

## OCI image

The [OCI images](https://code.forgejo.org/forgejo/-/packages/container/runner/) are built from the Dockerfile which is
[found in the source directory](https://code.forgejo.org/forgejo/runner/src/branch/main/Dockerfile). It contains the
`forgejo-runner` binary.

```shell
$ docker run --rm data.forgejo.org/forgejo/runner:12 forgejo-runner --version
forgejo-runner version v12.7.2
```

It does not run as root:

```shell
$ docker run --rm data.forgejo.org/forgejo/runner:12 id
uid=1000 gid=1000 groups=1000
```

## Docker Compose

One way to run the Docker image is via Docker Compose. To do so, as root, first prepare a `data` directory with non-root
permissions (in this case, we pick `1001:1001`):

```shell
#!/usr/bin/env bash

set -e

mkdir -p data/.cache

chown -R 1001:1001 data
chmod 775 data/.cache
chmod g+s data/.cache
```

After running this script with `bash setup.sh`, define the following `docker-compose.yml`:

```yaml
version: '3.8'

services:
  docker-in-docker:
    image: docker:dind
    container_name: 'docker_dind'
    privileged: 'true'
    command: ['dockerd', '-H', 'tcp://0.0.0.0:2375', '--tls=false']
    restart: 'unless-stopped'

  runner:
    image: 'data.forgejo.org/forgejo/runner:12'
    links:
      - docker-in-docker
    depends_on:
      docker-in-docker:
        condition: service_started
    container_name: 'runner'
    environment:
      DOCKER_HOST: tcp://docker-in-docker:2375
    # User without root privileges, but with access to `./data`.
    user: 1001:1001
    volumes:
      - ./data:/data
    restart: 'unless-stopped'
    command: 'forgejo-runner daemon --config runner-config.yml'
```

Generate the default configuration file for Forgejo Runner, and store it in the `data` directory created previously:

```shell
$ docker run --rm data.forgejo.org/forgejo/runner:12 \
  forgejo-runner generate-config > data/runner-config.yml
```

Forgejo Runner needs to be configured and registered with Forgejo before it can be started successfully. [Configure
Forgejo Runner](../../configuration/#initial-configuration), editing `data/runner-config.yml` file as you proceed.

Once the configuration is complete, you can start the runner by executing `docker compose up -d`.

More [docker compose](https://docs.docker.com/compose/) examples [are
provided](https://code.forgejo.org/forgejo/runner/src/branch/main/examples/docker-compose) to demonstrate how to install
the OCI image to successfully run a workflow.
File: docs\admin\actions\installation\packaging.md

---
title: 'Installation from packaging'
license: 'CC-BY-SA-4.0'
---

### NixOS

A [`forgejo-runner`](https://search.nixos.org/packages?channel=unstable&show=forgejo-runner&type=packages&query=forgejo-runner) package is available for Nix.
As NixOS service module [`services.gitea-actions-runner.*`](https://search.nixos.org/options?channel=unstable&type=options&query=services.gitea-actions-runner) can be used.

If application containers are to be used (Docker or Podman), one of `virtualisation.docker.enable` or `virtualisation.podman.enable` must also be set to `true`.

An example service definition might look like this:

```nix
services.gitea-actions-runner = {
  package = pkgs.forgejo-runner;
  instances.my-forgejo-instance = {
    enable = true;
    name = "my-forgejo-runner-01";
    token = "<registration-token>";
    url = "https://code.forgejo.org/";
    labels = [
      "node-22:docker://node:22-bookworm"
      "nixos-latest:docker://nixos/nix"
    ];
    settings = { ... };
  };
```

The runner configuration can be specified in `services.gitea-actions-runner.instances.<instance>.settings` as per [Configuration](../../configuration/).

IPv6 support is not enabled by default for docker. The following snippet enables this.

```nix
virtualisation.docker = {
  daemon.settings = {
    fixed-cidr-v6 = "fd00::/80";
    ipv6 = true;
  };
};
```

If you would like to use docker runners in combination with [cache actions](#cache-configuration), be sure to add docker bridge interfaces "br-\*" to the firewalls' trusted interfaces:

```nix
networking.firewall.trustedInterfaces = [ "br-+" ];
```
File: docs\user\actions\github-actions.md

---
title: 'Forgejo Actions | GitHub Actions'
license: 'CC-BY-SA-4.0'
---

If you are familiar with GitHub Actions, you'll likely recognize many things in Forgejo Actions. Forgejo Actions is designed to be familiar to users of GitHub Actions, but it is **not designed to be compatible**.

## Familiarity instead of compatibility

Forgejo Actions is built on top of several existing technologies that were built to emulate GitHub Actions. For this reason, Forgejo Actions will seem very similar to GitHub Actions. Many features are (nearly) identical: workflows defined by YAML files in the repository, a swarm of runners executing actions inside docker containers, the ability to reuse workflows with Actions.

However, GitHub has different constraints when designing GitHub Actions. Because of this, they are able to add some features that are not a great fit for Forgejo Actions. On the other hand, Forgejo Actions has some features that GitHub Actions doesn't have, like running workflows in LXC containers.

Overall, many features from GitHub Actions translate one-to-one to Forgejo Actions. It is mostly the small differences that mean we can't claim to be 100% compatible. These small things are also usually the most difficult and least useful for our users to implement. And, since GitHub continues development on GitHub Actions, keeping up with all the changes would be impractical.

For all of these reasons, Forgejo Actions strives for _familiarity_ instead of _compatibility_. We want users of GitHub actions to feel familiar using Forgejo Actions, even if there are some small changes here and there. Workflows should work with some minimal changes.

If there is a feature you are missing, you are welcome to [discuss it](https://code.forgejo.org/forgejo/runner/issues), but keep in mind this philosophy.

## Known list of differences

> This list may be incomplete. If you find a notable difference, you can [edit this page](https://codeberg.org/forgejo/docs/src/branch/next/docs/user/actions/github-actions.md).

- The default environment is very different. Most Forgejo Runners use a Debian bookworm image with just node.js by default, while GitHub uses a larger `ubuntu` image.
- Some keys in the `github` context are missing.
- Certain subkeys on the `job` key in workflow files are ignored, like `permissions`, and `continue-on-error`.
- Enabling [OIDC ID token generation](../security-openid-connect/) uses the [`enable-openid-connect`](../reference/#enable-openid-connect) key in the workflow file instead of `permissions: id-token: write`
File: docs\user\actions\overview.md

---
title: 'Forgejo Actions | User guide'
license: 'CC-BY-SA-4.0'
---

`Forgejo Actions` is a Continuous Integration system built into Forgejo. It lets you automatically build, lint, test, deploy or publish your software.

## Quick start

If you want a quick way to get started with an example, check out the [quick start guide](../quick-start/).

## Workflows

Forgejo Actions workflows are defined using `.yaml` files in the `.forgejo/workflows` directory of the repository. The workflow file describes the events that should trigger the workflow, and which jobs need to be executed.

> **NOTE:** in the absence of a `.forgejo/workflows` directory, workflows will be looked up in the `.github/workflows` directory, if it exists.

For more information about how to write workflow files, check out the [basic concepts](../basic-concepts/). There is also a guide to the more [advanced features](../advanced-features/).

## Runners

Workflows are not executed by the Forgejo instance itself. Instead, they are handed out to runners, which perform the workflow and report back with the results.

In order for a workflow to run, an appropriate runner needs to be available to the repository. You can view the available runners in the repository settings, under Actions > Runners.

If the instance does not provide runners, or if you wish to use your own runners, check out the [Forgejo Runner installation guide](../../../admin/actions/runner-installation/) to see how to set up and connect your own runner.

## Troubleshooting

Learn the basics of [troubleshooting a failed workflow or action](../troubleshooting/).

## Security

Sensitive security-related issues should be reported to [security@forgejo.org](mailto:security@forgejo.org) using [encryption](https://keyoxide.org/security@forgejo.org).

A security audit of the [runner](https://code.forgejo.org/forgejo/runner) was conducted late 2024 (see [the penetration test report](https://code.forgejo.org/forgejo/nlnet-off-ngie-forgejo/raw/commit/69f76976cc6a62bc7a64f9f76e4be75eec3d608d/target/Forgejo%20penetration%20test%20report%202024%201.0.pdf) for more information). All issues found on that occasion were fixed in 2025.

## About GitHub Actions

If you are familiar with GitHub Actions, you'll likely recognize many things in Forgejo Actions. Forgejo Actions is designed to be familiar to users of GitHub Actions, but it is **not designed to be compatible**.

If you wish to migrate a workflow from GitHub Actions to Forgejo Actions, some minimal tweaking will most likely be necessary.

For a more detailed description of the differences between GitHub Actions and Forgejo Actions, check out the [GitHub Actions differences](../github-actions/) page.

## Alternative CI options

Forgejo Actions is a CI system built into Forgejo. There are also other CI systems available, which may be more suitable for certain use-cases. A list of these is available [in the forgejo-contrib repository](https://codeberg.org/forgejo-contrib/delightful-forgejo#ci-cd).
File: docs\user\packages\chef.md

---
title: 'Chef Package Registry'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/e865de1e9d65dc09797d165a51c8e705d2a86030/docs/content/usage/packages/chef.en-us.md'
---

Publish [Chef](https://chef.io/) cookbooks for your user or organization.

## Requirements

To work with the Chef package registry, you have to use [`knife`](https://docs.chef.io/workstation/knife/).

## Authentication

The Chef package registry does not use an username:password authentication but signed requests with a private:public key pair.
Visit the package owner settings page to create the necessary key pair.
Only the public key is stored inside Forgejo. If you lose access to the private key you must re-generate the key pair.
[Configure `knife`](https://docs.chef.io/workstation/knife_setup/) to use the downloaded private key with your Forgejo username as `client_name`.

## Configure the package registry

To [configure `knife`](https://docs.chef.io/workstation/knife_setup/) to use the Forgejo package registry, add this URL to the `~/.chef/config.rb` file:

```
knife[:supermarket_site] = 'https://forgejo.example.com/api/packages/{owner}/chef'
```

| Parameter | Description               |
| --------- | ------------------------- |
| `owner`   | The owner of the package. |

## Publish a package

To publish a Chef package execute the following command:

```shell
knife supermarket share {package_name}
```

| Parameter      | Description       |
| -------------- | ----------------- |
| `package_name` | The package name. |

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

To install a package from the package registry, execute the following command:

```shell
knife supermarket install {package_name}
```

Optionally, you can specify the package version:

```shell
knife supermarket install {package_name} {package_version}
```

| Parameter         | Description          |
| ----------------- | -------------------- |
| `package_name`    | The package name.    |
| `package_version` | The package version. |

## Delete a package

If you want to remove a package from the registry, execute the following command:

```shell
knife supermarket unshare {package_name}
```

Optionally, you can specify the package version:

```shell
knife supermarket unshare {package_name}/versions/{package_version}
```

| Parameter         | Description          |
| ----------------- | -------------------- |
| `package_name`    | The package name.    |
| `package_version` | The package version. |
File: docs\user\packages\conan.md

---
title: 'Conan Package Registry'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/e865de1e9d65dc09797d165a51c8e705d2a86030/docs/content/usage/packages/conan.en-us.md'
---

Publish [Conan](https://conan.io/) packages for your user or organization.

## Requirements

To work with the Conan package registry, you need to use the [conan](https://conan.io/downloads.html) command line tool to consume and publish packages.

## Configuring the package registry

To register the package registry you need to configure a new Conan remote:

```shell
conan remote add {remote} https://forgejo.example.com/api/packages/{owner}/conan
conan user --remote {remote} --password {password} {username}
```

| Parameter  | Description                                                                                                                                  |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `remote`   | The remote name.                                                                                                                             |
| `username` | Your Forgejo username.                                                                                                                       |
| `password` | Your Forgejo password. If you are using 2FA or OAuth use a [personal access token](../../api-usage/#authentication) instead of the password. |
| `owner`    | The owner of the package.                                                                                                                    |

For example:

```shell
conan remote add forgejo https://forgejo.example.com/api/packages/testuser/conan
conan user --remote forgejo --password password123 testuser
```

## Publish a package

Publish a Conan package by running the following command:

```shell
conan upload --remote={remote} {recipe}
```

| Parameter | Description           |
| --------- | --------------------- |
| `remote`  | The remote name.      |
| `recipe`  | The recipe to upload. |

For example:

```shell
conan upload --remote=forgejo ConanPackage/1.2@forgejo/final
```

The Forgejo Conan package registry has full [revision](https://docs.conan.io/en/latest/versioning/revisions.html) support.

## Install a package

To install a Conan package from the package registry, execute the following command:

```shell
conan install --remote={remote} {recipe}
```

| Parameter | Description             |
| --------- | ----------------------- |
| `remote`  | The remote name.        |
| `recipe`  | The recipe to download. |

For example:

```shell
conan install --remote=forgejo ConanPackage/1.2@forgejo/final
```

## Supported commands

```
conan install
conan get
conan info
conan search
conan upload
conan user
conan download
conan remove
```
File: docs\user\packages\cran.md

---
title: 'CRAN Package Registry'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/e865de1e9d65dc09797d165a51c8e705d2a86030/docs/content/usage/packages/cran.en-us.md'
---

Publish [R](https://www.r-project.org/) packages to a [CRAN](https://cran.r-project.org/)-like registry for your user or organization.

## Requirements

To work with the CRAN package registry, you need to install [R](https://cran.r-project.org/).

## Configuring the package registry

To register the package registry you need to add it to `Rprofile.site`, either on the system-level, user-level (`~/.Rprofile`) or project-level:

```
options("repos" = c(getOption("repos"), c(forgejo="https://forgejo.example.com/api/packages/{owner}/cran")))
```

| Parameter | Description               |
| --------- | ------------------------- |
| `owner`   | The owner of the package. |

If you need to provide credentials, you may embed them as part of the url (`https://user:password@forgejo.example.com/...`).

## Publish a package

To publish a R package, perform a HTTP `PUT` operation with the package content in the request body.

Source packages:

```
PUT https://forgejo.example.com/api/packages/{owner}/cran/src
```

| Parameter | Description               |
| --------- | ------------------------- |
| `owner`   | The owner of the package. |

Binary packages:

```
PUT https://forgejo.example.com/api/packages/{owner}/cran/bin?platform={platform}&rversion={rversion}
```

| Parameter  | Description                  |
| ---------- | ---------------------------- |
| `owner`    | The owner of the package.    |
| `platform` | The name of the platform.    |
| `rversion` | The R version of the binary. |

For example:

```shell
curl --user your_username:your_password_or_token \
     --upload-file path/to/package.zip \
     https://forgejo.example.com/api/packages/testuser/cran/bin?platform=windows&rversion=4.2
```

If you are using 2FA or OAuth, use a personal access token instead of the password.

You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first.

The server responds with the following HTTP Status codes.

| HTTP Status Code  | Meaning                                                                |
| ----------------- | ---------------------------------------------------------------------- |
| `201 Created`     | The package has been published.                                        |
| `400 Bad Request` | The package is invalid.                                                |
| `409 Conflict`    | A package file with the same combination of parameters exists already. |

## Install a package

To install a R package from the package registry, execute the following command:

```shell
install.packages("{package_name}")
```

| Parameter      | Description       |
| -------------- | ----------------- |
| `package_name` | The package name. |

For example:

```shell
install.packages("testpackage")
```
File: docs\user\packages\go.md

---
title: 'Go Package Registry'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/e865de1e9d65dc09797d165a51c8e705d2a86030/docs/content/usage/packages/go.en-us.md'
---

Publish Go packages for your user or organization.

## Publish a package

To publish a Go package perform a HTTP `PUT` operation with the package content in the request body.
You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first.
The package must follow the [documented structure](https://go.dev/ref/mod#zip-files).

```
PUT https://forgejo.example.com/api/packages/{owner}/go/upload
```

| Parameter | Description               |
| --------- | ------------------------- |
| `owner`   | The owner of the package. |

To authenticate to the package registry, you need to provide custom HTTP headers or use HTTP Basic authentication:

```shell
curl --user your_username:your_password_or_token \
     --upload-file path/to/file.zip \
     https://forgejo.example.com/api/packages/testuser/go/upload
```

If you are using 2FA or OAuth use a personal access token instead of the password.

You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first.

The server responds with the following HTTP Status codes.

| HTTP Status Code  | Meaning                                     |
| ----------------- | ------------------------------------------- |
| `201 Created`     | The package has been published.             |
| `400 Bad Request` | The package is invalid.                     |
| `409 Conflict`    | A package with the same name exist already. |

## Install a package

To install a Go package instruct Go to use the package registry as proxy:

```shell
# use latest version
GOPROXY=https://forgejo.example.com/api/packages/{owner}/go go install {package_name}
# or
GOPROXY=https://forgejo.example.com/api/packages/{owner}/go go install {package_name}@latest
# use specific version
GOPROXY=https://forgejo.example.com/api/packages/{owner}/go go install {package_name}@{package_version}
```

| Parameter         | Description               |
| ----------------- | ------------------------- |
| `owner`           | The owner of the package. |
| `package_name`    | The package name.         |
| `package_version` | The package version.      |

If the owner of the packages is private you need to [provide credentials](https://go.dev/ref/mod#private-module-proxy-auth).

More information about the `GOPROXY` environment variable and how to protect against data leaks can be found in [the documentation](https://go.dev/ref/mod#private-modules).
File: docs\user\packages\helm.md

---
title: 'Helm Chart Registry'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/e865de1e9d65dc09797d165a51c8e705d2a86030/docs/content/usage/packages/helm.en-us.md'
---

Publish [Helm](https://helm.sh/) charts for your user or organization.

## Requirements

To work with the Helm Chart registry use a simple HTTP client like `curl` or the [`helm cm-push`](https://github.com/chartmuseum/helm-push/) plugin.

## Publish a package

Publish a package by running the following command:

```shell
curl --user {username}:{password} -X POST --upload-file ./{chart_file}.tgz https://forgejo.example.com/api/packages/{owner}/helm/api/charts
```

or with the `helm cm-push` plugin:

```shell
helm repo add  --username {username} --password {password} {repo} https://forgejo.example.com/api/packages/{owner}/helm
helm cm-push ./{chart_file}.tgz {repo}
```

| Parameter    | Description                                                                                                                                  |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `username`   | Your Forgejo username.                                                                                                                       |
| `password`   | Your Forgejo password. If you are using 2FA or OAuth use a [personal access token](../../api-usage/#authentication) instead of the password. |
| `repo`       | The name for the repository.                                                                                                                 |
| `chart_file` | The Helm Chart archive.                                                                                                                      |
| `owner`      | The owner of the package.                                                                                                                    |

## Install a package

To install a Helm chart from the registry, execute the following command:

```shell
helm repo add  --username {username} --password {password} {repo} https://forgejo.example.com/api/packages/{owner}/helm
helm repo update
helm install {name} {repo}/{chart}
```

| Parameter  | Description                                       |
| ---------- | ------------------------------------------------- |
| `username` | Your Forgejo username.                            |
| `password` | Your Forgejo password or a personal access token. |
| `repo`     | The name for the repository.                      |
| `owner`    | The owner of the package.                         |
| `name`     | The local name.                                   |
| `chart`    | The name Helm Chart.                              |