[Proposal] Support reusable `Registration Token` of runners

[sillyguodong]

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
• Provide a programmable way to register a new action runner #23643
• Improve Config Management/Stateless Runner Deploy Workflows #23703

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

• add CLI command to register runner tokens #23762
• Add API endpoint to get token for registering runners for repos #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:

      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.
   

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，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

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.

[silverwind]

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]

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 😆.

[wolfogre]

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.

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

gitea/routers/api/actions/runner/runner.go

Lines 67 to 80 in 2d0ff00

	if err := runner.GenerateToken(); err != nil {
	return nil, errors.New("can't generate token")
	}
	// create new runner
	if err := actions_model.CreateRunner(ctx, runner); err != nil {
	return nil, errors.New("can't create new runner")
	}
	// update token status
	runnerToken.IsActive = true
	if err := actions_model.UpdateRunnerToken(ctx, runnerToken, "is_active"); err != nil {
	return nil, errors.New("can't update runner token status")
	}

---

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

[silverwind]

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.

[jon-ressio]

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

[nwmcsween]

This needs to be done for any sort of autoscaling.

[garymoon]

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.

[a9eesh]

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

[lunny]

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.