Github Organizations

Github Teams and Organizations provide a means of organizing research people and institutions.

Github Organizations: Organizations are the ‘owners’ of shared repositories, discussions, and projects where these things are kept completely separate from each other. For example, NOAA Fisheries has a single nmfs-ost Github Org.

Github Teams: Github Teams are groups of users of common projects, and there can also be teams within teams. For example: the PAM Strategic Initiative Team has a number of additional teams within it (one for each PAM-SI Team).

A team belongs to an organization, and an organization can have many teams. Best practices suggest minimizing the number of existing Github Organizations, deferring to ‘Teams’ for identifying groups within an Organization.

Because of the large number of teams and repositories within the nmfs-ost organization, we HIGHLY recommend that all PAM-SI teams and repositories contain the prefix ‘PAM’ in their name (at a minimum!). Additional key words should also be considered.

In this exercise, each PAM-SI Team will develop a strategy for their Github team and develop a “Lab Manual” repository to serve as the ‘landing page’ for their team. Throughout, we will use the PAM-Glider team as an example. For reference, here is a link to the nmfs-ost Organization Standard Operating Procedures.

Create your team

  • Create a Team. The PAM-SI teams have been created for you; here are directions if you’d like to create other teams. Here is a link to the list of PAM Strategic Initiative Teams.

  • Add Team Members. Identify one or more administrators and ensure they have full administrative rights. If this team is within the nmfs-ost Organization, you may need to reach out to the Org Administrators to modify team members’ administrative rights. You can submit an Issue here to request assistance from the nmsf-ost administrators.

  • Create a Team Manual. This will serve as the primary go-to for all components of that team.

    • Follow the methods for creating a ‘Lab Manual’ for your team (a ‘Team Manual’). Use the same naming structure for your team manual as your name. For example, the repository for the PAM-Glider team will be titled “PAM-Glider”.

    • ReadMe: Include an “About” statement to make it clear what this repository is.

    • Index.qmd: Create a home page that summarizes the goals and tasks of the teams. For suggestions, we recommend viewing the PAM-SI pages from the National PAM Network site and the PAM-Glider site.

    • Create a page for each component of your research (see PAM-Glider site as an example). Provide any methods, figures, preliminary results, or other summary information that might be useful to the public or to our NOAA administrators and managers.

    • Add a ‘contact us’ Page. Your team can decide the best way to receive contacts (email or submission of an issue related to the repository). If you ask them to submit an issue, create an issue templatethat automatically identifies the Assignees for that issue (and ensure that those Assignees will automatically receive an email for that issue).

  • Align Team Manual with PAM_National_Network

    • Review the PAM-SI Page for your Team. Identify inconsistencies, updates, and helpful figures.

    • Create an Issue for that page by selecting the “Report an Issue” button on the upper right-hand side of the relevant page. Describe all the suggested changes (and provide any images or links to images to include), and provide a link to the website for your PAM-Team Manual website. Submit the issue and assign to Bella and yourself.

Transfer existing repositories

For instructional purposes, we will refer to the original repository as the OldRepo and the New Repository (within the nmfs-ost org) as the NewRepo. If your previous repository was located within a different organization (say your science center org), we will refer to that as the OldOrg, and as the nmfs-ost as the NewOrg. For additional information, see the nmfs-ost SOP.

NO PII/BII are allowed on Github!! This includes confidential fisheries data, passwords, etc!

  1. Identify Team Members. Ensure that all relevant NOAA personnel are listed as team members on the new organization (nmfs-ost). If there are non-NOAA partners who require administrative access to the repository, you will need to use alternative methods for outside collaboration (see Outside Collaborators, below). If this is unacceptable, then you may wait on transferring the repository, but still link to that repository from your Team Manual.

  2. Prepare Project Boards. Do you have any project boards linked to this repository? Project boards do not transfer; however, if you ensure that all Project Board entries are saved as ‘Issues’, then the Issues will transfer over and you can rebuild your Project Board in the new org (note that they will not retain their ‘status’ tags, so you may want to include a comment stating their status prior to transferring the repository). Closed issues may not transfer using this method and you may want to consider manually entering closed issues that should be retained.

  3. Check Discussion Boards All discussions should transfer if they are at the repository level and being transferred to an organization that does not allow for organization level discussions. Currently, the NMFS OST does not have a discussion board at the organization level, so any repositories transferred there should include the existing discussion boards. More information on discussions here

  4. Transfer Repository. Navigate to the Settings of your OldOrg, and scroll down to the ‘Danger Zone’. Select the Transfer button to transfer the repository, and select the nmfs-ost Organization. Rename your Repository to include the prefix ‘PAM’ as part of the name (to facilitate searching).

  5. Identify Admin Settings. Open the NewRepo in the nmfs-ost Enterprise organization. Can you see the settings? If not, you may not have admin rights. Submit an Issue here to request assistance from the nmsf-ost administrators to provide you with administrative rights for that repository.

  6. Fix Github Pages. If your OldRepo had GithubPages (a website), check the Settings –> Github Pages to ensure that GithubPages is turned ‘on’. If you have links to the Github Pages in your Readme or on the right sidebar, update those links. Update links in any other important locations. If you suspect the broken link from your previous OldRepo will be problematic, you can create a redirect from your old Organization by following the methods outlined in the nmfs-ost SOP ‘Auto-redirect Github Pages’.

  7. Add an “About” Statement. Open the ReadMe and provide an “About” statement to make it clear what the purpose of the repository is.

  8. Add NOAA Disclaimer and License. Revise readme to ensure that there is a NOAA Disclaimer (below) and a License file for software (including R packages){target=“_blank”}.

    Suggested Disclaimer:

    “This repository is a scientific product and is not official communication of the National Oceanic and Atmospheric Administration, or the United States Department of Commerce. All NOAA GitHub project code is provided on an ‘as is’ basis and the user assumes responsibility for its use. Any claims against the Department of Commerce or Department of Commerce bureaus stemming from the use of this GitHub project will be governed by all applicable Federal law. Any reference to specific commercial products, processes, or services by service mark, trademark, manufacturer, or otherwise, does not constitute or imply their endorsement, recommendation or favoring by the Department of Commerce. The Department of Commerce seal and logo, or the seal and logo of a DOC bureau, shall not be used in any manner to imply endorsement of any commercial product or activity by DOC or the United States Government.”

Add new repositories

As the work of your PAM-SI team expands, add additional repositories as needed. These teams are intended as cross-office or National level projects.

  1. Identify active Repo Users. Will all active Repo Users have noaa emails? Will they have access to nmfs-ost? If not, then you can choose to either (1) host those repositories outside of the Enterprise Github nmfs-ost organization, or (2) require non-noaa users to submit push requests as a means of interacting with the repository. We have not yet tested this system to identify any problems.

  2. Create Repository. Create your repository (see Quickstart for repositories) and use a thoughtful name that includes the Prefix ‘PAM’ (at a minimum). Use the word ‘test’ in the name if the purpose of this repo is to test something out (and later delete!). Consider using a template for your repo, such as our Research Compendium or our [Lab Manual](https://nmfs-ost.github.io/PAM-OpenScience/content/labManual.html{target=“_blank”} templates.

  3. Add Team Members and ensure they have the appropriate level of user access.

  4. Add an “About” Statement. Open the ReadMe and provide an “About” statement to make it clear what the purpose of the repository is.

  5. Add NOAA Disclaimer and License. Revise the ReadMe to ensure that there is a NOAA Disclaimer (below) and a License file for software (including R packages) .

    Suggested Disclaimer:

    “This repository is a scientific product and is not official communication of the National Oceanic and Atmospheric Administration, or the United States Department of Commerce. All NOAA GitHub project code is provided on an ‘as is’ basis and the user assumes responsibility for its use. Any claims against the Department of Commerce or Department of Commerce bureaus stemming from the use of this GitHub project will be governed by all applicable Federal law. Any reference to specific commercial products, processes, or services by service mark, trademark, manufacturer, or otherwise, does not constitute or imply their endorsement, recommendation or favoring by the Department of Commerce. The Department of Commerce seal and logo, or the seal and logo of a DOC bureau, shall not be used in any manner to imply endorsement of any commercial product or activity by DOC or the United States Government.”

  6. Add Relevant Page to Team Manual. Create a page within the Team Manual to identify, link, and describe this repository (and summarize any results).

Outside Collaborators

If you would like to request someone be added as an outside collaborator (because they do not have a noaa.gov email account), please contact the nmfs-ost GitHub organization administrators. Those outside of NOAA can collaborate by forking the repository and submitting a pull request to public repositories, and the GitHub Governance Team is clarifying which additional permissions are allowed for non-NOAA collaborators on GitHub Enterprise. See nmfs-ost SOP for more information.