Managing a repository

Rename a repository or a branch, change its default branch, website and topics, make it public or private, archive it, and delete and restore it.

A repository’s details and its lifecycle are managed from its Settings → Repository page, at g1t.sh/<workspace>/<repo>/settings/repository, and from the API and MCP server. This guide covers each change, who can make it, and what happens when you do.

The settings page

Section	What it holds
Name	The repository’s name, the second part of its address.
Details	Its description, website and topics, shown on its page, in search and Explore.
Branches	The default branch, renaming a branch, and a link to Branches and merging: branch protection, required approvals, the merge queue and what agents do. What a sandbox may reach is under Guardrails; see guardrails.
Danger zone	Change visibility, archive, transfer and delete. Shown to people with the Admin role.

While a repository is archived, the settings that change it are turned off until it is unarchived.

Who can do what

Each change needs a role on the repository. Owners of its workspace have Admin on it.

Change	Needs
Description, website, topics	Maintain
Default branch	Admin
Rename a branch	Write; Admin for the default branch
Rename the repository	Admin
Make it public or private	Admin
Archive or unarchive	Admin
Transfer	An owner of both workspaces
Delete, restore and purge	An owner of its workspace
See the Recently deleted list	An owner of its workspace

Renaming the repository or its default branch, changing its visibility and archiving it are done by a person, not a workspace token. A g1t agent’s token can never use the tools that make these changes, whatever its run. See credentials.

Edit the details

Open the repository’s Settings → Repository.
Under Details, change Description, Website or Topics.
Choose Save.

Field	Rules
Description	Up to 200 characters. Empty clears it.
Website	An http or https address. `https://` is added when you leave the scheme out. Empty clears it.
Topics	Lowercase letters, digits and hyphens, at most 20, each up to 35 characters. Separate them with commas or spaces.

From the API, call PATCH /repos/{owner}/{name} with the fields to change. Fields you leave out stay as they are.

curl -X PATCH https://api.g1t.sh/repos/acme/rocket \
  -H "Authorization: Bearer $G1T_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"description": "Launches things.", "website": "rocket.acme.dev", "topics": ["cli", "rust"]}'

The MCP tool is update_repo, with repo and the same fields.

Change the default branch

The default branch is what the repository opens on, what new clones check out, what pull requests target, and what branch protection covers.

Open the repository’s Settings → Repository.
Under Branches → Default branch, pick another branch.
Choose Change default branch.

The branch must already exist; push it first. When you change it:

Open pull requests merge into the new default branch.
New clones check out the new default branch. Existing clones keep the branches they have; run git remote set-head origin -a to update what origin/HEAD points at.
Branch protection covers the new default branch.

From the API, send default_branch to PATCH /repos/{owner}/{name}:

curl -X PATCH https://api.g1t.sh/repos/acme/rocket \
  -H "Authorization: Bearer $G1T_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"default_branch": "trunk"}'

The MCP tool is update_repo, with repo and default_branch. When the same call changes other fields, they are changed first.

Rename a branch

Open the repository’s Settings → Repository.
Under Branches → Rename a branch, pick the Branch and type its New name.
Choose Rename branch.

Renaming the default branch needs Admin. It stays the default under its new name. When a branch is renamed:

Open pull requests from it follow it to the new name.
Web addresses that name the old branch, such as g1t.sh/acme/rocket/tree/old-name, redirect to the new one until a branch with the old name is made again.
Git remotes do not follow. In each clone, rename the local branch and track the new one:

git branch -m old-name new-name
git fetch origin
git branch -u origin/new-name new-name
git remote set-head origin -a

From the API, call POST /repos/{owner}/{name}/branches/{branch}/rename with new_name. A branch name with slashes goes in the path URL-encoded, as one segment: feature/login is feature%2Flogin.

curl -X POST https://api.g1t.sh/repos/acme/rocket/branches/feature%2Flogin/rename \
  -H "Authorization: Bearer $G1T_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"new_name": "feature/sign-in"}'

The MCP tool is rename_branch, with repo, branch and new_name.

Rename a repository

Open the repository’s Settings → Repository.
Under Name, type the new name. It shows the new address.
Choose Rename.

A name is lowercase letters, digits, dots, hyphens and underscores, up to 100 characters. It cannot start with a dot or end in .git, and no other repository in the workspace may have it, including one that was recently deleted.

Everything stays with the repository: its git data, issues, pull requests, workflow runs, deployments, settings, secrets and webhooks. Its old address keeps working, the same way as after a transfer:

	Behaviour
Web pages	A permanent redirect (`301`) to the same page at the new address.
`git clone`, `fetch`, `pull` and `push`	Redirected to the new remote. Git follows it and prints a warning each time.
API and MCP	A call that names the repository by its old name runs against it under its new name.

Its project follows: a project that had the repository’s name takes the new one, unless another project in the workspace already has it, and its deployed apps are built again under the new name while the old addresses redirect.

A redirect stops as soon as a repository is made at the old address. Update your remotes rather than relying on it:

git remote set-url origin https://g1t.sh/acme/launcher.git

From the API, call POST /repos/{owner}/{name}/rename with name:

curl -X POST https://api.g1t.sh/repos/acme/rocket/rename \
  -H "Authorization: Bearer $G1T_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "launcher"}'

The MCP tool is rename_repo, with repo and name.

Change who can see a repository

A public repository can be seen and cloned by anyone, signed in or not. A private one can be seen only by people with a role on it.

Open the repository’s Settings → Repository.
Under Danger zone → Change visibility, choose Make private or Make public.
Read what changes, type the repository’s full name (<workspace>/<repo>) to confirm, and choose Make private or Make public again.

	Making it public	Making it private
Who can see it	Anyone: its code, issues and pull requests, and cloning it, without signing in.	Only people with a role on it: its workspace’s owners, its members (unless the base permission is None), and anyone given a role on it. Anyone else gets a page that says it does not exist.
Search and Explore	It is added to search and Explore for everyone.	It leaves search and Explore for everyone outside the workspace.
Link previews	Links to it show a preview card with its name and description.	Links to it stop showing a preview card.
Storage	It stops counting toward the workspace’s private storage.	It counts toward the workspace’s private storage. A free workspace has 1 GB; making it private is refused when that would go over. See what is free.

Nothing else changes: its address, members, settings, secrets, webhooks and deployments stay as they are.

From the API, call POST /repos/{owner}/{name}/visibility with private and its full name in confirm:

curl -X POST https://api.g1t.sh/repos/acme/rocket/visibility \
  -H "Authorization: Bearer $G1T_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"private": true, "confirm": "acme/rocket"}'

The MCP tool is set_repo_visibility, with repo, private and confirm. private on PATCH /repos/{owner}/{name} makes the same change without the confirmation, for people with Admin.

Archive a repository

Archiving makes a repository read-only. Use it for work that is finished but should stay readable.

Open the repository’s Settings → Repository.
Under Danger zone, choose Archive.
Read what changes and choose Archive again.

While it is archived:


Pushes and merges	Refused, whatever your role, and for agents too.
Issues and pull requests	Locked. They stay readable.
Agents and workflows	Do not run.
Settings	The ones that change the repository are turned off.
Deployments	Keep serving.
Who can see it	Unchanged. Anyone who could see it still can, and clone it.

Its page says it is archived, and so do its project’s card on the workspace overview and its card on Explore, with an archived label. To undo it, someone with Admin chooses Unarchive in the same place. Pushes, merges, issues, pull requests, agents and workflows work again; nothing that was refused while it was archived runs by itself.

From the API, call POST /repos/{owner}/{name}/archive or POST /repos/{owner}/{name}/unarchive:

curl -X POST https://api.g1t.sh/repos/acme/rocket/archive \
  -H "Authorization: Bearer $G1T_TOKEN"

The MCP tools are archive_repo and unarchive_repo, with repo. The repository’s archived_at field says when it was archived, and is null when it is not.

Delete a repository

Deleting takes a repository away at once, but an owner can restore it for 30 days. After that it is purged: removed for good, its git data with it.

Open the repository’s Settings → Repository.
Under Danger zone, choose Delete.
Read what happens, type the repository’s full name (<workspace>/<repo>) to confirm, and choose Delete repository.

	While it is deleted	When it is purged
Its pages, git remote and API	Answer as if it did not exist, for everyone.	The same.
Its name	Stays taken: no repository can be made at its address.	Free to use again.
Agents and workflows	Stop, and do not start.
Deployments	Taken down. Its `g1t.page` addresses stop serving.	Removed.
Custom domains	Kept, and serve nothing.	Removed.
Search	Drops it.
Webhooks	The workspace’s webhooks are sent `repo.deleted`.	Sent `repo.purged`.
Storage	Stops counting toward the workspace’s storage.
Git data, issues, pull requests, settings, secrets	Kept, for restoring.	Removed, and cannot be recovered.

Its entries in the audit log are kept, as for anything else.

From the API, call DELETE /repos/{owner}/{name} with its full name in confirm. It returns the deleted repository with purge_after, when it will be purged:

curl -X DELETE https://api.g1t.sh/repos/acme/rocket \
  -H "Authorization: Bearer $G1T_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"confirm": "acme/rocket"}'

The MCP tool is delete_repo, with repo and confirm.

To move a repository to another workspace instead of deleting it, see transferring a repository.

Restore a repository

A workspace’s recently deleted repositories are listed for its owners under Recently deleted in the workspace’s Settings → Repositories, at g1t.sh/<workspace>/-/repositories, each with who deleted it and when it will be purged.

Open the workspace’s Settings → Repositories.
Under Recently deleted, find the repository and choose Restore.

It comes back at the address it had, as it was when it was deleted: git data, issues, pull requests, settings, secrets and webhooks. Its deployments are built again, and its custom domains serve them once they are live. Agents and workflows run again for new work; they do not catch up on what they missed.

From the API, list them with GET /workspaces/{workspace}/repos/deleted (MCP: list_deleted_repos), then call POST /repos/{owner}/{name}/restore with the path it had (MCP: restore_repo):

curl https://api.g1t.sh/workspaces/acme/repos/deleted \
  -H "Authorization: Bearer $G1T_TOKEN"

curl -X POST https://api.g1t.sh/repos/acme/rocket/restore \
  -H "Authorization: Bearer $G1T_TOKEN"

Purge a repository now

To remove a deleted repository for good before its 30 days are up, and free its name:

Open the workspace’s Settings → Repositories.
Under Recently deleted, choose Delete permanently beside it.
Type its full name (<workspace>/<repo>) to confirm, and choose Delete permanently again.

This cannot be undone. From the API, call POST /repos/{owner}/{name}/purge with its full name in confirm:

curl -X POST https://api.g1t.sh/repos/acme/rocket/purge \
  -H "Authorization: Bearer $G1T_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"confirm": "acme/rocket"}'

The MCP tool is purge_repo, with repo and confirm.

A workspace whose only repositories are recently deleted ones can itself be deleted; they are purged with it.

When a change is refused

Response	Why	What to do
`401 unauthenticated`	No token, or one that is not valid.	Send a personal access token.
`403 forbidden`	You are not an owner, for a change that needs one; or a g1t agent’s token was used.	Ask an owner of the workspace.
`404 not_found`	No such repository or branch, or you cannot see it. For restore and purge: no deleted repository had that path, or it was purged.	Check the path. A deleted repository is named by the path it had.
`409 conflict`	The new name is taken in the workspace, by a repository or a recently deleted one; or a branch with the new name exists.	Pick another name, or purge the deleted repository first.
`422 invalid`	`confirm` is not the repository’s full name; the name, branch name or website is not valid; or the new default branch does not exist.	Type `<workspace>/<repo>` exactly; push the branch first.
`402 payment_required`	Making it private would take a free workspace’s private storage over 1 GB.	Start the g1t plan, or make room first.

Each refusal comes with a message that says what to do.

Events and the audit log

Each change is sent to webhooks and recorded in the audit log:

Change	Event
Description, website, topics, protection	`repo.updated`
Visibility	`repo.visibility_changed`
Rename	`repo.renamed`
Default branch	`repo.default_branch_changed`
Branch rename	`branch.renamed`
Archive, unarchive	`repo.archived`, `repo.unarchived`
Transfer	`repo.transferred`
Delete, restore, purge	`repo.deleted`, `repo.restored`, `repo.purged`