GitHub Collaboration Tools: Issues, Pull Requests, Discussions, Notifications and Pages (GH-900)

Use an issue for actionable work that should be owned and closed, a pull request to propose and review a specific code change, and a discussion for open-ended conversation that may never become work. All three live in a repository, support Markdown, @mentions and reactions, and cross-reference each other with #number.

The deciding question is whether there is concrete work with an owner and an end. A defect that needs someone to fix it and should close when the fix merges is an issue. "How do I configure this?" or "should we redesign the plugin system?" is a discussion until the community agrees on work.

GitHub Discussions is a forum attached to a repository (or an organization), organised into categories; each category has a format that controls how threads behave. Maintainers enable Discussions in the repository settings and manage the categories.

Other discussion tools: pinning a discussion gives it extra visibility at the top of the Discussions page, labels help sort threads, and moderators can lock, edit or delete. Discussions and issues convert in both directions: people with triage access can convert an issue into a discussion (the conversation and comments move with it, and the issue backlog keeps only actionable work), and an issue can be created from a discussion once it turns into concrete work.

What discussions do not have is the work-tracking machinery of issues: no assignees, no milestones, and no closing keywords — a merged pull request cannot close a discussion.

A pull request review is a set of comments submitted together with one of three states: Comment, Approve or Request changes. The state is what tells the author (and any branch protection rules) where the change stands.

Reviewers can comment on a specific line or range of lines. Inside a line comment, a suggested change (a suggestion block) proposes the exact replacement text; the author can commit the suggestion to the branch from the pull request page, one at a time or several in a batch, without retyping it. A plain line comment that describes the fix still leaves the edit to the author.

A draft pull request signals work in progress: it cannot be merged and code owners are not automatically asked to review it until it is marked ready. Requesting reviewers, CODEOWNERS and branch protection are covered with repository administration in other GH-900 lessons.

A closing keyword followed by an issue reference in a pull request's description links the pull request to that issue and closes the issue automatically when the pull request is merged into the repository's default branch. The supported keywords are close, closes, closed, fix, fixes, fixed, resolve, resolves and resolved; they are case-insensitive and a colon after the keyword is optional (Fixes #42 and Fixes: #42 both work). Words such as "refs", "tracks" or "relates to" only create a cross-reference on the issue's timeline.

The rules that trip people up:

• Default branch only. If the pull request targets any other branch (for example release-2.0), the keywords are ignored: no link is created and merging does not close the issue.
• One keyword per issue. To close several issues, repeat the full syntax: Resolves #10, resolves #123. A comma list after a single keyword closes only the first issue.
• Other repositories need the full reference. An issue in another repository is written OWNER/REPOSITORY#NUMBER, for example Fixes octo-org/web#12. A bare #12 always means the pull request's own repository, and the repository name without the owner is not enough.
• Commit messages close, but don't link. A closing keyword in a commit message closes the issue when that commit reaches the default branch, but the pull request containing the commit is not listed as a linked pull request. Put the keyword in the pull request description to get both the link and the closure.

Once linked, the pull request appears in the issue's Development section, and the issue appears on the pull request, so anyone can see what work is in flight for an issue.

Instead of a keyword, anyone with write access to a repository can link pull requests and issues manually from the Development section of the sidebar — useful when the description should not be edited. A pull request can be manually linked to up to ten issues.

So to link a pull request in one repository to an issue in another without touching the description, start from the issue. Manual links behave like keyword links: a linked pull request merged into the default branch closes the issue. Only a closing keyword or a Development-sidebar link connects the two; a plain #number mention is just a timeline cross-reference.

Templates pre-fill new issues and pull requests so contributors give maintainers the information they need. They take effect only once they are committed to the repository's default branch.

Issue templates

Markdown files in .github/ISSUE_TEMPLATE/ make the New issue page show a template chooser (for example, a bug report and a feature request). Each Markdown template starts with YAML front matter: name and about describe it in the chooser, and title, labels, assignees and type are applied automatically to every issue opened from it. YAML issue forms, with typed fields, also go in this folder (they are a public preview feature).

A config.yml file in the same folder customises the chooser:

• blank_issues_enabled: false discourages blank issues (people with write, maintain or admin access still see an option to open one); true leaves the blank option for everyone.
• contact_links entries (name, url, about) send people elsewhere — for example support questions to a community forum — straight from the New issue page.

Pull request templates

A file named pull_request_template.md in the repository root, the docs/ folder or the .github/ folder pre-fills the body of every new pull request (a checklist is a common use). For several templates, put them in a PULL_REQUEST_TEMPLATE/ subfolder and choose one with the template query parameter.

Defaults for every repository

An organization or personal account can provide default community health files, including issue and pull request templates, from a public repository named .github. A repository uses a default only when it has no file of that type of its own, and issue templates do not merge: a repository with anything in its own ISSUE_TEMPLATE folder uses none of the defaults.

The search bar on the Issues and Pull requests tabs takes qualifiers that combine with spaces (AND) and can be negated with a leading -. Knowing which qualifier expresses which relationship is the skill.

For example, is:issue is:open label:docs no:assignee lists open documentation issues nobody has taken, and is:pr review-requested:octocat lists pull requests still waiting on Octocat.

Assignees show who owns an issue or pull request. You can assign up to ten people to one item — yourself, anyone who has commented on it, anyone with write permission to the repository, and organization members with read permission. Assignment is different from an @mention (which only notifies) and from requesting a review (which applies to pull requests and asks for feedback, not ownership). Labels, milestones, saved replies and Projects are covered in the GH-900 project-management lesson.

Notifications tell you about activity you care about; you control their volume by choosing what you subscribe to and how they are delivered. Each repository has a Watch setting:

To hear only about new versions of a library you use, watch it with Custom and select only Releases. To quiet a busy repository while still hearing about mentions and threads you joined, choose Participating and @mentions — Ignore goes too far. Starring a repository bookmarks it and shows appreciation; it is not a notification setting. You can also subscribe to (or unsubscribe from) a single issue, pull request or discussion from its sidebar without changing the repository's watch level.

Triage in the inbox

The notifications inbox (github.com/notifications) is where you work through them:

• Done clears a notification from the inbox; Unsubscribe also stops future notifications from that thread.
• Save keeps a notification indefinitely so you can return to it (find it with is:saved); unsaved notifications are kept for five months. Marking read or unread changes only its read state.
• Filters narrow the list, for example reason:participating, reason:review-requested or repo:, and you can save custom filters.

Delivery

Notifications can be delivered on the web, in GitHub Mobile and by email; you choose channels per type of activity. With custom routing you send email notifications for repositories owned by a particular organization to a different verified address — for example, employer repositories to a work address and everything else to a personal one (an organization can require an address in its verified domain).

A gist is a lightweight way to share code snippets, notes or small files by URL without creating a full repository. Every gist is a Git repository, so it keeps a revision history of each edit and can be cloned and forked; a gist can contain several files, and it can be embedded in a web page.

Secret gists are not private. They are only unlisted. Content that must stay hidden — such as credentials — belongs in a private repository, and any secret that was ever posted in a gist should be rotated. Gists are edited by their owner; others contribute by forking.

Use a repository wiki for longer documentation that sits with the code, and GitHub Pages for a published website. A wiki holds supplementary documentation — usage guides, design principles, how the project is organised — alongside the code. The README stays the short "what is this and how do I start" page; the wiki is where the detail goes. A wiki is itself a Git repository that can be cloned and edited locally. Wikis are available in public repositories on every plan, and in private repositories on paid plans.

• Who can edit: by default, people with write access to the repository. For a public repository, clearing Restrict editing to collaborators only (under Features in the repository settings) lets anyone with a GitHub account edit — no need to hand out write access to the code.
• Search engines: a wiki is indexed only when the repository has 500 or more stars and wiki editing is restricted to collaborators. Both conditions must hold. For documentation that must be found by search engines, GitHub recommends a GitHub Pages site.

GitHub Pages

GitHub Pages hosts a static website (HTML, CSS, JavaScript) straight from a repository — common for project documentation, personal sites and handbooks. It does not run server-side code.

• Site types: a user or organization site is published from a repository named exactly <owner>.github.io and served at https://<owner>.github.io (one per account). Any other repository publishes a project site at https://<owner>.github.io/<repository>. Custom domains are supported.
• Publishing source: either Deploy from a branch — the root or /docs folder of a chosen branch, with an optional Jekyll build — or GitHub Actions, where a workflow builds the site and deploys it as a Pages artifact. Use Actions for any other static site generator (Hugo, for example) or when you don't want a branch of compiled files.
• Visibility: a Pages site is public on the internet even when its repository is private (publishing from a private repository needs a paid plan). Restricting a site so only organization members can view it — private publishing — requires an organization on GitHub Enterprise Cloud.