Gitea - Repository Management & Visibility

Connection requirements

In order to be able to connect to gitea you either need a gitea account or a valid SSO user. A SSO user seen as valid by Gitea is one with a JWT that contains a giteam field. This field is used to determine which kind of role you'll have.

The first time your SSO user is used to connect to gitea you'll be prompted to create your account.

Available roles

Admin

The admin role allow you to access the Profile and Settings (upper right corner) > Site Administration button that is used to configure the gitea server. Every admin is automatically part of the initial athea organization as a member of its Owners team.

You won't have administrative permission during your first connection, you'll need to disconnect and reconnect to have gitea take it into account.

User

The user role allow a user to connect to gitea. Contrary to an admin, a simple user permissions will be decided for each ressource by their respective owners.

eg: You'll need to be invited to a team to access its private repositories

Creating a new organization

In order to create a new organization you need to get to click on the big + sign in the upper right corner and choose New Organization.

Creating a new team inside an organization

1. First get into your organization page
   • Explore > Organizations > pick the organization
2. Click on the New Team on the right
   • configure your new team permissions

Some information about the configuration :

• its name which should be unique
• the Repository Access section allow you to configure:
  • whether the member can create or not new repositories in the Organization
  • whether the member will be able to interact with all repositories
    • a public repository is always at least readable. You need acces to the repository to modify it though.
• the permission section allow the team to be seen as administrator or to be subjected to the permissions described by the next section.
• the Allow Access to Repository Sections section allow you to give fine-grained permission in the repository the team has access to.

It is possible to modify a team permissions later, add users or add project (when in Specific Repositories mode) after creation :

• Explore > Organizations > pick the organization > Teams tab > pick the team
• the bottom left Settings will allow you to change the team permissions
• the members/repositories tabs on the right allow you to add respectively new users and repositories to the team.

creating new repository

1. First get into your organization page
   • Explore > Organizations > pick the organization
2. Click on the New Repository on the right
   • configure your new repository

Note: You can also use the big + sign in the upper right corner and choose New Repository, but remember to change the Owner field to the organization in which you cant to create the repository, otherwise you'll create a personal repository.

Some information about the configuration :

• A public repository will be seen by everyone, even when they are not part of the organization whereas a private one will only be accessible by member of the Organization with sufficient permission.
  • Administrator and team with all repositories access will see private repositories
  • Team with specific repositories access will need to have the repository added to their access list before it can be seen.
• When a user create a new repo he will be the only collaborator and only the team with all repositories access and its creator will be able to see it.
  • The repository will need to be manually added to the specific repositories teams access list (see below) to be seen by them.

It is possible to modify a repository access list (users/team) after creation :

• Explore > Organizations > pick the organization > Repositories tab > pick the repository
• Settings button on the upper right of the repository page > Collaborators
• You can add new users or team to the repository access list

Creating a new project

1. First get into your organization page
   • Explore > Organizations > pick the organization
2. Click on the Projects tab and then New Project

You can also create project limited to a repository by going in the repository page and then clicking on the Projects tab followed by New Project.

Associating a role to an organization

Note: You MUST have the admin role to perform this action as you need to be an administrative user.

1. First get into the administration page
   • Profile and Settings (upper right corner) > Site Administration
2. The go into the OIDC configuration
   • Identity & Access > Authentication Sources > pick the OIDC config
3. Locate the Map claimed groups to Organization teams configuration field
   • provide a new mapping

A json is expected where you assign for a given role the organization and its team that will be automatically associated with the SSO user. You must provide at least one team in an organization, a user cannot belong to an organization but not to one of its teams. By default, any team created has a Owners team with administrative permissions over the organization.

In the following exemple, any SSO user with the role admin will automatically be invited to the athea organization in the Owners team, but one with the role user will be invited to the athea organization in the Developpers team.

{
    "admin": {
        "athea": [
            "Owners"
        ]
    },
    "user": {
        "athea": [
            "Developpers"
        ]
    }
}

Providing a gitea role to a keycloak User

The available roles are the client role which have been defined in the keycloak client named 'gitea'.

In order to provide a role to a user, you need to associate one of the client role to a user in Keycloak. To do so you can either :

• Associate the client role to a realm role that is associated to your user. (indirect association)
• Associate the client role to a groups in which your user is. (indirect association)
• Associate the client role to your user directly. (direct association)