The Basics of GitHub: Organizations, Repositories, & Issues

This serves as a quick reference and step by step guide for users with no prior GitHub experience. For more complete information and detailed instructions, see GitHub Fundamentals for OBO Engineers and GitHub Issue for OBO Engineers.

Signing up for GitHub

GitHub is a cloud-based platform where you can store, share, and work together with others to write code. Collaborative working, one of GitHub’s fundamental features, is made possible by the open-source software, Git, upon which GitHub is built.

1. Sign up for GitHub at github.com.
2. After signing up, your Username will be your GitHub handle. This serves as your unique identity on the platform and is used to log in, reference your profile, and mention you in discussions.
3. Note: You can go to Settings to provide additional personal information, connect ORCID id, and customize your avatar.

Understanding Organization and Repository

1. Organization: A shared account that allows groups to collaboratively manage multiple repositories with centralized access control, permissions, and team management. Organizations own repositories (instead of individual users) and enable admins to manage members, teams, security settings, and integrations across all projects.

2. Example: https://github.com/zappfish, https://github.com/monarch-initiative

3. Repository (repo): A storage space on GitHub where your project’s files, code, or documentation are kept. It tracks every change made to those files, allowing collaboration, version control, and issue tracking.

4. Example: https://github.com/zappfish/zapp-atlas

Creating an Issue from a Repository

Issues are easy to create, flexible, and useful for tracking ideas, feedback, tasks, or bugs, making them an excellent tool for collaborate. Note: See Writing Good Issues for best practices on creating effective issues.

1. On GitHub, navigate to the main page of the repository (e.g. https://github.com/zappfish/zapp-atlas).

2. Under your repository name, click Issues.
   

3. Click New issue.

4. In the Add a title field, type a concise title for your issue.The title should convey at a glance what the issue is about.

5. Example: add phenotype abnormal intestinal cells
   

6. In the Add a description field, type a description providing more information of your issue.

7. Example:https://github.com/zappfish/zapp-atlas/issues/52

8. Add any labels to specify the issue by clicking on Labels. Note: This is not required.

9. To draw someone's attention (with access to the repository) to your issue, mention them in your issue, click on or type @, followed by a GitHub handle.
10. To link related issues in the same repository, you can type # followed by part of the issue title and then clicking the issue that you want to link.
11. When you're finished, click Create.

Commenting on Issues

Commenting on issues is an important way to communicate and collaborate. Anyone with write access to a repository can comment on issues, and issue creator will be notified through email. 1. Under the repository name, click Issues.

1. Select an issue by clicking its title.

2. In the Add a comment field, type in your comment under the Write tab.

3. Note: Github content is written using Markdown, a text-to-HTML conversion tool. More information on Markdown can be found here. If you aren't familiar with Markdown, you can simply use the format commands at the top of a comment section to format your text.

4. To mention someone in your comment, click on or type @, followed by a GitHub handle.

5. Preview your comment under the Preview tab.

6. When you're finished, click Comment.