Intro to GitHub for non-technical roles
What is GitHub?
If you’re not a software developer, you can think of GitHub like Dropbox, Google Drive, or SharePoint, but for software development. It’s primarily used by software developers to collaborate on software and track their progress, but can be used by anyone involved in the software development process.
Repositories
Repositories are the most basic unit of GitHub. Each repository represents a real-world project, initiative, or team. Repositories contain issues, discussions, and pull requests (more on that in a moment), as well as “code”, which for non-technical roles, is often text files in the form of Markdown (more on that too).
Markdown
Markdown is how text is formatted on GitHub. If you wanted to format text in a text box that didn’t support formatting, you might use *
s to represent bullets, or wrap a word in _
to emphasize it. That’s Markdown. Markdown is plain text, with optional lightweight formatting that GitHub can render. It sounds like “coding”, but you’ll get the hang of it in no time. To get started, check out the official GitHub docs.
Pro-tip: To convert a Word or Google Doc to Markdown, you can use my very own Word to Markdown converter.
Issues
Issues are how work is tracked on GitHub. You can think of them as “To Do” items (or “tickets” in some contexts). Issues describe the problems you or your team want to solve, with the list of potential problems being referred to as team’s “issue backlog”. You can comment on issues, like you would a blog post, assign them to people, and close them when they have been completed. Issues can also be labeled for ease of discoverability and for tracking additional metadata. For especially complex problems, the body of the issue can even include a task list with checkboxes, to track progress of individual sub-tasks.
Discussions
Discussions are like issues, but don’t have a specific outcome or sense of state (open or closed). You can use discussions to ask questions, collaborate on ideas, and share announcements. You can think of discussions like blog posts, an online forum, or a chat room for your repository.
Pull requests
Pull requests are how you propose changes to a repository. If issues describe the problems, pull requests describe the proposed solutions. Others can also review your proposed changes and comment on, make suggested changes to, or “approve” your pull request. Pull requests modify files within the repository. Once approved, your pull requested is “merged” into the repository and your proposed changes are “live”.
Markdown files
Repositories contain files. These files can be anything, but are often text files in the form of Markdown. You can edit these files directly on GitHub, or you can clone the repository to your computer and edit them there (more on that below). You can also upload files directly to GitHub by dragging-and-dropping them. Generally filenames are lower case and use hyphens instead of spaces. Files, as Markdown is generally how long-lived information is shared and stored (documentation, policy, procedures, etc.).
Tracking changes
At the core of GitHub is a version control system called Git. Git tracks changes to files over time. You can think of it like tracked changes in Google Docs or Microsoft Word (or if you’re into Sci Fi, a time machine for your files). You can see who made changes, when they were made, and what the changes were. You can also “roll back” changes to a previous version of a file.
Commits
Git tracks changes as “commits”. A commit is a snapshot of the file (or files) at a point in time. Each commit should have a brief, descriptive message describing the changes from the previous version, to help you and your colleagues understand what’s going on.
Branches
Branches are like parallel universes or alternate timelines for your files. You can make changes to a branch without affecting files on the “main” branch. Branches contain one or more commits, and when you’re ready, you can merge your changes (commits) into the main branch to update the files there. You can think of branches as saving a copy of a file so that you can work on changes without affecting others’ work, but in a way that makes it easier to merge any changes you make back in with the original when you’re ready.
GitHub flow
GitHub flow describes the process of making changes to a repository. The basic steps are:
- Open an issue describing the problem you want to solve
- Once there is agreement that the problem should be solved, decide on the best solution
- Create a branch to work on the solution
- Make changes to files on the branch
- Commit those changes
- Open a pull request “requesting” that those changes be merged back into the “main” branch
- Your colleagues review your pull request and either approve them or suggest changes
- Once approved, your pull request is “merged” and your changes are now “live” on the main branch
Notifications
GitHub sends notifications to you when someone mentions you in a comment, assigns you to an issue, or requests your review on a pull request. You can also (and often should) “subscribe” to repositories to be notified about some or all activity. Likewise, you can unsubscribe from individual issues if you’re not interested. By default you’ll receive notifications via email, but you can also configure GitHub to use “web notifications”, or even set up notifications in your Slack or Teams channel.
@mentions
One of the most powerful GitHub features is @mentions. You can tag anyone into an issue or pull request by typing @
followed by their GitHub login. They’ll receive a notification and can respond. You can also use @mentions to tag teams, like @github/eng
or @github/eng-ops
. When @mentioning users or teams, it’s best to provide context in the comment so they know why they are receiving the notification.
Cross references
Another powerful GitHub feature is issue and pull request cross references. You can reference another issue or pull request in a comment by including its number (for example, This is related to #123
). When cross referenced, links are created between the two issues or pull requests, making it easier for others to discover and understand the context of the conversation.
Desktop vs. web
Almost everything you’d want to do on GitHub you can do entirely through the web interface. You can view, create, edit, or delete files, browse and comment on issues, and merge pull requests. If you’d prefer to work on your desktop using your favorite desktop software, you can install GitHub Desktop. GitHub desktop provides a visual interface for “pulling” (downloading) repositories onto your computer and interacting with GitHub.
Advanced-ish topics
Pushing and pulling
If you’re using the web interface, you don’t have to worry about pushing or pulling. If you’re using the desktop client, you can think of pushing (in some cases called cloning) as downloading (pulling the files from GitHub) and pushing as uploading (pushing the files back to GitHub).
Emoji and animated GIFs 🎉
In addition Markdown you’ll often see emoji and animated GIFs used heavily on issues and pull requests. You can think of emoji and animated GIFs as the facial expressions and body language of GitHub. They make it easier to convey emotion in written text. I like to describe the communication style on GitHub as “professional but informal”, meaning don’t be afraid to use emoji and animated GIFs to make your comments more expressive (while remaining appropriate, of course).
Project boards
If individual tasks are tracked as issues, project boards are how you track the progress of a project as a whole. Project boards are a visual representation of what issues are on deck, what issues are in progress, and what issues have been completed (todo, doing, done).
Finding information
With so much information available on GitHub, it’s often intimidating to find what you’re looking for. Here are some tips for using GitHub’s powerful search to find anything on GitHub:
- Use keyword search, just like you would any search engine. For example, searching for
widgets
will find all repositories, issues, pull requests, and discussions that contain the word “widgets”. - Scope your search to an organization or repository by using the
org:
orrepo:
qualifiers. For example,org:github
will find all issues in all repositories in thegithub
organization, orrepo:github/docs
will find all issues in thegithub/docs
repository. - You can further refine your search to only show threads that you’re involved in by using the
involves:@me
modifier. For example,widgets involves:@me
will find all issues, pull requests, and discussions that contain the word “widgets” and that you are involved in. - Different types of information (issues, pull requests, discussions, Markdown) are displayed as separate results. Be sure to check the side bar to see all the different types of information that match your search.
- You can limit a “code” search to only Markdown files, by clicking “Markdown” in the sidebar to filter results, or adding
language:Markdown
to your search query.
Checks
You may see one or more status checks on your pull request. Checks are automated tests that run against your proposed changes to enforce certain rules (such as formatting, spelling, or style). If a check fails, you’ll need to fix the problem before your pull request can be merged. You can click “details” next to a failed check to learn more.
When to use an issue vs. a pull request vs. a discussion vs. a Markdown file vs. a project board
Project work generally flows in this order:
- Discussions - Opened-ended conversation without a specific outcome or concept of “done”. This is often the ideation or brainstorming stage.
- Issues - How problems are tracked, discussed, and prioritized.
- Pull requests - How solutions/changes are proposed and reviewed. Generally pull requests should tie back to the issue/problem they are solving.
- Markdown files - How long-lived information is shared and stored (documentation, policy, procedures, etc.). Markdown files are changed via pull request.
As a project proceeds in one or more repositories, high-level project progress is tracked on one or more project boards (which visually organizes the state of multiple issues).
Putting it all together, editing a file on the web
- Open the repository you want to edit
- Navigate to the file you want to edit
- Click the pencil icon to edit the file
- Make your changes
- Click “Commit changes” to save your changes
- Describe your changes in the commit message
- Name your branch
- Click “Propose changes” to open a pull request
- Describe your changes in the pull request, ideally referencing the issue you’re solving (for example,
Closes #123
) - Your colleagues review your pull request and either approve them or suggest changes
- Once approved and checks pass, your pull request is “merged” and your changes are now “live” on the main branch
- Celebrate your first contribution to GitHub!
Glossary
If you come across a term or concept not covered here, be sure to check out the official GitHub glossary.
Happy GitHubbing! 🎉
Check out these popular posts on GitHub's culture and communication patterns.
If you enjoyed this post, you might also enjoy:
- 15 rules for communicating at GitHub
- Twelve tips for growing communities around your open source project
- Four characteristics of modern collaboration tools
- Why open source
- Five best practices in open source: external engagement
- Manage like an engineer
- How to make a product great
- How I re-over-engineered my home network for privacy and security
- Leaders show their work
- Why everything should have a URL
- 19 reasons why technologists don't want to work at your government agency
Ben Balter is the Director of Hubber Engagement within the Office of the COO at GitHub, the world’s largest software development platform, ensuring all Hubbers can do their best (remote) work. Previously, he served as the Director of Technical Business Operations, and as Chief of Staff for Security, he managed the office of the Chief Security Officer, improving overall business effectiveness of the Security organization through portfolio management, strategy, planning, culture, and values. As a Staff Technical Program manager for Enterprise and Compliance, Ben managed GitHub’s on-premises and SaaS enterprise offerings, and as the Senior Product Manager overseeing the platform’s Trust and Safety efforts, Ben shipped more than 500 features in support of community management, privacy, compliance, content moderation, product security, platform health, and open source workflows to ensure the GitHub community and platform remained safe, secure, and welcoming for all software developers. Before joining GitHub’s Product team, Ben served as GitHub’s Government Evangelist, leading the efforts to encourage more than 2,000 government organizations across 75 countries to adopt open source philosophies for code, data, and policy development. More about the author →
This page is open source. Please help improve it.
Edit