Forge API and Git access

Forge accepts several credentials for Git clients, scripts and CI jobs. This page is for developers who clone and push from a terminal, call the Forge REST API, or log in to the registry. For the Orbit API, see API authentication.

Credentials at a glance

Credential	Use it for
Project access token (`ofp_...`)	Git over HTTPS, Forge REST requests, Git LFS, container registry login and package uploads
SSH key	Git over SSH
`CI_JOB_TOKEN`	Package registry, container registry and releases from a running job
Orbit session	The web application, and everything that needs a signed-in person

Personal API tokens (opt_...) belong to the Orbit API and are not Forge credentials.

Project access tokens

Create a project access token for the repository in Forge. Forge shows it once and stores only a hash.

Scope	Allows
`read_repository`	Clone and fetch over HTTPS
`write_repository`	Push over HTTPS
`read_api`	Read-only Forge REST requests, acting as a viewer
`api`	Forge REST requests under your current role

A token lives 1 to 365 days. The list shows when it was last used.
A token works only in its own project, even if its owner is a global administrator, and always under the owner’s current role.
Rotating replaces the secret at once. The new secret keeps the name and scopes, gets a fresh lifetime and is shown once.
Project administrators can list every member’s tokens, never their secrets, and revoke them.
A removed member’s or disabled user’s tokens stop working at once.

Call the Forge REST API

Forge REST routes live under /api/v1/forge on your site’s address. Send the token in either header.

curl -sS -G "https://acme.orbit.inortix.com/api/v1/forge/repositories/<repository id>/commits" \
  -H "PRIVATE-TOKEN: ofp_..." \
  --data-urlencode "path=docs"

curl -sS -G "https://acme.orbit.inortix.com/api/v1/forge/repositories/<repository id>/commits" \
  -H "Authorization: Bearer ofp_..." \
  --data-urlencode "path=docs"

An unknown token answers 401. A read_api token that tries to write answers 403. In an archived project, every write answers 409 with the code project_archived, while clones and fetches still work. Forge limits each client address to 900 requests a minute.

These always need an interactive Orbit session and never accept a token:

token management and CI secrets;
trigger tokens;
deployment approvals and protections;
Git operation reviews and instance administration.

Git over HTTPS

Use the clone URL shown in the repository. When Git asks for a password, give it a token. Cloning and fetching need read_repository, and pushing needs write_repository.

Branch protection, tag rules and push rules apply to every push, see Protected branches, tags and push rules.
git push -o ci.skip skips every pipeline from that push, and [skip ci] or [ci skip] in a commit message skips the automatic pipelines for it. Other push options are rejected before any ref changes.
Objects over 32 MiB are not supported. The size of a repository is limited per plan, see Pricing.

Git over SSH

Add an OpenSSH public key under Git access, and use the SSH clone URL shown there.

Rule	Detail
Key types	Ed25519, ECDSA and their security-key variants, and RSA of at least 2048 bits. DSA, short RSA, keys with options and certificates are refused.
Limits	A key is unique across Orbit, and a person can add at most 50. An expiry is optional, and the last use is shown.
Access	Forge acts as the key’s owner, with their live permissions. Fetches need read access.
Same checks as HTTPS	Branch protection, tag rules, push rules and `ci.skip`
What the server offers	`git-upload-pack` and `git-receive-pack`. Other commands get a greeting or a refusal, and there are no terminals or port forwarding.

Forge publishes its host key fingerprint, so compare it on your first connection. Removing a key, or disabling its owner, ends access at once. Orbit’s instance administrators can also revoke any key.

Git LFS

Git LFS works over HTTPS with the batch API and the basic transfer adapter. Authenticate with a token as the password or with your Orbit session. Objects are verified on upload and download and can be read only through a repository the person can read. A fork shares the LFS objects of its upstream.

Registry and packages

A token also logs in to the container registry: read scopes pull and write scopes push. The api scope uploads generic packages. See Environments, deployments and releases.