Gitea

​

What Oleria discovers

• Accounts - every user on the server, with username, full name, email, creation date, and last sign-in. Oleria also shows:
  • Status - a user is enabled when they’re active and not prohibited from signing in. Gitea refuses a suspended or inactive user’s sign-ins, tokens, and git access.
  • Account role - Site administrator, User, Restricted user, or Bot. Site administrators are marked as administrators.
  • MFA - on Gitea 1.26 or later, users enrolled in TOTP two-factor authentication show MFA as required, and other local users as not required. See Known limitations.
  • Single sign-on (SSO) - users who sign in through an authentication source configured in Gitea, such as LDAP or OAuth2, show SSO as required, with their login name. Local users show SSO as not configured.
  • An Anonymous (not signed in) account, which Oleria adds to stand for visitors who aren’t signed in.
• Groups - every organization, and every team in each organization, with the team’s organization, permission, and per-unit permissions. Each organization’s Owners team is marked as built in. Oleria also adds two groups, All signed-in users and All signed-in non-restricted users, to show who gets access from a repository’s visibility. The members of an organization’s Owners team are shown as the people who manage the organization and each of its teams.
• Roles:
  • Site administrator - held by every site administrator, with owner access to every repository and organization.
  • Owner of organization - one per organization, held by the members of its Owners team, and by any team with owner permission.
  • Team admin access, Team write access, and Team read access - held by the teams with that permission. A team with per-unit permissions holds none of these: its unit levels appear on its repository access instead.
• Memberships - which users belong to which teams, which teams belong to which organizations, and who holds each role. Gitea has no organization membership outside teams.
• Resources - every repository on the server, with its visibility, owner, and whether it’s archived, a mirror, a fork, a template, or empty. Each organization also appears as a resource that contains its repositories. A repository’s owner, or its organization’s owners, are shown as the people who manage it.
• Repository access - one access entry for each way someone can reach a repository, with the level it grants:

  Access path	Who	Level
  Owner	The user who owns a repository in their own namespace	Owner
  Organization owners	The organization’s Owners team, on every repository of the organization	Owner
  Team	Each team that holds the repository, including teams with access to all the organization’s repositories	The team’s permission (read, write, or admin). For a team with per-unit permissions, its level on each unit enabled on the repository, such as code, issues, or pull requests.
  Direct collaborator	Each user or bot added as a collaborator on the repository	The collaborator’s own level (see below)
  Visibility	Anonymous (not signed in) and All signed-in users for public repositories, or All signed-in non-restricted users when the server requires sign-in to view. All signed-in non-restricted users for repositories of a limited-visibility owner. The organization’s own group for public repositories of a private organization.	Read
  Site administrator	The Site administrator role, on every repository	Owner
  Deploy key or token	Each deploy key or deploy token on the repository	Write, or read for a read-only key

  Gitea’s API doesn’t return a direct collaborator’s own level, only their effective level. When a team or site administrator grant hides it, Oleria shows the collaborator at read, as a lower bound, and the team or role entry shows the real access. To find out whether the server requires sign-in to view, Oleria makes one request to the server without credentials.
• Non-human identities (NHIs):

  Identity	Shown as
  Bots	Service account. Gitea has bot users from Gitea 28.
  SSH keys	SSH key, with its owner, title, key type, fingerprint, creation date, last use, and whether it’s read-only.
  Access tokens	Personal access token (PAT), with its owner, scopes, creation date, and last use. Needs the optional Admin username and Admin password (see Optional settings).
  OAuth2 applications	Application, with its owner, client ID, redirect origins, and creation date. A confidential client also shows its client secret as a credential. By default, only the OAuth2 applications of the connection’s own user appear. See Optional settings.
  Actions runners	System identity, with its labels, status, and whether it’s ephemeral or disabled. A runner registered to one organization shows that organization as its owner.
  Webhooks	Application, for system and default webhooks, organization webhooks, and repository webhooks, with its events, branch filter, and target. Oleria keeps only the target’s scheme, host, and port.
  Deploy keys and deploy tokens	SSH key or API token, scoped to its repository, with read or write access. Gitea has deploy tokens from Gitea 28.
  Actions secrets	Secret, for organization and repository Actions secrets, by name only. Oleria never reads secret values.

  SSH keys and access tokens of a user who is suspended or inactive show as disabled, because Gitea refuses them. Each SSH key, access token, deploy key or token, and secret also appears as a credential, and so does a confidential OAuth2 application’s client secret. A user’s SSH keys, access tokens, and OAuth2 applications show that user as their owner.
• Activity - repository events from each user’s activity feed, attributed to the user who performed them and linked to the repository: pushes, tags, branch deletions, mirror syncs, issues and comments, pull requests opened, closed, reopened, merged, and reviewed, releases, repositories created, renamed, and transferred, and stars and watches. Every event keeps its Gitea event name. Oleria doesn’t store commit messages or comment text.

​

Prerequisites

• A Gitea server running Gitea 1.24 or later, reachable from the internet over HTTPS on port 443, by a host name that resolves to a public IP address. IP addresses, other ports, and on-premises agents aren’t supported.
• The server’s host on Oleria’s egress allowlist. Before you connect, contact support@oleria.com with the server’s host name, such as gitea.example.com, and ask for it to be allowlisted.
• A Gitea site administrator, to create a dedicated administrator account for Oleria and its access token. Oleria needs a site administrator’s token to read every user, organization, and repository. Shared hosted services where you aren’t a site administrator, such as gitea.com and Codeberg, can’t be connected.
• Optional: the server’s TLS certificate, or the CA certificate that issued it, in PEM format, if the server doesn’t use a publicly trusted certificate. Oleria always verifies the server’s certificate.
• Admin access on the Oleria platform to add a new integration.

​

Create the Oleria account and access token in Gitea

​

Optional settings

• Access token inventory and revocation. Gitea lists and deletes other users’ access tokens only for a request signed in with a username and password. It refuses an access token for this, even a site administrator’s. To discover access tokens, and to revoke them with Disable NHI accounts, enter the username and password of a site administrator in Admin username and Admin password. That administrator must not use two-factor authentication, and Basic authentication (ENABLE_BASIC_AUTHENTICATION) must be enabled on the server. Oleria uses the password only to list and revoke access tokens, and uses the access token for everything else. Without it, access tokens don’t appear, and Oleria can’t revoke them.
• OAuth2 applications of every user. Gitea lists a user’s OAuth2 applications only to that user. To discover the OAuth2 applications of every enabled user, select Inventory OAuth2 apps of all users (Sudo). Oleria then reads each user’s applications by acting as that user with Gitea’s Sudo header, one request per user on every sync. On Gitea 28 with audit logging turned on, each request writes an impersonation event to Gitea’s audit log. Without it, only the connection’s own user’s OAuth2 applications appear.

​

Connect Gitea to Oleria

• Gitea rejected the access token (HTTP 401) - check the token, and that its user isn’t suspended.
• The token’s user … must be a Gitea site administrator - make the token’s user a site administrator, or generate the token as a site administrator.
• Gitea denied the request (HTTP 403) - the message gives Gitea’s reason. Usually the token lacks a scope Oleria needs, so generate a token with read:admin, read:organization, read:user, and read:repository. Gitea also returns this when the token’s user is prohibited from signing in.
• Gitea refused the token’s user (HTTP 403) - Gitea refused the request for another reason, given in the message.
• The access token has the public-only scope - generate a token with access to all repositories, not public only.
• The access token lacks scopes - generate a token with read:admin, read:organization, read:user, and read:repository.
• Gitea refused the admin username and password - check the username and password. Basic authentication may be disabled on the server, or the administrator may use two-factor authentication.
• Forgejo is not supported by the Gitea connector yet - the server runs Forgejo. Forgejo isn’t supported.
• Gitea … is not supported; the connector needs Gitea 1.24 or later - upgrade the server, then try again.
• Gitea API not found (HTTP 404) - check that Gitea URL is the server’s ROOT_URL, including any sub-path.
• The Gitea server’s TLS certificate is not trusted - paste the server’s certificate or its issuing CA certificate into Trusted certificate (PEM), or install a publicly trusted certificate on the server.
• Gitea server … is not reachable from Oleria - check that the server is reachable over public HTTPS on port 443 by host name, and that Oleria support has added its host to the egress allowlist. This message also appears when the server’s certificate has expired.
• Gitea URL should be https://… on port 443 on the form, or Hostname resolves to private or loopback IP - enter the server’s https address by host name, on port 443. The host name must resolve to a public IP address.
• trustedCertificatePem must be one PEM-encoded CERTIFICATE block, must hold exactly one certificate, or is not a valid certificate - paste exactly one certificate, with nothing else, such as a private key or a second certificate.

​

Edit the integration

• Leave Access token or Admin password blank to keep the stored value.
• Clear Admin username to stop discovering and revoking access tokens. Clear Trusted certificate (PEM) to remove the stored certificate.

​

Verify the integration

​

Remediation actions

• Oleria refuses to suspend, remove from a team or organization, remove a role from, or remove as a collaborator the user this integration connects as, and the user in Admin username. It also refuses to revoke the access token this integration uses. If it can’t identify its own user or token, it refuses rather than risk cutting off its own access. Deleting their SSH keys is allowed, because SSH keys don’t carry Oleria’s API access.
• Oleria refuses to remove an organization’s last owner, from the Owners team or from the organization. Gitea also refuses to remove the last site administrator.
• Add user to group and Remove user from group refuse the Owners team, because it grants organization ownership. Use Add user to role or Remove user from role with Owner of organization instead. Add user to group also refuses an organization, because Gitea has no organization membership outside teams: add the user to one of its teams.
• Add user to role and Remove user from role accept only Site administrator and Owner of organization. The team access roles describe what teams grant: add the user to a team instead.
• Revoke permission to resource instance works only for a direct collaborator. If the user isn’t one, the message names where their access comes from: owning the repository, being a site administrator, a team, or the repository’s visibility. If a team or site administrator grant hides the collaborator’s own level, Oleria refuses, because it couldn’t add them back at the same level. Change it in Gitea.
• Remove access for external accounts refuses an account that isn’t external: an unrestricted user on a personal repository, or an unrestricted member of the repository’s organization. Use Revoke permission to resource instance instead. Otherwise it has the same limits as Revoke permission to resource instance.
• Create group refuses the name Owners, and fails without creating anything if a team with the same name, ignoring upper and lower case, already exists in the organization.
• The All signed-in users, All signed-in non-restricted users, and Anonymous (not signed in) entries are added by Oleria, so actions on them are refused.
• If the user, team, membership, or NHI is already in the state the action asks for, Oleria makes no change, and reverting the action makes no change either. A target that no longer exists fails the action, because Oleria can’t tell it apart from a wrong ID.
• After each change, Oleria reads the target again. If the read doesn’t show the change, the action fails and says the change wasn’t confirmed: check the target in Gitea.
• Reverting an action changes only what the action changed. If the target has changed since, or no longer exists, the revert makes no change and says why.

​

Known limitations

• No sign-in, permission-change, or audit events. Activity comes from users’ activity feeds, which record repository events only. Gitea’s audit log has no API that accepts a token, so sign-ins, failed sign-ins, membership and permission changes, and token and key changes don’t appear as activity. Gitea Enterprise’s audit log export isn’t used.
• Last activity is the last interactive sign-in. Gitea updates a user’s last sign-in when they sign in, not when they use an access token, an SSH key, or git. Newer events in their activity feed don’t change it.
• No password change date. Gitea’s API doesn’t report when a user last changed their password.
• MFA is TOTP only. Gitea’s API reports only TOTP enrollment, from Gitea 1.26. A user who uses only WebAuthn security keys shows MFA as not required. Before Gitea 1.26, and for users from an authentication source, MFA shows as unavailable.
• Authentication sources aren’t discovered. Gitea manages LDAP, OAuth2, and other authentication sources only in its web interface and command line, so Oleria shows only each user’s source ID and login name.
• Access tokens need a password. Without Admin username and Admin password, access tokens don’t appear and can’t be revoked.
• OAuth2 applications. Without the Sudo option, only the connection’s own user’s OAuth2 applications appear. Organization and instance-wide OAuth2 applications have no API, so they never appear.
• Secrets and variables. Actions secrets appear by name only. Actions variables don’t appear, because Gitea returns their values when they’re listed. Runner registration tokens are never requested.
• Direct collaborator levels. When a team or site administrator grant hides a direct collaborator’s own level, the collaborator shows read access, as a lower bound, and Revoke permission to resource instance refuses them.
• Activity history. When you connect, Oleria reads up to 30 days of activity, one request per user per day, so the first activity sync of a large server can take a while. Gitea’s feeds filter by day in the server’s time zone, which Oleria learns from the newest user’s creation time. Oleria reads a little more than each day, so a daylight saving change can’t hide events.
• Some actions aren’t available. Oleria can’t change a collaborator’s level, remove a team’s access to a repository, make a repository private, create or delete users, or end a user’s sessions. Creating and deleting users and making a repository private are left out on purpose. Gitea has no API to end sessions. Disabling a user stops every request they make.
• Actions job tokens aren’t shown. Gitea creates one for each workflow job, and it’s valid only while the job runs.
• Version-dependent data. MFA and disabling runners need Gitea 1.26 or later. Checking the token’s scopes needs Gitea 1.27 or later. Bots and deploy tokens exist from Gitea 28.
• Network access. Oleria connects only over public HTTPS on port 443, to a server host that Oleria support has added to the egress allowlist. Each server’s host is allowlisted separately, and there’s no on-premises agent option. Oleria paces its requests to each server, so the first sync of a server with many repositories can take a while.

​

Contact us