[Proposal] Support changing labels of Actions runner without re-registration #10784

New Issue

GiteaMirror · 2025-11-02T09:18:03-06:00

GiteaMirror commented

2025-11-02 09:18:03 -06:00

Originally created by @wolfogre on GitHub (May 5, 2023).

Originally assigned to: @sillyguodong on GitHub.

Background

Act runner will ask for labels when you register it to a Gitea instance. For example, one of the default labels is ubuntu-latest:docker://node:16-bullseye . It could be split into two parts.:

ubuntu-latest: This means it can run jobs with runs-on: ubuntu-latest
docker://node:16-bullseye: This means that the jobs will run in Docker containers with the specified image.

The runner will report ubuntu-latest to the Gitea instance, so the instance will know what kind of jobs can be assigned to this runner. However, the instance doesn't know the second part of the label because Gitea doesn't care how a runner runs jobs.

For some reason, it was designed to allow modifying labels on the Gitea side, in a special way:

Gitea cannot modify the labels reported by runners, which are called "Agent Labels".
Gitea can append more labels to runners, which are called "Custom Labels".

So it will be convenient for users when they have a job with runs-on: centos, but there are no runners with the label. They can add centos as a custom label to let the runner pick up the jobs.

Unfortunately, when the runner receives the job, it doesn't understand how to run it. To avoid failure, the act runner will use the default image to run jobs with unrecognized labels. This may surprise users.

IMO, the point is that we shouldn't let Gitea define runners. It should be the runners who decide what kind of jobs they can run, not the Gitea instance. However, we also need to provide an elegant way to modify labels on the runner side, instead of re-registration.

Solution

Forbid modifying runner labels on the Gitea side

~~Combine “agent labels” and “custom labels” to “labels”.~~ Drop “custom labels” and use “agent labels” only.
Users cannot modify the labels on settings pages of Gitea.

Provide a new RPC method for runners to declare their labels

A new method like Declare(or a better name).
Act runner will call Declare to pass its current labels to Gitea once it has started.
Gitea will update the labels of the runner in database.

Support specifying labels in the config file of the runner

Users can specify labels in the config file; it's optional. An empty value means "none" instead of "empty”.
When registering a runner:
1. Ignore the step/flag for labels if a config file with labels has been specified.
2. Otherwise, ask for labels.
When running a runner:
1. Overwrite the labels to state file (.runner) if a config file with labels has been specified, and declare with new labels to Gitea.
2. Otherwise, use the labels stored in the state file.

Benefits

Provide convenience. Users can add/remove/change the labels of a runner by simply updating the config file and restarting the runner.
Reduce confusion. The only way to the labels of a runner is modifying the config file.
Clear boundaries. Users cannot modify the labels if they cannot touch the runner, even if they are the admin of the Gitea instance.

Originally created by @wolfogre on GitHub (May 5, 2023). Originally assigned to: @sillyguodong on GitHub. ## Background Act runner will ask for labels when you register it to a Gitea instance. For example, one of the default labels is `ubuntu-latest:docker://node:16-bullseye` . It could be split into two parts.: - `ubuntu-latest`: This means it can run jobs with `runs-on: ubuntu-latest` - `docker://node:16-bullseye`: This means that the jobs will run in Docker containers with the specified image. The runner will report `ubuntu-latest` to the Gitea instance, so the instance will know what kind of jobs can be assigned to this runner. However, the instance doesn't know the second part of the label because Gitea doesn't care how a runner runs jobs. For some reason, it was designed to allow modifying labels on the Gitea side, in a special way: - Gitea cannot modify the labels reported by runners, which are called "Agent Labels". - Gitea can append more labels to runners, which are called "Custom Labels". <img width="943" alt="Untitled" src="https://user-images.githubusercontent.com/9418365/236415302-4bafe363-fb55-4236-9c2e-f8649e21d79b.png"> So it will be convenient for users when they have a job with `runs-on: centos`, but there are no runners with the label. They can add `centos` as a custom label to let the runner pick up the jobs. Unfortunately, when the runner receives the job, it doesn't understand how to run it. To avoid failure, the act runner will use the default image to run jobs with unrecognized labels. This may surprise users. IMO, the point is that we shouldn't let Gitea define runners. It should be the runners who decide what kind of jobs they can run, not the Gitea instance. However, we also need to provide an elegant way to modify labels on the runner side, instead of re-registration. ## Solution ### Forbid modifying runner labels on the Gitea side 1. ~Combine “agent labels” and “custom labels” to “labels”.~ Drop “custom labels” and use “agent labels” only. 2. Users cannot modify the labels on settings pages of Gitea. ### Provide a new RPC method for runners to declare their labels 1. A new method like `Declare`(or a better name). 2. Act runner will call `Declare` to pass its current labels to Gitea once it has started. 3. Gitea will update the labels of the runner in database. ### Support specifying labels in the config file of the runner 1. Users can specify labels in the config file; it's optional. An empty value means "none" instead of "empty”. 2. When registering a runner: 1. Ignore the step/flag for labels if a config file with labels has been specified. 2. Otherwise, ask for labels. 3. When running a runner: 1. Overwrite the labels to state file (.runner) if a config file with labels has been specified, and declare with new labels to Gitea. 2. Otherwise, use the labels stored in the state file. ## Benefits 1. Provide convenience. Users can add/remove/change the labels of a runner by simply updating the config file and restarting the runner. 2. Reduce confusion. The only way to the labels of a runner is modifying the config file. 3. Clear boundaries. Users cannot modify the labels if they cannot touch the runner, even if they are the admin of the Gitea instance.

GiteaMirror added the topic/gitea-actions type/proposal labels 2025-11-02 09:18:03 -06:00

GiteaMirror closed this issue

2025-11-02 09:18:03 -06:00

GiteaMirror commented

2025-11-02 09:18:04 -06:00

@sillyguodong commented on GitHub (May 16, 2023):

However, the instance does the second part of the label because Gitea doesn't care how a runner runs jobs.

Maybe "the instance does not know the second part of the label"?

@sillyguodong commented on GitHub (May 16, 2023): > However, the instance does the second part of the label because Gitea doesn't care how a runner runs jobs. Maybe "the instance does not know the second part of the label"?

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/gitea#10784