From b0c584ca85fb259842adafdfacd39c914b5c23cc Mon Sep 17 00:00:00 2001 From: samanthaandrews Date: Tue, 5 Mar 2024 17:20:02 -0500 Subject: [PATCH 1/4] add github org management best practices --- README.md | 70 +++++++++++++----------- on-off-board/github-org-management.md | 24 ++++++++ on-off-board/offboarding.md | 2 +- on-off-board/onboarding.md | 79 ++++++++++++++------------- 4 files changed, 105 insertions(+), 70 deletions(-) create mode 100644 on-off-board/github-org-management.md diff --git a/README.md b/README.md index 5f5a975..5b51084 100644 --- a/README.md +++ b/README.md @@ -7,42 +7,48 @@ The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY/OPTIONAL, in these doc ## Contents ### Core Values -* [Engineering Values](culture/values.md) -* [Library Values](culture/library-values.md) + +- [Engineering Values](culture/values.md) +- [Library Values](culture/library-values.md) ### Policies -* [Accessibility](standards/accessibility.md) -* [Privacy & Data Retention](standards/privacy.md) - + +- [Accessibility](standards/accessibility.md) +- [Privacy & Data Retention](standards/privacy.md) + ### Code Standards -* [Coding Style](standards/coding-standards.md) - * [Versioning](standards/versioning.md) - * [Naming Conventions](standards/naming-conventions.md) - * [Logging](standards/logging.md) - * [Test Coverage](standards/test-coverage.md) - * [Documentation](standards/documentation.md) - * [Javascript](standards/javascript.md) - * [NYPL React Design System]() - * [Python]() - * [Ruby on Rails]() - * [PHP]() -* [Technical Approach Documents](standards/technical-approach.md) -* [Peer Review](standards/peer-review.md) -* [CI Coverage](standards/ci.md) - * [Github Actions](standards/github-actions.md) - * [Travis CI](standards/travis-ci.md) -* [Deployment](standards/deployment.md) - * [AWS](standards/aws.md) - * [Node Lambda](standards/node-lambda.md) -* [Production Readiness](standards/production-readiness.md) -* [Monitoring & Alarms](standards/alerting.md) -* [Root Cause Analysis](standards/root-cause-analysis.md) + +- [Coding Style](standards/coding-standards.md) + - [Versioning](standards/versioning.md) + - [Naming Conventions](standards/naming-conventions.md) + - [Logging](standards/logging.md) + - [Test Coverage](standards/test-coverage.md) + - [Documentation](standards/documentation.md) + - [Javascript](standards/javascript.md) + - [NYPL React Design System]() + - [Python]() + - [Ruby on Rails]() + - [PHP]() +- [Technical Approach Documents](standards/technical-approach.md) +- [Peer Review](standards/peer-review.md) +- [CI Coverage](standards/ci.md) + - [Github Actions](standards/github-actions.md) + - [Travis CI](standards/travis-ci.md) +- [Deployment](standards/deployment.md) + - [AWS](standards/aws.md) + - [Node Lambda](standards/node-lambda.md) +- [Production Readiness](standards/production-readiness.md) +- [Monitoring & Alarms](standards/alerting.md) +- [Root Cause Analysis](standards/root-cause-analysis.md) #### Security -* [General](security/README.md) -* [OAuth](security/oauth.md) -* [Secrets Management](security/secrets.md) + +- [General](security/README.md) +- [OAuth](security/oauth.md) +- [Secrets Management](security/secrets.md) ### Onboarding/Offboarding -* [Onboarding](on-off-board/onboarding.md) -* [Offboarding](on-off-board/offboarding.md) + +- [Onboarding](on-off-board/onboarding.md) +- [Offboarding](on-off-board/offboarding.md) +- [GitHub Org Management](on-off-board/github-org-management.md) diff --git a/on-off-board/github-org-management.md b/on-off-board/github-org-management.md new file mode 100644 index 0000000..d8542bb --- /dev/null +++ b/on-off-board/github-org-management.md @@ -0,0 +1,24 @@ +# GitHub Org Management + +1. All new repositories and Teams should be created within the existing [NYPL](https://github.com/NYPL) Org, unless specifically called out in the Product Brief, BRD, or TAD. There should not be a need to create additional organizations outside of the NYPL Org or to add repositories within any of the other NYPL organizations, such as NYPL-Simplified. We are aiming to consolidate all extranneous orgs under the NYPL org. +2. All active NYPL employees, this includes both FTEs and Contractors, who need Read, Write, or Admin access to NYPL repositories must be invited as a Member to the NYPL Org. They should _not_ be added to any repository as an Outside Collaborator. +3. NYPL employees can use an existing GitHub account created with a non-NYPL email address or create a new GitHub account using their NYPL email address. +4. It is recommended, but not required, that their [profile](https://github.com/settings/profile) include an easily recognizable name. This allows us to manage Members more easily. +5. Anyone who is part of the NYPL GitHub Org must enable two-factor authentication (2FA). +6. Use GitHub [Teams](https://github.com/orgs/NYPL/teams) + - Each portfolio group will have a Team. There will also be additional teams for Design System and Data Engineering, which operate outside of a traditional portfolio group structure. The manager or tech lead/architect who manages that team should be listed in that team's About section. + - Within each Team, there will be two or three child Teams: (1) Read access for people who don’t push code, (2) Write access for people who push code, and (3) Admin access for tech leads, architects, and managers. + - Add Teams to repositories. Don’t add contributors individually. Unless… + - Non-NYPL employee contributors should be added to the individual repo as an Outside Collaborator. This makes it easy for us to see who is an Outside Collaborator with access to repositories, since all Outside Collaborators are grouped into their own tab. + - Non-portfolio Teams or Teams outside Digital may be necessary. The Preservation & Collections Processing Team is an example of this. These Teams should have a designated “owner” with an email address in the “About” section. + - Do not create “Secret” Teams, which is discouraged by GitHub, unless there is a sensitive situation that requires their use. + - [Onboarding](./onboarding.md) should include adding contributors to the NYPL Org and the appropriate portfolio Team(s). + - [Offboarding](./offboarding.md) should include removing Members and Outside Collaborators from the NYPL Org. + +## How to add a user to a repo: + +_Note: The first step in this workflow is done by Hellen Lee during the onboarding process. We recognize that many people realize they need access to certain repositories after the onboarding process has been completed, so we’re listing them here for managers and GitHub admins._ + +1. If the person you're adding is an NYPL FTE or Contractor, [invite them](https://github.com/orgs/NYPL/people) to the NYPL Organization. They will need to accept this invite via email. Then make sure they have 2FA enabled (required) & ask them to add a recognizable name to their [profile](https://github.com/settings/profile) (optional). +2. Once the first step is complete, add them to the appropriate portfolio team(s). This should automatically grant them access to any repositories they need. Avoid adding individuals to repositories, unless they're an Outside Collaborator. +3. If they are not an NYPL employee or Contractor, add them to the repo they need access to as an Outside Collaborator. diff --git a/on-off-board/offboarding.md b/on-off-board/offboarding.md index a8b85f1..9e34daa 100644 --- a/on-off-board/offboarding.md +++ b/on-off-board/offboarding.md @@ -6,7 +6,7 @@ It's so hard to say goodbye but sometimes we must at NYPL. Remove the [accounts](onboarding.md#2-set-up-accounts) that might have been created during the onboarding process. -Remove github permissions +Remove the user from the [NYPL GitHub Organization](https://github.com/orgs/NYPL/people). ### Slack diff --git a/on-off-board/onboarding.md b/on-off-board/onboarding.md index 13572c1..0a1f706 100644 --- a/on-off-board/onboarding.md +++ b/on-off-board/onboarding.md @@ -16,60 +16,65 @@ This document is intended to help developers become familiar with NYPL digital p ### Commonly used accounts A developer will generally need accounts for the following services: + - Slack - - [nypl.slack.com](https://nypl.slack.com/) -- Github (Can use a personal account or make a new NYPL specific github account) - - Github organizations: - - [NYPL](https://github.com/NYPL) - - [NYPL-discovery](https://github.com/NYPL-discovery) - - [NYPL-Simplified](https://github.com/NYPL-Simplified) - - Note that membership in these organizations requires that your Github account have MFA enabled. We'd prefer MFA based on an app or hardware key over MFA based on SMS. - - Old and no-longer used organizations - - [NYPL-registry](https://github.com/NYPL-registry) - - [nypl-spacetime](https://github.com/nypl-spacetime) - - [nypl-open-audio](https://github.com/nypl-openaudio) - - [nypl-publicdomain](https://github.com/NYPL-publicdomain) -- JIRA* - - [jira.nypl.org](https://jira.nypl.org/) + - [nypl.slack.com](https://nypl.slack.com/) +- Github (Can use a personal account or make a new NYPL specific GitHub account) + + - NYPL Github organization: + + - [NYPL](https://github.com/NYPL) + - See [GitHub Organization Management](./github-org-management.md) for onboarding steps. + + - Old and no-longer used organizations + - [NYPL-registry](https://github.com/NYPL-registry) + - [nypl-spacetime](https://github.com/nypl-spacetime) + - [nypl-open-audio](https://github.com/nypl-openaudio) + - [nypl-publicdomain](https://github.com/NYPL-publicdomain) + - [NYPL-discovery](https://github.com/NYPL-discovery) + - [NYPL-Simplified](https://github.com/NYPL-Simplified) + +- JIRA\* + - [jira.nypl.org](https://jira.nypl.org/) - [Docker Hub](https://hub.docker.com/u/nypl/) - Amazon Web Services (AWS) - - Primary AWS accounts (MFA Login): - - [nypl-digital-dev](https://nypl-digital-dev.signin.aws.amazon.com/console) -- Bamboo*: Deployment happens via Bamboo - - [http://bamboo.nypl.org/](http://bamboo.nypl.org/) + - Primary AWS accounts (MFA Login): + - [nypl-digital-dev](https://nypl-digital-dev.signin.aws.amazon.com/console) +- Bamboo\*: Deployment happens via Bamboo + - [http://bamboo.nypl.org/](http://bamboo.nypl.org/) ### Less commonly used accounts - NYPL Platform - - [https://platform.nypl.org](https://platform.nypl.org) -- [npm organization](https://www.npmjs.com/org/nypl): You do not need an npm account to publish to npm + - [https://platform.nypl.org](https://platform.nypl.org) +- [npm organization](https://www.npmjs.com/org/nypl): You do not need an npm account to publish to npm - [Stash](https://stash.nypl.org/): (NYPL VPN needed) IT and devops keep AWS configurations, among other things, here. -- [Travis CI](https://travis-ci.com): Accounts are OAuthed and synced through Github. Adding/Removing access to Github controls access to Travis. +- [Travis CI](https://travis-ci.com): Accounts are OAuthed and synced through GitHub. Adding/Removing access to GitHub controls access to Travis. - Bitbucket: Older apps are on bitbucket - - [bitbucket.org/NYPL](https://bitbucket.org/NYPL) + - [bitbucket.org/NYPL](https://bitbucket.org/NYPL) - Loggly - - [https://nypl.loggly.com](https://nypl.loggly.com) + - [https://nypl.loggly.com](https://nypl.loggly.com) - CI Servers (e.g Jenkins instances) - - [https://ci-sa.prod.aws.nypl.org](https://ci-sa.prod.aws.nypl.org) + - [https://ci-sa.prod.aws.nypl.org](https://ci-sa.prod.aws.nypl.org) - Optimizely - - [https://app.optimizely.com](https://app.optimizely.com) + - [https://app.optimizely.com](https://app.optimizely.com) - Google Analytics - - [https://analytics.google.com](https://analytics.google.com) + - [https://analytics.google.com](https://analytics.google.com) - Amazon Web Services (AWS) - - Secondary AWS accounts (MFA Login): - - [nypl-sandbox](https://nypl-sandbox.signin.aws.amazon.com/console) - - [nypl/prod](https://nypl.signin.aws.amazon.com/console) - - [nypl-dev](https://nypl-dev.signin.aws.amazon.com/console) - - [nypl-labs](https://nypl-labs.signin.aws.amazon.com/console) + - Secondary AWS accounts (MFA Login): + - [nypl-sandbox](https://nypl-sandbox.signin.aws.amazon.com/console) + - [nypl/prod](https://nypl.signin.aws.amazon.com/console) + - [nypl-dev](https://nypl-dev.signin.aws.amazon.com/console) + - [nypl-labs](https://nypl-labs.signin.aws.amazon.com/console) - Data Warehouse DB credential - - [https://github.com/NYPL/data-warehouse#users](https://github.com/NYPL/data-warehouse#users) + - [https://github.com/NYPL/data-warehouse#users](https://github.com/NYPL/data-warehouse#users) - [New Relic](https://newrelic.com/) (Not currently used, just legacy for off-boarding) -** uses [NYPL/ServiceNow](https://nyplprod.service-now.com) credentials for authentication* +_\* uses [NYPL/ServiceNow](https://nyplprod.service-now.com) credentials for authentication_ ## 3. Set up keys -* Having public key added/removed to appropriate `.authorized_keys` files on machines - * If ensuring provisioning scripts that contain this key are updated / run -* Add user's public key to [NYPL/public_keys](https://github.com/NYPL/public_keys) - * See that repo's README for offboarding instructions +- Having public key added/removed to appropriate `.authorized_keys` files on machines + - If ensuring provisioning scripts that contain this key are updated / run +- Add user's public key to [NYPL/public_keys](https://github.com/NYPL/public_keys) + - See that repo's README for offboarding instructions From f89d94a11dbb65e808e6fdb51482f1cdc695099d Mon Sep 17 00:00:00 2001 From: samanthaandrews Date: Tue, 5 Mar 2024 17:22:04 -0500 Subject: [PATCH 2/4] title --- on-off-board/github-org-management.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/on-off-board/github-org-management.md b/on-off-board/github-org-management.md index d8542bb..2d35030 100644 --- a/on-off-board/github-org-management.md +++ b/on-off-board/github-org-management.md @@ -1,4 +1,4 @@ -# GitHub Org Management +# GitHub Organization Management 1. All new repositories and Teams should be created within the existing [NYPL](https://github.com/NYPL) Org, unless specifically called out in the Product Brief, BRD, or TAD. There should not be a need to create additional organizations outside of the NYPL Org or to add repositories within any of the other NYPL organizations, such as NYPL-Simplified. We are aiming to consolidate all extranneous orgs under the NYPL org. 2. All active NYPL employees, this includes both FTEs and Contractors, who need Read, Write, or Admin access to NYPL repositories must be invited as a Member to the NYPL Org. They should _not_ be added to any repository as an Outside Collaborator. From 900458723afa4e6b9ae246bd2a5a837684ece5f9 Mon Sep 17 00:00:00 2001 From: samanthaandrews Date: Thu, 7 Mar 2024 17:51:33 -0500 Subject: [PATCH 3/4] cleanup --- on-off-board/github-org-management.md | 2 +- on-off-board/onboarding.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/on-off-board/github-org-management.md b/on-off-board/github-org-management.md index 2d35030..5ab0946 100644 --- a/on-off-board/github-org-management.md +++ b/on-off-board/github-org-management.md @@ -17,7 +17,7 @@ ## How to add a user to a repo: -_Note: The first step in this workflow is done by Hellen Lee during the onboarding process. We recognize that many people realize they need access to certain repositories after the onboarding process has been completed, so we’re listing them here for managers and GitHub admins._ +_Note: Only GitHub Admins/Owners have the ability to add and remove members from the GitHub Org. If you don't have access and need to add or remove someone, contact an Engineering Manager or Tech Lead._ 1. If the person you're adding is an NYPL FTE or Contractor, [invite them](https://github.com/orgs/NYPL/people) to the NYPL Organization. They will need to accept this invite via email. Then make sure they have 2FA enabled (required) & ask them to add a recognizable name to their [profile](https://github.com/settings/profile) (optional). 2. Once the first step is complete, add them to the appropriate portfolio team(s). This should automatically grant them access to any repositories they need. Avoid adding individuals to repositories, unless they're an Outside Collaborator. diff --git a/on-off-board/onboarding.md b/on-off-board/onboarding.md index 0a1f706..285ae6f 100644 --- a/on-off-board/onboarding.md +++ b/on-off-board/onboarding.md @@ -19,9 +19,9 @@ A developer will generally need accounts for the following services: - Slack - [nypl.slack.com](https://nypl.slack.com/) -- Github (Can use a personal account or make a new NYPL specific GitHub account) +- GitHub (Can use a personal account or make a new NYPL specific GitHub account) - - NYPL Github organization: + - NYPL GitHub organization: - [NYPL](https://github.com/NYPL) - See [GitHub Organization Management](./github-org-management.md) for onboarding steps. From 82e5ed03fa50c62a48dce87173527724c8267b8f Mon Sep 17 00:00:00 2001 From: samanthaandrews Date: Mon, 18 Mar 2024 11:49:30 -0400 Subject: [PATCH 4/4] include interns in list of gh org members --- on-off-board/github-org-management.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/on-off-board/github-org-management.md b/on-off-board/github-org-management.md index 5ab0946..eee398f 100644 --- a/on-off-board/github-org-management.md +++ b/on-off-board/github-org-management.md @@ -1,7 +1,7 @@ # GitHub Organization Management 1. All new repositories and Teams should be created within the existing [NYPL](https://github.com/NYPL) Org, unless specifically called out in the Product Brief, BRD, or TAD. There should not be a need to create additional organizations outside of the NYPL Org or to add repositories within any of the other NYPL organizations, such as NYPL-Simplified. We are aiming to consolidate all extranneous orgs under the NYPL org. -2. All active NYPL employees, this includes both FTEs and Contractors, who need Read, Write, or Admin access to NYPL repositories must be invited as a Member to the NYPL Org. They should _not_ be added to any repository as an Outside Collaborator. +2. All active NYPL employees, this includes FTEs, Interns, and Contractors, who need Read, Write, or Admin access to NYPL repositories must be invited as a Member to the NYPL Org. They should _not_ be added to any repository as an Outside Collaborator. 3. NYPL employees can use an existing GitHub account created with a non-NYPL email address or create a new GitHub account using their NYPL email address. 4. It is recommended, but not required, that their [profile](https://github.com/settings/profile) include an easily recognizable name. This allows us to manage Members more easily. 5. Anyone who is part of the NYPL GitHub Org must enable two-factor authentication (2FA). @@ -19,6 +19,6 @@ _Note: Only GitHub Admins/Owners have the ability to add and remove members from the GitHub Org. If you don't have access and need to add or remove someone, contact an Engineering Manager or Tech Lead._ -1. If the person you're adding is an NYPL FTE or Contractor, [invite them](https://github.com/orgs/NYPL/people) to the NYPL Organization. They will need to accept this invite via email. Then make sure they have 2FA enabled (required) & ask them to add a recognizable name to their [profile](https://github.com/settings/profile) (optional). +1. If the person you're adding is an NYPL FTE, Intern, or Contractor, [invite them](https://github.com/orgs/NYPL/people) to the NYPL Organization. They will need to accept this invite via email. Then make sure they have 2FA enabled (required) & ask them to add a recognizable name to their [profile](https://github.com/settings/profile) (optional). 2. Once the first step is complete, add them to the appropriate portfolio team(s). This should automatically grant them access to any repositories they need. Avoid adding individuals to repositories, unless they're an Outside Collaborator. 3. If they are not an NYPL employee or Contractor, add them to the repo they need access to as an Outside Collaborator.