Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

GitHub Management Policy: Teams & outside collaborators updates #49

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

GitHub Management Policy: Teams & outside collaborators updates #49

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
133 changes: 89 additions & 44 deletions resources/github-management-policy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,59 +5,75 @@
## Table of Contents

##### [GitHub Organization Access](#github-organization-access)

- [Get access to a team as a member](#get-access-to-a-team-as-a-member)
- [Request a new team to be created](#request-a-new-team-to-be-created)
- [Request a new repo to be created](#request-a-new-repo-to-be-created)
- [Request a team to be added to a repo](#request-a-team-to-be-added-to-a-repo)
- [Request a third-party integration to be added to the repo](#request-a-third-party-integration-to-be-added-to-the-repo)

##### [Offboarding](#offboarding)

- [Monthly audit of membership](#monthly-audit-of-membership)
- [Review activity log](#review-activity-log)
- [Security](#security)
- [Organization-wide Settings](#organization-wide-settings)
- [Authentication Security](#authentication-security)
- [Code Security](#code-security)
- [Check Tokens & Keys](#check-tokens--keys)
- [Personal Access Tokens](#personal-access-tokens)
- [Private Keys for GitHub Apps](#private-keys-for-github-apps)
- [Check Secrets](#check-secrets)
- [Actions Secrets & Variables](#actions-secrets--variables)
- [Codespaces Secrets](#codespaces-secrets)
- [Dependabot Secrets](#dependabot-secrets)
- [Monitor usage under GitHub plan](#monitor-usage-under-github-plan)
- [Organization-wide Settings](#organization-wide-settings)
- [Authentication Security](#authentication-security)
- [Code Security](#code-security)
- [Check Tokens & Keys](#check-tokens--keys)
- [Personal Access Tokens](#personal-access-tokens)
- [Private Keys for GitHub Apps](#private-keys-for-github-apps)
- [Check Secrets](#check-secrets)
- [Actions Secrets & Variables](#actions-secrets--variables)
- [Codespaces Secrets](#codespaces-secrets)
- [Dependabot Secrets](#dependabot-secrets)
- [Monitor usage under GitHub plan](#monitor-usage-under-github-plan)

##### [FAQs](#faqs)

## GitHub Organization Access

### Get access to a team as a member
### Request a new team to be created for a Project

The member will be under the **member role** where they have no administrative permissions on the team.
#### Step 1: Creating a Team with Project Maintainers - Maintainers Team

Project maintainers will be placed in their own separate team and serve as the main point of contact for coordinating team & repository management with the OSPO.

Information required:
- GitHub username
- Team name

### Request a new team to be created
- Project name
- Team name: _projectName_\_maintainers
- List of GitHub usernames to be added
- Team visibility: visible or secret

#### Step 1: Creating a Parent Team with All Project Members
#### Step 2: Creating a Parent Team with All Project Members - Committers Team

All project members will be under the **member role** where they have no administrative permissions on the team. Team visibility and notifications are enabled unless specified otherwise.

Information required:
- Team name: *projectName*\_committers

- Team name: _projectName_\_committers
- List of GitHub usernames to be added
- Team visibility: visible or secret

#### (Optional) Step 2: Creating Child Teams
#### (Optional) Step 3: Creating Child Teams

[Child teams](https://docs.github.com/en/organizations/organizing-members-into-teams/about-teams#nested-teams) can be granted additional and more granular access to certain repositories. Examples of child teams can include code reviewers, developers under a repo domain, and project leads.

Information required:
- Team name: *projectName*\_*teamType*
- Examples of team types: frontend team, backend team, reviewers

- Team name: _projectName_\__teamType_
- Examples of team types: frontend team, backend team, reviewers
- List of GitHub usernames to be added

### Requesting access to a team as a member

The member will be under the **member role** where they have no administrative permissions on the team.

Information required:

- GitHub username
- Team name

### Request a new repo to be created

Expand All @@ -66,37 +82,56 @@ If you are looking to migrate an existing repository hosted in a different organ
If you are looking to create a completely new repository, your repository can be created as private or public. Based on the maturity model tier selected, a collection of [markdown templates](https://github.com/DSACMS/ospo-guide/blob/main/outbound/REPOSITORY_TEMPLATES_AND_LINTERS.md) will be included as part of our repository hygiene standards. GitHub security features such as Dependabot and secret scanning will be enabled.

Information required:

- Repository Name
- Repository Description
- Project’s [Maturity Model Tier](https://github.com/DSACMS/repo-scaffolder/blob/main/maturity-model-tiers.md)
- Repository Topics
- Team name or List of Committers’ GH username + email
- Project teams to add to repository, such as:

- Maintainer team
- Committer team
- Any other teams/child teams

- Repository Visibility: private or public
- Include an assessment of benefits and risks of selecting this visibility
- Include an assessment of benefits and risks of selecting this visibility

### Request a team to be added to a repo
### Request a new team to be added to a repo

All team members will be granted WRITE access to the repo. If you or other members want to be promoted to MAINTAIN access, please indicate this in the form. ADMIN access is only available to DSACMS organization owners for now.
Maintainer teams have MAINTAIN access while committer teams have WRITE access. If you or other members want to be promoted to MAINTAIN access, please indicate this in the form. ADMIN access is only available to DSACMS organization owners for now. MAINTAINERS.md will be updated accordingly.

Information required:

- Team name
- Team type: parent or child
- Repository name to be given access to
- Reason for access

### Request an outside collaborator to be added to a repo

For individuals that are not members of the DSACMS GitHub organization, these outside collaborators can request access to a repository. Fill out this issue to file the request or make a pull request to the `MAINTAINERS.md` file, then a repository admin will grant access.

Information required:

- Name of individual
- GitHub username
- Repository to be added
- Role of the Outside Collaborator as listed in `MAINTAINERS.md`
- Maintainers, Approvers, Reviewers
- Any additional information

### Request a third-party integration to be added to the repo

The DSACMS org uses the following third-party GitHub apps: SonarCloud. If your team would like to install and use an integration in your repository, please file a request by sending a slack message at #cms-ospo. We are open to adding more integrations to this list based on team needs.

Information required:

- Third-party Integration / GitHub App to be added
- Reason for usage
- Project’s [Maturity Model Tier](https://github.com/DSACMS/repo-scaffolder/blob/main/maturity-model-tiers.md)
- Keys that will need to be created


## Offboarding
## GitHub Organization Management

### Monthly audit of membership

Expand All @@ -121,10 +156,9 @@ Review the [list of sent invitations](https://github.com/orgs/DSACMS/people/pend

- Assess whether to resend or delete failed invitations


### Review activity log

The audit log for organization activity must be reviewed on a monthly basis. Export the log as a CSV and attach it to the *name_of_ticket_here* in internal CMS GitHub. Any org members can do this. https://github.com/organizations/DSACMS/settings/audit-log
The audit log for organization activity must be reviewed on a monthly basis. Export the log as a CSV and attach it to the _name_of_ticket_here_ in internal CMS GitHub. Any org members can do this. https://github.com/organizations/DSACMS/settings/audit-log

- Organization Membership
- Team Management
Expand All @@ -134,12 +168,12 @@ The audit log for organization activity must be reviewed on a monthly basis. Exp
- Hook Activity
- Personal Access Token Activity


### Security

#### Organization-wide Settings

##### Authentication Security

Two-factor authentication is required for everyone under the DSACMS organization.

##### Code Security
Expand All @@ -148,26 +182,26 @@ Two-factor authentication is required for everyone under the DSACMS organization
https://github.com/organizations/DSACMS/settings/security_products

- All repositories use the GitHub-recommended code security configuration:
![Code Security Configuration](../assets/githubmanagementpolicy/code_security_configurations.png)
![Code Security Configuration](../assets/githubmanagementpolicy/code_security_configurations.png)

- Currently, all public repositories under DSACMS use GitHub Advanced Security
features (i.e. Code Scanning, Secret Scanning). Private repositories will only have
free features enabled.
features (i.e. Code Scanning, Secret Scanning). Private repositories will only have
free features enabled.

<ins>Review Global Settings</ins>\
https://github.com/organizations/DSACMS/settings/security_analysis

- Dependabot is enabled by default with a rule to dismiss low-impact alerts for
development-scoped dependencies.
development-scoped dependencies.
- Code scanning features will be enabled on a case-by-case basis.


#### Check Tokens & Keys

##### Personal Access Tokens

<ins>Review Tokens Settings</ins>

The active tokens must be reviewed on a monthly basis. Export the log as a CSV and attach it to the *name_of_ticket_here* in internal GitHub.\
The active tokens must be reviewed on a monthly basis. Export the log as a CSV and attach it to the _name_of_ticket_here_ in internal GitHub.\
https://github.com/organizations/DSACMS/settings/personal-access-tokens/active

- Who is the owner?
Expand All @@ -178,39 +212,44 @@ https://github.com/organizations/DSACMS/settings/personal-access-tokens/active
Personal Access Tokens will be granted for repo permissions with read and/or write access. Organization permissions will require explicit permission.

##### Private Keys for GitHub Apps
Please review keys used for third-party apps and GitHub apps: https://github.com/organizations/DSACMS/settings/installations

Please review keys used for third-party apps and GitHub apps: https://github.com/organizations/DSACMS/settings/installations

#### Check Secrets

##### Actions Secrets & Variables

https://github.com/organizations/DSACMS/settings/secrets/actions

- Secrets and variables allow you to manage reusable configuration data. Secrets
are encrypted and are used for sensitive data.\
https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions
are encrypted and are used for sensitive data.\
https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions
- Anyone with collaborator access to the repositories with access to a secret or variable can use it for Actions.
- Cannot be used in private repositories in our current plan.

##### Codespaces Secrets

https://github.com/organizations/DSACMS/settings/secrets/codespaces

- Development environment secrets are environment variables that are encrypted.
They are available to any codespace user with collaborator access to the
repositories with access to that secret.
They are available to any codespace user with collaborator access to the
repositories with access to that secret.
- Cannot be used in private repositories in our current plan.

##### Dependabot Secrets

https://github.com/organizations/DSACMS/settings/secrets/dependabot

- Anyone with collaborator access to the repositories with access to each secret can
use it for Dependabot.
use it for Dependabot.

### Monitor usage under GitHub plan

The DSACMS GitHub Organization is currently under the **GitHub free plan**.

![GitHub Free Plan Features](../assets/githubmanagementpolicy/github_free_plan_features.png)

The [usage](https://github.com/settings/billing/summary#usage) of the features below must be reviewed on a monthly basis. Export this information into a report using the “Get Usage Report” button and attach it to the *name_of_ticket_here* in internal GitHub.
The [usage](https://github.com/settings/billing/summary#usage) of the features below must be reviewed on a monthly basis. Export this information into a report using the “Get Usage Report” button and attach it to the _name_of_ticket_here_ in internal GitHub.

<table>
<thead>
Expand Down Expand Up @@ -254,9 +293,15 @@ The [usage](https://github.com/settings/billing/summary#usage) of the features b
### FAQs

##### Can I be admin for a repository?

For now, no. Admin is only reserved for OSPO staff but as we continue to use this organization and form our GitHub policy guidance, this may change in the future.

##### How do GitHub Teams work? What are the differences between parent teams and child teams?

- Teams can only be made up of members of your organization, outside collaborators are unable to be on a team.
- You should give parent teams repository access permissions that are safe for every member of the parent team and its child teams. As you move toward the bottom of the hierarchy, you can grant child teams additional, more granular access to
more sensitive repositories.
more sensitive repositories.

##### Can we add outside collaborators as code reviewers?

Yes! `MAINTAINERS.md` in the repository’s root directory is the ‘source of truth’ for this list of users. This file can be updated indirectly by creating an issue as noted in the outside collaborator section, or directly by creating a Pull Request with Name and github username for the collaborator under the `Reviewers` section. Once this list is updated, a repository admin can grant appropriate levels of access upon request in #cms-ospo or by filing a ticket.