Guidance for Creating Organization Profiles, Team Profiles, and Repository READMEs
- General Transparency Expectations
- Organization Profile Pages
- Team Profile Pages
- Repository README Files
- Licensing and Reuse Notes for READMEs
- Data, Security, and Policy Considerations
- Minimum Information by Location
- Maintenance Expectations
- Need Help?
GitHub organization profiles, team profiles, and repository README files serve similar purposes: they help people understand where they are, what they are looking at, and what they should do next. The difference is scope.
- An organization profile explains the purpose of the GitHub organization.
- A team profile explains the purpose of a GitHub Team and who the team represents.
- A repository README explains the purpose, status, use, ownership, and support path for a specific repository.
General Transparency Expectations
GitHub profiles and README files should make ownership, purpose, and contact information easy to find. Where applicable, they should help users answer the following questions:
- What is this GitHub organization, team, or repository for?
- Who owns, manages, or maintains it?
- Who should be contacted with questions?
- What website, service, system, project, or business process does it support?
- Who is allowed to use it, manage it, or contribute to it?
- Is it public, UWM-only, team-restricted, or private?
- Does it involve institutional data, student data, research data, credentials, integrations, automation, or production services?
- What UWM or UW System responsibilities may apply?
Do not assume that users will know the history of a GitHub organization, team, or repository from its name. Names should be clear, but the profile or README should provide enough context for someone new to understand the space.
Organization Profile Pages
An organization profile is the front door for a GitHub organization. It should explain what the organization represents and what kinds of repositories belong there.
For more information, see:
An organization profile should include:
- The name and purpose of the organization.
- The UWM unit, service, program, project, or function the organization supports.
- The types of repositories that belong in the organization.
- Who manages the organization.
- How to request help.
- How to request a new repository, if applicable.
- Links to relevant UWM websites, service pages, request forms, documentation, or support channels.
- Any important visibility expectations, such as whether repositories are normally private, UWM-only, or public.
- An organization profile should not include:
- Repository-specific setup instructions.
- Detailed internal procedures that belong in a repository README, wiki, or KB article.
- Sensitive operational details.
- Secrets, credentials, private keys, access tokens, or protected data.
- Private information that should not be visible to everyone who can view the organization profile.
Suggested organization profile structure:
- Purpose
- Managed by
- What belongs here
- Common repositories or services
- Requesting help or access
- Related UWM links
Team Profile Pages
A team profile explains who a GitHub Team represents and why the team exists. Teams are especially important because they are often used to manage access to private repositories.
GitHub Teams do not function like repositories and do not have full README pages in the same way repositories do. However, team names, descriptions, membership, maintainers, and linked repositories should still be clear enough for users and administrators to understand the team’s purpose.
For more information, see:
A team profile should make clear:
- What the team represents.
- Who should belong to the team.
- Who manages or maintains the team.
- What repositories, systems, services, or responsibilities the team is associated with.
- What access the team commonly provides.
- Who to contact if team membership appears incorrect.
- How to request membership changes.
A team profile should not include:
- Vague descriptions such as “admins,” “developers,” or “project team” without context.
- Sensitive access rationale that should be handled through an approved support or access request process.
- Secrets, credentials, private keys, access tokens, or protected data.
A team should have at least one clearly identified owner or maintainer group. If a team controls access to repositories, the team should be reviewed when project membership changes, service ownership changes, or access is no longer needed.
Suggested team profile structure:
- Team purpose
- Who belongs in this team
- What this team can access
- Team owner or maintainer
- How to request membership changes
- Related repositories, services, or documentation
Repository README Files
A repository README is the front door for a specific repository. It should explain what the repository contains, who it is for, how it should be used, and who is responsible for it.
For more information, see:
A repository README should include:
- The repository name and purpose.
- The repository status, such as active, pilot, experimental, internal support only, archived, deprecated, or historical.
- The repository owner, service owner, responsible unit, or maintainer.
- Contact information for questions, support, or access requests.
- Links to the related website, application, service, documentation, or issue tracker.
- Who the intended audience is.
- How to use the repository.
- How to install, run, build, or deploy the contents, if applicable.
- How to contribute or request changes, if applicable.
- Any major dependencies, integrations, or related systems.
- Any important data, privacy, security, or compliance notes.
- Licensing or reuse information.
A repository README should not include:
- Passwords, secrets, access tokens, private keys, or credentials.
- Protected student information or restricted institutional data unless the repository has been approved for that use.
- Outdated setup instructions.
- Unclear ownership statements.
- Licensing statements that have not been reviewed when ownership or release authority is unclear.
Suggested repository README structure:
- Purpose
- Status
- Audience
- Owner or maintainer
- Contact or support path
- Related website, service, or documentation
- Setup or usage instructions
- Contribution or change process
- Data, privacy, and security notes
- License or reuse statement
Licensing and Reuse Notes for READMEs
Repository READMEs should state whether the repository has an approved license or whether licensing has not yet been determined. If a license applies, the README should identify the license and link to the repository’s license file.
Choosing a license is not always a unilateral decision by the repository owner or maintainer. Licensing may depend on who owns the work, whether the work was created as part of university duties, whether students or external contributors were involved, whether sponsored research or grant terms apply, whether third-party code or dependencies are included, and whether the repository supports an institutional service or public release.
Repository owners and maintainers should not assume they can independently choose an open-source or reuse license for university work. UW System and UWM policy should be reviewed where applicable, including UW System policy on computer software ownership and UWM copyright policy. If ownership, responsibility, or release authority is unclear, contact the UWM Office of Legal Affairs before adding or changing a repository license.
Relevant policy references:
Suggested README language when the license is approved:
License: This repository is licensed under [license name]. See the LICENSE.md file for details.
Suggested README language when licensing has not been determined:
License: Licensing for this repository has not yet been determined. Do not reuse, redistribute, or publish this work outside
its approved UWM context without appropriate review.
Suggested README language when the repository is internal/private and not approved for reuse:
License and reuse: This repository is intended for approved UWM use. It may contain work owned by or subject to rights held
by the Board of Regents of the University of Wisconsin System. Internal reuse within UWM may be appropriate depending on the
purpose, context, data involved, and any applicable policy or contractual obligations. External reuse, redistribution,
open-source release, or publication outside the approved UWM context requires appropriate review and authorization.
If ownership, responsibility, or release authority is unclear, contact UWM Legal before adding or changing a license or approving reuse outside UWM.
Data, Security, and Policy Considerations
GitHub profiles and README files should not expose information that is inappropriate for their audience. Public pages should be written for public visibility. UWM-only, private, and team-restricted pages may include more institutional context, but they should still avoid secrets, credentials, and protected data.
Repository visibility should not be treated as a complete security control. Private repositories may still be visible to authorized GitHub administrators, including owners of the organization that manages the repository.
Where applicable, repository owners, team maintainers, and organization owners should consider UW System and UWM requirements related to data classification, information security, acceptable use, research data, software ownership, copyright, and institutional responsibility.
Relevant policy references:
- UW System Administrative Policy 1031, Information Security: Data Classification
- UW System Administrative Policy 1039, Information Security: Risk Management
- Regent Policy Document 25-3, Acceptable Use of Information Technology Resources
- UWM Research Data Management policy
Minimum Information by Location
Organization profiles should explain what the organization represents, who manages it, what belongs there, and where to get help.
Team profiles should explain what the team represents, who manages the team, who should belong to it, what access it supports, and how membership changes are requested.
Repository README files should explain what the repository contains, who owns or maintains it, how it is used, how to get help, what data or security expectations apply, and whether licensing or reuse has been approved.
Maintenance Expectations
Organization profiles, team profiles, and repository README files should be reviewed when:
- Ownership changes.
- Team maintainers change.
- Repository status changes.
- A project moves from pilot to production.
- A repository is archived or deprecated.
- Access expectations change.
- A related website, service, or support path changes.
- Policy, data, security, or licensing expectations change.
Outdated documentation can create confusion about who owns a repository, who can approve access, whether the work is still active, and whether reuse is allowed. Keep profiles and READMEs current enough that a new user can understand what they are seeing without needing the history of the project.
Need Help?
For help with GitHub Enterprise organization profiles, team information, repository READMEs, access questions, ownership updates, or licensing questions, contact the UWM Help Desk.
If ownership, responsibility, or licensing authority is unclear, contact the UWM Office of Legal Affairs before adding or changing a repository license or publishing the repository for broader reuse.