| 1 | --- |
| 2 | title: Managing a repository |
| 3 | description: What a repository's header and Code page show, and how to rename it or a branch, change its default branch, website and topics, make it public or private, archive it, and delete and restore it. |
| 4 | --- |
| 5 | |
| 6 | A repository's details and its lifecycle are managed from its |
| 7 | **Settings → Repository** page, at |
| 8 | `g1t.sh/<workspace>/<repo>/settings/repository`, and from the API and MCP |
| 9 | server. This guide covers each change, who can make it, and what happens |
| 10 | when you do. |
| 11 | |
| 12 | ## What it is, and the facts beside the files |
| 13 | |
| 14 | The header at the top of every page of a repository (Code, Issues, Pull |
| 15 | requests, Actions, Settings and the rest) shows its project's description, |
| 16 | and its website and topics as you set them under |
| 17 | [Edit the details](#edit-the-details). The website is the project's |
| 18 | homepage when it has one. |
| 19 | |
| 20 | A repository has no description of its own: its |
| 21 | [project](/guides/projects/) has, and search, link previews and lists of |
| 22 | repositories show that one. Change it in the project's **Settings → |
| 23 | General**, or with |
| 24 | [`update_project`](/reference/api/projects/update-project/). |
| 25 | |
| 26 | The **Code** page shows its files with its facts beside them. On a phone |
| 27 | they come after the files. |
| 28 | |
| 29 | | Part | What it shows | |
| 30 | | --- | --- | |
| 31 | | **Readme** | A link to the README shown under the files. | |
| 32 | | **License** | The license its `LICENSE` file holds, such as **MIT license**, linked to the file. **View license** when the text is not one g1t recognizes. `LICENCE`, `COPYING` and `UNLICENSE` are read too, with or without an extension, and an `SPDX-License-Identifier` line says it outright. | |
| 33 | | **Security policy** | A link to `SECURITY.md` at the root, or in `.g1t`, `.github` or `docs`. | |
| 34 | | **Activity** | The repository's [activity](#activity): pushes, merges, new branches and tags. | |
| 35 | | **Stars**, **watching** | How many people [starred](#stars) it, and how many watch all or some of its activity from the [Watch menu](/guides/notifications/). | |
| 36 | | **Releases** | How many [releases](/guides/releases/) it has and the latest. With none published, how many tags it has, linked to its tags, and **Create a new release** for people who can push. | |
| 37 | | **Packages** | [Packages](/guides/packages/) linked to it, or how to publish the first. | |
| 38 | | **Contributors** | How many people and agents made it. Up to five are listed by name with how many commits each made; more show as the most active's avatars. Each opens their card. See [contributors](#contributors). | |
| 39 | | **Languages** | The languages it is written in, by bytes. See [languages](#languages). | |
| 40 | |
| 41 | The license, security policy, languages and contributors are read from the |
| 42 | default branch in the background each time it moves, and kept by commit, so |
| 43 | the page never waits for them. A push to the default branch starts the |
| 44 | reading as soon as git has its answer; a branch that moved otherwise, such |
| 45 | as by merging a pull request, is read again when its page is next opened. |
| 46 | A repository pushed to for the first time shows **Reading the default |
| 47 | branch…** for a few seconds. |
| 48 | |
| 49 | ### Languages |
| 50 | |
| 51 | The bar counts the bytes of each language's files on the default branch. |
| 52 | Programming and markup languages count; data such as JSON and YAML, and |
| 53 | prose such as Markdown, do not. TSX counts as TypeScript and JSX as |
| 54 | JavaScript. The sidebar lists every language down to a tenth of a percent, |
| 55 | the largest eight, and gathers the rest as **Other**. Neither do these count: |
| 56 | |
| 57 | | Files | Such as | |
| 58 | | --- | --- | |
| 59 | | Vendored | `node_modules/`, `vendor/`, `third_party/`, minified jQuery, and anything under a dot-directory such as `.github/` | |
| 60 | | Generated | `dist/`, `*.min.js`, `*.pb.go`, lockfiles | |
| 61 | | Documentation | `docs/`, `doc/`, `examples/` | |
| 62 | |
| 63 | Change what counts with `linguist-*` attributes in the repository's |
| 64 | `.gitattributes` file at the root. A later line wins over an earlier one. |
| 65 | |
| 66 | ```text |
| 67 | vendor/ours/** -linguist-vendored |
| 68 | *.gen.ts linguist-generated |
| 69 | docs/** -linguist-documentation |
| 70 | *.inc linguist-language=PHP |
| 71 | *.sql linguist-detectable |
| 72 | ``` |
| 73 | |
| 74 | A repository too large to read in full (more than 10,000 files) counts the |
| 75 | files read. |
| 76 | |
| 77 | ### Contributors |
| 78 | |
| 79 | **Insights → Contributors** lists everyone whose commits are on the default |
| 80 | branch, most commits first, with their commits by week, and the |
| 81 | repository's commits per week over the last year. |
| 82 | |
| 83 | | Who | How they are matched | |
| 84 | | --- | --- | |
| 85 | | A person | By an address they confirmed on their account, or their noreply address. Several addresses of one account count as one. | |
| 86 | | g1t | Its own commits, by its address. | |
| 87 | | A coding agent or bot | Claude, Codex, Copilot, Gemini, Jules, Cursor, Devin, Aider, Dependabot, Renovate and GitHub Actions, by the address they write on their commits (as author or `Co-authored-by`), never by name. Each shows its maker's mark and a card saying what it is; none is an account on g1t. | |
| 88 | | Anyone else | By the name on their commits, with a card that says they aren't on g1t and how to add the address to your account if the commits are yours. | |
| 89 | |
| 90 | The newest 3,000 commits are counted. |
| 91 | |
| 92 | ### Activity |
| 93 | |
| 94 | **Insights → Activity** lists, newest first, who pushed to which branch, |
| 95 | created a branch or tag, deleted a branch (with the commit it pointed to), |
| 96 | merged a pull request, renamed a branch or changed the default branch, |
| 97 | person or agent. A branch's **Activity**, from its **⋯** menu on the |
| 98 | [Branches page](/guides/git/#the-branches-page), keeps only what happened to |
| 99 | that branch (`?branch=<name>`); each page of the repository's activity is |
| 100 | read and filtered, so **Older** may be needed to reach earlier changes. |
| 101 | |
| 102 | ### Stars |
| 103 | |
| 104 | Choose **Star** in the repository's header to keep it in your profile's |
| 105 | **Stars** tab, at `g1t.sh/u/<you>?tab=stars`. The number beside it leads |
| 106 | to who starred it. Anyone signed in who can read a repository can star it; |
| 107 | stars on a private repository are seen only by people who can read it. |
| 108 | |
| 109 | ## The settings page |
| 110 | |
| 111 | | Section | What it holds | |
| 112 | | --- | --- | |
| 113 | | **Name** | The repository's name, the second part of its address. | |
| 114 | | **Details** | Its website and topics, shown on its page, in [search and Explore](/guides/search/). Its description is its project's, on **General**. | |
| 115 | | **Branches** | The default branch, renaming a branch, and a link to **Branches and merging**: [branch protection](/guides/git/#protected-branches), [required status checks](/guides/pull-requests/#required-status-checks), required approvals, and the [merge queue](/guides/merge-queue/). What a sandbox may reach is under **Guardrails**; see [guardrails](/guides/guardrails/). | |
| 116 | | **Artifacts** | How many days the files workflow runs upload are kept, 1 to 90 (14 unless changed). See [artifacts](/guides/actions/#artifacts). | |
| 117 | | **Features** | Whether it has issues (a [fork](/concepts/forks/) starts with them off), and whether merges and commits close issues. See [issues](#issues). | |
| 118 | | **Commits** | Sign-off on commits made on g1t, and comments on commits. See [commits](#commits). | |
| 119 | | **Pushes** | How many branches and tags one push may update. See [pushes](#pushes). | |
| 120 | | **Archives** | Whether downloads hold Git LFS objects. Coming soon. | |
| 121 | | **Forking** | For a private repository, whether people who can read it may [fork it](/guides/forking-repositories/#allow-forking-a-private-repository). Public repositories can always be forked. | |
| 122 | | **Danger zone** | Change visibility, archive, [transfer](/guides/transferring-repositories/), [detach a fork](/guides/forking-repositories/#detach-a-fork) and delete. Shown to people with the Admin role. | |
| 123 | |
| 124 | While a repository is [archived](#archive-a-repository), the settings that |
| 125 | change it are turned off until it is unarchived. |
| 126 | |
| 127 | ## Settings |
| 128 | |
| 129 | How a repository handles pull requests, commits, pushes and issues. Each |
| 130 | setting is a field of |
| 131 | [`PATCH /repos/{owner}/{name}/settings`](/reference/api/repositories/update-repo-settings/) |
| 132 | (the `repository` tool's `update_settings` action), except |
| 133 | `max_ref_updates`, which is |
| 134 | [`PATCH /repos/{owner}/{name}`](/reference/api/repositories/update-repo/)'s. |
| 135 | Fields you leave out stay as they are. Changing them needs the Maintain |
| 136 | [role](/guides/access-and-roles/) or higher; `max_ref_updates` needs Admin. |
| 137 | The pull request settings are on the repository's **Settings → Branches |
| 138 | and merging** page; the rest are on **Settings → Repository**, in the |
| 139 | sections named below. |
| 140 | |
| 141 | ### Pull requests |
| 142 | |
| 143 | On **Settings → Branches and merging**, under **Merge methods**, |
| 144 | **Updating branches**, **Auto-merge** and **After merging**. Merge commits |
| 145 | and squash merging, the two methods that write a commit message, each have |
| 146 | a **Default commit message** and, with **Custom template**, a **Template**, |
| 147 | with a preview of the message it makes. |
| 148 | |
| 149 | | Setting | Field | Default | What it does | |
| 150 | | --- | --- | --- | --- | |
| 151 | | Allow merge commits | `allow_merge_commit` | On | Pull requests may merge with a merge commit (`merge`). | |
| 152 | | Allow squash merging | `allow_squash_merge` | On | They may merge as one squashed commit (`squash`). | |
| 153 | | Allow rebase merging | `allow_rebase_merge` | On | They may merge by making each commit again on the base (`rebase`). | |
| 154 | | Allow fast-forward merging | `allow_fast_forward` | Off | They may merge by moving the base to their head, with no new commit (`fast_forward`). | |
| 155 | | Default merge method | `default_merge_method` | `merge` | The method the merge button offers first, and the one a merge that names none uses. It must be allowed. | |
| 156 | | Default commit message, under Allow merge commits | `merge_commit_message` | `default` | What a merge commit says unless its merger writes it: **Default message** (`default`), **Pull request title** (`pull_title`), **Pull request title and description** (`pull_title_and_description`) or **Custom template** (`custom`). | |
| 157 | | Default commit message, under Allow squash merging | `squash_commit_message` | `default` | What a squash commit says: the same, and **Pull request title and commit details** (`pull_title_and_commits`). | |
| 158 | | Template | `merge_commit_template`, `squash_commit_template` | None | The message used with `custom`, with [placeholders](/guides/pull-requests/#commit-messages). An empty string clears it. | |
| 159 | | Always suggest updating pull request branches | `suggest_updating_branches` | On | Offer to update a pull request's branch whenever its base has new commits, not only when it must be up to date. | |
| 160 | | Allow auto-merge | `allow_auto_merge` | On | People may turn on [auto-merge](/guides/pull-requests/#auto-merge) for a pull request. | |
| 161 | | Automatically delete head branches | `delete_branch_on_merge` | Off | A pull request's branch is deleted once it merges. It can be [restored](/guides/pull-requests/#deleting-the-branch) from the pull request. | |
| 162 | |
| 163 | At least one method stays allowed. [Rules](/guides/rules/#pull-requests-and-checks) |
| 164 | can narrow the methods for a branch, with `allowed_merge_methods` and |
| 165 | **Require linear history**; they never allow one the repository does not. |
| 166 | |
| 167 | ### Commits |
| 168 | |
| 169 | On **Settings → Repository**, under **Commits**. |
| 170 | |
| 171 | | Setting | Field | Default | What it does | |
| 172 | | --- | --- | --- | --- | |
| 173 | | Require contributors to sign off on web-based commits | `require_web_commit_sign_off` | Off | Commits made on g1t (web edits, merge and squash commits) end with a `Signed-off-by:` trailer for whoever made them, agreeing to the repository's terms, commonly the Developer Certificate of Origin. | |
| 174 | | Allow comments on individual commits | `allow_commit_comments` | On | Anyone who can read the repository may [comment on its commits](/guides/pull-requests/#commit-comments). Off keeps existing comments readable and refuses new ones. | |
| 175 | |
| 176 | ### Pushes |
| 177 | |
| 178 | On **Settings → Repository**, under **Pushes**. Turned on, it asks for |
| 179 | **Most branches and tags per push**. |
| 180 | |
| 181 | | Setting | Field | Default | What it does | |
| 182 | | --- | --- | --- | --- | |
| 183 | | Limit how many branches and tags can be updated in a single push | `max_ref_updates` | No limit | The most branches and tags one push may create, move or delete, 1 to 1,000. A push that would change more is declined whole, so nothing of it lands: "This push changes N branches and tags; owner/name takes at most M at a time. Push fewer at once." `0` removes the limit. | |
| 184 | |
| 185 | ### Archives |
| 186 | |
| 187 | On **Settings → Repository**, under **Archives**. |
| 188 | |
| 189 | | Setting | Field | Default | What it does | |
| 190 | | --- | --- | --- | --- | |
| 191 | | Include Git LFS objects in archives | None yet | Off | Coming soon. g1t does not store Git LFS files yet (see [limitations](/about/limitations/)), so archives hold what git stores; the setting is shown, turned off, until it does. | |
| 192 | |
| 193 | ### Issues |
| 194 | |
| 195 | On **Settings → Repository**, under **Features**. |
| 196 | |
| 197 | | Setting | Field | Default | What it does | |
| 198 | | --- | --- | --- | --- | |
| 199 | | Issues | `has_issues` | On; off for a [fork](/concepts/forks/) | Whether issues can be opened. Off keeps existing issues readable. `null` goes back to the default. `issues_enabled` says whether they can be opened now. | |
| 200 | | Auto-close issues with merged linked pull requests | `auto_close_issues` | On | A pull request that merges into the default branch closes its issue and those it names after a [closing keyword](/guides/pull-requests/#closing-issues), and so does a commit pushed to the default branch whose message names them. | |
| 201 | |
| 202 | ```sh |
| 203 | curl -X PATCH https://api.g1t.sh/repos/acme/rocket/settings \ |
| 204 | -H "Authorization: Bearer $G1T_TOKEN" \ |
| 205 | -H "Content-Type: application/json" \ |
| 206 | -d '{"allow_merge_commit": false, "default_merge_method": "squash", "squash_commit_message": "pull_title_and_description", "delete_branch_on_merge": true}' |
| 207 | ``` |
| 208 | |
| 209 | ## Who can do what |
| 210 | |
| 211 | Each change needs a [role](/guides/access-and-roles/) on the repository. |
| 212 | Owners of its workspace have Admin on it. |
| 213 | |
| 214 | | Change | Needs | |
| 215 | | --- | --- | |
| 216 | | Website, topics | Maintain | |
| 217 | | How long artifacts are kept | Maintain | |
| 218 | | [Merge, commit and issue settings](#settings) | Maintain | |
| 219 | | How many branches and tags a push may update | Admin | |
| 220 | | Default branch | Admin | |
| 221 | | Create, delete or restore a branch | Write; the default branch is never deleted. See [branches](/guides/git/#the-branches-page) | |
| 222 | | Rename a branch | Write; Admin for the default branch | |
| 223 | | Rename the repository | Admin | |
| 224 | | Make it public or private | Admin, and the [member privileges](/guides/workspaces/#member-privileges) to allow it, or an owner | |
| 225 | | Archive or unarchive | Admin | |
| 226 | | [Transfer](/guides/transferring-repositories/) | An owner of its workspace, or a member with Admin when the member privileges allow it; and in the other workspace, being able to create a repository | |
| 227 | | Delete | An owner of its workspace, or a member with Admin when the member privileges allow it | |
| 228 | | Restore and purge | An owner of its workspace | |
| 229 | | See the Recently deleted list | An owner of its workspace | |
| 230 | |
| 231 | Renaming the repository or its default branch, changing its visibility |
| 232 | and archiving it are done by a person, not a workspace token. |
| 233 | |
| 234 | ## Edit the details |
| 235 | |
| 236 | 1. Open the repository's **Settings → Repository**. |
| 237 | 2. Under **Details**, change **Website** or **Topics**. The description |
| 238 | is the project's: change it on **Settings → General**. |
| 239 | 3. Choose **Save**. |
| 240 | |
| 241 | | Field | Rules | |
| 242 | | --- | --- | |
| 243 | | Website | An http or https address. `https://` is added when you leave the scheme out. Empty clears it. | |
| 244 | | Topics | Lowercase letters, digits and hyphens, at most 20, each up to 35 characters. Separate them with commas or spaces. | |
| 245 | |
| 246 | From the API, call |
| 247 | [`PATCH /repos/{owner}/{name}`](/reference/api/repositories/update-repo/) |
| 248 | with the fields to change. Fields you leave out stay as they are. |
| 249 | |
| 250 | ```sh |
| 251 | curl -X PATCH https://api.g1t.sh/repos/acme/rocket \ |
| 252 | -H "Authorization: Bearer $G1T_TOKEN" \ |
| 253 | -H "Content-Type: application/json" \ |
| 254 | -d '{"website": "rocket.acme.dev", "topics": ["cli", "rust"]}' |
| 255 | ``` |
| 256 | |
| 257 | Over MCP, it is the `repository` tool's `update` action, with `repo` and |
| 258 | the same fields. |
| 259 | |
| 260 | ## Change the default branch |
| 261 | |
| 262 | The default branch is what the repository opens on, what new clones check |
| 263 | out, what pull requests target, and what branch protection covers. |
| 264 | |
| 265 | 1. Open the repository's **Settings → Repository**. |
| 266 | 2. Under **Branches → Default branch**, pick another branch. |
| 267 | 3. Choose **Change default branch**. |
| 268 | |
| 269 | The branch must already exist; push it first. When you change it: |
| 270 | |
| 271 | - Open pull requests merge into the new default branch. |
| 272 | - New clones check out the new default branch. Existing clones keep the |
| 273 | branches they have; run `git remote set-head origin -a` to update what |
| 274 | `origin/HEAD` points at. |
| 275 | - [Branch protection](/guides/git/#protected-branches) covers the new |
| 276 | default branch. |
| 277 | |
| 278 | From the API, send `default_branch` to |
| 279 | [`PATCH /repos/{owner}/{name}`](/reference/api/repositories/update-repo/): |
| 280 | |
| 281 | ```sh |
| 282 | curl -X PATCH https://api.g1t.sh/repos/acme/rocket \ |
| 283 | -H "Authorization: Bearer $G1T_TOKEN" \ |
| 284 | -H "Content-Type: application/json" \ |
| 285 | -d '{"default_branch": "trunk"}' |
| 286 | ``` |
| 287 | |
| 288 | Over MCP, it is the `repository` tool's `update` action, with `repo` and |
| 289 | `default_branch`. When the |
| 290 | same call changes other fields, they are changed first. |
| 291 | |
| 292 | ## Rename a branch |
| 293 | |
| 294 | 1. Open the repository's **Settings → Repository**. |
| 295 | 2. Under **Branches → Rename a branch**, pick the **Branch** and type its |
| 296 | **New name**. |
| 297 | 3. Choose **Rename branch**. |
| 298 | |
| 299 | Or, on the repository's [Branches page](/guides/git/#the-branches-page), |
| 300 | open the branch's **⋯** menu and choose **Rename branch**. |
| 301 | |
| 302 | Renaming the default branch needs Admin. It stays the default under its |
| 303 | new name. When a branch is renamed: |
| 304 | |
| 305 | - Open pull requests from it follow it to the new name. |
| 306 | - Web addresses that name the old branch, such as |
| 307 | `g1t.sh/acme/rocket/tree/old-name`, redirect to the new one until a |
| 308 | branch with the old name is made again. |
| 309 | - Git remotes do not follow. In each clone, rename the local branch and |
| 310 | track the new one: |
| 311 | |
| 312 | ```sh |
| 313 | git branch -m old-name new-name |
| 314 | git fetch origin |
| 315 | git branch -u origin/new-name new-name |
| 316 | git remote set-head origin -a |
| 317 | ``` |
| 318 | |
| 319 | From the API, call |
| 320 | [`POST /repos/{owner}/{name}/branches/{branch}/rename`](/reference/api/repositories/rename-branch/) |
| 321 | with `new_name`. A branch name with slashes goes in the path URL-encoded, |
| 322 | as one segment: `feature/login` is `feature%2Flogin`. |
| 323 | |
| 324 | ```sh |
| 325 | curl -X POST https://api.g1t.sh/repos/acme/rocket/branches/feature%2Flogin/rename \ |
| 326 | -H "Authorization: Bearer $G1T_TOKEN" \ |
| 327 | -H "Content-Type: application/json" \ |
| 328 | -d '{"new_name": "feature/sign-in"}' |
| 329 | ``` |
| 330 | |
| 331 | Over MCP, it is the `repository` tool's `rename_branch` action, with |
| 332 | `repo`, `branch` and `new_name`. |
| 333 | |
| 334 | ## Rename a repository |
| 335 | |
| 336 | 1. Open the repository's **Settings → Repository**. |
| 337 | 2. Under **Name**, type the new name. It shows the new address. |
| 338 | 3. Choose **Rename**. |
| 339 | |
| 340 | A name is lowercase letters, digits, dots, hyphens and underscores, up to |
| 341 | 100 characters. It cannot start with a dot or end in `.git`, and no other |
| 342 | repository in the workspace may have it, including one that was |
| 343 | [recently deleted](#restore-a-repository). |
| 344 | |
| 345 | Everything stays with the repository: its git data, issues, pull requests, |
| 346 | workflow runs, deployments, settings, secrets and webhooks. Its old address |
| 347 | keeps working, the same way as after a |
| 348 | [transfer](/guides/transferring-repositories/#old-addresses): |
| 349 | |
| 350 | | | Behaviour | |
| 351 | | --- | --- | |
| 352 | | Web pages | A permanent redirect (`301`) to the same page at the new address. | |
| 353 | | `git clone`, `fetch`, `pull` and `push` | Redirected to the new remote. Git follows it and prints a warning each time. | |
| 354 | | API and MCP | A call that names the repository by its old name runs against it under its new name. | |
| 355 | |
| 356 | Its project follows: a project that had the repository's name takes the |
| 357 | new one, unless another project in the workspace already has it, and its |
| 358 | deployed apps are built again under the new name while the old addresses |
| 359 | redirect. |
| 360 | |
| 361 | A redirect stops as soon as a repository is made at the old address. |
| 362 | Update your remotes rather than relying on it: |
| 363 | |
| 364 | ```sh |
| 365 | git remote set-url origin https://g1t.sh/acme/launcher.git |
| 366 | ``` |
| 367 | |
| 368 | From the API, call |
| 369 | [`POST /repos/{owner}/{name}/rename`](/reference/api/repositories/rename-repo/) |
| 370 | with `name`: |
| 371 | |
| 372 | ```sh |
| 373 | curl -X POST https://api.g1t.sh/repos/acme/rocket/rename \ |
| 374 | -H "Authorization: Bearer $G1T_TOKEN" \ |
| 375 | -H "Content-Type: application/json" \ |
| 376 | -d '{"name": "launcher"}' |
| 377 | ``` |
| 378 | |
| 379 | Over MCP, it is the `repository` tool's `rename` action, with `repo` and |
| 380 | `name`. |
| 381 | |
| 382 | ## Change who can see a repository |
| 383 | |
| 384 | A public repository can be seen and cloned by anyone, signed in or not. A |
| 385 | private one can be seen only by people with a |
| 386 | [role](/guides/access-and-roles/) on it. |
| 387 | |
| 388 | 1. Open the repository's **Settings → Repository**. |
| 389 | 2. Under **Danger zone → Change visibility**, choose **Make private** or |
| 390 | **Make public**. |
| 391 | 3. Read what changes, type the repository's full name (`<workspace>/<repo>`) |
| 392 | to confirm, and choose **Make private** or **Make public** again. |
| 393 | |
| 394 | A [fork](/concepts/forks/) is as visible as the repository it came from and |
| 395 | cannot change on its own: [detach it](/guides/forking-repositories/#detach-a-fork) |
| 396 | first. When a repository with forks is made public or private, its forks |
| 397 | are detached and keep the visibility they had. |
| 398 | |
| 399 | | | Making it public | Making it private | |
| 400 | | --- | --- | --- | |
| 401 | | 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](/guides/access-and-roles/#the-base-permission) is None), and anyone given a role on it. Anyone else gets a page that says it does not exist. | |
| 402 | | Search and Explore | It is added to [search](/guides/search/) and Explore for everyone. | It leaves search and Explore for everyone outside the workspace. | |
| 403 | | Link previews | Links to it show a preview card with its name and its project's description. | Links to it stop showing a preview card. | |
| 404 | | 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](/guides/usage-and-billing/#what-is-free). | |
| 405 | |
| 406 | Nothing else changes: its address, members, settings, secrets, webhooks |
| 407 | and deployments stay as they are. |
| 408 | |
| 409 | From the API, call |
| 410 | [`POST /repos/{owner}/{name}/visibility`](/reference/api/repositories/set-repo-visibility/) |
| 411 | with `private` and its full name in `confirm`: |
| 412 | |
| 413 | ```sh |
| 414 | curl -X POST https://api.g1t.sh/repos/acme/rocket/visibility \ |
| 415 | -H "Authorization: Bearer $G1T_TOKEN" \ |
| 416 | -H "Content-Type: application/json" \ |
| 417 | -d '{"private": true, "confirm": "acme/rocket"}' |
| 418 | ``` |
| 419 | |
| 420 | Over MCP, it is the `repository` tool's `set_visibility` action, with |
| 421 | `repo`, `private` and `confirm`. `private` on |
| 422 | [`PATCH /repos/{owner}/{name}`](/reference/api/repositories/update-repo/) |
| 423 | makes the same change without the confirmation, for people with Admin. |
| 424 | |
| 425 | ## Archive a repository |
| 426 | |
| 427 | Archiving makes a repository read-only. Use it for work that is finished |
| 428 | but should stay readable. |
| 429 | |
| 430 | 1. Open the repository's **Settings → Repository**. |
| 431 | 2. Under **Danger zone**, choose **Archive**. |
| 432 | 3. Read what changes and choose **Archive** again. |
| 433 | |
| 434 | While it is archived: |
| 435 | |
| 436 | | | | |
| 437 | | --- | --- | |
| 438 | | Pushes and merges | Refused, whatever your role, and for agents too. | |
| 439 | | Issues and pull requests | Locked. They stay readable. | |
| 440 | | Workflows | Do not run. | |
| 441 | | Settings | The ones that change the repository are turned off. | |
| 442 | | Deployments | Keep serving. | |
| 443 | | Who can see it | Unchanged. Anyone who could see it still can, and clone it. | |
| 444 | |
| 445 | Its page says it is archived, and so do its project's card on the |
| 446 | workspace overview and its card on [Explore](/guides/search/#explore), |
| 447 | with an **archived** label. To undo it, someone with Admin chooses **Unarchive** |
| 448 | in the same place. Pushes, merges, issues, pull requests and workflows |
| 449 | work again; nothing that was refused while it was archived runs |
| 450 | by itself. |
| 451 | |
| 452 | From the API, call |
| 453 | [`POST /repos/{owner}/{name}/archive`](/reference/api/repositories/archive-repo/) |
| 454 | or |
| 455 | [`POST /repos/{owner}/{name}/unarchive`](/reference/api/repositories/unarchive-repo/): |
| 456 | |
| 457 | ```sh |
| 458 | curl -X POST https://api.g1t.sh/repos/acme/rocket/archive \ |
| 459 | -H "Authorization: Bearer $G1T_TOKEN" |
| 460 | ``` |
| 461 | |
| 462 | Over MCP, they are the `repository` tool's `archive` and `unarchive` |
| 463 | actions, with `repo`. The |
| 464 | repository's `archived_at` field says when it was archived, and is null |
| 465 | when it is not. |
| 466 | |
| 467 | ## Delete a repository |
| 468 | |
| 469 | Deleting takes a repository away at once, but an owner can restore it for |
| 470 | 30 days. After that it is purged: removed for good, its git data with it. |
| 471 | |
| 472 | 1. Open the repository's **Settings → Repository**. |
| 473 | 2. Under **Danger zone**, choose **Delete**. |
| 474 | 3. Read what happens, type the repository's full name |
| 475 | (`<workspace>/<repo>`) to confirm, and choose **Delete repository**. |
| 476 | |
| 477 | | | While it is deleted | When it is purged | |
| 478 | | --- | --- | --- | |
| 479 | | Its pages, git remote and API | Answer as if it did not exist, for everyone. | The same. | |
| 480 | | Its name | Stays taken: no repository can be made at its address. | Free to use again. | |
| 481 | | Workflows | Stop, and do not start. | | |
| 482 | | Deployments | Taken down. Its `g1t.page` addresses stop serving. | Removed. | |
| 483 | | Custom domains | Kept, and serve nothing. | Removed. | |
| 484 | | Search | Drops it. | | |
| 485 | | Webhooks | The workspace's webhooks are sent `repo.deleted`. | Sent `repo.purged`. | |
| 486 | | Storage | Stops counting toward the workspace's storage. | | |
| 487 | | Git data, issues, pull requests, settings, secrets | Kept, for restoring. | Removed, and cannot be recovered. | |
| 488 | |
| 489 | Its entries in the [audit log](/guides/audit-log/) are kept, as for |
| 490 | anything else. |
| 491 | |
| 492 | From the API, call |
| 493 | [`DELETE /repos/{owner}/{name}`](/reference/api/repositories/delete-repo/) |
| 494 | with its full name in `confirm`. It returns the deleted repository with |
| 495 | `purge_after`, when it will be purged: |
| 496 | |
| 497 | ```sh |
| 498 | curl -X DELETE https://api.g1t.sh/repos/acme/rocket \ |
| 499 | -H "Authorization: Bearer $G1T_TOKEN" \ |
| 500 | -H "Content-Type: application/json" \ |
| 501 | -d '{"confirm": "acme/rocket"}' |
| 502 | ``` |
| 503 | |
| 504 | Over MCP, it is the `repository` tool's `delete` action, with `repo` and |
| 505 | `confirm`. |
| 506 | |
| 507 | To move a repository to another workspace instead of deleting it, see |
| 508 | [transferring a repository](/guides/transferring-repositories/). |
| 509 | |
| 510 | ## Restore a repository |
| 511 | |
| 512 | A workspace's recently deleted repositories are listed for its owners |
| 513 | under **Recently deleted** in the workspace's **Settings → Repositories**, |
| 514 | at `g1t.sh/<workspace>/-/repositories`, each with who deleted it and when |
| 515 | it will be purged. |
| 516 | |
| 517 | 1. Open the workspace's **Settings → Repositories**. |
| 518 | 2. Under **Recently deleted**, find the repository and choose **Restore**. |
| 519 | |
| 520 | It comes back at the address it had, as it was when it was deleted: git |
| 521 | data, issues, pull requests, settings, secrets and webhooks. Its |
| 522 | deployments are built again, and its custom domains serve them once they |
| 523 | are live. Workflows run again for new work; they do not catch up on what |
| 524 | they missed. |
| 525 | |
| 526 | From the API, list them with |
| 527 | [`GET /workspaces/{workspace}/repos/deleted`](/reference/api/repositories/list-deleted-repos/) |
| 528 | (the `repository` tool's `list_deleted` action over MCP), then call |
| 529 | [`POST /repos/{owner}/{name}/restore`](/reference/api/repositories/restore-repo/) |
| 530 | with the path it had (the `restore` action): |
| 531 | |
| 532 | ```sh |
| 533 | curl https://api.g1t.sh/workspaces/acme/repos/deleted \ |
| 534 | -H "Authorization: Bearer $G1T_TOKEN" |
| 535 | |
| 536 | curl -X POST https://api.g1t.sh/repos/acme/rocket/restore \ |
| 537 | -H "Authorization: Bearer $G1T_TOKEN" |
| 538 | ``` |
| 539 | |
| 540 | ### Purge a repository now |
| 541 | |
| 542 | To remove a deleted repository for good before its 30 days are up, and |
| 543 | free its name: |
| 544 | |
| 545 | 1. Open the workspace's **Settings → Repositories**. |
| 546 | 2. Under **Recently deleted**, choose **Delete permanently** beside it. |
| 547 | 3. Type its full name (`<workspace>/<repo>`) to confirm, and choose |
| 548 | **Delete permanently** again. |
| 549 | |
| 550 | This cannot be undone. From the API, call |
| 551 | [`POST /repos/{owner}/{name}/purge`](/reference/api/repositories/purge-repo/) |
| 552 | with its full name in `confirm`: |
| 553 | |
| 554 | ```sh |
| 555 | curl -X POST https://api.g1t.sh/repos/acme/rocket/purge \ |
| 556 | -H "Authorization: Bearer $G1T_TOKEN" \ |
| 557 | -H "Content-Type: application/json" \ |
| 558 | -d '{"confirm": "acme/rocket"}' |
| 559 | ``` |
| 560 | |
| 561 | Over MCP, it is the `repository` tool's `purge` action, with `repo` and |
| 562 | `confirm`. |
| 563 | |
| 564 | A workspace whose only repositories are recently deleted ones can itself |
| 565 | be [deleted](/guides/workspaces/#delete-a-workspace); they are purged with |
| 566 | it. |
| 567 | |
| 568 | ## When a change is refused |
| 569 | |
| 570 | | Response | Why | What to do | |
| 571 | | --- | --- | --- | |
| 572 | | `401 unauthenticated` | No token, or one that is not valid. | Send a personal access token. | |
| 573 | | `403 forbidden` | You are not an owner, for a change that needs one; or g1t's token was used. | Ask an owner of the workspace. | |
| 574 | | `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. | |
| 575 | | `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. | |
| 576 | | `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. | |
| 577 | | `402 payment_required` | Making it private would take a free workspace's private storage over 1 GB. | Start [the g1t plan](/guides/usage-and-billing/#the-g1t-plan), or make room first. | |
| 578 | |
| 579 | Each refusal comes with a message that says what to do. |
| 580 | |
| 581 | ## From the API and MCP |
| 582 | |
| 583 | | Route | MCP | What it does | |
| 584 | | --- | --- | --- | |
| 585 | | [`GET /repos/{owner}/{name}/languages`](/reference/api/repository-insights/get-languages/) | `repository` `languages` | Its languages by bytes, with `color` and `percent`. | |
| 586 | | [`GET /repos/{owner}/{name}/contributors`](/reference/api/repository-insights/list-contributors/) | `repository` `contributors` | Its contributors with `kind`, `commits` and `weeks`. | |
| 587 | | [`GET /repos/{owner}/{name}/license`](/reference/api/repository-insights/get-license/) | `repository` `license` | Its license's `spdx_id`, `name` and `path`. | |
| 588 | | [`GET /repos/{owner}/{name}/stargazers`](/reference/api/stars/list-stargazers/) | `repository` `stargazers` | Who starred it, newest first. | |
| 589 | | [`PUT /user/starred/{owner}/{name}`](/reference/api/stars/star-repo/) | `repository` `star` | Star it. `DELETE` takes the star back; `GET` says whether you did. | |
| 590 | | [`GET /user/starred`](/reference/api/stars/list-starred/) | `repository` `list_starred` | What you starred. | |
| 591 | |
| 592 | Answers read from the default branch say which `commit` they are for and |
| 593 | the `head` now; `pending` is true until the first is read. Stars take the |
| 594 | `account:read` and `account:write` scopes; the rest `repo:read`. |
| 595 | |
| 596 | ## Events and the audit log |
| 597 | |
| 598 | Each change is sent to [webhooks](/guides/webhooks/#events) and recorded |
| 599 | in the [audit log](/guides/audit-log/): |
| 600 | |
| 601 | | Change | Event | |
| 602 | | --- | --- | |
| 603 | | Website, topics, protection | `repo.updated` | |
| 604 | | Visibility | `repo.visibility_changed` | |
| 605 | | Rename | `repo.renamed` | |
| 606 | | Default branch | `repo.default_branch_changed` | |
| 607 | | Branch rename | `branch.renamed` | |
| 608 | | Branch made or deleted | `git.push`, `git.deleted`; in the audit log, `branch.created`, `branch.deleted` | |
| 609 | | Archive, unarchive | `repo.archived`, `repo.unarchived` | |
| 610 | | Transfer | `repo.transferred` | |
| 611 | | Delete, restore, purge | `repo.deleted`, `repo.restored`, `repo.purged` | |