Skip to content

How to set up a new GitHub repo

Setting up a new GitHub repo involves a bunch of different steps to tie into our GitHub workflows.

Setup tasks

If you’re creating a GitHub repo, please make sure you do all of these things.

  • Repo name should use hyphens, not underscores
  • Default branch name should be master, not main
  • Repo collaborators should ONLY use Teams, not individual accounts.
    • Private repos only the “Mathesar Maintainers” should have access, and the access level should be “Maintain”.
    • Public repos should also have the “Mathesar Community Team” added with “Write” permissions.
  • Set up our default GitHub workflows
    • This plugs the repo into the main Mathesar project and sets up some QoL automations
    • See update of sync.yml in this example PR
  • Merge the new PR this generates (example)
  • Set up comprehensive .gitignore file
    • You can copy this from mathesar-private-notes repo since it’s fairly basic and doesn’t involve code-specific things.
  • Set up label & milestone sync
    • This syncs labels and milestones between repos
    • See update of sync-github-labels-milestones.yml in this example
  • Run the workflow above manually in the mathesar repo (so you don’t have to wait a day for labels and milestones to sync)
    • Click “run workflow” here
  • Verify that the new milestones and labels are now available on the new repo
  • Delete default labels created by GitHub that we don’t use (i.e. bug, documentation, enhancement, question etc.)
  • Ensure that repo has access to correct GitHub token for actions
    • This involves going to the org settings > Secrets & variables > Actions and granting the new repo permissions to the MATHESAR_ORG_GITHUB_TOKEN secret
  • Set up repo settings
    • Ensure Issues is on
    • Turn off Wikis
    • Turn off Projects (we use org-level projects, not repo-level projects)
    • Turn off Discussions
    • Pull requests
      • Turn off squash merging
      • Turn off rebase merging
      • Turn on auto-merge
      • Turn on automatically deletion of head branches

Teardown tasks

If you’re removing a GitHub repo, please make sure you do all of these things.

  • Remove all references to the repo from within the .github directory of the main mathesar repo.