Skip to main content

Renaming Repositories

A safe-rename playbook for GitHub repositories on the p6m platform.

Renaming a repository on GitHub is straightforward — in most cases, the application namespace is already hardcoded in your workflow and the rename has no platform impact. This guide walks you through verifying that and handling the cases where it doesn't.

GitHub's Official Docs

For the basic mechanics (Settings → Repository name → Rename), required permissions, and how GitHub's built-in redirects work, see Renaming a repository in the GitHub docs.

Before You Start​

  • Notify the team (Teams, Slack, Standup)
  • Pick a low-traffic window
  • Confirm you have admin access to the repo, the .platform repo, and ArgoCD
  • Find the application in ArgoCD and verify it is healthy/synced in all environments (dev, stg, prd) — you want a known-good baseline before making changes
  • Identify which workflow pattern you're using (direct dispatch or upstream reusable workflow)
  • If the repo is a reusable GitHub Action (p6m-actions/*), identify and plan updates for all consumers before renaming

How Our Platform Uses the Repository Name​

The application namespace — which determines the Kubernetes namespace, the ArgoCD application name, the .platform/kubernetes/ folder path, and the container image name — is typically set at project creation time by the archetype. In most cases it's hardcoded in your workflow and does not change when you rename the repo.

However, some workflows derive the namespace from the repository name. If yours does, renaming the repo without pinning the namespace first will result in a duplicate deployment under the new name. The procedure below covers how to check and handle both cases.

One namespace per repo

Each application namespace must belong to exactly one repository. If two repos share the same namespace, their pipelines will overwrite each other's deployments — only one will end up running at a time.

Rename Procedure​

Verify (or Pin) the Current Namespace​

Check that your CI/CD pipeline won't pick up the new repo name as the namespace. If the namespace is already hardcoded (which is the default for archetype-generated projects), no change is needed. See How the Namespace Is Set for code examples of both patterns.

  • Direct dispatch step (platform-application-manifest-dispatch in your workflow): Check the directory-name parameter. If it's already hardcoded, you're good. If it's derived from github.repository, hardcode it to the current name.
  • Upstream reusable workflow (calling a shared workflow from p6m-dev/github-actions): Check whether a PLATFORM_NAMESPACE input is set. If not, and the workflow defaults to the repo name, add it set to the current repository name.

Rename the Repository​

  1. Merge the workflow change (if any) to main.
  2. Rename the repository in GitHub Settings.
  3. Run the CI/CD pipeline. Because the namespace is pinned, everything deploys to the same namespace as before.
  4. Have developers update their local git remotes.

Validate​

  • ArgoCD application is still synced and healthy in all environments
  • CI/CD workflows trigger correctly on push to the renamed repo
  • Pods are running and healthy — no disruption
  • Developers have updated their local git remotes

Rollback​

If something goes wrong, rename the repo back to the old name. Since the namespace never changed, there's nothing else to undo.

Also Changing the Namespace?​

If you want the Kubernetes namespace, ArgoCD app, and image name to match the new repo name, that's a separate effort — effectively a namespace migration. Get the rename done and stable first, then plan the namespace change deliberately.

See Changing Your Application Namespace for the full procedure.

Out of Scope​

  • Moving repos between GitHub orgs — different (larger) process with additional implications
  • Performing renames on behalf of teams — this is self-service documentation