[Proposal] Support configuring permissions of automatic tokens of Actions jobs

[wolfogre]

Background

When a Gitea Actions job has been picked by a runner, a automatically generated token will be given to the runner at the same time. This is a short-lived token that immediately becomes invalid when the job is completed.

The token can be used to access the repository to which it belongs, such as cloning code via actions/checkout. You can use it with gitea.token, secrets.GITEA_TOKEN, or github.token, secrets.GITHUB_TOKEN to ensure compatibility.

However, the permissions of this token are not really clear to everyone. IIRC, currently it can:

• Read the code of the repository to which it belongs, and write the code if the job is not triggered by a pull request from a forked repository.
• Read resources of public repositories or submit issues to them as a signed-in user.

Sometimes it’s not convenient, for example, you cannot use this token to write packages, so it’s annoying when releasing.

Some PRs try to add more permissions to this token, but I’m cautious about this, see:

• Add actions support to package auth verification #23729 (comment)
• Implement a simple ActionsUser permission check in package api #24554 (comment)

My reason is that, in the absence of a means to configure permissions for automatic tokens, we need to be cautious about granting more permissions by default, even if it may cause some inconvenience, as it could bring about security risks. I would say it's "inconvenient", not "impossible", because you can always provide an access token or deploy key as a secret to do anything you want, just like using an external CI/CD system.

However, Gitea Actions isn't an external CI/CD system, so it could do better. The first thing that should be done is supporting the configuration of permissions for automatic tokens. It's not a simple thing, but the good news is that we can refer to GitHub.

How does a GitHub do

On GitHub, you can choose between permissive mode or restricted mode on the settings page of a repository or organization.

The two modes have different default permissions, see Automatic token authentication. This is a coarse-grained setting. Sometimes it's not enough.

So you can specify permissions for specific workflows or jobs in the workflow files. See:

• permissions
• jobs.<job_id>.permissions

However, you can overwrite the default permissions of the mode in workflow files by this, instead of being limited by them. That means even if the repository is in restricted mode, it is still possible to obtain higher permission in its workflow files. In my opinion, Gitea is not suitable for this design, because Gitea doesn't support code owners yet, that means as long as someone has permission to write code, they can access anything via Actions by obtaining higher permission in workflow files.

Unfortunately, I noticed that the permission control only applies to accessing the same repository, not to accessing other repositories in the same organization. Therefore, the token cannot access other private repositories within the same organization. See Cloning private github repository within organisation in actions - Stackoverflow.

I think Gitea needs to do more to support it.

Solution

Here is my proposal, which draws heavily from GitHub but has been adjusted for Gitea.

Support configuring the permissions

Support configuring the maximum access on the settings page of a repository or organization Something like (this is a fake sketch, I haven't done anything yet):

You can still specify permissions for specific workflows or jobs in the workflow files. However, you cannot obtain higher permissions than the configuration on setting page. You may have noticed that the units in Gitea are not exactly the same as the scopes in GitHub, so some adjustments are needed.

If the job is triggered by a pull request from a forked repository, the maximum access will always be lower than read.

Support configuring access between repositories

On the settings page of an organization, users can configure which repositories can be accessed by Actions from other repositories within the same organization.

Private packages can be accessed by Actions only when they have been linked to repositories

As packages belong to the organization level, it is difficult to determine what to do when repository X tries to write package Y. So let's make things simpler, repository X can write package Y only if:

• Package Y has been linked to repository X, and write permission to packages has been granted to repository X.
• Package Y has been linked to repository Z, but repository Z has been set to be accessible by other repos within the same organization, including repository X. Additionally, write permission to packages has been granted to repository X.

An access token or deploy key as a secret is recommended for more complex situations

Such as:

• A organization has repositories X, Y and Z, I want X to be accessed by Y, but not Z; And Y can be accessed by Z, but not A.
• I want create/delete repositories in Actions workflows.
• I am the only user of my Gitea instance, I want the workflows can do anything without limits.

[silverwind]

Hmm, having it in-action sure would be convenient because then this permission config would be easily ported to new repos and possibly GH actions without fiddling with the UI. Why exactly do you think such config is unsuitable?

BTW, on GH actions it's possible to obtain write access to the repo by using a write-level deploy key while checking out. I think this method was mostly superceded by the permissions option now, but we should be aware that this "escape hatch" exists.

      - uses: actions/checkout@v3
        with:
          ssh-key: ${{ secrets.DEPLOY_KEY }}

[wolfogre]

Why exactly do you think such config is unsuitable?

I'm sorry I didn't make myself clear, please check the latest version of the description.

BTW, on GH actions it's possible to obtain write access to the repo by using a write-level deploy key while checking out.

Yes, and you can do that on Gitea Actions too.

I think this method was mostly superceded by the permissions option now, but we should be aware that this "escape hatch" exists.

I agree with you, just like I said, "An access token or deploy key as a secret is recommended for more complex situations".

[Renari]

I encountered this today and thought this token feature didn't even exist because it was unable to push releases, my work around atm is to create an application token and to reassign GITEA_TOKEN to the application token:

e.g.

env:
  GITEA_TOKEN: ${{ secrets.APPLICATION_TOKEN }}

This is less than ideal though since it binds the repo permissions to that user account, for my use case a single developer on this project this is fine, but less than ideal since in a team scenario it's binding functionality to an individual user account.