data/github/github_support_docs.txt

GitHub — Product Support Documentation
============================================================
Product: GitHub
Description: Code hosting, version control, and collaboration platform.
Source: Public help center documentation
============================================================


────────────────────────────────────────────────────────────
TOPIC: About GitHub and Git
URL: https://docs.github.com/en/get-started/start-your-journey/about-github-and-git
────────────────────────────────────────────────────────────

About GitHub
GitHub is a cloud-based platform where you can store, share, and work together with others to write code.
Storing your code in a "repository" on GitHub allows you to:
Showcase or share
your work.
Track and manage
changes to your code over time.
Let others
review
your code, and make suggestions to improve it.
Collaborate
on a shared project, without worrying that your changes will impact the work of your collaborators before you're ready to integrate them.
Collaborative working, one of GitHub’s fundamental features, is made possible by the open-source software, Git, upon which GitHub is built.
About Git
Git is a version control system that intelligently tracks changes in files. Git is particularly useful when you and a group of people are all making changes to the same files at the same time.
Typically, to do this in a Git-based workflow, you would:
Create a branch
off from the main copy of files that you (and your collaborators) are working on.
Make edits
to the files independently and safely on your own personal branch.
Let Git intelligently
merge
your specific changes back into the main copy of files, so that your changes don't impact other people's updates.
Let Git
keep track
of your and other people's changes, so you all stay working on the most up-to-date version of the project.
To try using Git yourself, see
Getting started with Git
How do Git and GitHub work together?
When you upload files to GitHub, you'll store them in a "Git repository." This means that when you make changes (or "commits") to your files in GitHub, Git will automatically start to track and manage your changes.
There are plenty of Git-related actions that you can complete on GitHub directly in your browser, such as creating a Git repository, creating branches, and uploading and editing files.
However, most people work on their files locally (on their own computer), then continually sync these local changes—and all the related Git data—with the central "remote" repository on GitHub. There are plenty of tools that you can use to do this, such as GitHub Desktop.
Once you start to collaborate with others and all need to work on the same repository at the same time, you’ll continually:
Pull
all the latest changes made by your collaborators from the remote repository on GitHub.
Push
back your own changes to the same remote repository on GitHub.
Git figures out how to intelligently merge this flow of changes, and GitHub helps you manage the flow through features such as "pull requests."
Where do I start?
If you're new to GitHub, and unfamiliar with Git, we recommend working through the articles in the
Start your journey
category. The articles focus on tasks you can complete directly in your browser on GitHub and will help you to:
Create an account
on GitHub.
Learn the "GitHub Flow"
, and the key principles of collaborative working (branches, commits, pull requests, merges).
Personalise your profile
to share your interests and skills.
Explore GitHub
to find inspiration for your own projects and connect with others.
Learn how to
download
interesting code for your own use.
Learn how to
upload
something you're working on to a GitHub repository.
Next steps
Creating an account on GitHub
Further reading
Connecting to GitHub


────────────────────────────────────────────────────────────
TOPIC: About GitHub Repositories
URL: https://docs.github.com/en/repositories/creating-and-managing-repositories/about-repositories
────────────────────────────────────────────────────────────

About repositories
A repository is the most basic element of GitHub. It's a place where you can store your code, your files, and each file's revision history. Repositories can have multiple collaborators and can be either public or private.
To create a new repository, go to
https://github.com/new
. For instructions, see
Quickstart for repositories
Repository terminology
Before getting started with repositories, learn these important terms.
Term
Definition
Branch
A parallel version of your code that is contained within the repository, but does not affect the primary or main branch.
Clone
To download a full copy of a repository's data from GitHub.com, including all versions of every file and folder.
Fork
A new repository that shares code and visibility settings with the original "upstream" repository.
Merge
To take the changes from one branch and apply them to another.
Pull request
A request to merge changes from one branch into another.
Remote
A repository stored on GitHub, not on your computer.
Upstream
The branch on an original repository that has been forked or cloned. The corresponding branch on the cloned or forked repository is called the "downstream."
About repository ownership
You can own repositories individually, or you can share ownership of repositories with other people in an organization.
In either case, access to repositories is managed by permissions. For more information, see
Permission levels for a personal account repository
and
Repository roles for an organization
About collaboration
You can use repositories to manage your work and collaborate with others.
You can use issues to collect user feedback, report software bugs, and organize tasks you'd like to accomplish. For more information, see
About issues
You can use GitHub Discussions to ask and answer questions, share information, make announcements, and conduct or participate in conversations about a project. For more information, see
About discussions
You can use pull requests to propose changes to a repository. For more information, see
About pull requests
You can use Projects to organize and prioritize your issues and pull requests. For more information, see
About Projects
With GitHub Free for personal accounts and organizations, you can work with unlimited collaborators on unlimited public repositories with a full feature set, or unlimited private repositories with a limited feature set. To get advanced tooling for private repositories, you can upgrade to GitHub Pro, GitHub Team, or GitHub Enterprise Cloud. For more information, see
GitHub's plans
About repository visibility
You can restrict who has access to a repository by choosing a repository's visibility: public or private.
When you create a repository, you can choose to make the repository public or private. Repositories in organizations that use GitHub Enterprise Cloud and are owned by an enterprise account can also be created with internal visibility. For more information, see
the GitHub Enterprise Cloud documentation
Public repositories are accessible to everyone on the internet.
Private repositories are only accessible to you, people you explicitly share access with, and, for organization repositories, certain organization members.
Security considerations for repository visibility
Public repositories expose your codebase to everyone, increasing the risk that attackers might exploit vulnerabilities or access sensitive information. You can mitigate these risks by enabling GitHub security features such as Dependabot, secret scanning, push protection, and code scanning for the repository. Additionally, you should add a security policy (a
SECURITY.md
file) to your repository, that outlines how vulnerabilities should be reported, to ensure that potential threats are addressed efficiently.
Although private repositories restrict access to authorized users, it's still essential to implement strong access controls, multi-factor authentication, and regular audits to mitigate risks.
For more information, see
Quickstart for securing your repository
Organization owners always have access to every repository created in an organization. For more information, see
Repository roles for an organization
People with admin permissions for a repository can change an existing repository's visibility. For more information, see
Setting repository visibility
Next steps
Here are some helpful resources for taking your next steps with repositories.
Best practices for repositories
: Learn how to use repositories most effectively.
Creating a new repository
: Create a new repository.
Creating and deleting branches within your repository
: Learn how to create and delete branches within your repository.
Creating a pull request
: Create a pull request to propose and collaborate on changes to a repository.


────────────────────────────────────────────────────────────
TOPIC: About GitHub Pull Requests
URL: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests
────────────────────────────────────────────────────────────

Pull requests are proposals to merge code changes into a project. A pull request is GitHub's foundational
collaboration feature
, letting you discuss and review changes before merging them. This helps teams work together, catch issues early, and maintain code quality.
View your pull requests
Working with pull requests
The
Conversation
tab of a pull request displays a description of the changes, a timeline of events, and comments and reviews from collaborators. This central hub lets you track the discussion and progress of the proposed changes.
The
Commits
tab shows all commits made to the pull request branch in chronological order. This helps you understand the development history and see how the changes evolved over time.
The
Checks
tab displays the status of any automated tests, builds, or other continuous integration workflows that run when you push commits. These checks help ensure your changes meet quality standards before merging.
The
Files changed
tab shows the differences between the proposed changes and the existing code, making it easy to see what will change when the pull request merges.
Draft pull requests
When you create a pull request, you can choose to make it a draft pull request. Draft pull requests cannot be merged, and code owners are not automatically requested to review them. This is useful when you want to share work-in-progress without formally requesting reviews.
When you're ready to get feedback on your pull request, you can mark your draft pull request as ready for review. Marking a pull request as ready for review will request reviews from any code owners. You can convert a pull request to a draft at any time. See
Changing the stage of a pull request
Pull request refs and merge branches
When you open a pull request, GitHub creates up to two temporary, read-only Git references for it:
Ref
Description
refs/pull/PULL_REQUEST_NUMBER/head
Points to the latest commit on the pull request's head branch.
refs/pull/PULL_REQUEST_NUMBER/merge
A merge branch—a simulated merge commit that represents what the repository would look like if the pull request were merged right now. This ref is only available when the pull request has no merge conflicts.
The merge branch automatically updates when the head branch or base branch changes. To fetch it locally:
git fetch origin refs/pull/PULL_REQUEST_NUMBER/merge
git checkout FETCH_HEAD
Replace
PULL_REQUEST_NUMBER
with the number of your pull request.
For information about how GitHub Actions uses the merge branch, see
Events that trigger workflows
Differences between commits on compare and pull request pages
The compare and pull request pages use different methods to calculate the diff for changed files:
Compare pages show the diff between the tip of the head ref and the current common ancestor (that is, the merge base) of the head and base ref.
Pull request pages show the diff between the tip of the head ref and the common ancestor of the head and base ref at the time when the pull request was created. As a result, the merge base used for the comparison might be different.
Further reading
Creating a pull request
About branches
Commenting on a pull request


────────────────────────────────────────────────────────────
TOPIC: About GitHub Issues
URL: https://docs.github.com/en/issues/tracking-your-work-with-issues/about-issues
────────────────────────────────────────────────────────────

You can create issues in your repository to plan, discuss, and track work. Issues are quick to create, flexible, and can be used in many ways. Issues can track bug reports, new features and ideas, and anything else you need to write down or discuss with your team, and you can use projects to plan and track the work for your team. You can also break your work down further by adding sub-issues and easily browse the full hierarchy of work to be done.
Issues can be created in a variety of ways, so you can choose the most convenient method for your workflow. For example, you can create an issue from a repository, while adding sub-issues, convert a comment in an issue or pull request, create an issue from a specific line of code, or via a URL query. You can also create an issue from your platform of choice: through the web UI, GitHub Desktop, GitHub CLI, GraphQL and REST APIs, or GitHub Mobile. See
Creating an issue
Tip
You can also use Copilot Chat to generate ideas, outlines, or drafts for discussions or blog posts, based on your issues. See
Writing discussions or blog posts
About sub-issues
You can add sub-issues to an issue to quickly break down larger pieces of work into smaller issues. Sub-issues add support for hierarchies of issues on GitHub by creating relationships between your issues. You can create multiple levels of sub-issues that accurately represent your project by breaking down tasks into exactly the amount of detail that you and your team require. See
Adding sub-issues
and
Browsing sub-issues
About issue dependencies
You can define blocking relationships between issues using issue dependencies. Issue dependencies let you identify issues that are blocked by, or blocking, other work. See
Creating issue dependencies
Metadata on issues
You can add metadata to your issues, including issue types, labels and milestones to organize your issues.
See
Managing issue types in an organization
Managing labels
and
About milestones
About integration with GitHub
Issues integrate with your work all across GitHub. Mentioning an issue in another issue or pull request will create references between them and using keywords, like
fixes:
, in your pull requests will automatically close the associated issues. See
Linking a pull request to an issue
Using Projects to plan and track your work
Projects is strongly integrated with issues to plan and track the work for your team. All your issue metadata is available in your projects, allowing you to create views and filters to represent your work. See
About Projects
Staying up to date
To stay updated on the most recent comments in an issue, you can subscribe to an issue to receive notifications about the latest comments. To quickly find links to recently updated issues you're subscribed to, visit your dashboard. For more information, see
About notifications
and
Quickstart for your personal dashboard
You can assign yourself and teammates to issues to make it clear who is working on an issue and also make it easier for you to locate your issues. See
Assigning issues and pull requests to other GitHub users
and
Viewing all issues and pull requests
Community management
To help contributors open meaningful issues that provide the information that you need, you can use issue forms and issue templates. See
Using templates to encourage useful issues and pull requests
To maintain a healthy community, you can report comments that violate GitHub's
Community Guidelines
. See
Reporting abuse or spam
Efficient communication
You can @mention collaborators who have access to your repository in an issue to draw their attention to a comment. 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. To communicate responsibility, you can assign issues. If you find yourself frequently typing the same comment, you can use saved replies.
See
Basic writing and formatting syntax
and
Assigning issues and pull requests to other GitHub users
Comparing issues and discussions
Some conversations are more suitable for GitHub Discussions. You can use GitHub Discussions to ask and answer questions, share information, make announcements, and conduct or participate in conversations about a project. For more information, see
About discussions
. For guidance on when to use an issue or a discussion, see
Communicating on GitHub
When a conversation in an issue is better suited for a discussion, you can convert the issue to a discussion.
Next steps
Here are some helpful resources for taking your next steps with GitHub Issues:
To learn about getting started using issues, see
Quickstart for GitHub Issues
To learn about the essentials for using GitHub's planning and tracking tools, see
Planning and tracking work for your team or project
To learn more about how projects can help you with planning and tracking, see
Learning about Projects


────────────────────────────────────────────────────────────
TOPIC: GitHub Authentication Guide
URL: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/about-authentication-to-github
────────────────────────────────────────────────────────────

About authentication to GitHub
To keep your account secure, you must authenticate before you can access certain resources on GitHub. When you authenticate to GitHub, you supply or confirm credentials that are unique to you to prove that you are exactly who you declare to be.
You can access your resources in GitHub in a variety of ways: in the browser, via GitHub Desktop or another desktop application, with the API, or via the command line. Each way of accessing GitHub supports different modes of authentication.
Username and password (or social login) with two-factor authentication, or a passkey (GitHub Free, and GitHub Enterprise Cloud only)
Personal access token
SSH key
Authenticating in your browser
If you're a member of an enterprise with managed users, you will authenticate to GitHub in your browser using your IdP. For more information, see
About Enterprise Managed Users
in the GitHub Enterprise Cloud documentation.
If you're not a member of an enterprise with managed users, you will authenticate using your GitHub username and password, or a passkey. You may also use two-factor authentication and SAML single sign-on, which can be required by organization and enterprise owners.
Note
As of March 2023, GitHub required all users who contribute code on GitHub.com to enable one or more forms of two-factor authentication (2FA). If you were in an eligible group, you would have received a notification email when that group was selected for enrollment, marking the beginning of a 45-day 2FA enrollment period, and you would have seen banners asking you to enroll in 2FA on GitHub.com. If you didn't receive a notification, then you were not part of a group required to enable 2FA, though we strongly recommend it.
For more information about the 2FA enrollment rollout, see
this blog post
If you need to use multiple accounts on GitHub.com, such as a personal account and a service account, you can quickly switch between your accounts without always needing to reauthenticate each time. For more information, see
Switching between accounts
Username and password only
You'll create a password when you create your account on GitHub. We recommend that you use a password manager to generate a random and unique password. For more information, see
Creating a strong password
If you have not enabled 2FA, GitHub may ask for additional verification when you first sign in from a new or unrecognized device, such as a new browser profile, a browser where the cookies have been deleted, or a new computer. For more information, see
Verifying new devices when signing in
Social login
You'll authenticate with Google or Apple, which are the supported social login providers when you create your account on GitHub. We recommend that you also configure 2FA and add a passkey or a password as an additional account recovery mechanism.
If you have an existing account created with a password, you can add your social login email to the account. This allows you to use your social login identity as a first-factor (password) replacement when you sign in to GitHub.
You can unlink your social login identities from your GitHub email settings page. For more information, see
Unlinking your email address from a locked account
Two-factor authentication (2FA)
(recommended)
If you enable two-factor authentication (2FA), after you sign in with social login or your username and password, you'll be prompted to enter a code from a time-based one-time password (TOTP) application on your mobile device or sent as a text message (SMS).
After you configure 2FA, your account enters a check up period for 28 days. You can leave the check up period by successfully performing 2FA within those 28 days. If you don't perform 2FA in that timespan, you'll then be asked to perform 2FA inside one of your existing GitHub sessions.
If you cannot perform 2FA to pass the 28th day checkup, you will be provided a shortcut that lets you reconfigure your 2FA settings. You must reconfigure your settings before you can access the rest of GitHub. For more information, see
Accessing GitHub using two-factor authentication
and
Configuring two-factor authentication
In addition to authentication with a TOTP application or a text message, you can optionally add an alternative method of authentication with GitHub Mobile or a security key using WebAuthn. See
Configuring two-factor authentication using GitHub Mobile
Configuring two-factor authentication using a security key
Note
If you cannot use any recovery methods, you have permanently lost access to your account. However, you can unlink an email address tied to the locked account. The unlinked email address can then be linked to a new or existing account. For more information, see
Unlinking your email address from a locked account
Passkey
You can add a passkey to your account to enable a secure, passwordless login. Passkeys satisfy both password and 2FA requirements, so you can complete your sign in with a single step. See
About passkeys
SAML single sign-on
Before you can access resources owned by an organization or enterprise account that uses SAML single sign-on, you may need to also authenticate through an IdP. For more information, see
About authentication with single sign-on
in the GitHub Enterprise Cloud documentation.
Session cookies
GitHub uses cookies to provide services and increase security. You can review details about GitHub's cookies in
GitHub Cookies
The gist.github.com and github.com domains use separate cookies.
GitHub typically marks a user session for deletion after two weeks of inactivity.
GitHub does not immediately delete a session when you sign out. Periodically, GitHub automatically deletes expired sessions.
Authenticating with GitHub Desktop
You can authenticate with GitHub Desktop using your browser. For more information, see
Authenticating to GitHub in GitHub Desktop
Authenticating with the API
You can authenticate with the API in different ways. For more information, see
Authenticating to the REST API
Authenticating to the API with a personal access token
If you want to use the GitHub REST API for personal use, you can create a personal access token. If possible, GitHub recommends that you use a fine-grained personal access token instead of a personal access token (classic). For more information about creating a personal access token, see
Managing your personal access tokens
Authenticating to the API with an app
If you want to use the API on behalf of an organization or another user, GitHub recommends that you use a GitHub App. For more information, see
About authentication with a GitHub App
You can also create an OAuth token with an OAuth app to access the REST API. However, GitHub recommends that you use a GitHub App instead. GitHub Apps allow more control over the access and permission that the app has.
Authenticating to the API in a GitHub Actions workflow
If you want to use the API in a GitHub Actions workflow, GitHub recommends that you authenticate with the built-in
GITHUB_TOKEN
instead of creating a token. You can grant permissions to the
GITHUB_TOKEN
with the
permissions
key.
Note that
GITHUB_TOKEN
can only access resources within the repository that contains the workflow. If you need to make changes to resources outside of the workflow repository, you will need to use a personal access token or GitHub App.
For more information, see
Use GITHUB_TOKEN for authentication in workflows
Authenticating with the command line
You can access repositories on GitHub from the command line in two ways, HTTPS and SSH, and both have a different way of authenticating. The method of authenticating is determined based on whether you choose an HTTPS or SSH remote URL when you clone the repository. For more information about which way to access, see
About remote repositories
HTTPS
You can work with all repositories on GitHub over HTTPS, even if you are behind a firewall or proxy.
If you authenticate with GitHub CLI, you can either authenticate with a personal access token or via the web browser. For more information about authenticating with GitHub CLI, see
gh auth login
If you authenticate without GitHub CLI, you must authenticate with a personal access token. When Git prompts you for your password, enter your personal access token. Alternatively, you can use a credential helper like
Git Credential Manager
. Password-based authentication for Git has been removed in favor of more secure authentication methods. For more information, see
Managing your personal access tokens
. Every time you use Git to authenticate with GitHub, you'll be prompted to enter your credentials, unless you cache them with a
credential helper
SSH
You can work with all repositories on GitHub over SSH, although firewalls and proxies might refuse to allow SSH connections.
If you authenticate with GitHub CLI, the CLI will find SSH public keys on your machine and will prompt you to select one for upload. If GitHub CLI does not find a SSH public key for upload, it can generate a new SSH public/private keypair and upload the public key to your account on GitHub.com. Then, you can either authenticate with a personal access token or via the web browser. For more information about authenticating with GitHub CLI, see
gh auth login
If you authenticate without GitHub CLI, you will need to generate an SSH public/private keypair on your local machine and add the public key to your account on GitHub.com. For more information, see
Generating a new SSH key and adding it to the ssh-agent
. Every time you use Git to authenticate with GitHub, you'll be prompted to enter your SSH key passphrase, unless you've
stored the key
Authorizing for SAML single sign-on
To use a personal access token or SSH key to access resources owned by an organization that uses SAML single sign-on, you must also authorize the personal token or SSH key. For more information, see
Authorizing a personal access token for use with single sign-on
Authorizing an SSH key for use with single sign-on
in the GitHub Enterprise Cloud documentation.
GitHub's token formats
GitHub issues tokens that begin with a prefix to indicate the token's type.
Token type
Prefix
More information
Personal access token (classic)
ghp_
Managing your personal access tokens
Fine-grained personal access token
github_pat_
Managing your personal access tokens
OAuth access token
gho_
Authorizing OAuth apps
User access token for a GitHub App
ghu_
Authenticating with a GitHub App on behalf of a user
Installation access token for a GitHub App
ghs_
Authenticating as a GitHub App installation
Refresh token for a GitHub App
ghr_
Refreshing user access tokens
For more information GitHub's token types and their management, see
GitHub credential types reference