# Bring your organization's Git provider

> Register your organization's own Gitea or Forgejo, so the organization's members connect to it and its teams' workspaces use it.

URL: https://docs.harthelm.dev/guides/organization-git-providers/ · Harthelm v1.6.1

Since 1.6.1 an organization can bring its own Gitea or Forgejo, next to the Git providers your installation offers.
Organization owners manage these providers; the organization's members then connect their own accounts to them, and
only the organization's teams can use them. Forgejo speaks Gitea's API, so both are the kind **Gitea / Forgejo**.

## Add a provider

**Console**

1. Open **Members**, switch to the **Organization** tab and find **Git providers**. Click
   **Add Git provider**.
2. Keep **Gitea / Forgejo** as the **Kind** and type an **ID**, for example `forge`: lower-case
   letters, digits and dashes, starting with a letter. The ID cannot be changed later. As soon as it is valid, the
   dialog shows the **Redirect URI** for it, `https://<console>/auth/git/forge-<suffix>/callback`.
   **Copy** it.
3. At your Gitea or Forgejo, create an OAuth2 application (**Settings** › **Applications**, for a user, an
   organization or the whole site) as a confidential client, with that redirect URI. The sign-in at the provider comes
   back to exactly this address and nowhere else.
4. Back in the dialog, fill in a **Name**, the provider's **URL** (`https://` only, for example
   `https://git.example.org`), the application's **Client ID** and **Client secret**. Only if the provider's
   certificate comes from a private CA, add that CA under **CA certificate (PEM, optional)**: paste it or
   **Load from file**. Click **Add**.

**hart**

```sh title="Terminal"
hart org git-providers redirect-uri forge --org Acme
```

prints the redirect URI. Create the OAuth2 application at your Gitea or Forgejo with it (a confidential client), save
its client secret to a file and register the provider:

```sh title="Terminal"
hart org git-providers add forge --org Acme --name "Acme Forge" \
  --url https://git.example.org --client-id <client id> --client-secret-file forge.secret
```

Without `--client-secret-file`, `hart` asks for the secret without echo, or reads it from stdin when it is piped; it
never takes the secret as an argument. `--ca-file ca.pem` adds a private CA. `--org` takes the organization's id or
exact name; without it, the organization of your current team. See [`hart org`](https://docs.harthelm.dev/reference/hart/org/).

The client secret and the CA are stored encrypted and never shown again, not even to you: the list says
**Secret set** and **Custom CA**.

## Addresses Harthelm refuses

Harthelm does not connect to every address, and says why under **URL** (in the API, 422
`git-provider-url-refused`):

- anything but `https://`;
- this machine: `localhost` and loopback addresses;
- link-local addresses, where cloud metadata services answer (`169.254.169.254`);
- names inside the cluster (`*.svc` and the cluster's domain) and names without a dot;
- private IP addresses typed as numbers (`10.0.0.5`).

A provider on your own network is registered by its DNS name; a name that resolves to a private address is allowed.
If your installation narrows where Harthelm may connect to, its administrator has to let your provider's address
through ([Git providers › An organization's providers](https://docs.harthelm.dev/self-hosting/configure/git-providers/#an-organizations-providers)).

## Members connect

Members of the organization connect their own account like any other: **Account settings** ›
**Git connections**, where the provider shows with the organization's name
([Start from a repository](https://docs.harthelm.dev/guides/start-from-a-repository/#connect-your-git-account)). **Create workspace** and
**Git access** offer it as `<name> · <organization>`, to the organization's teams only. Members of other
organizations do not see it.

## Change or retire a provider

**Edit** changes the name, URL, client ID, secret or CA (**Replace client secret**, **Remove CA**).
A URL on another host needs the client secret again and disconnects every member: their tokens belong to the old host.

**Retire** disconnects everyone, and the workspaces lose access to the provider's repositories while their files
stay. Adding the same ID again brings it back. Running workspaces of the organization's teams see an added, retired or
moved provider within about 10 minutes.

Only owners of the organization (and cluster admins) manage its providers; other members get "forbidden" (`hart`
exit 4), people outside the organization "not found" (exit 5).