[Proposal] Support reusable Registration Token of runners #10947

New Issue

GiteaMirror · 2025-11-02T09:22:59-06:00

GiteaMirror commented

2025-11-02 09:22:59 -06:00

Originally created by @sillyguodong on GitHub (Jun 1, 2023).

Background

Currently, the Registration Token obtained in the UI becomes invalid immediately after registering a runner, making it impossible to reuse. However, it is annoying that not having reusbale annoying in some auto-scaling environments.

Here are some related issues::

In fact, we already have related PRs that enable Gitea to provide the ability to generate Tokens via the command line or API:

But I believe it would be more convenient to have a reusable token. Of course, it would also be necessary to provide the ability to invalidate Tokens in real-time to prevent misuse.

Solution

Add the following fields to the table:

   type ActionRunnerToken struct {
       ID       int64
       Token    string `xorm:"UNIQUE"`
       IsActive bool
       // Omitting other fields
       // The following are the added fields:
       Type          ActionRunnerTokenType
       ParentTokenID int64
       Desc          string
   }

   type ActionRunnerTokenType int

   const (
       NormalRunnerToken ActionRunnerTokenType = iota

       ReusableRunnerToken
   )

In the UI, users can create reusable tokens and view them in a list. In the list, they can enable, disable, or delete tokens at any time.
When Gitea receives a runner registration request, it first checks if the token is a reusable token. If it is, a normal token is generated for the runner and returned. This normal token will be written to the .runner file. At the same time, the normal token inherits the owner_id and repo_id from the reusable token and is stored in the database.

As mentioned in this comment，we should also provide the ability to deregister runners:

It would also be great if there was a way to unregister act_runner as well, especially if you want them to be created and deleted dynamically, to avoid having unnecessary act_runner corpses in the database.

To achieve this, we need to add the following to the protocol buffer:

   service RunnerService {
     // Deregister deregister new runner in server.
     rpc Deregister(DeregisterRequest) returns (DeregisterResponse) {}
   }

   message DeregisterRequest {
     int64 id = 1;
     string uuid = 2;
     string token = 3; // must be normal token in .runner file
   }

   message DeregisterResponse {
     Runner runner = 1;
   }

Benefits

Creating a reusable token needs to be done in Site Administration, Repo Settings, or Org Settings, defining the scope of runners that use this reusable token. This is consistent with the previous token logic.
The implementation is simple and does not affect the existing logic.

Originally created by @sillyguodong on GitHub (Jun 1, 2023). ## Background Currently, the `Registration Token` obtained in the UI becomes invalid immediately after registering a runner, making it impossible to reuse. However, it is annoying that not having reusbale annoying in some auto-scaling environments. Here are some related issues:: - https://gitea.com/gitea/act_runner/issues/210 - https://github.com/go-gitea/gitea/issues/23643 - https://github.com/go-gitea/gitea/issues/23703 In fact, we already have related PRs that enable Gitea to provide the ability to generate Tokens via the command line or API: - https://github.com/go-gitea/gitea/pull/23762 - https://github.com/go-gitea/gitea/pull/23761 But I believe it would be more convenient to have a reusable token. Of course, it would also be necessary to provide the ability to invalidate Tokens in real-time to prevent misuse. ## Solution 1. Add the following fields to the table: ```golang type ActionRunnerToken struct { ID int64 Token string `xorm:"UNIQUE"` IsActive bool // Omitting other fields // The following are the added fields: Type ActionRunnerTokenType ParentTokenID int64 Desc string } type ActionRunnerTokenType int const ( NormalRunnerToken ActionRunnerTokenType = iota ReusableRunnerToken ) ``` 2. In the UI, users can create `reusable tokens` and view them in a list. In the list, they can enable, disable, or delete tokens at any time. ![image](https://github.com/go-gitea/gitea/assets/33891828/89e44b0a-9d94-408e-b5a0-6ddcf704f5b7) 3. When Gitea receives a runner registration request, it first checks if the token is a reusable token. If it is, a normal token is generated for the runner and returned. This normal token will be written to the `.runner` file. At the same time, the normal token inherits the `owner_id` and `repo_id` from the reusable token and is stored in the database. 4. As mentioned in this [comment](https://github.com/go-gitea/gitea/pull/23761#issuecomment-1564694434)，we should also provide the ability to deregister runners: > It would also be great if there was a way to unregister act_runner as well, especially if you want them to be created and deleted dynamically, to avoid having unnecessary act_runner corpses in the database. To achieve this, we need to add the following to the protocol buffer: ```protobuf service RunnerService { // Deregister deregister new runner in server. rpc Deregister(DeregisterRequest) returns (DeregisterResponse) {} } message DeregisterRequest { int64 id = 1; string uuid = 2; string token = 3; // must be normal token in .runner file } message DeregisterResponse { Runner runner = 1; } ``` ## Benefits 1. Creating a reusable token needs to be done in `Site Administration`, `Repo Settings`, or `Org Settings`, defining the scope of runners that use this reusable token. This is consistent with the previous token logic. 2. The implementation is simple and does not affect the existing logic.

GiteaMirror added the type/enhancement topic/gitea-actions type/proposal labels 2025-11-02 09:22:59 -06:00

GiteaMirror closed this issue

2025-11-02 09:22:59 -06:00

GiteaMirror commented

2025-11-02 09:23:00 -06:00

@silverwind commented on GitHub (Jun 1, 2023):

ReusableRunnerToken

Would not introduce a new struct, but extend current struct with a boolean isPermanent that defaults to false. When set to true, it will not be deleted on use. On the UI, add a checkbox that controls this value on token creation.

@silverwind commented on GitHub (Jun 1, 2023): > `ReusableRunnerToken` Would not introduce a new struct, but extend current struct with a boolean `isPermanent` that defaults to false. When set to true, it will not be deleted on use. On the UI, add a checkbox that controls this value on token creation.

GiteaMirror commented

2025-11-02 09:23:00 -06:00

@silverwind commented on GitHub (Jun 1, 2023):

In the UI, users can create reusable tokens and view them in a list. In the list, they can enable, disable, or delete tokens at any time.

Maybe not make it a modal, but a separate page that can be linked to, etc. Someone recently linked this in discord 😆.

@silverwind commented on GitHub (Jun 1, 2023): > In the UI, users can create reusable tokens and view them in a list. In the list, they can enable, disable, or delete tokens at any time. Maybe not make it a modal, but a separate page that can be linked to, etc. Someone recently linked [this](https://youdontneedamodalwindow.dev/) in discord 😆.

GiteaMirror commented

2025-11-02 09:23:00 -06:00

@wolfogre commented on GitHub (Jun 6, 2023):

I have different ideas. I think we can just keep it simple.

No Normal token or Reusable token, just Registration token
By default, a registration token will be ~~inactive~~ mark used (actually, IsActive = true means used) when it has been used, just like what has been done now.
Users can "pin" a registration token to make it reusable, that means the token will keep usable when it has been used.
Users can still reset the registration token or "unpin" it.

BTW, I think you may misunderstand "registration token"(ActionRunnerToken.Token) and "runner token"(ActionRunner.Token), they are different. Runners will have different token for authentication when connecting to Gitea even they have used the same registration token.

See 2d0ff00823/routers/api/actions/runner/runner.go (L67-L80)

Agree with Deregister, but it could be another PR/issue.

@wolfogre commented on GitHub (Jun 6, 2023): I have different ideas. I think we can just keep it simple. 1. No `Normal token` or `Reusable token`, just `Registration token` 2. By default, a registration token will be ~inactive~ mark used (actually, `IsActive = true` means used) when it has been used, just like what has been done now. 3. Users can "pin" a registration token to make it reusable, that means the token will keep usable when it has been used. 4. Users can still reset the registration token or "unpin" it. <img width="436" alt="image" src="https://github.com/go-gitea/gitea/assets/9418365/b3397570-c1ef-4b7e-b213-cd39df3fb7d3"> BTW, I think you may misunderstand "registration token"(`ActionRunnerToken.Token`) and "runner token"(`ActionRunner.Token`), they are different. Runners will have different token for authentication when connecting to Gitea even they have used the same registration token. See https://github.com/go-gitea/gitea/blob/2d0ff00823bf92ee32df107416fd30010638f21d/routers/api/actions/runner/runner.go#L67-L80 --- Agree with `Deregister`, but it could be another PR/issue.

GiteaMirror commented

2025-11-02 09:23:00 -06:00

@silverwind commented on GitHub (Jun 6, 2023):

Yes, I had been suggesting a checkbox too. Would name it "Permanent".

To manage tokens, add Actions -> Tokens to manage them with a table view. Non-permanent tokens should show up in the table, but be automatically deleted upon use.

To avoid generating trash tokens every time this menu is opened, I suggest a explicit "Generate" button, which then could link to a single-token page, or popup with instructions how to use.

@silverwind commented on GitHub (Jun 6, 2023): Yes, I had been suggesting a checkbox too. Would name it "Permanent". To manage tokens, add Actions -> Tokens to manage them with a table view. Non-permanent tokens should show up in the table, but be automatically deleted upon use. To avoid generating trash tokens every time this menu is opened, I suggest a explicit "Generate" button, which then could link to a single-token page, or popup with instructions how to use.

GiteaMirror commented

2025-11-02 09:23:00 -06:00

@jon-ressio commented on GitHub (Jul 6, 2023):

This would be great. I've got a starting point for a helm chart for gitea-runner but can't scale it out beyond 1 runner, or delete and recreate the pod

@jon-ressio commented on GitHub (Jul 6, 2023): This would be great. I've got a starting point for a helm chart for gitea-runner but can't scale it out beyond 1 runner, or delete and recreate the pod

GiteaMirror commented

2025-11-02 09:23:00 -06:00

@nwmcsween commented on GitHub (Aug 4, 2023):

This needs to be done for any sort of autoscaling.

@nwmcsween commented on GitHub (Aug 4, 2023): This needs to be done for any sort of autoscaling.

GiteaMirror commented

2025-11-02 09:23:01 -06:00

@garymoon commented on GitHub (Aug 4, 2023):

This needs to be done for any sort of autoscaling.

While I'm a strong proponent of this proposal, autoscaling would also be made possible (though involving greater effort than if this proposal were accepted) if this PR (and subsequently the org-level and global variants) were merged.

@garymoon commented on GitHub (Aug 4, 2023): > This needs to be done for any sort of autoscaling. While I'm a strong proponent of this proposal, autoscaling would also be made possible (though involving greater effort than if this proposal were accepted) if [this PR](https://github.com/go-gitea/gitea/pull/23761) (and subsequently the org-level and global variants) were merged.

GiteaMirror commented

2025-11-02 09:23:01 -06:00

@a9eesh commented on GitHub (Aug 9, 2023):

please add this feature anyways. its perfect for docker stacks!

@a9eesh commented on GitHub (Aug 9, 2023): please add this feature anyways. its perfect for docker stacks!

GiteaMirror commented

2025-11-02 09:23:01 -06:00

@lunny commented on GitHub (Sep 20, 2023):

I sent #27143 to try to fix this one. I just have a simple design to reuse is_active column and only the latest token could be used. Then the UI kept as before.

@lunny commented on GitHub (Sep 20, 2023): I sent #27143 to try to fix this one. I just have a simple design to reuse `is_active` column and only the latest token could be used. Then the UI kept as before.

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#10947

[Proposal] Support reusable Registration Token of runners #10947

Background

Solution

Benefits

[Proposal] Support reusable `Registration Token` of runners #10947