From 9f7d041693b8de4ef333aea02f0cfbdcaf1696c3 Mon Sep 17 00:00:00 2001 From: alpha nerd Date: Fri, 15 May 2026 11:55:53 +0200 Subject: [PATCH] doc: update with full examples for copy and paste --- run-tests/README.md | 137 +++++++++++++++++++++++++++++++++----------- 1 file changed, 105 insertions(+), 32 deletions(-) diff --git a/run-tests/README.md b/run-tests/README.md index e3603b0..6d5d022 100644 --- a/run-tests/README.md +++ b/run-tests/README.md @@ -24,6 +24,8 @@ This ordering ensures artifacts are always uploaded on failure, even though the ## Usage +Each example below is a complete workflow — drop it into `.forgejo/workflows/test.yml` (or `.github/workflows/test.yml`) and adjust `runs-on` to match a label one of your runners is registered with. See [Choosing a runner](#choosing-a-runner) below. + ### Node.js ```yaml @@ -31,7 +33,7 @@ name: PR Tests on: [pull_request] jobs: test: - runs-on: docker + runs-on: docker-amd64 steps: - uses: https://code.forgejo.org/actions/checkout@v4 - uses: https://bitfreedom.net/code/apunkt/actions/run-tests@v1 @@ -46,58 +48,129 @@ jobs: ### Python (pytest) ```yaml -- uses: https://bitfreedom.net/code/apunkt/actions/run-tests@v1 - with: - setup: | - python -m pip install --upgrade pip - pip install -e .[test] - command: pytest --junitxml=report.xml - artifacts-path: report.xml +name: PR Tests +on: [pull_request] +jobs: + test: + runs-on: docker-amd64 + steps: + - uses: https://code.forgejo.org/actions/checkout@v4 + - uses: https://bitfreedom.net/code/apunkt/actions/run-tests@v1 + with: + setup: | + python -m pip install --upgrade pip + pip install -e .[test] + command: pytest --junitxml=report.xml + artifacts-path: report.xml ``` ### Rust ```yaml -- uses: https://bitfreedom.net/code/apunkt/actions/run-tests@v1 - with: - command: cargo test --all +name: PR Tests +on: [pull_request] +jobs: + test: + runs-on: docker-amd64 + steps: + - uses: https://code.forgejo.org/actions/checkout@v4 + - uses: https://bitfreedom.net/code/apunkt/actions/run-tests@v1 + with: + command: cargo test --all ``` ### Java (Gradle) ```yaml -- uses: https://bitfreedom.net/code/apunkt/actions/run-tests@v1 - with: - setup: ./gradlew --version - command: ./gradlew test - artifacts-path: | - **/build/reports/tests/** - **/build/test-results/**/*.xml +name: PR Tests +on: [pull_request] +jobs: + test: + runs-on: docker-amd64 + steps: + - uses: https://code.forgejo.org/actions/checkout@v4 + - uses: https://bitfreedom.net/code/apunkt/actions/run-tests@v1 + with: + setup: ./gradlew --version + command: ./gradlew test + artifacts-path: | + **/build/reports/tests/** + **/build/test-results/**/*.xml ``` ### Java (Maven) ```yaml -- uses: https://bitfreedom.net/code/apunkt/actions/run-tests@v1 - with: - setup: mvn --version - command: mvn -B test - artifacts-path: | - **/target/surefire-reports/** - **/target/failsafe-reports/** +name: PR Tests +on: [pull_request] +jobs: + test: + runs-on: docker-amd64 + steps: + - uses: https://code.forgejo.org/actions/checkout@v4 + - uses: https://bitfreedom.net/code/apunkt/actions/run-tests@v1 + with: + setup: mvn --version + command: mvn -B test + artifacts-path: | + **/target/surefire-reports/** + **/target/failsafe-reports/** ``` ### Multi-line command +Any of the examples above can run multiple commands in a single step by passing a YAML block scalar to `command`: + ```yaml -- uses: https://bitfreedom.net/code/apunkt/actions/run-tests@v1 - with: - command: | - make lint - make test - make integration-test + - uses: https://bitfreedom.net/code/apunkt/actions/run-tests@v1 + with: + command: | + make lint + make test + make integration-test ``` +## Choosing a runner + +`runs-on` must match the labels a runner was registered with — there is no fuzzy match. If your runners are registered as `docker-amd64` and `docker-arm64`, then `runs-on: docker` will queue forever waiting for a runner that doesn't exist. + +### Single architecture + +Pick the label that matches your runner: + +```yaml +jobs: + test: + runs-on: docker-amd64 +``` + +### Both architectures (matrix) + +Run the same job on every arch in parallel. Useful when you ship binaries, link against native libraries, or want to catch arch-specific bugs early: + +```yaml +jobs: + test: + strategy: + fail-fast: false + matrix: + arch: [docker-amd64, docker-arm64] + runs-on: ${{ matrix.arch }} + steps: + - uses: https://code.forgejo.org/actions/checkout@v4 + - uses: https://bitfreedom.net/code/apunkt/actions/run-tests@v1 + with: + command: ./run-tests.sh +``` + +`fail-fast: false` lets the other arch finish even if one fails, so you see both results. + +### Does the architecture matter for the tests? + +- **Pure JVM, Python, or Node** with no native dependencies: only execution speed differs. +- **Native code** (Rust, C/C++, JNI, Python wheels like `numpy`/`cryptography`, Node modules built with `node-gyp`): the compiled artifact is arch-specific. Same source, different binary — running the matrix exercises both. +- **Container images pulled during setup**: must publish a manifest for the runner's arch. Most official images do; some niche ones are amd64-only and will fail on arm64. + ## Making it a merge gate This action alone does not block merges. To enforce passing tests before merge on Forgejo: @@ -111,6 +184,6 @@ After the workflow has run at least once on a PR, the check name will appear in ## Notes -- Forgejo runners often use the `docker` label rather than `ubuntu-latest`. Adjust `runs-on` per your runner setup. +- `runs-on` must match a label your runner was registered with — see [Choosing a runner](#choosing-a-runner). The GitHub-style `ubuntu-latest` typically does not exist on Forgejo. - Action references must use full URLs on Forgejo (`https://code.forgejo.org/actions/checkout@v4`), unlike GitHub where `actions/checkout@v4` is shorthand. - The failure-artifact upload uses [`forgejo/upload-artifact`](https://code.forgejo.org/forgejo/upload-artifact), which is API-compatible with `actions/upload-artifact` and works on both Forgejo and GitHub.