How to remove repository from bitbucket: UI and API Guide

Meta description: Need to remove repository from Bitbucket without breaking your workflow? Here’s the safe UI path, API cleanup approach, and soft-delete alternative.

You open Bitbucket to find the same mess teams often collect over time. A prototype nobody shipped. A repo from the pre-monorepo days. A personal sandbox that turned into shared infrastructure and then got abandoned. They keep showing up in search, in CI configs, and in conversations where nobody is fully sure whether the repo is still alive.

That’s usually when someone decides to remove repository from Bitbucket and treat it like a two-click cleanup task. It isn’t. Delete the wrong repo and you don’t just lose code. You lose commit history, pull requests, pipeline data, and every URL that pointed at it.

For teams trying to keep release engineering clean, old repos are friction. If you care about smoother git commits and deployments, repo cleanup is part of that discipline, not an afterthought.

When a Git Repo Reaches End-of-Life

A repo usually dies long before anyone deletes it. The project gets folded into another service. The migration finishes. Nobody pushes new commits, but the repo still exists, still looks official, and still catches traffic from developers who don’t know the history.

The awkward part is that stale repos often remain connected to real systems. A Jenkins job still clones them. A deployment script still points at the old remote. Someone’s local checkout still has origin set to the dead URL. By the time you notice, “unused” no longer means isolated.

The common failure mode

A lead or admin sees clutter and starts deleting one repo at a time from the UI. That works fine until one of those repos still matters indirectly. The deletion itself is fast. The cleanup after it usually isn’t.

Practical rule: Treat repo deletion like infrastructure teardown. Inventory dependencies first, then remove the hosting object.

Bitbucket adds enough friction to signal that this is destructive, but not enough to save you from a bad decision. The platform will delete the repository. It won’t rewrite your pipeline files, fix your webhooks, or tell your team why their next push failed.

What counts as end-of-life

A repo is a deletion candidate when:

• The source of truth moved to another repo or monorepo.
• The service was retired and no job, webhook, or deployment references it anymore.
• The repo is orphaned and nobody on the team owns it.
• The code needs a hard reset, but you still have to decide whether deletion or a history wipe is the better move.

That last case matters more than people think. Sometimes the right answer isn’t deletion at all.

Permissions, Prerequisites, and The Archive Option

The first thing to check isn’t the delete button. It’s whether you can even see it.

Only repository owners and admins can delete a Bitbucket repository. That’s a core security rule, and Bitbucket keeps it tight on purpose. Community reports also show that up to 20% of deletion-related support queries come from users who don’t have the required permissions and can’t find the settings in team workspaces (Atlassian Community discussion on missing settings and permissions).

If you’re in a team workspace with Developer or Write access, you may not see the settings path needed for deletion at all. That isn’t a UI bug. It’s how Bitbucket blocks unauthorized data loss.

What to check before you touch anything

If the delete option is missing, check:

• Your workspace role: You may have push rights but not admin rights.
• Repo ownership: On older or inherited repos, ownership can be murky.
• Shared responsibility: In team repos, the workspace admin may be the only person who can remove it.
• Dependencies outside Bitbucket: CI jobs, deploy hooks, and internal docs often outlive the code.

A lot of engineering teams need better discipline around source ownership before cleanup even starts. If your process is already shaky, this guide on managing code across DevOps workflows is worth a read because deletion failures usually start as ownership failures.

Deletion vs archive

When a repo is stale but you’re not fully confident it’s dead, archive first. Deletion is final. Archiving buys you distance without erasing context.

Deletion removes the hosted repository and its associated data. Archive keeps the repository available for reference while taking it out of active circulation.

Archive when the repo still has diagnostic value. Delete when keeping it around creates more risk than removing it.

A short decision filter

Choose archive if:

• You might need to inspect old code later.
• Past pull requests still matter as engineering context.
• You haven’t audited every integration yet.

Choose delete if:

• The replacement repo is live and documented.
• Your CI and automation no longer reference the old remote.
• The repo’s continued existence creates confusion.

Most bad deletions happen because teams skip that distinction.

How to Remove a Repository Using the Bitbucket UI

If you’re removing one repo and you have the right permissions, the UI is still the quickest path. What matters is understanding where the point of no return is.

The Bitbucket flow has stayed consistent for years. You go to Repository settings, then the repository management area, then Delete repository. In many cases Bitbucket asks you to type the repository name as confirmation before it proceeds.

Bitbucket Cloud

For Bitbucket Cloud, the path usually looks like this:

1. Open the repository.
2. Go to Repository settings.
3. Find the deletion area, often shown in the lower-risk or danger area of settings.
4. Select Delete repository.
5. Confirm by typing the repository name if prompted.

The last confirmation step exists for a reason. Once you confirm, the repository is gone from the UI immediately. Any bookmarked URLs pointing to it stop being valid.

Bitbucket Data Center or Server

The interface differs a bit, but the practical flow is the same:

1. Open the repository under the project.
2. Go to Repository settings.
3. Open Manage repository.
4. Select Delete repository.
5. Confirm the action.

What actually disappears

Deletion is not just “remove the files.” Bitbucket permanently removes the repository and the data attached to it, including:

• Source and history: All files and commit history in that hosted repo.
• Review context: Pull requests and associated metadata.
• Automation state: Pipeline data tied to the repository.
• References: Existing repository URLs become invalid immediately.

That invalid URL problem is where a lot of downstream breakage starts. Your hosted Git remote disappears before your surrounding systems have caught up.

If you’re hesitating at the confirmation prompt, stop and archive instead. That hesitation usually means you haven’t checked enough dependencies.

What doesn’t get cleaned up for you

The UI delete flow won’t help with:

• Local clones on developer machines
• Jenkinsfiles or deployment jobs with hardcoded remotes
• Webhook targets that still expect events
• Internal docs linking to the old repository
• Fork governance and any team assumptions built around the original repo

For a single repo, the UI is fine. For a cleanup campaign across a workspace, it’s a poor tool. Clicking through settings screens one by one doesn’t scale, and it’s too easy to miss a pattern like orphaned repos or migration leftovers.

Automating Cleanup with the REST API

UI deletion is fine for one repo. It’s the wrong tool when you’re cleaning up a project migration, expired test environments, or a workspace full of old service repos.

Bitbucket Cloud’s UI has no native bulk or scheduled deletion option, which is why admins end up using the API for obsolete or orphaned repositories. For Bitbucket Data Center and Server, Atlassian documents DELETE /rest/api/latest/projects/{projectKey}/repos/{repositorySlug} as the official scripted cleanup path, and that endpoint schedules the repository for removal (Atlassian Data Center REST API deletion guidance).

Data Center and Server example

For Data Center or Server, the documented pattern is a DELETE request against the repository resource:

curl -X DELETE -u Admin \
  "https://<baseurl>/rest/api/1.0/projects/TES/repos/testrepo01"

In Atlassian’s documented flow, deletion is scheduled rather than handled as an interactive UI event. That matters if you’re writing cleanup tooling and expecting immediate disappearance.

Cloud example

For Bitbucket Cloud, teams commonly use the v2.0 repository endpoint with a delete request when they need programmatic cleanup:

curl -X DELETE -u user:app_password \
  "https://api.bitbucket.org/2.0/repositories/<workspace>/<repo_slug>"

Use an app password or the auth method your environment already trusts. Don’t drop personal credentials into scripts committed to source control.

Bulk deletion pattern

The useful part isn’t the one-liner. It’s wrapping deletion in a repeatable script so you can review targets before you remove them.

#!/usr/bin/env bash
set -euo pipefail

WORKSPACE="example-workspace"
AUTH_USER="user"
AUTH_TOKEN="app-password"

while read -r REPO; do
  [ -z "$REPO" ] && continue
  echo "Deleting ${REPO}"
  curl -sS -X DELETE -u "${AUTH_USER}:${AUTH_TOKEN}" \
    "https://api.bitbucket.org/2.0/repositories/${WORKSPACE}/${REPO}"
done < repos-to-delete.txt

That file-driven approach is safer than generating targets inline from memory. It gives you a review surface. Teammates can diff the list before anything destructive runs.

What works better than blind deletion

A few habits make API cleanup less dangerous:

• Dry-run the repo list: Print candidate repos before you call DELETE.
• Archive first when possible: On Data Center, archival is part of the documented admin workflow before deletion.
• Log every action: Keep a timestamped record of what your script attempted.
• Separate discovery from deletion: One script lists repos. Another one removes reviewed targets.

If you work with REST semantics often, Goptimise’s PUT vs PATCH analysis is a good refresher on update behavior. It’s not about Bitbucket specifically, but it helps when you’re building internal admin tooling that mixes destructive and non-destructive API calls.

For cleanup scripts, the dangerous bug isn’t usually authentication. It’s a bad target list.

Where automation helps most

API cleanup is worth it when you’re dealing with:

• Workspace migrations
• Orphaned repos left by departed users
• Ephemeral test repos
• Policy-driven cleanup jobs for old environments

If your team already automates repo-adjacent tasks, it’s worth keeping that same mindset for localization or content repos too. The TranslateBot Python API usage docs are a good example of the kind of repeatable, scriptable workflow engineers usually prefer over portal clicks.

The main trade-off is obvious. Automation reduces toil, but it also scales mistakes. That’s why deletion scripts need review just like infrastructure code.

Alternative Wipe a Repository Without Deleting It

Sometimes you don’t want to remove repository from Bitbucket at all. You want the URL, permissions, pull request context, and repo settings to stay put, but you need the codebase reset to an empty state.

That’s where the orphan-branch method is useful. It wipes content and history from the branch you force-push, while keeping the Bitbucket repository object alive. Community guidance around this method is consistent on one key point: use git checkout --orphan and git push --force, and temporarily disable branch protection first or the push will fail (Atlassian Community discussion on wiping repo contents without deleting the repo).

When this is the better move

Use a history wipe when:

• The repo URL is embedded in CI or integrations you don’t want to rebuild.
• You need to restart the codebase but keep Bitbucket metadata like pull requests.
• You want a clean branch state without deleting and recreating the repository.

Deletion removes the host object. A wipe keeps the shell and replaces the contents.

A working sequence

Start from a fresh local clone or a clean checkout:

git clone <repo-url>
cd <repo>
git checkout --orphan temp-branch

If you want the repo to become effectively empty, remove tracked files and create a minimal commit:

git rm -rf .
touch README.md
git add README.md
git commit -m "Wipe history"

Then push the orphan branch with force:

git push origin temp-branch --force

After that, switch Bitbucket’s main branch to the new branch and remove the old branch references in the repository settings. Locally, clean up remote references too:

git remote prune origin

The step people miss

Protected branches will block the force-push. If your main branch has branch permissions, disable them temporarily in Bitbucket before pushing, then restore the protections after the new branch becomes the main line.

A repo wipe is safer for integrations, but riskier for operator error. Force-push the wrong branch and you create a different mess.

The operational upside is that CI jobs tied to the repository’s existence usually keep working after you update branch expectations. That’s often better than delete-and-recreate when your build, deploy, or audit systems are coupled to the repo identity.

If you’re automating translation or release workflows around a long-lived repo, that continuity matters. The TranslateBot command reference follows the same philosophy engineers usually want from tooling. Keep the artifact stable, change only what needs changing.

The Post-Deletion Cleanup Checklist

Deleting the Bitbucket repo is the loud part. The cleanup work after it is where teams either stay clean or create a month of low-grade breakage.

Start with communication. Tell the team the repo is gone, what replaced it if anything did, and which local remotes should be removed. Otherwise someone will spend part of tomorrow debugging a failed push to a URL that no longer exists.

Local and team cleanup

On developer machines, remove or update the old remote:

git remote -v
git remote rm origin

If the code moved to a new repo instead of dying, set the new remote explicitly:

git remote add origin <new-repo-url>

Then audit references in your shared tooling:

• CI configs: Check bitbucket-pipelines.yml, Jenkinsfiles, GitHub Actions mirrors, and any deploy scripts.
• Webhooks: Remove endpoints that were only used by the deleted repo.
• Docs: Update onboarding docs, internal runbooks, and architecture notes.
• Bots and integrations: Verify anything that cloned or scanned the old repo.

Watch for hidden dependencies

The most annoying failures come from systems nobody remembers until they fail. That can be a nightly sync job, a release script in another repo, or a stale dashboard link in an internal wiki.

A good final pass is to search your org’s code and docs for the old repo slug. If you still find references after deletion, you haven’t finished cleanup.

Delete the repo once. Remove the references everywhere.

If your team already automates localization or release tasks in CI, apply the same rigor here. The TranslateBot CI usage docs are a useful example of how to keep repetitive repo-bound work explicit and reviewable in pipeline config instead of tribal knowledge.

The next time you remove repository from Bitbucket, treat it as a small decommission project. That mindset prevents most of the avoidable breakage.

If your Django app ships in multiple languages, the same cleanup mindset applies to localization. Keep translation changes in Git, review diffs, and automate the repetitive parts. TranslateBot helps you translate .po files and model fields from your codebase with a developer-first workflow, so you stay in your editor and CI instead of bouncing through a separate portal.