Go to file
earl-warren 8de0ce42b9 Merge pull request 'upgrade examples/docker-compose with runner 3.0.1 & Forgejo 1.20.4-1' (#88) from earl-warren/runner:wip-upgrade-example into main
Reviewed-on: https://code.forgejo.org/forgejo/runner/pulls/88
Reviewed-by: dachary <dachary@noreply.code.forgejo.org>
2023-10-06 10:21:27 +00:00
.forgejo/workflows upgrade tests to use v1.20.4-1 2023-10-04 14:54:42 +02:00
examples upgrade examples/docker-compose with runner 3.0.1 & Forgejo 1.20.4-1 2023-10-06 12:14:13 +02:00
internal [FORGEJO] add the create-runner-file 2023-08-23 16:03:12 +02:00
scripts [FORGEJO] fix name of binary to `forgejo-runner` for rootless docker image 2023-08-23 16:03:12 +02:00
.dockerignore [FORGEJO] build forgejo-runner 2023-08-23 14:44:47 +02:00
.editorconfig Add .editorconfig and .gitattributes (#186) 2023-05-13 23:51:22 +08:00
.gitattributes Add .editorconfig and .gitattributes (#186) 2023-05-13 23:51:22 +08:00
.gitignore [FORGEJO] build forgejo-runner 2023-08-23 14:44:47 +02:00
.golangci.yml ci(lint): refactor code for clarity and linting compliance (#289) 2023-07-13 01:10:54 +00:00
Dockerfile general purpose rootless container 2023-08-25 15:30:24 +02:00
LICENSE [FORGEJO] branding 2023-08-23 16:03:12 +02:00
Makefile [FORGEJO] use go vet without any third party addition 2023-08-23 16:03:12 +02:00
README.md README: the documentation is part of the Forgejo documentation 2023-08-26 12:15:27 +02:00
RELEASE-NOTES.md update release notes for 3.0.1 2023-10-04 16:07:50 +02:00
build.go Support cache (#25) 2023-02-28 23:39:30 +08:00
go.mod upgrade to act v1.11.0 2023-10-04 16:00:22 +02:00
go.sum upgrade to act v1.11.0 2023-10-04 16:00:22 +02:00
main.go Refactor to new framework (#98) 2023-04-04 21:32:04 +08:00

README.md

Forgejo Runner

WARNING: this is alpha release quality code and should not be considered secure enough to deploy in production.

A daemon that connects to a Forgejo instance and runs jobs for continous integration. The installation and usage instructions are part of the Forgejo documentation.

Hacking

The Forgejo runner depends on a fork of ACT and is a dependency of the setup-forgejo action. Together they provide a development environment with end to end testing. Each repository also has some unit testing that can be used to quickly detect the simplest mistakes such as a failure to compile or static code checking failures (vulnerability, lint, etc.).

Assuming the modifications to the Forgejo runner are pushed to a fork in a branch named wip-runner-change, a pull request will verify it compiles and the binary is sane (running forgejo-runner --version). It will not verify that it is able to properly run jobs when connected to a live Forgejo instance.

For end to end testing, a branch should be pushed to a fork of the setup-forgejo action with a modification to the tests, similar to:

#
# Uncomment the following for a shortcut to debugging the Forgejo runner.
# It will build the runner from a designated repository and branch instead of
# downloading it from a canonical release.
#
./forgejo-test-helper.sh build_runner https://code.forgejo.org/earl-warren/runner wip-runner-change

Where https://code.forgejo.org/earl-warren/runner is the URL of the Forgejo runner fork and wip-runner-change is the branch where the changes under test were pushed. When they do the wip-runner-change branch can be discarded.

The runner can be released by merging the wip-runner-change branch and by pushing a new tag, for instance v10.2.3. For more information see the documentation that details this release process in the Forgejo infrastructure. Once published, the setup-forgejo action can be updated to default to this latest version knowing it already passed integration tests.

ACT

Assuming the modifications to ACT are pushed to a fork in a branch named wip-act-change, a pull request will verify it compiles. It will not verify that the Forgejo runner can compile with it.

For verifying it is compatible with the Forgejo runner, a branch should be pushed to a fork of the Forgejo runner (for instance wip-runner-change) that uses the ACT version under test in wip-act-change by modifying go.mod to contain something like the following and running go mod tidy:

replace github.com/nektos/act => code.forgejo.org/earl-warren/act wip-act-change

Where https://code.forgejo.org/earl-warren/act is the URL of the ACT fork and wip-act-change is the branch where the changes under test were pushed. It will not verify that it is able to properly run jobs when connected to a live Forgejo instance. The wip-runner-change branch must, in turn, be tested as explained above. When the Forgejo runner modified to include the changes in the wip-act-change branch pass the end to end test of the setup-forgejo action, it is ready to be released.

ACT can be released by merging the wip-act-change branch and by pushing a new tag, for instance v48.8.20. Once published, the Forgejo runner can be updated to default to this latest version knowing it already passed end to end tests with something like:

replace github.com/nektos/act => code.forgejo.org/forgejo/act v48.8.20

Local debug

The repositories are checked out in the same directory:

Install dependencies

The dependencies are installed manually or with:

setup-forgejo/forgejo-dependencies.sh

Build the Forgejo runner with the local ACT

The Forgejo runner is rebuilt with the ACT directory by changing the runner/go.mod file to:

replace github.com/nektos/act => ../act

Running:

cd runner ; go mod tidy

Building:

cd runner ; rm -f forgejo-runner ; make forgejo-runner

Launch Forgejo and the runner

A Forgejo instance is launched with:

cd setup-forgejo ; ./forgejo.sh setup
firefox http://$(cat forgejo-ip):3000

The user is root with password admin1234. The runner is registered with:

cd setup-forgejo
docker exec --user 1000 forgejo forgejo actions generate-runner-token > forgejo-runner-token
../runner/forgejo-runner register --no-interactive --instance "http://$(cat forgejo-ip):3000/" --name runner --token $(cat forgejo-runner-token) --labels docker:docker://node:16-bullseye,self-hosted

And launched with:

cd setup-forgejo ; ../runner/forgejo-runner --config runner-config.yml daemon

Note that the runner-config.yml is required in that particular case to configure the network in bridge mode, otherwise the runner will create a network that cannot reach the forgejo instance.

Try a sample workflow

From the Forgejo web interface, create a repository and add the following to .forgejo/workflows/try.yaml. It will launch the job and the result can be observed from the actions tab.

on: [push]
jobs:
  ls:
    runs-on: docker
    steps:
      - uses: actions/checkout@v3
      - run: |
          ls ${{ github.workspace }}