Members and teams

Roles

Every org member has exactly one org-level role.

An org must have at least one Owner at all times. You cannot remove or demote the last Owner.

Inviting members

Member management lives in the fremforge admin UI at /<org>/_admin/members — the Members page lists every current member with per-member Manage drawers and an Invite dialog at the top. Forgejo’s native frem.sh/org/<org>/teams page remains available as a fallback when you need to compose finer-grained team permissions; the in-product page covers the day-to-day invite / role / remove flow.

1. Go to Org admin → Members (/<org>/_admin/members).
2. Click Invite member.
3. Enter the invitee’s username or email address and pick a role.
4. Click Send invitation.

The invitee receives an email from noreply@frem.sh with an accept link. The link is valid for 72 hours (Forgejo-managed). If it expires, re-send it from the Pending invitations section on the same page.

In the Pending invitations section, the invitee appears as Pending until they accept. Pending members:

• Cannot access any org resource.
• Do not count as a billable seat until they accept the invitation.
• Can be cancelled at any time by removing them from the team while still pending.

Once the invitee accepts, their status changes to Active and they are added to the billable seat count at the next billing cycle. Activity is not required, acceptance is what counts.

Free readers (read-only, no billable seat)

A Reader has read-only access to the repositories they’re granted — clone, browse code, read issues and pull requests — but cannot push, create repositories, or reach org admin settings. Readers are free: they do not count against your seat cap and are never billed. Add as many as you like — auditors, stakeholders, contractors who only need to look, read-only dashboards, and so on.

Under the hood a Reader is simply a member of the org’s canonical Viewers team and of no paid team. Seat counting is only the paid teams: a person is billed when they belong to Members or Owners; belonging only to Viewers is free. (If you add someone to Viewers and Members, they are billed — the paid membership wins.)

Add a reader

Any of these work; the in-product path is the simplest:

1. From the Members page (recommended). Go to Org admin → Members (/<org>/_admin/members) → Invite member → enter the email → in Team(s), select Viewers (and nothing else) → Send invitation. When they accept, they join as a free reader.
2. Convert an existing member. Open the member’s Manage drawer and move them to Viewers (remove them from Members/Owners). They drop out of the billable seat count at the next billing cycle.
3. Automatically via SSO. Map an identity-provider group to the Viewers team (see SSO and SCIM). Everyone in that group is provisioned as a free reader — no per-person invite needed.
4. Forgejo-native fallback. frem.sh/org/<org>/teams → Viewers → Add team member. Use this only when you need finer team composition; the Members page covers the normal case.

Free readers are counted separately from paid seats in your billing summary (Org admin → Billing) and in the seats API, so you can always see how many free readers you have versus how many billable seats you’re using.

Not the same as a docs-only reader. If you want someone who can read your published docs but has no repository access and no Forgejo account at all, don’t add them to Viewers — instead give their SSO group an empty group→team mapping. See Wiki and public docs. A Reader (Viewers team) does get a Forgejo account and read access to granted repos; a docs-only reader does not.

When seats are full

If your org has reached its seat cap, a member who tries to access the org is shown a “seats full” page at /<org>/seats-full instead of the resource they requested. From that page they can send a one-click request to the org’s owners to add a seat.

Owners receive that request (by email and in the admin notifications bell) and can add a seat from Org admin → Billing, which clears the block for the waiting member. Raise the seat cap before the member can proceed; until then their access stays paused at the seats-full page.

Changing roles

A member’s role (Owner, Member, or Reader) is changed in-product from the Manage drawer on the Members page. Under the hood the role maps to Forgejo team membership: Owners = full org admin, Members = scoped read/write access defined by the team’s repo grants, Viewers = read-only (and free). Moving a member into Viewers-only drops them from the billable seat count at the next billing cycle.

1. Go to Org admin → Members (/<org>/_admin/members).
2. Open the Manage drawer for the member.
3. Pick the new role and confirm. The matching Forgejo team change is applied immediately.

For finer team composition (custom teams, repo-scoped grants) use the Forgejo-native team page at frem.sh/org/<org>/teams. Role changes take effect immediately. There is no grace period or confirmation email sent to the member.

Removing a member

1. Go to Org admin → Members (/<org>/_admin/members).
2. Open the Manage drawer for the member and choose Remove member.
3. Confirm the removal.

What happens immediately:

• Access to all org repositories is revoked.
• Any active sessions (browser or API) for that user are invalidated.
• The member is removed from any team assignments within the org.

What does not change:

• Repositories are not deleted. Repos belong to the org, not to individual members. A member who owned repos in the org does not take those repos when they leave.
• Issues, PRs, and commits remain attributed to their username. Historical contribution records are preserved.
• Open PRs and issues they authored remain open and unmodified.

The removed member is taken out of the billable seat count at the next billing cycle. There is no credit for the current period.

Offboarding checklist

When a member leaves the org, run through this checklist before completing the removal.

• Transfer repository ownership if the departing member owns any repos directly (check Org admin → Repositories for repos with their username as owner). Transfer to the org or to another member before removing them.
• Rotate secrets they may have known. Check which secrets were created or last updated while they had access. Rotate any that are now exposed by their departure.
• Revoke API tokens they created. Go to Org admin → API tokens (/<org>/_admin/api-tokens) to see all org API tokens. Revoke any token created by the departing member.
• Check for personal access tokens (PATs). PATs are tied to the user’s account, not the org. Once removed from the org, their PATs can no longer access org resources. But if the departing member was an Owner, confirm no tokens with elevated scopes were shared with external systems under their name.
• Review active integrations and webhooks. If any webhook or external integration is authenticating as this user, update it to use an org API token or another account.

SCIM-managed deprovisioning

If SCIM provisioning is configured for the org, user lifecycle is managed by the connected IdP (Okta, Entra ID, etc.). Deactivating or removing a user in the IdP deactivates them in fremforge automatically within the SCIM sync interval, which is typically under five minutes.

When a user is deactivated via SCIM:

• Their fremforge session is invalidated immediately.
• They cannot sign in via SSO or local password.
• Their seat is removed from the billable count at the next billing cycle.

Manual removal via Org admin → Members is not required when SCIM is active. The IdP is the source of truth for membership. Removing a user in fremforge without deactivating them in the IdP will cause SCIM to re-provision them on the next sync.

See SCIM provisioning for setup instructions.

SSO-only members

A member who has only ever signed in via SSO has no local fremforge password. Their identity is entirely controlled by the IdP.

To block a SSO-only member’s access:

1. Revoke their access in the IdP (deactivate the account, remove from the app assignment, or disable SSO for their account).
2. Optionally remove them from the org in fremforge to clean up the seat count.

Revoking IdP access alone is sufficient to prevent sign-in. The fremforge session will fail at the next SSO validation check. If SCIM is enabled, the IdP deactivation also triggers automatic deprovisioning without the manual org removal step.

Re-inviting a former member

To re-invite someone who was previously removed, send them a fresh invitation from Org admin → Members → Invite member as normal.

When they rejoin:

• Previous commits, issues, and PRs remain attributed to their username.
• Repository access is determined freshly by org role and any repo-level collaborator assignments. No previous access configuration is automatically restored.

If the former member deleted their fremforge account after leaving, their username may show as a deleted-account indicator on historical contributions. If a different person has taken that username in the interim, historical attribution reflects the original account via the underlying user ID, not just the username string.

Per-repository permissions

Org-level roles determine baseline access. For finer-grained control, you can add individual users as collaborators on specific repositories.

Add a collaborator:

1. Go to Repository → Settings → Collaborators.
2. Search for the user by username or email.
3. Select a permission level:

Collaborator permissions are additive on top of the user’s org role, not a replacement. A Member with Write collaborator access on a repo can push to that repo. An Owner collaborator has no additional effective permissions beyond what the Owner org role already grants.

Collaborators do not need to be org members. You can add external users (with a fremforge account) as collaborators on individual repositories without inviting them to the org. External collaborators count as a billable seat for the org that adds them, same flat €30/seat/month rate, counted on assignment regardless of activity.

Via REST API

The day-to-day member-lifecycle flow (invite / list / revoke / remove) is available on the public API surface. Use this when scripting onboarding from an HRIS, automating offboarding, or driving operations from an AI agent.

• List invitations GET /api/v1/orgs/:slug/members/invitations?status=pending (scope seats:read)
• Invite a member POST /api/v1/orgs/:slug/members/invitations body: { "email": "...", "full_name": "...", "team_names": [...] } (scope seats:write)
• Revoke a pending invitation DELETE /api/v1/orgs/:slug/members/invitations/:id (scope seats:write)
• Remove a member DELETE /api/v1/orgs/:slug/members/:login (scope seats:write)
• Grant / dismiss a seat hold POST /api/v1/orgs/:slug/members/seat-holds/:id/grant or .../dismiss (scope seats:write)

Requires a Personal Access Token (PAT) with the seats:write scope:

curl -X POST \
  -H "Authorization: Bearer ${FREMFORGE_PAT}" \
  -H "Content-Type: application/json" \
  -d '{"email":"new.hire@example.com","full_name":"New Hire","team_names":["engineering"]}' \
  https://frem.sh/api/v1/orgs/acme/members/invitations

See the public REST API reference for the full OpenAPI specification.

Cross-references

• SCIM provisioning, automated user lifecycle via Okta, Entra ID, or any SCIM 2.0-compliant IdP
• OIDC SSO, configure SSO so members sign in with their corporate identity
• Billing, how seats are counted and when removed members leave the billable count
• Org admin, full reference for the org admin surface
• API, manage members programmatically via the REST API