# Gitpin documentation Public onboarding, the public Git/API gateway and customer charging are not open yet. These pages document the private service. If setup is unavailable, tell the owner instead of inventing access. Never ask for a secret in chat. Source: https://gitpin.dev/docs/agents # Agent-readable documentation Read [/llms.txt](/llms.txt) first. It states availability and links the current documentation. [/llms-full.txt](/llms-full.txt) combines the same pages into one text resource; [/docs/openapi.json](/docs/openapi.json) describes the REST operations. ## Follow availability Public onboarding is not open yet. If a required capability or setup step is unavailable, report that to the owner. Do not invent credentials, endpoints or install commands. ## Keep secrets out of chat Ask the owner to install a scoped key in trusted runtime configuration or a Git credential helper. Never ask for their secret in the conversation and never put one in a URL or command argument. ## Make recoverable changes Use a working branch, focused commits and pull requests. Keep the original operation key and payload for idempotent retries. Refresh uncertain writes before issuing another operation. ## Tools Ordinary Git and the documented HTTP API are the supported starting point. MCP is implemented privately and remains subject to deployment availability. No released Gitpin CLI or installable agent skill is advertised. --- Source: https://gitpin.dev/docs/billing # Usage and billing Gitpin charges for stored bytes over time and outbound transfer. Seats, repository counts, keys and API request counts do not have a separate fee. ## Planned launch rates | Meter | USD rate, before tax | | ----------------- | -------------------- | | Storage | $0.001 per GiB-hour | | Outbound transfer | $0.02 per GiB | The rate card is `gitpin-usd-v1`. Public charging is not activated. One GiB stored for 30 days is 720 GiB-hours, or $0.72, before outbound transfer and tax. ## Measurements and gaps Storage uses hourly physical Git measurements and reports their sample time. Current values may lag a recent push. Unknown, stale or incomplete coverage is not zero usage; an incomplete month cannot claim a complete aggregate dollar total. ## Estimates, bills and invoices The current-month estimate is provisional. A closed monthly bill is a usage record, not proof of collection. Collection carries small balances until the $5 threshold, twelve-month settlement or account closure according to the accepted terms. A saved card does not pay an outstanding invoice. ## Payment repair Stripe handles payment methods and billing identity through the Customer Portal. The console does not store or display a local card, address or tax-ID summary. Use a payable invoice's supported payment action when collection requires it; changing the card alone does not settle it. ## Grace and suspension A verified first payment failure starts the fixed grace deadline. A provider outage alone does not. After grace, ordinary work is restricted, but billing, key revocation, owner export and deletion remain reachable. Restore activity only after every overdue invoice is paid and reconciliation has finished. ## Cleanup and retained debt Deletion stops storage only after removal is confirmed. It does not erase accrued usage, debt, invoices or required billing history. See the owner recovery guidance before deleting your last copy. --- Source: https://gitpin.dev/docs/concepts # Git, with boundaries Gitpin hosts private Git repositories for agents and the products that use them. Your product owns its users and workflow; Gitpin keeps versioned data and enforces the authority you give each key. ## Repositories and organisations Every repository belongs to one organisation. Its public ID identifies it across Git and REST. Use a repository per workspace, customer or job when their histories and access should stay separate. Repository names are labels, not permission boundaries. ## Branches and protected main Agents push work to their own branches. Ordinary writes cannot overwrite or delete protected `main`. Pull requests give you a normal Git comparison and merge workflow. A merge key may merge; the service does not require a human approval step. ## Keys are authority A key has a repository scope, capabilities and a UTC expiry. Give the smallest useful scope. A delegated child can only narrow its parent's authority. Revoking a parent invalidates its descendants; independent root keys remain independent. ## Owners and agents Owners sign in through the web console. Agents use scoped keys in trusted runtime configuration. Signing in does not create a repository, and a setup link does not grant agent authority. Keep both paths separate. ## Bytes and billing Storage is measured physical Git data, not the number of seats or repositories. Outbound traffic is a separate meter. An unavailable measurement is not zero. See [usage and billing](/docs/billing). --- Source: https://gitpin.dev/docs/errors # Errors and recovery Read the error code, message and next action together. A missing response is not proof that an operation failed. ## Session and permissions Sign in again after session expiry. The console clears private caches and one-time results before showing another owner. Unknown and wrong-organisation resources share a safe unavailable response. Do not retry with a broader credential automatically. ## Lost creation response Keep the original idempotency key, trimmed repository name and request ID. Retry or resume that same request. Card verification, allocation and readiness are separate; a browser callback is not creation confirmation. ## Lost credential response A secret is returned once and cannot be replayed. Resolve the original key's public metadata before revocation and reissue. If several keys could match, ask an operator to reconcile them rather than guessing. ## Merge or replacement uncertainty Refresh the same public operation. Do not assume a timeout means the upstream rejected a change. A replaced generation requires fresh references, not a forced retry against old state. ## Meter and payment failures An unavailable meter is not zero. A provider outage does not create a customer payment deadline. Saving a card is not invoice payment. Keep cleanup accessible while payment is restricted. --- Source: https://gitpin.dev/docs/git # Git over HTTPS Use normal Git over HTTPS against the canonical repository URL shown by Gitpin. SSH and Git LFS are not offered. ## Clone and fetch A key needs read authority for the repository. Use username `gitpin`; a Git credential helper or private password prompt supplies the secret. ```sh git clone https://gitpin.dev/git/REPOSITORY_ID.git git -C YOUR_REPOSITORY fetch origin ``` Never put a credential in a URL, command argument or chat message. The public URL itself contains no secret. ## Push a working branch ```sh git switch -c agent/my-change git add . git commit -m 'Make a focused change' git push origin agent/my-change ``` The key needs write authority. Protected main rejects ordinary writes, forced updates and deletion. Use [pull requests](/docs/pulls) for review and merge. ## Limits and conflicts A push is bounded by the documented request limit, currently 1 GiB. Storage quotas may refuse new writes while reads and cleanup remain available. Git conflicts still need ordinary resolution on a working branch. ## Interrupted transfers A cancelled client connection does not imply the upstream operation stopped immediately. Refresh state before retrying a write. Outbound bytes already sent remain usage, even when the client abandons a clone. ## Owner export The owner console can issue a short-lived, read-only reachable-history export login. Its username is `gitpin-export`, and its secret is separate from its URL. Mirror all advertised refs, verify the saved repository and revoke the grant before deleting the source. An export is not a promise to recover unreachable objects or application-specific data outside Git. --- Source: https://gitpin.dev/docs/keys # Keys and scopes A key is a deliberate permission grant. Select its repository scope, capabilities and UTC expiry before issuing it. ## Capabilities | Capability | What it permits | | ---------- | ------------------------------------------------------------------------- | | `read` | Clone, fetch and inspect repository content. | | `write` | Push work to permitted branches. | | `merge` | Merge a pull request into protected main. | | `replace` | Start and finish deliberate history replacement; requires read and write. | | `delegate` | Issue a child key with narrower scope, capabilities and expiry. | | `publish` | Append to protected main where the documented publish flow is available. | A write key alone cannot force or delete main. Merge authority is independent of write. The service checks capability dependencies rather than silently granting extra rights. ## Scope and expiry Prefer one repository and the shortest useful lifetime. Advanced organisation-wide authority is a separate explicit choice. A child cannot add a repository, capability or lifetime that its parent lacks. ## One-time secrets Only the issuance response contains the secret. It is not recoverable from the key list. Keep it in trusted runtime configuration or a credential helper, outside browser persistence, query caches and logs. If an issuance response is lost, first resolve the original operation using its replay metadata. Revoke the uniquely identified key before issuing another. If it cannot be identified safely, ask an operator to reconcile it; do not guess. ## Revocation Review the public key ID and consequence before revoking. A revoked parent invalidates delegated descendants. Independent root keys are unaffected. An already authorised stream may finish; later requests are denied. --- Source: https://gitpin.dev/docs/limits # Limits Limits keep requests predictable and shared capacity usable. Current defaults come from the service configuration; a deployment may lower them. ## Git and storage A single Git push is capped at 1 GiB. An organisation also has a soft physical-storage quota. Unlimited repository count is not a promise of unlimited push size or capacity. Above quota, new writes can be refused while reads and cleanup remain available. ## Bounded responses Lists use bounded pages and opaque cursors. Content, files and diffs have response limits. A binary or oversized file may show metadata and an explanation instead of rendered content. The UI must not treat a truncated response as a complete file. ## Authority Every key has a required expiry. Children can only narrow their parent's authority. Protected main is not a normal write destination. Cross-organisation IDs do not reveal private resource identity. ## Unavailable interfaces There is no SSH transport, Git LFS, hosted CI runner, issue tracker, wiki UI, code search or customer webhook service. The client repository has no released Gitpin CLI. Check [the current availability index](/llms.txt) before choosing an integration. --- Source: https://gitpin.dev/docs/mcp # MCP The service includes a private MCP adapter for repository operations with one configured scoped key. The public MCP endpoint is not open yet; do not configure a client against an unavailable endpoint. ## Authority stays with the key The adapter uses the configured key's repository scope, capabilities and expiry. A web owner session does not silently become agent authority. Delegated keys may only narrow the parent. ## Writes and retries Repository creation, file writes and credential issuance require their documented idempotency key. Retain that key and identical payload through retries. A cancelled credential issue does not intentionally retain a usable key. ## Errors Tool failures return a stable code, message and next action. Inspect those before retrying, especially where a write result is uncertain. Read [errors and recovery](/docs/errors). ## Availability Connection instructions will be published with the deployed endpoint. Until then, use the documented Git and REST workflows only where available. No released skill or separate CLI is implied by this adapter. --- Source: https://gitpin.dev/docs/owner-setup # Owner setup Public onboarding is not open yet. This guide explains the existing owner flow so you can recognise each step when it becomes available. ## Sign in with GitHub GitHub supplies identity only. Gitpin does not request access to your GitHub repositories. A new owner explicitly accepts the current Terms; a returning owner does not need to repeat signup acceptance. One owner belongs to one organisation. ## Create a repository Choose a name. If a card is needed, the console opens Stripe's embedded setup form. Stripe handles payment details. Saving a card is not a repository creation confirmation and is not proof that an invoice was paid. The console retains the original creation request and idempotency key after an interrupted response. Resume that request. Do not create another repository while the first result is uncertain. ## Wait for readiness Verification, allocation and provisioning are separate states. The repository is usable only when its server lifecycle says `ready`. Leaving setup pauses your browser flow; it does not delete or cancel a repository. ## Issue a scoped key Choose a repository, capabilities and expiry. The secret is shown once. Install it through your agent's trusted runtime or Git credential helper. Do not send it through chat or put it into a Git URL. See [keys and scopes](/docs/keys). ## Follow an agent's setup link A pending setup URL identifies a request; it grants no authority. Sign in as the request's owner. Wrong-owner and unknown requests share a safe unavailable response. The agent continues retrying its original creation request while owner setup is pending. --- Source: https://gitpin.dev/docs/pulls # Pull requests A pull request compares a working branch with the repository's protected main branch. It belongs to one repository generation and has a public generation-and-index ID. ## Open a pull request Push the working branch first, then supply its name, a title and an optional description. The branch must be a permitted working branch, not main. The API returns the public request ID and current mergeability. ## Review the change Inspect the summary and diff. A diff may be bounded; an unavailable revision or replaced generation is not an empty change. Refresh stale data before acting. ## Merge A key with merge authority, or an authorised owner where the console operation is shipped, may request a normal merge into main. There is no mandatory human approval gate. Conflicts block the merge; update the working branch and inspect again. ## An uncertain result If the upstream accepted a merge but its resulting status cannot be read, the service reports an uncertain outcome. Refresh the same pull request. Do not assume it failed or issue a different merge merely because the response was interrupted. ## Replaced history and suspension History replacement changes the generation. A request from the old generation cannot be merged into the new one. Payment suspension blocks ordinary review/work actions while owner billing and cleanup remain available. --- Source: https://gitpin.dev/docs/quickstart # Agent quickstart Start by reading [the availability index](/llms.txt). Public account setup is not open yet. If setup is unavailable, tell your owner; do not invent an endpoint, request their GitHub credentials or ask them to paste a key into chat. ## Get the right authority Your owner supplies a key through trusted runtime configuration or a Git credential helper. It needs `read` to clone and `write` to push to a working branch. Opening and merging pull requests use their documented capabilities. Choose a short expiry and one repository. ## Clone over HTTPS Use the repository's canonical Git URL from the console. A credential helper or a private password prompt supplies the key; the command contains no secret. ```sh git clone https://gitpin.dev/git/REPOSITORY_ID.git cd YOUR_REPOSITORY ``` The Git username is `gitpin`. Never put the key in the URL, command arguments, a transcript or a checked-in file. ## Work on a branch ```sh git switch -c agent/docs-refresh # make a focused change git add . git commit -m 'Refresh the documentation' git push origin agent/docs-refresh ``` Write authority does not permit rewriting protected main. Normal Git conflicts are still possible. ## Open and merge a pull request Use the [pull request API](/docs/pulls) or the owner console when that workflow is available. Inspect the diff, then merge with an actor that has merge authority. A conflict needs a new branch update, not a forced push to main. ## Retry deliberately For operations that accept an idempotency key, retain that original key and identical payload after a lost response. A timeout is not proof that a write failed. Refresh the public operation status before retrying or creating another resource. --- Source: https://gitpin.dev/docs/replacement # History replacement History replacement is an explicit operation for replacing the repository's reachable Git history. It is not a force push to protected main. ## Start an attempt An actor with the required read, write and replacement authority starts an attempt. Use the returned staging instructions and retain its public attempt ID. The current generation remains the reference until completion is confirmed. ## Stage and complete Upload the intended history to the staging location documented by the service, then request completion of that same attempt. Completion fences the old generation before publishing the replacement. Refresh an uncertain outcome rather than starting a competing attempt. ## Abort Abort an open attempt only when the service offers that action. Review the attempt ID first. A completed replacement cannot be undone by an abort request. ## Inspect status Open, completing, completed and absent-attempt states are different. A load error is not evidence that no attempt exists. Old-generation credentials, content references and pull requests cannot silently operate against a new generation. ## Keep a verified copy If you need the old history, export it before replacing or deleting it. [Owner export](/docs/git#owner-export) covers advertised reachable refs, not every unreachable object or historical backup. --- Source: https://gitpin.dev/docs/rest # REST and OpenAPI The [OpenAPI document](/docs/openapi.json) is the source for request and response types. It is exported from the same Python service that implements the routes. ## Two authority paths Agents use the documented credential-authenticated API. The browser console uses owner-session endpoints on the same origin. An agent key does not grant owner billing authority; the browser never needs an agent credential to discover its owner session. ## Repository operations Use public organisation and repository IDs. Follow the operation's scope and capability requirements. The canonical Git URL comes from the repository response; do not construct upstream Forgejo URLs. ## Errors Failures use a stable `code`, a human-readable `message` and a practical `next_action`. Unknown and cross-organisation resources share safe unavailable responses. Do not infer a successful mutation from an HTTP transport timeout. ## Idempotency Where an operation requires `Idempotency-Key`, retain the original key and payload until the result is resolved. Reusing it with different content is a conflict. A secret-free replay identifies an issued credential but cannot return its secret again. ## Pagination List endpoints return bounded pages and opaque cursors. Follow `next_cursor` until it is absent. Preserve filters and page size across calls; do not interpret a partial page as the whole organisation. ## Client tooling The public [client repository](https://github.com/writeitai/gitpin) contains the open-source client work. No separate Gitpin CLI or install command is released. Use ordinary Git and the documented HTTP API.