> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/go-gitea/gitea/llms.txt
> Use this file to discover all available pages before exploring further.

# Organizations

> Learn how to create and manage organizations in Gitea

Organizations in Gitea allow multiple users to collaborate across many repositories at once. Organizations provide a way to group users into teams with different levels of access to repositories.

## What is an Organization?

An organization is a shared account where groups of users can collaborate on projects. Organizations have:

* **Multiple owners and members** - Organizations can have multiple users with different permission levels
* **Teams** - Group users with specific access rights to repositories
* **Centralized repository management** - All repositories belong to the organization
* **Visibility controls** - Public, limited, or private visibility

## Creating an Organization

To create a new organization:

1. Click the **+** icon in the top navigation bar
2. Select **New Organization**
3. Fill in the organization details:
   * **Organization Name** - Must be unique and follow naming rules
   * **Visibility** - Choose how the organization appears to others
   * **Repository Admin Change Team Access** - Allow repository admins to modify team access

<Note>
  Users must have permission to create organizations. This is controlled by the `DEFAULT_ALLOW_CREATE_ORGANIZATION` setting in your Gitea configuration.
</Note>

### Organization Creation Code Example

Here's how organizations are created in Gitea:

```go theme={null}
// CreateOrganization creates record of a new organization.
func CreateOrganization(ctx context.Context, org *Organization, owner *user_model.User) (err error) {
    if !owner.CanCreateOrganization() {
        return ErrUserNotAllowedCreateOrg{}
    }

    org.LowerName = strings.ToLower(org.Name)
    org.MaxRepoCreation = -1
    org.NumTeams = 1
    org.NumMembers = 1
    org.Type = user_model.UserTypeOrganization

    return db.WithTx(ctx, func(ctx context.Context) error {
        // Insert organization
        if err = db.Insert(ctx, org); err != nil {
            return fmt.Errorf("insert organization: %w", err)
        }

        // Add initial creator to organization
        if err = db.Insert(ctx, &OrgUser{
            UID:      owner.ID,
            OrgID:    org.ID,
            IsPublic: setting.Service.DefaultOrgMemberVisible,
        }); err != nil {
            return fmt.Errorf("insert org-user relation: %w", err)
        }

        // Create default owner team
        t := &Team{
            OrgID:                   org.ID,
            Name:                    OwnerTeamName,
            AccessMode:              perm.AccessModeOwner,
            NumMembers:              1,
            IncludesAllRepositories: true,
            CanCreateOrgRepo:        true,
        }
        return db.Insert(ctx, t)
    })
}
```

Source: `models/organization/org.go:284-376`

## Organization Visibility

Organizations support three visibility levels:

<CardGroup cols={3}>
  <Card title="Public" icon="globe">
    Visible to everyone, including anonymous users
  </Card>

  <Card title="Limited" icon="users">
    Visible only to authenticated users
  </Card>

  <Card title="Private" icon="lock">
    Visible only to organization members
  </Card>
</CardGroup>

### Changing Organization Visibility

When you change an organization's visibility, it affects:

* All organization repositories
* Repository access permissions
* Issue indexing
* Fork visibility (cascades to all forks)

```go theme={null}
func ChangeOrganizationVisibility(ctx context.Context, org *org_model.Organization, visibility structs.VisibleType) error {
    if org.Visibility == visibility {
        return nil
    }

    org.Visibility = visibility
    return db.WithTx(ctx, func(ctx context.Context) error {
        if err := user_model.UpdateUserColsNoAutoTime(ctx, org.AsUser(), "visibility"); err != nil {
            return err
        }

        // Update all organization repositories
        repos, _, err := repo_model.GetUserRepositories(ctx, repo_model.SearchRepoOptions{
            Actor: org.AsUser(), Private: true, ListOptions: db.ListOptionsAll,
        })
        if err != nil {
            return err
        }
        for _, repo := range repos {
            if err := updateOrgRepoForVisibilityChanged(ctx, repo, visibility == structs.VisibleTypePrivate); err != nil {
                return fmt.Errorf("updateOrgRepoForVisibilityChanged: %w", err)
            }
        }
        return nil
    })
}
```

Source: `services/org/org.go:145-170`

## Organization Members

Organization members are users who belong to at least one team in the organization.

### Member Visibility

Members can choose to make their membership:

* **Public** - Visible on the organization's member list
* **Private** - Only visible to other organization members

The default visibility is controlled by the `DEFAULT_ORG_MEMBER_VISIBLE` setting.

### Adding Members

Members are automatically added to the organization when they join a team:

```go theme={null}
// AddOrgUser adds new user to given organization.
func AddOrgUser(ctx context.Context, orgID, uid int64) error {
    isAlreadyMember, err := IsOrganizationMember(ctx, orgID, uid)
    if err != nil || isAlreadyMember {
        return err
    }

    return db.WithTx(ctx, func(ctx context.Context) error {
        ou := &OrgUser{
            UID:      uid,
            OrgID:    orgID,
            IsPublic: setting.Service.DefaultOrgMemberVisible,
        }

        if err := db.Insert(ctx, ou); err != nil {
            return err
        }
        _, err = db.Exec(ctx, "UPDATE `user` SET num_members = num_members + 1 WHERE id = ?", orgID)
        return err
    })
}
```

Source: `models/organization/org.go:495-521`

## Managing Organization Settings

Organization owners can configure:

* **Profile** - Avatar, description, location, website
* **Repositories** - Default repository settings
* **Webhooks** - Organization-wide webhooks
* **Labels** - Organization-wide labels
* **Packages** - Package registry settings
* **Runners** - CI/CD runner configuration
* **Secrets** - Organization-wide secrets for actions

## Deleting an Organization

<Warning>
  Deleting an organization is permanent and cannot be undone. All repositories, teams, and data will be deleted.
</Warning>

Before deletion:

1. All repositories must be transferred or deleted
2. All packages must be removed
3. Only organization owners can delete the organization

```go theme={null}
// DeleteOrganization completely and permanently deletes everything of organization.
func DeleteOrganization(ctx context.Context, org *org_model.Organization, purge bool) error {
    return db.WithTx(ctx, func(ctx context.Context) error {
        if purge {
            err := repo_service.DeleteOwnerRepositoriesDirectly(ctx, org.AsUser())
            if err != nil {
                return err
            }
        }

        // Check ownership of repository
        count, err := repo_model.CountRepositories(ctx, repo_model.CountRepositoryOptions{OwnerID: org.ID})
        if err != nil {
            return fmt.Errorf("GetRepositoryCount: %w", err)
        } else if count > 0 {
            return repo_model.ErrUserOwnRepos{UID: org.ID}
        }

        // Check ownership of packages
        if ownsPackages, err := packages_model.HasOwnerPackages(ctx, org.ID); err != nil {
            return fmt.Errorf("HasOwnerPackages: %w", err)
        } else if ownsPackages {
            return packages_model.ErrUserOwnPackages{UID: org.ID}
        }

        return deleteOrganization(ctx, org)
    })
}
```

Source: `services/org/org.go:54-103`

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Who can create organizations?">
    Users who have the `CanCreateOrganization` permission. This is controlled by:

    * Server configuration (`DEFAULT_ALLOW_CREATE_ORGANIZATION`)
    * User-specific permissions set by administrators
  </Accordion>

  <Accordion title="What's the difference between an organization and a user?">
    Organizations:

    * Cannot sign in directly
    * Have multiple owners
    * Support teams with granular permissions
    * Are designed for collaborative work

    Users:

    * Can sign in and perform actions
    * Own their own repositories
    * Can belong to multiple organizations
  </Accordion>

  <Accordion title="How many owners can an organization have?">
    An organization can have multiple owners. All owners have equal permissions and can:

    * Manage all teams and members
    * Access all repositories
    * Modify organization settings
    * Delete the organization

    However, at least one owner must remain - you cannot remove the last owner.
  </Accordion>

  <Accordion title="Can I transfer repositories to an organization?">
    Yes, repository owners can transfer their repositories to any organization where they have permission to create repositories. The transfer is immediate and includes all issues, pull requests, and history.
  </Accordion>

  <Accordion title="What happens to forks when organization visibility changes?">
    When you change an organization's visibility, the change cascades to all repositories and their forks. Making an organization private will:

    * Make all organization repositories private
    * Update access permissions
    * Remove stars from repositories
    * Update the issue indexer
  </Accordion>
</AccordionGroup>

## Related Resources

* [Teams](/users/teams) - Learn about managing teams within organizations
* [Permissions](/users/permissions) - Understand the permission model
* [Repository Management](/repositories/overview) - Managing organization repositories