Intro to GitHub for non-technical roles

TL;DR: GitHub isn’t just for software developers. If you’re in a non-technical role, you can use GitHub to follow along, collaborate with your team, track your work, and share information. This brief guide includes everything you need to know to get started confidently with GitHub.

7 minute read

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 to 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: or repo: qualifiers. For example, org:github will find all issues in all repositories in the github organization, or repo:github/docs will find all issues in the github/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.

Official docs.

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! 🎉

Interested in learning more about how GitHub works and what it's like to be a GitHubber?
Check out these popular posts on GitHub's culture and communication patterns.

Originally published March 2, 2023 | View revision history

If you enjoyed this post, you might also enjoy:

Ben Balter is the Director of Engineering Operations and Culture at GitHub, the world’s largest software development platform. Previously, 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