gitea runner labels can't use extended (docker image) syntax

[Infinoid]

Hi,

The garm pool has a comma-separated set of labels, which are passed through to the gitea act_runner executable. That's great. But label syntax is a little more complex for gitea, and garm's parser should be aware of this.

If you just say "ubuntu-latest", the default is to run the job in "host" mode, meaning it runs as a normal child process, under the same OS as the runner itself. To configure a label to run jobs in a docker container, the label syntax becomes "ubuntu-latest:docker://dockertag", as documented here.

The problem occurs when I pass in my own label using similar syntax, like this:

% garm-cli pool add \
    --repo=c7ad5df3-efd4-4d09-880c-4827ddae290c \
    --provider-name=aws \
    --tags=garm-test:docker://docker.gitea.com/runner-images:ubuntu-latest \
[…]

Garm receives this webhook:

{
  "action": "queued",
  "workflow_job": {
    "id": 6652,
    "labels": [
      "garm-test"
    ],
[…]

Garm doesn't appear to know the label is "garm-test"... I think it matches against the full string. I see this in the logs:

time=2026-04-01T15:09:14.040Z level=WARN msg="no pools matching tags; not recording job" requested_tags=garm-test action=handle_workflow pool_mgr=hello-world/hello-world endpoint=gitea pool_type=repository
time=2026-04-01T15:09:14.040Z level=ERROR msg="failed to handle workflow job" error="job 6652 should not be recorded"
time=2026-04-01T15:09:14.040Z level=INFO msg=access_log method=POST uri=/webhooks/5d4dc1da-0b83-44b4-b034-e995c886307e user_agent=Go-http-client/1.1 ip=[2600:1f18:7bbe:ba49:7925::10]:41074 code=500 bytes=38 request_time=1.801309ms

When I set the label simply as "garm-test", it works. But this effectively limits the gitea runner to acting in host mode. Which means I would need separate EC2 AMIs and Garm pools for "debian" vs "alpine", for example.

Would it be possible to handle this syntax in pool labels? It should continue passing the whole thing through to act_runner, but the webhook handler should only match the part before the colon.

Thanks!

[gabriel-samfira]

Would you mind trying out the following workflow syntax (notice the container section):

name: "test workflow"

on:
  # Set your `on` rules here.
  workflow_dispatch:

jobs:
  dummy:
    name: "Do nothing, really"

    runs-on: garm-test
    container:
      # Define the image you want to use, here.
      image: docker.gitea.com/runner-images:ubuntu-latest
      env:
        NODE_ENV: development

    steps:
      - name: "Just print some info"
        shell: bash
        run: |
          hostname
          uname -a
          df -h
          whoami
      - name: Check for dockerenv file
        run: (ls /.dockerenv && echo Found dockerenv) || (echo No dockerenv)

This workflow can run on any OS as long as docker and nodejs is available and it will pull in any image you specify in the image: section of the container option. So you can use the same AMI to run workflows on any docker image built from any OS (debian, alpine, etc).

The EC2 AMI you use, must have docker installed for this to work. You can create your own image with everything bundled, or have GARM inject userdata to install the needed packages automatically by defining the pool with the following extra_specs (example for an Ubuntu image - other distros may have different package names):

garm-cli pool add \
    --repo=c7ad5df3-efd4-4d09-880c-4827ddae290c \
    --provider-name=aws \
    --tags=garm-test \
    --extra-specs='{"extra_packages":["docker.io","nodejs"]}' \
[…]

GARM does not parse the tags you set on a pool. They are strings to garm which it sets on the runners, as-is. When a webhook comes in, if the requested labels don't match the user defined labels, garm will not react.

This might be added in the future, but given that workflows already allow you to programmatically request that the job should run in a container, I am unsure if we should add a special case for Gitea to cover this scenario. Both GitHub and Gitea (I suspect Forgejo as well) support this.

That being said, I am not familiar enough with Gitea to have strong opinions on the matter. If it turns out that the above suggestion is impractical, I can definitely look into handling this.

[gabriel-samfira]

Some more info about running jobs in containers:

https://docs.github.com/en/actions/how-tos/write-workflows/choose-where-workflows-run/run-jobs-in-a-container

This gives you a lot more flexibility (mount volumes, expose ports, etc).

[Infinoid]

You're right. The workflow can specify for itself which docker image it wants to run in, and that works. This issue only affects act_runner's ability to specify the default image on a per-label basis. So that reduces the impact of this issue somewhat.

It also caused me some confusion when I tried to copy the same set of labels from my old runner into garm.

Thanks for reminding me, I was staring too hard at the labels and forgot about this option. (Does anyone actually use the exposed ports?)

[Infinoid]

Both GitHub and Gitea (I suspect Forgejo as well) support this.

Yeah. Forgejo's runner supports that extended label syntax, and it supports overriding the container image in the workflow yaml, same as gitea.

[gabriel-samfira]

Does anyone actually use the exposed ports?

I've no idea tbh. It might be useful if you run jobs in parallel (default if needs is not set), build and start the service you want to test in one job, run tests against it in another job, but you'd have to expose a known/predictable address in the first job, poll untill available in the second, etc.

The volume option I think is more useful if you need to pass through potentially updated /etc/ssl/certs or something.

That being said, if you feel we should try and support the extended syntax and have a "user story" that is not covered by the container workflow syntax, we can add it. I am not against adding it, but time being short, I would focus on other things before tackling this if it's not a blocker.

[Infinoid]

Given that workflows can specify their own image tags, this issue only really affects shops which were using labels to imply default image tags, and expect garm to be a drop-in replacement, without having to change their workflows. Otherwise this is just a detail to be documented.

[gabriel-samfira]

I will keep this open so I don't forget about this nuance. I need to update the docs (severely outdated for main) when I free up my current work queue.

I will add an FAQ section or something and scour the issues for questions that have popped up over time, were answered but never documented.

[Infinoid]

Thanks. Otherwise, things are working pretty well so far! Looking forward to seeing gitea (and eventually forgejo (I use both)) support fully released.

[gabriel-samfira]

I will probably release 0.2.0 this month if nothing urgent comes up. There are 2 issues I want to create PRs for before I do. Forgejo has a couple of PRs that need to merge before we can try to integrate it. Really looking forward to that.