GitHub repository administration policies and best practices

[micaeljtoliveira]

We should agree on a set of GitHub repository administration policies and best practices. There should then be properly documented and enforced.

Here is a first draft. Probably lots of things missing, but it's a way of getting the document started and the discussion going.

Repository administration recommended policies and best practices

Repository administrators

As stated in the GitHub management policy, each repository must have at least two individual administrators. These cannot be teams and there needs to be a very compelling reason for an external user to be made an administrator.

User permissions

We recommend users be given permissions on need basis. That means, for example, that write permissions to a repository should only be given if a user needs those permissions for their work. By default, all members of the ACCESS-NRI GitHub organisation have read permissions to all repositories in the organisation. Read permissions allow users to

• clone a repository
• create issues
• create a pull request from a fork

Write permissions are needed if a user needs to:

• push a branch to the repository (not through a fork)
• use the pre-release infrastructure, as pre-release builds are not triggered for forks
• merge a pull request

Branch protections

At a minimum, the default branch of a repository should always be protected.

Topics

All repositories should be tagged with the appropriate topics for better discoverability.

Private repositories

New repository check-list

To ensure new repositories follow our policies and best-practices, we recommend using the following check-list when creating a new repository:

• Add at least two administrators to the repository
• Add relevant topics
• Give users write permissions, on need basis
• Add branch protection rules

[ccarouge]

I'm happy to rewrite the whole thing with my comments integrated, but I think it's clearer if I just write the bits individually. My additions/edits are in bold

Repository administrators

As stated in the GitHub management policy, each repository must have at least two individual administrators. These cannot be teams and there needs to be a very compelling reason for an external user to be made an administrator. The organisation administrators must validate the reason to add an external user as an repository administrator

User permissions

By default, all members of the ACCESS-NRI GitHub organisation have read permissions to all repositories in the organisation, including all private repositories.

At the end of the section add: Please refer to GitHub documentation for a full description of the permissions for each role and details of other existing roles. Repository administrators are free to assign any role to members for the good management of their repositories.

Maybe we give more info on other roles?

Branch protections
Doesn't @CodeGat have a minimal ruleset?

Topics
All repositories should be tagged with the appropriate topics for better discoverability.

(adding the link to the now-existing wiki page about topics)

[ccarouge]

Private repositories
Private repositories should only be used for licensing reasons. The same policies and best practices apply to private and public repositories, except for branch protection which is not available for private repositories. The documentation for these repositories must clearly indicate which proprietary licence is used and how to get access.

[ccarouge]

Add a recommendation to add admin names in the About section of the repository.

[ccarouge]

Second draft

---

Repository administration recommended policies and best practices

Repository administrators

As stated in the GitHub management policy, each repository must have at least two individual administrators. These cannot be teams and there needs to be a very compelling reason for an external user to be made an administrator. The organisation administrators must validate the reason to add an external user as a repository administrator

User permissions

We recommend users be given permissions on need basis. That means, for example, that write permissions to a repository should only be given if a user needs those permissions for their work. By default, all members of the ACCESS-NRI GitHub organisation have read permissions to all repositories in the organisation, including all private repositories. Read permissions allow users to

• clone a repository
• create issues
• create a pull request from a fork

Write permissions are needed if a user needs to:

• push a branch to the repository (not through a fork)
• use the pre-release infrastructure, as pre-release builds are not triggered for forks
• merge a pull request

Please refer to GitHub documentation for a full description of the permissions for each role and details of other existing roles. Repository administrators are free to assign any role to members for the good management of their repositories.

Branch protections

At a minimum, the default branch of a public repository should always be protected.

Topics

All repositories should be tagged with the appropriate topics for better discoverability.

Private repositories

Private repositories should only be used for licensing reasons. The same policies and best practices apply to private and public repositories, except for branch protection which is not available for private repositories. The documentation for these repositories must clearly indicate which proprietary licence is used and how to get access.

New repository check-list

To ensure new repositories follow our policies and best-practices, we recommend using the following check-list when creating a new repository:

• Add at least two administrators to the repository
• Add relevant topics
• Give users write permissions, on need basis
• Add branch protection rules

[CodeGat]

Regarding the minimal ruleset @ccarouge, I do have something like this:

{
  "id": 13476216,
  "name": "Main Protection",
  "target": "branch",
  "source_type": "Repository",
  "source": "ACCESS-NRI/dev-docs",
  "enforcement": "active",
  "conditions": {
    "ref_name": {
      "exclude": [],
      "include": [
        "~DEFAULT_BRANCH"
      ]
    }
  },
  "rules": [
    {
      "type": "deletion"
    },
    {
      "type": "non_fast_forward"
    },
    {
      "type": "pull_request",
      "parameters": {
        "required_approving_review_count": 1,
        "dismiss_stale_reviews_on_push": true,
        "required_reviewers": [],
        "require_code_owner_review": true,
        "require_last_push_approval": true,
        "required_review_thread_resolution": true,
        "allowed_merge_methods": [
          "merge",
          "squash",
          "rebase"
        ]
      }
    }
  ],
  "bypass_actors": [
    {
      "actor_id": null,
      "actor_type": "OrganizationAdmin",
      "bypass_mode": "always"
    },
    {
      "actor_id": 5,
      "actor_type": "RepositoryRole",
      "bypass_mode": "always"
    }
  ]
}

[ccarouge]

@CodeGat Is it stored somewhere people can pick up and import in their repositories easily? Just wondering if it's feasible to recommend it. Something like: if you are looking for a ready-made set of rules, you can start with <blah>.

[CodeGat]

As a file? No. But, I suppose we could commit it to this repository?

[ccarouge]

@atteggiani Since you weren't at the meeting this morning, one task for everyone is to review the proposed repositories admin policies (2nd version here) before next meeting.

@micaeljtoliveira @CodeGat @rbeucher @atteggiani , speaking of branch protection with Tommy. I feel the text we have in the policy is too vague. Should it say: "At a minimum, the default branch of a public repository should always be write protected." (Preventing direct push)

[atteggiani]

About the minimal rules protection, should we also add requirement for signed commits?

"rules": [
    {
      "type": "deletion"
    },
    {
      "type": "non_fast_forward"
    },
+    {
+      "type": "required_signatures"
+    },
    {

[rbeucher]

I think you are right @ccarouge.

I am not sure about signed commits. I would rather leave the responsibility of checking that the contributors are legit to the person reviewing the PR. (I have been very bad at signing my commits 😅...)

[ccarouge]

(I have been very bad at signing my commits 😅...)

I hear you @rbeucher !

[CodeGat]

I like required signed commits, but they do have their drawbacks, specifically when rebasing changes of multiple authours. I think we should highly recommend that people sign their commits, and be extra careful to vet people that don't - but not make it a requirement.

[atteggiani]

Some minor updates I would suggest to the proposed repositories admin policies (based on the 2nd draft)

---

Repository administration recommended policies and best practices

Repository administrators

As stated in the GitHub management policy, each repository must have at least two individual administrators. These cannot be teams and there needs to be a very compelling reason for an external user to be made an administrator. The organisation administrators must validate the reason to add an external user as a repository administrator.

User permissions

We recommend users be given permissions on need basis. That means, for example, that write permissions to a repository should only be given if a user needs those permissions for their work. By default, all members of the ACCESS-NRI GitHub organisation have read permissions to all repositories in the organisation, including all private repositories. Read permissions allow users to:

• clone a repository
• create issues
• create a pull request from a fork

Write permissions are needed if a user needs to:

• push to the repository, including creating a new branch on the repository (not through a fork)
• use the pre-release infrastructure, as pre-release builds are not triggered for forks
• merge a pull request

Please refer to GitHub documentation for a full description of the permissions for each role and details of other existing roles. Repository administrators are free to assign any role to members for the good management of their repositories.

Branch protections

At a minimum, the default branch of a public repository should always be protected.

Topics

All repositories should be tagged with the appropriate topics for better discoverability.

Private repositories

Private repositories should only be used for licensing reasons. The same policies and best practices apply to private and public repositories, except for branch protection which is not available for private repositories. The documentation for these repositories must clearly indicate which proprietary licence is used and how to get access.

New repository check-list

To ensure new repositories follow our policies and best-practices, we recommend using the following check-list when creating a new repository:

• Add at least two administrators to the repository
• Add relevant topics
• Add branch protection rules
• Give users write permissions, on need basis

---

[micaeljtoliveira]

@ccarouge @atteggiani Thanks for the updates to the draft. I'm happy for us to add the new draft as is to the wiki, as we can always update it later if needed.

Some of the things in the draft are "mandatory", so should be added to ACCESS-NRI/.github#2

[ccarouge]

It's good to go for me as well.