migration-cirad

Context

https://forge-inrae.pages.mia.inra.fr/www/

Procedure guidelines

• Re-create groups at Cirad
• For each group
  • Transcribe group parameters
    • Group Description
    • Group Avatar
• For each project in Forgemia
  • Make a direct transfer
    • Import project from URL in Cirad (New Project > Import > Repository by URL)
    • This is possible for public projects (use the https:// URL)
    • For private or internal projects you need the user name and a PAT
    • Alternatively, export project and download export file (Settings > General > Advanced)
      • Import project from file in Cirad (New Project > Import > From GitLab export)
  • Transcribe project parameters that were not exported
    • Projec avatar
    • Project topics (tags and keywords) - no accents allowed in Cirad
    • Visibility parameters of the project and of GitLab pages, if any.
  • Update the URLs in the local repository
    • Rename the old origin

      git remote rename origin old-origin

    • Declare the new remote repository and make sure it's up to date in all branches:

      git remote add origin ssh://git@gitlab.cirad.fr:2022/astre/<projectname>.git
      git branch -m master main  # if the main branch is still called 'master'
      git push -u origin --all
      git push -u origin --tags

      • Notice the explicit specification of the protocol ssh:// before the URL. I've found that Cirad's GitLab fails to correctly parse the custom port specification in the URL, and some git commands (like push) incorrectly try to use the standard port 22. This problem vanishes when explicitly setting the protocol in the URL. Thanks to DeepSeek:

        The SCP-like syntax (git@host:path) is a shorthand for SSH URLs, but it has limitations when custom ports or complex paths are involved. The ssh:// protocol is more explicit and avoids ambiguity, ensuring Git handles the connection correctly.

      • I've also seen the suggestion to specify the port in ~/.ssh/config file as:

        Host gitlab.cirad.fr
        HostName gitlab.cirad.fr
        Port 2022
        User git

        But I think it is not necessary.
  • Special cases
    • If the default branch has been renamed from master to main
      • Configure the default branch at main
        • Set main at Settings > Repository > Branch defaults and save.
        • Add main as a protected branch and configure as desired at Settings > Repository > Protected branches. Unprotect the master branch.
      • Delete the remote branch master

        git push -d origin master

    • If the project is a R package
      • Fix URLs in package files

        sed -i 's/umr-astre\.pages\.mia\.inra\.fr/astre\.gitlab\.cirad\.fr/g' DESCRIPTION 
        sed -i 's/forgemia.inra.fr\/umr-astre/gitlab\.cirad\.fr\/astre/g' DESCRIPTION
        sed -i 's/install_github("Cirad-ASTRE\/<projectname>")/install_gitlab("astre\/<projectname>", host = "gitlab.cirad.fr")/g' README.Rmd

      • Update package web site

        Rscript -e "pkgdown::build_site()"

      • Push changes

        git add .
        git commit -m "Migrate to Cirad"
        git push

    • If GitLab pages is enabled
      • Uncheck Deploy > Pages > Settings > Use unique domain
      • Create a new tracking branch off old-origin/main (or master)

        git checkout -b deprecate-forgemia --track old-origin/main

      • Change the build script .gitlab-ci.yml for pages to write a redirect file

            - mkdir public
            # Redirect to forge Cirad
            # https://docs.gitlab.com/ee/user/project/pages/redirects.html#splats
            - echo '/<project-slug>/* https://astre.gitlab.cirad.fr/<project-slug>/:splat 301' > public/_redirects

      • Push changes

        git add .gitlab-ci.yml
        git commit -m "Migrate to forge Cirad."
        git push --set-upstream old-origin deprecate-forgemia:main # (or master)

      • Revert to branch main (or master)

        git checkout main  # (or master)

    • If alternative CI/CD systems (Travis-CI, Appveyor) are in use
      • Update the continuous integration systems of the repository
  • Deprecate the Forgemia repo
    • Edit the project description to: This repository moved to <url>
    • Archive the project (Settings > General > Advanced > Archive project)