Rename, archive or delete a repository#

A repository has the wrong name, its work is done and it must stay as it is, or it must go. You also want references like JIRA-123 to link to your tracker, and new repositories to start with a .gitignore and a license.

Each step below works on its own. Do only the steps that you need. Steps 1 to 4 are for admins of the repository. The settings are at Settings on the repository page (/<owner>/<repo>/settings).

1. Rename it#

On the web:

1. Open the repository, then Settings.
2. Under General, type the new name in Repository name.
3. Click Rename.

In a terminal, in your clone:

src repo rename app2 --yes

• The old name keeps leading to the repository, for links and for git remotes, until another repository of the owner takes that name.
• In a clone, src points the git remote at the new name. With -R acme/app, it renames that repository and changes no remote.
• A name that another repository of the owner has is refused.

2. Archive it#

An archived repository is read-only for everyone:

• Nobody can push.
• Nobody can open issues or pull requests, or comment on them.
• No CI run and no factory run starts.

Everyone who can read it still reads and clones it. Admins can still change its settings, rename it, unarchive it and delete it.

On the web:

1. Open Settings, then go to Danger zone.
2. Click Archive.
3. In the dialog, click Archive repository.

In a terminal:

src repo archive acme/old --yes
src repo unarchive acme/old --yes

The repository page then shows This repository is archived, and its name has the label Archived. A write to it gets the error "This repository was archived so it is read-only."

3. Delete it#

A deleted repository does not come back: its git data, its issues and its pull requests go.

On the web:

1. Open Settings, then go to Danger zone.
2. In Type acme/old to confirm, type the full name of the repository.
3. Click Delete this repository.

In a terminal:

src repo delete acme/old --yes

• A repository with forks cannot be deleted, because the forks read their history from it. Delete the forks first.
• src repo delete needs the name of the repository. It never deletes the repository of your clone without one.
• Only people delete repositories. An agent token is refused.

4. Link references to another tool#

Your team writes JIRA-123 in issues and comments. An autolink turns each such reference into a link.

On the web:

1. Open Settings, then click Autolinks (/<owner>/<repo>/settings/autolinks).
2. In Key prefix, type JIRA-.
3. In URL template, type https://jira.example.com/browse/JIRA-<num>. The reference goes in place of <num>.
4. If a reference has digits only, turn off Letters in references.
5. Click Add autolink.

In a terminal:

src repo autolink create JIRA- "https://jira.example.com/browse/JIRA-<num>"
src repo autolink list

• --numeric makes an autolink for references with digits only.
• src repo autolink delete <id> --yes deletes one.

5. Start a new repository with a .gitignore and a license#

On the web:

1. Open New repository.
2. In .gitignore template, pick a template, for example Node.
3. In License, pick a license, for example MIT License.
4. Click Create repository.

These two fields show only when Import from GitHub is off.

In a terminal:

src repo license list
src repo create acme/api --private --gitignore Node --license mit

• The first commit of the new repository has the .gitignore and a LICENSE file. The LICENSE has the current year and the name of the owner.
• src repo gitignore list lists the template names. A name is case-sensitive: Node, not node.
• src repo license list lists the license keys, like mit or apache-2.0.

Done#

The repository has the name that you want. An archived repository stays readable, and nobody pushes to it or comments on it. JIRA-123 in an issue is a link to your tracker. Each new repository starts with the files that it needs.

Later: the description and the default branch#

People with the maintain role or more change these under General in Settings, or in a terminal:

src repo edit --description "The API of Acme" --default-branch main

A default branch that does not exist is refused.

Later: REST and MCP#

An agent or a script does the same work over REST or MCP, with the same rules. A path that starts with ... is under /api/v1/repos/{owner}/{repo}.

You want to	REST	MCP tool
Rename	POST .../rename, with { "name" }	rename_repo
Archive or unarchive	PUT or DELETE .../archive	archive_repo
Delete	DELETE /api/v1/repos/{owner}/{repo}	delete_repo
Change the description or the default branch	PATCH /api/v1/repos/{owner}/{repo}	update_repo
List, add or delete autolinks	GET or POST .../autolinks, DELETE .../autolinks/{id}	list_autolinks, create_autolink, delete_autolink
Create a repository with templates	POST /api/v1/repos, with gitignore and license	create_repo

GET /api/v1/gitignore/templates and GET /api/v1/licenses list the templates. Use the REST API has the other routes.