infrastructure/.gitlab/issue_templates/New Official Project.md

Procedure for adding an official project to GitLab

Details

• Project name: my-example
• Type: MIGRATION or NEW PROJECT
• Current location: git.archlinux.org/my-example.git
• List of users who should get access to the project:

New repo checklist

If you want to add a new official project, here are some guidelines to follow:

1. Evaluate whether the project can sit in the official GitLab Arch Linux group or whether it needs its own group. It only needs its own group if the primary development group is somehow detached from Arch Linux and only losely related (for instance: pacman)
2. Create the project repository. If the repo already exists under another group or namespace, you can transfer it to the targeted group from the admin area. If the repo already exists somewhere outside of this GitLab, you can use the GitLab import function.
3. Add the responsible people to the project in the Members page (https://gitlab.archlinux.org/archlinux/my-example/-/project_members) and give them the Developer role. The idea is to let these people mostly manage their own project while not giving them enough permissions to be able to misconfigure the project.
4. If mirroring to github.com is desired, work through the GitHub.com mirroring checklist below and then return to this one.
5. If the project needs a secure runner to build trusted artifacts, coordinate with the rest of the DevOps team and if found to be reasonable, assign a secure runner to a protected branch of the project.
6. If a secure runner is used, create an MR to make sure the project's .gitlab-ci.yml specifies tags: secure.
7. Make sure that the Push Rules in https://gitlab.archlinux.org/archlinux/my-example/-/settings/repository reflect these values:
   • Reject unverified users: on
   • Reject inconsistent user name: on
   • Reject unsigned commits: on
   • Reject commits that aren't DCO certified: off
   • Do not allow users to remove tags with git push: on
   • Check whether author is a GitLab user: on
   • Prevent pushing secret files: on
   • All of these should be activated by default as per group rules but it's good to check.
8. The Protected Branches in https://gitlab.archlinux.org/archlinux/my-example/-/settings/repository should specify Allowed to merge and Allowed to push as Developers + Maintainers.
9. Disable unneeded project features under Visibility, project features, permissions (https://gitlab.archlinux.org/archlinux/my-example/edit)
   • Always:
     • Users can request access: off
   • Usually, but not always:
     • Repository -> Git Large File Storage (LFS)
     • Container registry
     • Analytics
     • Requirements
     • Security and compliance
     • Wiki
     • Snippets
     • Package registry
     • Model experiments
     • Model registry
     • Monitor
     • Environments
     • Feature flags
     • Infrastructure
10. Disable Activate Service Desk under Service Desk

GitHub.com mirroring checklist

GitLab side

1. If you want to mirror your repository "my-example" from gitlab.archlinux.org to the github.com/archlinux organization, you should create an empty project for your project at github.com/archlinux/my-example or if that's an existing repository, make sure that the current histories of the source and target repository are exactly the same.
2. Go to https://gitlab.archlinux.org/archlinux/my-example/-/settings/repository and open Mirroring repositories. Make sure it has these settings:
   • Git repository URL: ssh://github.com/archlinux/my-example.git
   • Mirror direction: Push
   • Click Detect host keys
   • Authentication method: SSH public key
   • Username: git
   • Keep divergent refs : off
   • Mirror branches : Mirror all branches
3. Click Mirror repository.
4. A new entry will pop up which has a button titled Copy SSH public key. Click that to copy the public key to your clipboard.

GitHub side

1. Log in with your primary GitHub account.
2. Go to https://github.com/archlinux/my-example/settings/access and assign the Admin role to the GitHub account archlinux-github.
3. Log in as the archlinux-github technical user. This is important as otherwise pushes won't be associated correctly.
4. Go to https://github.com/archlinux/my-example/settings/keys and add a new deploy key.
5. Name it "gitlab.archlinux.org" so we know where it's from.
6. Paste the public key you copied from GitLab earlier.
7. Check Allow write access.
8. Click Add key.
9. Verify the push mirror works by clicking the Update now button.
10. In the repository settings on GitHub's side you should disable a few things to clean up the project page:
    • GitHub Actions
    • Wiki
    • Issues
    • Discussions
    • Projects
    • Pull requests
11. In the GitHub description of the mirrored project, append " (read-only mirror)" so that people know it's a mirror.
12. Disable Packages and Deployments from being shown on the main page.
13. In the website field put the full url to the repository on our GitLab.
14. Log in with your primary GitHub account.
15. Go to https://github.com/archlinux/my-example/settings/access and remove the GitHub account archlinux-github
16. Go to https://github.com/orgs/archlinux/teams/read-only-mirrors/repositories and add the repository with write permission