Forgejo Fine-Grained Repository Permissions: Assign Roles and Verify Access

Problem and useful answer

You need a contributor to push code to one Forgejo repository without giving them administrative control over your entire Forgejo instance. You also need proof that the restriction works before you rely on it.

Forgejo controls repository access through per-repository role assignments. A user can be granted Read, Write, Maintain, or Owner access to a specific repository, independently of their global account type. The most reliable confirmation is to assign the role, then attempt an authenticated push as that user.

How repository permissions work

Forgejo associates a role with each user-repository pair. Commonly described roles include Owner, Maintain, Write, Read, and Guest. Exact capabilities vary by Forgejo release, so check your installed version's documentation before treating any role as authoritative.

A global administrator is not automatically a repository Maintainer, and a repository Maintainer is not automatically a global administrator. Permissions are evaluated at the repository level; do not assume that access to one repository extends to another.

Permissions can be managed through the Forgejo admin UI or through the API. The API is useful for scripting access changes across many repositories, but the exact endpoint path and payload differ between releases. Confirm the current path in your Forgejo API documentation before sending requests to production data.

Worked example: assign a role through the API

Run the following from a terminal that can reach your Forgejo instance. Replace every placeholder in angle brackets.

curl -X POST '/api/v1/repos///permissions' \
  -H 'Authorization: token ' \
  -H 'Content-Type: application/json' \
  -d '{"user":"","role":"Maintain"}'

Where to run: any workstation with network access to the Forgejo host.

Required permissions: the API token must belong to a global administrator or to a user with permission to manage the target repository.

Meaningful placeholders:

• — the base URL of your Forgejo instance, without a trailing slash.
• — the user or organization that owns the repository.
• — the repository name.
• — a valid Forgejo API token.
• — the account receiving the repository role.

Expected checks:

• The API returns a 2xx response.
• The target user appears in the repository permission list in the Forgejo UI.
• An authenticated push by succeeds if the role includes write access, and is rejected if it does not.

Risks: assigning Owner or Maintain can allow repository deletion, setting changes, or access changes for other users. Test on a non-production repository first.

Verify the result

1. Create a temporary repository for the test.
2. Add a test user account, or use an existing account that should not have broad access.
3. Assign the user a role such as Write using the API example above or the repository settings UI.
4. Clone the repository as the test user.
5. Make a small commit and push it.
6. Observe whether the push is accepted or rejected with an access error.

If the push succeeds for a Write role and fails for a Read-only role, the permission mechanism is behaving as expected. If a Read-only user can push, or a Write user cannot, review the role assignment and the repository's default access settings.

Limits and common mistakes

• Permission entries are stored per repository. Confirm whether your Forgejo release enforces a maximum number of entries per repository, and monitor usage if you manage many users.
• Repository roles do not automatically cascade to other repositories or to nested groups in many releases. Check your instance's inheritance settings before assuming broader access.
• Assigning Write access without an appropriate baseline Read role can leave a user unable to clone after a repository reset.
• Older API versions may ignore permission changes. Use the current stable API documented for your Forgejo release.
• Custom roles, where available, can unintentionally grant higher privileges than intended. Review the exact capabilities of any custom role before assigning it.

Cleanup after testing

The example changes state by creating a repository and assigning permissions. Remove the test artifacts when verification is complete:

• Delete the temporary repository through the Forgejo UI or API.
• Revoke the test permission assignment.
• Remove the test user account if you created one solely for verification.

Practical check

After any permission change, repeat the push test with the affected account. A successful push for authorized roles and a clear access error for unauthorized roles is the simplest confirmation that your configuration is working.