setup-forgejo/README.md

# setup-forgejo

* v1: only supports running Forgejo from container images
* v2: only supports running Forgejo from binaries

<!-- action-docs-description -->
## Description

Setup Forgejo and a runner.

If `binary` is specified, Forgejo downloads the binary from the URL and uses
it to start an instance.

Otherwise, `image` and `image-version` must be specified and Forgejo
runs from the corresponding container image using docker.

The forgejo-test-helper.sh script is available to help test and debug actions.

`forgejo=http://root:admin1234@${{ steps.forgejo.outputs.host-port }}`

* `forgejo-test-helper.sh push_self_action $forgejo root myaction vTest`
  Creates the repository `$forgejo/root/myaction` and populates it with the
  content of the repository under test, except for the `.forgejo` directory
  (it would otherwise create an infinite loop). The tag `vTest` is
  set to the SHA under test.
* `forgejo-test-helper.sh run_workflow testrepo $forgejo root testrepo myaction`
  Creates the repository `$forgejo/root/testrepo` and populates it with the
  content of the `testrepo` directory. All occurrences of `SELF` in
  `testrepo/.forgejo/workflows/*.yml` are replaced with `$forgejo/root/myaction`.
* `forgejo-test-helper.sh push testrepo $forgejo root testrepo`
  Creates the repository `$forgejo/root/testrepo` and populates it with the
  content of the `testrepo` directory.

The combination of `push_self_action` and `run_workflow` allows to
run Forgejo Actions workflows from `testrepo` that use the action
under test (`myaction`) to verify it works as intended.

The [forgejo-curl.sh](https://code.forgejo.org/forgejo/forgejo-curl#forgejo-curlsh)
script is logged in the instance and ready to be used with web or api endpoints.
<!-- action-docs-description -->

It can only be used in a job with a `runs-on` label that designates a Forgejo runner
that [provides a LXC container](https://forgejo.org/docs/next/user/actions/#jobsjob_idruns-on).

<!-- action-docs-inputs -->
## Inputs

| parameter | description | required | default |
| --- | --- | --- | --- |
| image | Container image | `false` | codeberg.org/forgejo/forgejo |
| image-version | Container image version | `false` | 1.20 |
| binary | URL to a Forgejo binary | `false` |  |
| user | Administrator user name | `false` | root |
| password | Administrator password | `false` | admin1234 |
| runner | Runner repository | `false` | https://code.forgejo.org/forgejo/runner |
| runner-version | Runner version. If it starts with @ (for instance @featurebranch), the runner will be built from source using the specified branch. | `false` | v5.0.3 |
| container | Name of the container running the Forgejo instance | `false` | forgejo |
| lxc-ip-prefix | Class C IP prefix used by LXC | `false` | 10.0.23 |
| install-only | Only install Forgejo and the Forgejo runner, do not launch them | `false` | false |
<!-- action-docs-inputs -->


<!-- action-docs-outputs -->
## Outputs

| parameter | description |
| --- | --- |
| url | URL of the Forgejo instance |
| host-port | Host and port of the Forgejo instance, e.g 172.0.17.2:3000 |
| token | Administrator application token with all scopes |
| runner-logs | Filename of the Forgejo runner logs |
| runner-file | Path to the runner file |
<!-- action-docs-outputs -->

## Example

```
name: Setup Forgejo
on: [push]
jobs:
  setup-forgejo:
    runs-on: lxc
    steps:
      - uses: actions/checkout@v4
      - id: forgejo
        uses: actions/setup-forgejo@v1
        with:
          image-version: 1.20
      - run: |
          curl ${{ steps.forgejo.outputs.url }}/api/forgejo/v1/version | grep 1.20

```

## Documentation

Update the README from the action file with https://github.com/npalm/action-docs `action-docs --update-readme`