Appearance
Tarinoi Git Remote Integration
Version 0.0.2 — 2026-07-15
Tarinoi can link a project to a remote Git repository. This document describes how the integration works, what it does and does not do, and how to recover from common failure modes.
Purpose
A linked remote serves three distinct roles:
Permanent record and history ledger. Every commit in Tarinoi produces a corresponding Git commit on the remote. The remote accumulates the full history of the project, including authorship and timestamps, in a format that is readable by any standard Git tooling.
Build pipeline integration point. The remote is the natural interface between Tarinoi and external build pipelines. Point your build scripts at the remote repository; they will see committed project data as files in a well-known layout and can pull changes as they land.
Cold storage and disaster recovery. If a project is deleted from Tarinoi, its data is not lost — the remote retains the full commit history. A deleted project can be recreated at any time by cloning from the remote (see Linking a project to a remote).
Caveats
Data flow is primarily unidirectional. Tarinoi is designed around a one-way pipeline: client edits → Tarinoi database → Git sandbox → remote → downstream consumers (builds, pipelines, tools). This direction is robust and well-tested.
Pulling from the remote is supported but not routine. Tarinoi can fetch, merge, and ingest changes pushed to the remote from outside — for example, if a CI pipeline writes back to the repository. However, there are only minimal guards against breakage, and conflicts are resolved with a blunt remote-wins policy. Pulling is intended as an occasional reconciliation step, not a regular workflow. If your process depends on pushing data into Tarinoi from the remote, model it carefully and test it.
One project per remote. A remote repository must be associated with at most one Tarinoi project at a time. Pointing two projects at the same repository will cause their histories to collide and is not supported.
Last resort: fork and recreate. If a remote becomes irrecoverably desynced — for example, due to a force-push, a history rewrite, or a failed merge that left the repository in an inconsistent state — you can recover by forking the remote repository from its last known stable commit, then creating a new Tarinoi project cloned from the fork. The original repository can then be deleted or archived.
How it works
When a remote is configured, every commit in Tarinoi triggers a three-step pipeline:
- Flush — the committed documents are written as files to a local Git repository on the Tarinoi server (the sandbox).
- Commit — a Git commit is created in the sandbox.
- Push — the new commit is pushed to the configured remote over HTTPS.
Steps 2 and 3 are asynchronous and run in the background after the commit returns to you. Failures are retried automatically before being surfaced as errors.
Configuring a Git provider
Before linking any project to a remote, you must configure a Git provider for your organisation. Go to Projects Hub → Git Provider and provide:
- Provider — GitHub, GitLab, or Bitbucket.
- Namespace — the GitHub organisation or username, the GitLab group path or username, or the Bitbucket workspace slug under which Tarinoi will create and access repositories.
- Access token — a personal access token (PAT) or app password with sufficient privileges (see below). The token is encrypted at rest and never returned to clients.
Required token scopes by provider:
| Provider | Required scopes / permissions |
|---|---|
| GitHub | Classic PAT: repo scope (or public_repo for public repos only). Fine-Grained PAT: Contents — Read & Write and Metadata — Read-only. |
| GitLab (classic PAT) | api scope. This is the only classic scope that covers both REST API access (namespace resolution, repository creation) and git read/write. write_repository and read_repository only cover git operations and will fail on REST API calls. |
| GitLab (fine-grained PAT) | Under the User zone: User → Read and Project → Create. Under Group and project scoped to the target group: Group → Read, Project → Read, Branch → Read, Code → Download, Push, Read. |
| Bitbucket | App password with Repositories — Read, Repositories — Write, and Repositories — Admin (Admin is required to create new private repositories). |
After saving, Tarinoi validates the token against the provider API before storing it. If validation fails, the config is rejected and you will be shown an error.
You can update the Git config at any time (for example, to rotate a token or switch providers). The new token is validated before the old one is replaced.
Linking a project to a remote
Setting the remote on an existing project
Open the project info card and enter either:
- A repository name (e.g.
my-project) — the common case, when the repository doesn't exist yet. Tarinoi will create it in your configured namespace. Repositories are always created private. - The repository's full HTTPS URL (e.g.
https://github.com/my-org/my-project.git) — for the less common case of linking to a repository that already exists. The URL's namespace and provider must match your organisation's configured Git provider; Tarinoi will link to the existing repository after verifying that its history is compatible with the project's local history.
The remote mapping can be changed to a different repository at any time, but it cannot be removed — once a project is linked, it remains linked. Pointing a project at the wrong repository is recoverable: set the remote to the correct name or URL.
The source of truth for a project's remote mapping is Tarinoi's own record of it, not anything stored in the project itself — this is why the remote status always reflects what's actually configured, even if the project was exported and reimported elsewhere.
Creating a project by cloning from a remote
When creating a new project, you can choose to initialise it from an existing remote repository by pasting its full HTTPS URL (the URL's namespace and provider must match your organisation's configured Git provider). Tarinoi will clone the repository into a new project and import all of its documents. The project enters a working state during the clone and import; it opens normally once the process completes. Large repositories may take several minutes.
Automatic pushes
Once a remote is configured, every commit you make in Tarinoi is automatically pushed to the remote. You do not need to do anything. The push runs in the background after the commit completes; you will not be blocked on it.
If a push fails transiently (e.g. a brief network interruption), it is retried automatically. If a push fails definitively (e.g. a revoked token), it is surfaced as an error in the project info card.
Diverged remote: when someone pushes outside Tarinoi
If commits are pushed directly to the remote repository bypassing Tarinoi (for example, via a CI pipeline or another tool), the remote will contain commits that the Tarinoi sandbox does not have. Tarinoi detects this when you open the project info card and verifies the remote: the status will show remote ahead or diverged.
In the diverged case, Tarinoi's push will be blocked until the remote is reconciled. To reconcile:
- Open the project info card.
- Click Pull. Tarinoi will fetch the remote commits and merge them into the local sandbox using a remote-wins conflict resolution policy: where the remote and local histories have diverged, the remote version takes precedence at the file level.
- After the merge, Tarinoi immediately pushes the resulting merge commit to the remote.
- The remote status will update to show the repositories are in sync.
Note: Remote-wins applies only to the Git file content in the sandbox (which is a derived representation of Tarinoi documents). The authoritative data is always in the Tarinoi database; a Pull operation re-imports the remote documents and merges them into the project, which may overwrite local-only changes made outside the normal commit flow.
If the remote repository has no shared history with the local sandbox at all — for example, because the remote was pointed at an entirely different project — Pull will be blocked and you will need to set the remote to the correct repository.
When the remote becomes inaccessible
If the remote becomes temporarily or permanently unreachable (network outage, expired token, revoked credentials), Tarinoi will:
- Continue committing locally without interruption.
- Retry the push on each subsequent commit.
To push pending commits manually, open the project info card. If the remote status shows local ahead, a Push button will be available. Clicking it will push all pending commits immediately and refresh the remote status.
To resolve a permanently inaccessible remote (e.g. an expired token), update the Git provider credentials in My Account → Git and then click Push or wait for the next commit.
Project deletion
Deleting a project removes Tarinoi's link to the remote repository (the remote mapping), but does not delete the repository itself on the provider. The repository remains in the namespace and must be deleted manually from GitHub, GitLab, or Bitbucket if no longer needed.
Remote status reference
The project info card displays a remote status after running Verify remote:
| Status | Meaning |
|---|---|
| In sync | Local sandbox and remote are identical. |
| Local ahead | The sandbox has commits not yet on the remote. A push is pending or can be triggered manually. |
| Remote ahead | The remote has commits not in the sandbox. Click Pull to reconcile. |
| Diverged | Both sides have commits the other lacks. Click Pull to reconcile (remote-wins). |
| Empty | The remote branch does not exist yet. It will be created on the next push. |
| Missing | The remote repository could not be found. Check that the slug and provider credentials are correct. |
| Unknown | The local sandbox has no commits yet; history cannot be compared. |