Organizations and teams

Provider and source authority

This portable contract describes its linked source snapshot. For current deployment instructions, use current installation, authentication and native Cloudflare guides. Historical receipts do not verify later builds.

Golf shows your Forgejo organization memberships, visible teams, team members and accessible assigned repositories on either infrastructure track. Native organization owners can also add/remove existing accounts in non-owner teams through the bounded browser workflow below. Team creation, invitations, grant editing, owner-team changes and normalized Golf organization roles remain planned.

Open an organization

1. Sign in with a token containing read:user and read:organization, or use configured Forgejo OAuth with the expanded organization scope. For an older OAuth grant without that scope, revoke the existing Forgejo grant and start fresh consent; refreshing a session or repeating sign-in does not upgrade it.
2. Choose Organizations in the workspace header. Load further pages to inspect more memberships. Counts describe loaded visible results, not total membership.
3. Open an organization to read its description and provider visibility, then select a team to inspect its native permissions, members and repositories.
4. Open an assigned repository to use the existing source browser. That operation separately checks repository/code access and needs read:repository.

The list uses /organizations; a detail uses /organizations/:organization, with ?team=:id selecting a team. Links support direct navigation, reload and back/forward history. A team ID from another organization does not grant access through the selected organization.

An empty team-repository page may still offer another page: the provider can remove inaccessible assignments after calculating pagination. Continue when the page reports more results. Golf does not display the provider's unfiltered assignment total or invent rows to fill a page.

Manage an existing non-owner team

Choose Team settings from a team, then Add member to resolve an existing username and review its immutable identity and the team's native grants before adding it. Removal requires explicit confirmation. The settings walkthrough covers the editor, refresh and uncertain-outcome behavior.

OrganizationAdminService adds four browser-session procedures: GetTeamAdministration, ResolveTeamMember, AddTeamMember and RemoveTeamMember. Viewing requires current organization membership. Mutation/candidate lookup requires verified native organization ownership and a suitable scoped credential; a Golf instance role, site-admin visibility or read:organization alone does not grant write authority. The ordinary browser OAuth read grant is not silently widened by this feature. Owner teams and owner-valued unit grants remain locked.

The native authority, team revision and resolved user identity are checked around the write, with separate membership readback. These checks do not provide atomic native CAS, freeze repository assignments or eliminate username-addressed mutation races. A lost response may follow a completed change; inspect refreshed membership before another action. Removing one team membership does not remove independent grants. No durable membership journal or automatic write retry is provided. See the administration API contract for fields and the product contract for qualification and exclusions.

The six existing organization/team reads remain unchanged. CLI and local MCP tools expose those reads, not the new browser administration procedures; delegated API credentials are denied access to the administration service.

Inspect memberships from the CLI

The read-only CLI provides org list, org view, org teams, team view, team members and team repos. Supply a scoped PAT through GOLF_FORGE_TOKEN from your secret manager or the global --token-stdin option. The CLI does not reuse browser OAuth or retain credentials; each invocation signs into Golf, makes its read and logs out before writing a successful result.

# Replace acme with your organization and 123 with a returned team ID.
./bin/golf org list --page 1 --limit 20
./bin/golf org teams acme --page 1 --limit 20
./bin/golf team repos acme 123 --page 1 --limit 20

Use data.page.nextPage for the next explicit --page, even when the current repository page is empty. Team IDs stay decimal strings. The same membership, native-visibility and repository-access boundaries apply to all six commands.

Read provider permissions accurately

Organization and team visibility labels describe native Forgejo settings. Private teams are visible to their members or organization owners; limited teams to organization members; public teams to signed-in users. Golf's organization page additionally requires actual organization membership. A public label does not make that page public.

The team permission, per-unit grants and “all repositories” setting are observations from Forgejo. They are not a calculated Golf role or a promise that every listed repository permits every operation. For example, the legacy permission may be none while repo.code grants write. Multiple team memberships can combine, so removing one grant may leave another valid route to access.

The role qualification also records native limits: issue-read permits some collaboration writes, repository admin includes deletion, and an owner count does not establish account recovery. Golf has not implemented a stricter viewer, maintainer or recoverable-owner policy.

Denial and changes

Every read verifies the live provider user against the immutable identity stored in the Golf session. Detail and nested reads check actual membership before and after their provider calls. Public metadata, administrator visibility and a valid foreign team ID cannot substitute for membership. Missing scope returns a permission error; a missing or inaccessible organization/team remains denied. Forgejo can return permission denied for a hidden private team and not found for a missing organization or foreign team binding; neither is a successful empty result. Broader credentials cannot make a nonmember a member.

Refresh, loading and failed requests hide previous private content. Closing a view discards its private query data; sign-out or session expiry clears private application queries. Descriptions and user names remain plain text. Membership can change between calls, and revocation does not cancel an already-authorized response.

The six organization API procedures expose the same reads to generated clients. The CLI exposes those same six reads with explicit pagination. No AI or Cloudflare service is required. See the product's organization contract and implementation status for the verified scope.

Owner-issued Golf API credentials also support these reads through GOLF_API_TOKEN or --api-token-stdin, without temporary sign-in/sign-out. The PAT-mode lifecycle above remains available. Native scopes and permissions still govern access.

Organization creation ceiling

Golf now has an explicit organization creation flow and a separate administrator-managed ceiling at /admin/organizations: administrator-only, selected enrolled users or all users. Requests remain subject to the caller’s current native permission; Golf does not borrow a global native credential. The policy governs Golf’s own API, not independently exposed native routes. Existing native ownership still governs ordinary team membership and organization execution settings. The full delegated-role/invitation/team-grant system remains planned.