diff --git a/.github/instructions/content-guidelines.instructions.md b/.github/instructions/content-guidelines.instructions.md index 0efb2d4d2344..112bfc56d9c4 100644 --- a/.github/instructions/content-guidelines.instructions.md +++ b/.github/instructions/content-guidelines.instructions.md @@ -19,6 +19,20 @@ The strategic priority is simplification: create less content and remove content * Would a typical internet user figure this out on their own by exploring the UI? * Is the information presented at the moment the reader actually needs it? +## Give opinionated, actionable guidance + +This applies whenever you give the reader advice or present ways to accomplish a task. + +* Be opinionated when there is a better way: when several approaches exist, recommend the best one and explain why, rather than presenting all options as equally valid. When they are genuinely equivalent, stay neutral. +* Tell users the best practice AND how to follow it: whenever you state a best practice, pair it with concrete steps or an example so the reader can act on it, never the advice alone. + +## Focus on the reader's purpose, not the product + +Frame an article around what the reader is trying to accomplish, not the product or feature they use to do it. This applies when naming an article or deciding what a new or substantially reworked article should cover; do not use it to justify restructuring an article during a small edit. + +* Title articles by the reader's goal, not the product or feature. For example, "Secure your enterprise", not "Use GitHub Advanced Security". +* Scope articles around a task, not a product. When a task naturally spans multiple features or products, look for the opportunity to cover them together in one task-focused article or tutorial rather than splitting into per-product articles. Keep each article to a single purpose (the task): combine features only when they serve that same task, not to bundle unrelated capabilities. + ## Intros: pull people in This section applies mainly to the `intro` frontmatter field and, for conceptual articles, section openings. diff --git a/CHANGELOG.md b/CHANGELOG.md index 5eeaecca2432..b98b4b8e9bcf 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,11 @@ # Docs changelog +**13 July 2026** + +We published [Bring your own key for GitHub Copilot](https://docs.github.com/en/copilot/concepts/models/bring-your-own-key). This article distinguishes between two different mechanisms for customers to use Copilot with custom models. We have also retitled corresponding how-to content to make the distinction clearer. + +
+ **16 June 2026** We made some improvements to our documentation on Copilot policies: diff --git a/assets/images/help/code-quality/generate-fix.png b/assets/images/help/code-quality/generate-fix.png deleted file mode 100644 index 4316fd7c6c11..000000000000 Binary files a/assets/images/help/code-quality/generate-fix.png and /dev/null differ diff --git a/assets/images/help/code-quality/standard-findings-filters.png b/assets/images/help/code-quality/standard-findings-filters.png deleted file mode 100644 index 5662cbfb1445..000000000000 Binary files a/assets/images/help/code-quality/standard-findings-filters.png and /dev/null differ diff --git a/assets/images/help/code-quality/user-pr-ai-findings.png b/assets/images/help/code-quality/user-pr-ai-findings.png deleted file mode 100644 index b3395ad7ea5e..000000000000 Binary files a/assets/images/help/code-quality/user-pr-ai-findings.png and /dev/null differ diff --git a/content/admin/concepts/enterprise-best-practices/organize-work.md b/content/admin/concepts/enterprise-best-practices/organize-work.md index 2c74ddd45911..9136aba3368d 100644 --- a/content/admin/concepts/enterprise-best-practices/organize-work.md +++ b/content/admin/concepts/enterprise-best-practices/organize-work.md @@ -12,12 +12,48 @@ redirect_from: - /admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/best-practices-for-structuring-organizations-in-your-enterprise - /admin/concepts/best-practices-for-enterprises - /admin/concepts/best-practices + - /enterprise-onboarding/setting-up-organizations-and-teams/best-practices-for-organizations-in-your-enterprise + - /enterprise-onboarding/setting-up-organizations-and-teams/best-practices allowTitleToDifferFromFilename: true category: - Get started with GitHub Enterprise --- -{% data reusables.enterprise-onboarding.best-practices %} +## Use organizations for work or governance + +There are two main models of using organizations: + +* **Group related work projects**: Group repositories for a specific application and related services. Teams that work on that application will then be able to communicate effectively and contribute across the different repositories. +* **Group similar governance requirements**: Group repositories that require similar policies, security settings, or access restrictions. You will be able to apply the necessary settings to the organization at scale. For example, if you have highly confidential work projects or a specific data classification, group these in an organization where only a limited number of people have access. + +## Create organizations intentionally + +Creating organizations is a balance. While {% data variables.product.company_short %} continues to make organization management more scalable, you should be intentional about why you create an organization. It's always easier to add organizations than to remove them. + +Don't try to fit unnatural pieces of your company together into a single large organization. The administrative features of an enterprise account allow you to automate processes, manage access, and apply policies across multiple organizations at once. However, there are tradeoffs of segregating work into many different organizations: + +* It's easier for people to communicate within one organization, as @-mentions only work between members of the same organization. +* It's easier for people to find resources in one organization, as there's only one place to search. + +You may want to start with a small number of organizations as you develop your strategy. After you build confidence in what works well for your business, you can create additional organizations as the need arises. + +You should regularly evaluate your strategies for access, governance, and organization of work. Cleaning up legacy organizations is a part of that process. + +{% ifversion enterprise-teams %} + +## Use teams to organize people + +Enterprise teams are the best way to control access and permissions at scale. Create teams and manage their membership as your primary means of performing actions like adding users to organizations, granting licenses, and delegating access to enterprise settings. + +When you use teams in this way, controlling membership of teams is a sensitive action. Limit the permission to control teams and their membership to a small number of people. If you use an external identity provider (IdP), sync teams to IdP groups so that team membership can be controlled by a central administrator. + +Use roles to delegate administrative duties to teams. This allows you to limit the number of enterprise owners in your company and give people just the permissions they need to do their jobs effectively. For example, a team of auditors can receive access to the enterprise audit log without being able to access any other settings. + +{% endif %} + +## Collaborate in organization-owned repositories + +We recommend collaborating in organization-owned repositories whenever possible and minimizing collaboration in user-owned repositories. Organization-owned repositories have more sophisticated security and administrative features, and they remain accessible even as enterprise membership changes. ## Use innersource practices diff --git a/content/admin/concepts/enterprise-best-practices/use-innersource.md b/content/admin/concepts/enterprise-best-practices/use-innersource.md index d50090d1d057..93470ed98edb 100644 --- a/content/admin/concepts/enterprise-best-practices/use-innersource.md +++ b/content/admin/concepts/enterprise-best-practices/use-innersource.md @@ -6,9 +6,66 @@ versions: ghec: '*' ghes: '*' contentType: concepts +redirect_from: + - /enterprise-onboarding/setting-up-organizations-and-teams/use-innersource allowTitleToDifferFromFilename: true category: - Get started with GitHub Enterprise --- -{% data reusables.enterprise-onboarding.use-innersource %} +You can use innersource practices to drive collaboration and productivity in your enterprise. Innersource makes it easy for all employees to discover and reuse work. This allows development teams to learn from each other's work, share their expertise, and avoid duplicating effort to recreate common services. + +## Make repositories discoverable + +Unless they contain sensitive information, you should aim to make repositories visible to all employees. + +To do this, encourage employees to use **internal** visibility whenever possible. Internal visibility allows any member of any organization in the enterprise to view the repository, regardless of whether the user is a member of the organization that owns the repository. + +You should also set permissive **base permissions** for organizations. An organization's base permission policy determines the default level of access that members of that organization have to all the organization's repositories. Generally, organizations should have at least a "Read" base permission so that all organization members can see any repository. Organization owners can then use teams to grant people greater levels of access in specific repositories. + +If you have more sensitive repositories that should not be widely visible, you can set up a dedicated organization with a more restrictive base permission and add specific teams to this organization. + +For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/about-repositories#about-internal-repositories) and [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/setting-base-permissions-for-an-organization). + +## Document projects + +Organize and document your repositories so that people can search for work across the enterprise. + +Repository **READMEs** are effective because they're defined in files in the repository, so users can search for them like code. You can also create READMEs at the level of an organization or enterprise account to provide a higher-level overview of where to find different projects. For more formal internal documentation, consider setting up a **{% data variables.product.prodname_pages %} site** or **wikis**. + +You can use **repository topics** to group repositories that contain a certain programming language, are owned by a certain team, and so on. This is another way of making repositories easier to find. + +For more information, see: + +* [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes), [AUTOTITLE](/organizations/collaborating-with-groups-in-organizations/customizing-your-organizations-profile#adding-a-member-only-organization-profile-readme), and [AUTOTITLE](/admin/managing-your-enterprise-account/creating-a-readme-for-an-enterprise) +* [AUTOTITLE](/pages/getting-started-with-github-pages/creating-a-github-pages-site) +* [AUTOTITLE](/communities/documenting-your-project-with-wikis/adding-or-editing-wiki-pages) +* [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics) + +## Set up a culture for sharing work + +Encourage teams to publicize their work and share resources with other teams. {% data variables.product.github %} has a number of features that make this easier. For example, teams can: + +* Use **discussions** to make their work more visible to other teams. See [AUTOTITLE](/discussions/collaborating-with-your-community-using-discussions/participating-in-a-discussion#creating-a-discussion). +* Create a dedicated internal repository for sharing **actions and reusable {% data variables.product.prodname_actions %} workflows**, which anyone can reference when they write a workflow within the enterprise. See [AUTOTITLE](/actions/how-tos/reuse-automations/share-with-your-enterprise). +* Share reusable pieces of code in internal packages with **{% data variables.product.prodname_registry %}** registries. For enhanced security, you can give {% data variables.product.github %}'s security features access to these registries. See [AUTOTITLE](/packages/learn-github-packages/introduction-to-github-packages). +* Set up common templates and frameworks as **template repositories** that other people can copy to get started with a project. See [AUTOTITLE](/repositories/creating-and-managing-repositories/creating-a-template-repository). + +Like with an open source project, you should ensure shared projects have a support model and a clearly defined team of maintainers, especially for services that many parts of your enterprise rely on. Ideally the maintainers team will contain representatives from the different teams that use the service. + +## Hide content from external collaborators + +If you have external contractors or collaborators who need access to your enterprise's projects, you can grant them a different level of access from regular employees. + +Specifically, you may want to hide internal repositories from an external collaborator. To do this: + +* If you use {% data variables.product.prodname_emus %}, provision an account for the user with the **guest collaborator** role. Guest collaborators don't have access to internal repositories by default, but they receive base permissions in organizations where they're added as members. They can also be added as repository collaborators in repositories. +* If you do not use {% data variables.product.prodname_emus %}, add the user as an **outside collaborator** in the required repositories, but ensure they are not added as a member of any organization. + +Outside collaborators (called **repository collaborators** if you use {% data variables.product.prodname_emus %}) only have access to a specific repository. These users are not full organization members, so they do not receive the base level of access for the organization, and they cannot automatically see internal repositories in the enterprise unless they are a member of another organization. + +For more information, see {% ifversion ghec %}[AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/enabling-guest-collaborators) and{% endif %} [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-outside-collaborators/adding-outside-collaborators-to-repositories-in-your-organization). + +## Next steps + +Now that you've set up organizations and teams, learn how to stay compliant and secure by setting up governance policies for your users and repositories. See [AUTOTITLE](/admin/concepts/security-and-compliance/enterprise-policies). diff --git a/content/admin/concepts/enterprise-fundamentals/automations-in-your-enterprise.md b/content/admin/concepts/enterprise-fundamentals/automations-in-your-enterprise.md index 2515ac336e74..a7b16eda1cf6 100644 --- a/content/admin/concepts/enterprise-fundamentals/automations-in-your-enterprise.md +++ b/content/admin/concepts/enterprise-fundamentals/automations-in-your-enterprise.md @@ -5,6 +5,8 @@ intro: Learn how {% data variables.product.prodname_github_apps %}, external ser versions: feature: enterprise-apps-public-beta contentType: concepts +redirect_from: + - /enterprise-onboarding/github-apps/automations-in-your-enterprise category: - Get started with GitHub Enterprise --- diff --git a/content/admin/concepts/enterprise-fundamentals/roles-in-an-enterprise.md b/content/admin/concepts/enterprise-fundamentals/roles-in-an-enterprise.md index 043426f25e3a..521307212d67 100644 --- a/content/admin/concepts/enterprise-fundamentals/roles-in-an-enterprise.md +++ b/content/admin/concepts/enterprise-fundamentals/roles-in-an-enterprise.md @@ -6,12 +6,38 @@ versions: shortTitle: Roles redirect_from: - /admin/overview/about-roles + - /enterprise-onboarding/feature-enhancements/about-access-permissions-on-github + - /enterprise-onboarding/setting-up-organizations-and-teams/about-roles-in-an-enterprise contentType: concepts category: - Get started with GitHub Enterprise --- -{% data reusables.enterprise-onboarding.about-roles %} +## What are roles? + +Roles allow you to delegate administrative duties and manage access securely at every level of your enterprise. + +A role is a **set of permissions** that you can assign to individuals or teams. A permission is the ability to perform a specific action, such as changing billing settings. + +A user in an enterprise has roles for both the enterprise account and organizations where they have access. + +* The enterprise-level roles define the user's access to enterprise settings. +* Organization-level roles define the user's access to organization settings and repositories in an organization. + +## Predefined and custom roles + +Organization and enterprise roles can be **predefined** or **custom**. Enterprise custom roles are in {% data variables.release-phases.public_preview %}. + +* Predefined roles, such as enterprise owner, organization owner, or billing manager, are available for all accounts. They grant a predefined set of permissions to users or teams and may contain more permissions than someone needs to do their job. +* Custom roles include your choice of fine-grained permissions. They can include access to account settings and (for organization custom roles) repository access, allowing you to provide teams with just the access they need to do their jobs. For example, you could allow a team to view your enterprise's audit logs without allowing them to change any settings. + +To follow the principle of least privilege access, we recommend using custom roles if they allow for the permissions you require. However, not all capabilities of predefined roles can currently be replicated in custom roles. + +## Who manages roles? + +Enterprise owners can create custom enterprise roles and assign enterprise roles to users and teams. They can also create custom organization roles to be used across organizations, but these roles can only be assigned by organization owners. + +Organization owners can grant organization roles and create custom organization roles, but cannot edit roles or change role assignments that are defined at the enterprise level. ## Next steps diff --git a/content/admin/concepts/enterprise-fundamentals/teams-in-an-enterprise.md b/content/admin/concepts/enterprise-fundamentals/teams-in-an-enterprise.md index 2cb2e078124f..2b7e09f9c847 100644 --- a/content/admin/concepts/enterprise-fundamentals/teams-in-an-enterprise.md +++ b/content/admin/concepts/enterprise-fundamentals/teams-in-an-enterprise.md @@ -6,12 +6,81 @@ versions: shortTitle: Teams redirect_from: - /admin/overview/about-teams + - /enterprise-onboarding/setting-up-organizations-and-teams/managing-organization-members + - /enterprise-onboarding/setting-up-organizations-and-teams/about-teams-in-an-enterprise contentType: concepts category: - Get started with GitHub Enterprise --- -{% data reusables.enterprise-onboarding.about-teams %} +## What are teams? + +Teams are **groups of users** in an enterprise or organization. By creating teams, you can manage users at scale and simplify access, licensing, and communication. For example, you could create an auditor team for users who need access to audit logs{% ifversion copilot %}, or a {% data variables.product.prodname_copilot_short %} team for users who receive {% data variables.product.prodname_copilot_short %} licenses{% endif %}. + +**Enterprise teams** are managed at the enterprise level and can include users from across the enterprise and its organizations. With enterprise teams, you can centralize administration and manage organization access, roles, and licensing at scale. + +**Organization teams** are managed at the organization level and can only include members of a single organization. There are certain features of organization teams that are not currently supported for enterprise teams, such as CODEOWNER status. + +## Can I manage teams from an identity provider? + +{% ifversion ghes %}If you have enabled SCIM user provisioning on {% data variables.product.prodname_ghe_server %}{% else %}If you have integrated {% data variables.product.github %} with an identity provider (IdP){% endif %}, you can link teams on {% data variables.product.github %} with groups in your IdP. When membership of the IdP group changes, the change is reflected in the {% data variables.product.github %} team, allowing you to centralize access management. + +{% ifversion not ghes %} +The capabilities of this feature depend on whether you use {% data variables.product.prodname_emus %} or personal accounts. + +### {% data variables.product.prodname_emus %} + +{% endif %} + +You can make changes to IdP groups to manage repository access, add or remove users from organizations, or grant or remove {% data variables.product.prodname_copilot %} licenses. For example, if a new user is added to an IdP group that is linked to a team with access to an organization, the user receives access to that organization. For more information, see [AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/managing-team-memberships-with-identity-provider-groups). + +This feature is available with both enterprise and organization teams. + +{% ifversion not ghes %} + +### Personal accounts + +Team synchronization allows you to centrally manage any privileges linked to an organization team, such as repository access and CODEOWNER status. However, team sync cannot be used to add users to organizations where they don't already have access. For more information, see [AUTOTITLE](/admin/managing-iam/using-saml-for-enterprise-iam/managing-team-synchronization-for-organizations-in-your-enterprise). + +Team sync with personal accounts is only available with organization teams, and you must use Entra ID or Okta as an IdP. + +{% endif %} + +## What kind of team should I use? + +To simplify administration at scale, {% data variables.product.company_short %} recommends using enterprise teams for any use cases that apply to the enterprise account or to multiple organizations. Organization teams are useful when the need for the team is scoped to a single organization and the team can be managed by an organization administrator. + +You may need to create organization teams if the functionality you need is not covered by enterprise teams. The limitations listed below reflect the current capabilities of enterprise teams and may change over time. + +{% data reusables.enterprise.enterprise-teams-can %} + +{%- ifversion enterprise-teams-ga %} + +To @-mention an enterprise team, or request a review from the team, use the team's slug in the format `@/ent:TEAM-SLUG`. {% data variables.product.github %} generates the slug from the team's name and adds the `ent:` prefix, so an enterprise team named `Platform SRE` has the slug `ent:platform-sre`. + +To mention the team from an organization it is assigned to, such as `octo-org`, use `@octo-org/ent:platform-sre`. You can mention an enterprise team from any organization the team is assigned to. + +{%- endif %} + +However, unlike organization teams, enterprise teams currently do **not** support: + +{%- ifversion enterprise-teams-ga %} +{%- else %} +* `@-mentions` of the team name in organizations +* Review requests of the team in pull requests +{%- endif %} +* Adding the team to a project board +{%- ifversion not ghes %} +* Team sync if you use {% data variables.product.prodname_ghe_cloud %} with personal accounts +{%- endif %} +* CODEOWNER status +* Secret teams +* Nested teams +* Team maintainers + +{% data reusables.enterprise.enterprise-teams-limits %} + +For more information about the capabilities of organization teams, see [AUTOTITLE](/organizations/organizing-members-into-teams/about-teams). ## Next steps diff --git a/content/admin/concepts/security-and-compliance/audit-log-for-an-enterprise.md b/content/admin/concepts/security-and-compliance/audit-log-for-an-enterprise.md index 0ae676f46dc8..feae403c0956 100644 --- a/content/admin/concepts/security-and-compliance/audit-log-for-an-enterprise.md +++ b/content/admin/concepts/security-and-compliance/audit-log-for-an-enterprise.md @@ -12,6 +12,8 @@ redirect_from: - /admin/authentication/managing-your-enterprise-users-with-your-identity-provider/auditing-activity-in-your-enterprise - /admin/identity-and-access-management/managing-iam-with-enterprise-managed-users/auditing-activity-in-your-enterprise - /admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/about-the-audit-log-for-your-enterprise + - /enterprise-onboarding/feature-enhancements/about-the-audit-log-for-your-enterprise + - /enterprise-onboarding/govern-people-and-repositories/using-the-audit-log-for-your-enterprise versions: ghes: '*' ghec: '*' @@ -20,7 +22,39 @@ category: - Secure and govern your enterprise --- -{% data reusables.enterprise-onboarding.about-audit-logs %} +## What are audit logs? + +> [!NOTE] +> {% data reusables.webhooks.webhooks-as-audit-log-alternative %} + +{% data reusables.audit_log.retention-periods %} + +{% data reusables.audit_log.audit-log-search-list-info-about-action %} + +{% ifversion ghes %}Site administrators can review the audit log for an instance, which contains a wider range of events including system administrative events. To access the instance-level audit log: + +{% data reusables.enterprise_site_admin_settings.access-settings %} +1. In the left menu, click **Audit log**.{% endif %} + +In addition to viewing your audit log, you can monitor activity in your enterprise in other ways, such as {% ifversion ghes %}viewing push logs and {% endif %}managing global webhooks. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/exploring-user-activity-in-your-enterprise). You can also use the audit log, and other tools, to monitor the actions taken in response to security alerts. For more information, see [AUTOTITLE](/code-security/concepts/security-at-scale/audit-security-alerts). + +## How to use audit logs + +As an enterprise owner{% ifversion ghes %} or site administrator{% endif %}, you can interact with the audit log data for your enterprise in several ways: +* You can view the audit log for your enterprise. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/accessing-the-audit-log-for-your-enterprise). +* You can search the audit log for specific events{% ifversion ghec %} and export audit log data{% endif %}. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/searching-the-audit-log-for-your-enterprise){% ifversion ghec %} and [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/exporting-audit-log-activity-for-your-enterprise){% endif %}. +* You can identify all events that were performed by a specific access token. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/identifying-audit-log-events-performed-by-an-access-token).{% ifversion ghes %} +* You can configure settings, such as the retention period for audit log events and whether Git events are included. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/configuring-the-audit-log-for-your-enterprise).{% endif %} +{%- ifversion enterprise-audit-log-ip-addresses %} +* You can display the IP address associated with events in the audit log. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/displaying-ip-addresses-in-the-audit-log-for-your-enterprise). +{%- endif %} +* You can stream audit and Git events data from {% data variables.product.prodname_dotcom %} to an external data management system. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/streaming-the-audit-log-for-your-enterprise). +{%- ifversion ghes %} +* You can forward audit and system logs from your enterprise to a third-party hosted monitoring system. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/exploring-user-activity-in-your-enterprise/log-forwarding). +{%- endif %} +* You can use the Audit log API to view actions performed in your enterprise. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/using-the-audit-log-api-for-your-enterprise). + +For a full list of audit log actions that may appear in your enterprise audit log, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/audit-log-events-for-your-enterprise). ## Further reading diff --git a/content/admin/concepts/security-and-compliance/enterprise-policies.md b/content/admin/concepts/security-and-compliance/enterprise-policies.md index 310061aad17b..a0ae3313a179 100644 --- a/content/admin/concepts/security-and-compliance/enterprise-policies.md +++ b/content/admin/concepts/security-and-compliance/enterprise-policies.md @@ -9,13 +9,18 @@ contentType: concepts redirect_from: - /admin/policies/enforcing-policies-for-your-enterprise/about-enterprise-policies - /admin/enforcing-policies/enforcing-policies-for-your-enterprise/about-enterprise-policies + - /enterprise-onboarding/govern-people-and-repositories/about-enterprise-policies category: - Secure and govern your enterprise --- ## What are enterprise policies and why are they important? -{% data reusables.enterprise-onboarding.about-policies %} +To help you enforce business rules and regulatory compliance, policies provide a single point of management for all the organizations owned by an enterprise account. + +{% data reusables.enterprise.about-policies %} + +For example, with the "Base permissions" policy, you can allow organization owners to configure the "Base permissions" policy for their organization, or you can enforce a specific base permissions level, such as "Read", for all organizations within the enterprise. ## What are the steps to enforce enterprise policies? diff --git a/content/admin/data-residency/network-details-for-ghecom.md b/content/admin/data-residency/network-details-for-ghecom.md index ffeb60ace714..9ab6e88c3692 100644 --- a/content/admin/data-residency/network-details-for-ghecom.md +++ b/content/admin/data-residency/network-details-for-ghecom.md @@ -132,11 +132,17 @@ Actions IPs: EU region: * 108.143.197.176/28 +* 108.143.197.160/28 * 20.123.213.96/28 +* 20.123.214.144/28 * 20.224.46.144/28 +* 20.224.46.160/28 * 20.240.194.240/28 +* 20.240.194.224/28 * 20.240.220.192/28 +* 20.240.220.176/28 * 20.240.211.208/28 +* 20.240.211.224/28 #### Australia @@ -145,22 +151,26 @@ Actions IPs: * 20.53.114.78 Australia region: +* 4.237.73.144/28 * 4.237.73.192/28 +* 20.5.226.96/28 * 20.5.226.112/28 +* 20.248.163.160/28 * 20.248.163.176/28 #### Japan Actions IPs: - * 20.63.233.164 * 172.192.153.164 Japan region: - -74.226.88.241 -40.81.176.225 -4.190.169.240 +* 74.226.88.240/28 +* 74.226.88.224/28 +* 40.81.176.224/28 +* 40.81.178.160/28 +* 4.190.169.240/28 +* 4.190.170.0/28 #### Required for all regions diff --git a/content/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/managing-custom-properties-for-repositories-in-your-enterprise.md b/content/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/managing-custom-properties-for-repositories-in-your-enterprise.md index fb46a31defa7..82cba0f09cbb 100644 --- a/content/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/managing-custom-properties-for-repositories-in-your-enterprise.md +++ b/content/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/managing-custom-properties-for-repositories-in-your-enterprise.md @@ -2,6 +2,8 @@ title: Managing custom properties for repositories in your enterprise intro: 'Create custom properties to give organizations a consistent way to categorize repositories.' permissions: Enterprise owners +redirect_from: + - /enterprise-onboarding/govern-people-and-repositories/create-custom-properties versions: feature: custom-properties-enterprise shortTitle: Custom properties @@ -9,7 +11,38 @@ category: - Manage accounts and repositories --- -{% data reusables.enterprise-onboarding.creating-custom-properties %} +Custom properties allow you to decorate your repositories with information such as compliance frameworks, data sensitivity, or project details. Custom properties are private and can only be viewed by people with read permissions to the repository. An enterprise can have up to 100 property definitions. An allowed value list can have up to 200 items. + +Defining custom properties at the enterprise level allows you to create consistent values that users can apply to repositories. With custom properties in place, you can apply consistent governance across repositories in your enterprise by creating a ruleset or repository policy targeting repositories with certain properties. + +## Allowed characters + +{% data reusables.repositories.custom-property-allowed-characters %} + +## Who can set and view values for custom properties I define? + +After you define a custom property, users can set a value for that property in repositories in the enterprise. See [AUTOTITLE](/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization#setting-values-for-repositories-in-your-organization). + +* As an enterprise owner, you can set a default value for required properties. +* Organization owners can set values in their organization, either across repositories or at the repository level. +* If enabled, people with repository access, or the `custom properties` fine-grained permission, can set and update the property value for their repository. + +People with read permissions to a repository can view the custom property values for that repository. + +Additionally, organization owners can search for repositories in their organization by custom property values. See [AUTOTITLE](/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization#searching-and-filtering-repositories-by-custom-property-values). + +## Adding custom properties + +You can add custom properties to your enterprise to make those properties available in all of your organizations. + +{% data reusables.enterprise-accounts.access-enterprise %} +1. In the left sidebar, under "Policies", click **Custom properties**. +1. To add a new custom property, in the upper-right corner, click **New property**. +1. Enter a name, description, and type for the custom property. The name must be unique across all of your organizations, can't contain spaces, and cannot exceed 75 characters in length. +1. Optionally, select **Allow repository actors to set this property**. When enabled, repository users and apps with the repository-level `custom properties` fine-grained permission will be able to set and update the property value for their repository. Additionally, any actor creating a repository can set the property on the repository. +1. Optionally, select **Require this property for all repositories** and add a default value. This means that you require that all repositories in your enterprise have a value for this property. Repositories that don’t have an explicit value for this property will inherit the default value. +{% data reusables.organizations.custom-properties-required-values %} +1. Click **Save property**. ## Promoting organization properties to enterprise properties diff --git a/content/admin/managing-accounts-and-repositories/managing-roles-in-your-enterprise/assign-roles.md b/content/admin/managing-accounts-and-repositories/managing-roles-in-your-enterprise/assign-roles.md index 7e4a8a210929..84af307320d4 100644 --- a/content/admin/managing-accounts-and-repositories/managing-roles-in-your-enterprise/assign-roles.md +++ b/content/admin/managing-accounts-and-repositories/managing-roles-in-your-enterprise/assign-roles.md @@ -6,9 +6,50 @@ versions: shortTitle: Assign roles redirect_from: - /admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/assign-roles + - /enterprise-onboarding/setting-up-organizations-and-teams/assigning-roles-to-teams-and-users contentType: how-tos category: - Manage accounts and repositories --- -{% data reusables.enterprise-onboarding.assign-roles %} +Enterprise owners can assign custom and predefined **enterprise roles** to users and teams. Some roles can be assigned to enterprise teams, whereas other roles are only available for individual users. Find the section below for the role you want to assign. + +For more information about using roles effectively, see [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-roles-in-your-enterprise/identify-role-requirements). + +## Assigning app managers, security managers, and custom roles + +> [!NOTE] These roles are in public preview and subject to change. + +These roles can be assigned to existing users and teams in your enterprise settings, including {% ifversion ghes %}users whose accounts were provisioned with SCIM{% else %}{% data variables.enterprise.prodname_managed_users %}{% endif %}. + +Before you assign a role, you may need to create a team. Teams are the best way to manage role assignments at scale. The enterprise security manager role can **only** be assigned to a team, not to individual users. See [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/create-enterprise-teams). + +{% data reusables.enterprise-accounts.access-enterprise %} +{% data reusables.enterprise-accounts.people-tab %} +1. In the left sidebar, click **{% octicon "globe" aria-hidden="true" aria-label="globe" %} Enterprise roles**, then click **Role assignments**. +1. Click **Assign role**. +1. Choose the user or team and the role they should receive, then click **Assign role**. + +## Assigning enterprise owners{% ifversion not ghes %}, billing managers, and guest collaborators{% endif %} + +{% ifversion ghes %}This role{% else %}These roles{% endif %}: + +* Can be chosen when you invite a user to your enterprise or provision a user from your identity provider (IdP) +* Cannot currently be assigned to enterprise teams +* Can be changed for existing users + +### Assigning to new users + +* If you {% ifversion ghes %}have enabled SCIM provisioning{% else %}use **{% data variables.product.prodname_emus %}**{% endif %}, roles are assigned from your IdP via the SCIM `roles` attribute. +* Otherwise, you can invite someone as {% ifversion ghes %}an enterprise owner. See {% else %}a user or administrator. See [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/invite-users-directly) or {% endif %}[AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/inviting-people-to-manage-your-enterprise). + +### Assigning to existing administrators + +You can change an administrator's role or convert them to a regular member once they have joined your enterprise. + +* If you {% ifversion ghes %}provisioned the user via SCIM{% else %}use **{% data variables.product.prodname_emus %}**{% endif %}, you must do this from your IdP via the SCIM `roles` attribute. +* {% ifversion ghes %}For all other accounts{% else %}If you use an **enterprise with personal accounts**{% endif %}, you can change the role on your enterprise's "Administrators" page, using the **{% octicon "kebab-horizontal" aria-label="Administrator" %}** menu next to the user's name. See [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/viewing-people-in-your-enterprise#viewing-enterprise-administrators). + +## Assigning roles in an organization + +Enterprise owners cannot assign organization-level roles from the enterprise settings. An organization administrator must do this. See [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/using-organization-roles#assigning-an-organization-role). diff --git a/content/admin/managing-accounts-and-repositories/managing-roles-in-your-enterprise/create-custom-roles.md b/content/admin/managing-accounts-and-repositories/managing-roles-in-your-enterprise/create-custom-roles.md index 44947f3773ec..4abeb67722a9 100644 --- a/content/admin/managing-accounts-and-repositories/managing-roles-in-your-enterprise/create-custom-roles.md +++ b/content/admin/managing-accounts-and-repositories/managing-roles-in-your-enterprise/create-custom-roles.md @@ -6,12 +6,42 @@ versions: shortTitle: Create custom roles redirect_from: - /admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/custom-organization-roles + - /enterprise-onboarding/setting-up-organizations-and-teams/creating-custom-roles contentType: how-tos category: - Manage accounts and repositories --- -{% data reusables.enterprise-onboarding.create-custom-roles %} +To tailor access management to your company's needs, you can create custom roles for your{% ifversion enterprise-custom-roles %} enterprise account and{% endif %} organizations. + +Custom roles are sets of permissions for settings and resources that you can assign to users and teams.{% ifversion enterprise-custom-roles %} To learn best practices for using roles on {% data variables.product.github %}, see [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-roles-in-your-enterprise/identify-role-requirements).{% endif %} + +{% ifversion enterprise-custom-roles %} + +## Creating enterprise custom roles + +> [!NOTE] This feature is in {% data variables.release-phases.public_preview %} and subject to change. + +Enterprise custom roles grant access to a subset of enterprise settings, such as viewing audit logs and creating organizations. {% data variables.product.github %} plans to expand the list of available permissions over time. + +{% data reusables.enterprise-accounts.start-creating-custom-role %} +1. Enter the details, then click **Create role**. + +{% endif %} + +## Creating organization custom roles + +Organization custom roles grant access to organization settings and repositories. Custom organization roles created at the enterprise level use the same permissions and base roles as roles created at the organization level. For more information, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/permissions-of-custom-organization-roles). + +Enterprise owners can create and edit custom organization roles, but cannot assign them. Organization owners can assign custom roles in an organization. + +> [!NOTE] An enterprise can create up to 20 custom organization roles. This limit applies to the enterprise: each organization can also create up to 20 custom organization roles. + +{% data reusables.enterprise-accounts.access-enterprise %} +{% data reusables.enterprise-accounts.people-tab %} +1. In the left sidebar, select **Organization roles**. +1. Click **Create custom role**. +1. Enter the details, then click **Create role**. {% ifversion enterprise-teams %} diff --git a/content/admin/managing-accounts-and-repositories/managing-roles-in-your-enterprise/identify-role-requirements.md b/content/admin/managing-accounts-and-repositories/managing-roles-in-your-enterprise/identify-role-requirements.md index 5d98949b915e..e773b746c2be 100644 --- a/content/admin/managing-accounts-and-repositories/managing-roles-in-your-enterprise/identify-role-requirements.md +++ b/content/admin/managing-accounts-and-repositories/managing-roles-in-your-enterprise/identify-role-requirements.md @@ -6,11 +6,85 @@ versions: feature: enterprise-custom-roles allowTitleToDifferFromFilename: true contentType: tutorials +redirect_from: + - /enterprise-onboarding/setting-up-organizations-and-teams/identify-role-requirements category: - Manage accounts and repositories --- -{% data reusables.enterprise-onboarding.identify-role-requirements %} +Roles control people's access to settings and resources in your enterprise and organizations. For an introduction to roles, see [AUTOTITLE](/admin/concepts/enterprise-fundamentals/roles-in-an-enterprise). + +By using roles effectively, you can: + +* Delegate administrative duties and manage access securely at every level of your enterprise. +* Harden security by reducing the number of people with blanket administrative access in your enterprise. +* Ensure everyone has the permissions they need to be independent and productive. + +## 1. Review available roles and permissions + +This guide helps you understand best practices for roles, so you can plan which roles are required in your enterprise and organizations. You will then be able to create a team structure that uses roles effectively. + +As you think about tasks that would benefit from a specific role, refer to the available predefined roles and custom permissions to see if a granular role for this task is currently possible. If not, you will need to rely on a role with more blanket access, such as enterprise owner. + +> [!NOTE] Enterprise custom roles currently only cover a limited subset of enterprise settings, but {% data variables.product.company_short %} plans to expand the list of permissions over time. + +| Role type | More information | +| --------- | ---------------- | +| Predefined enterprise roles | [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-roles-in-your-enterprise/abilities-of-roles) | +| Predefined organization roles | [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization) | +| Custom enterprise roles | Review the list of available permissions at `{% data variables.product.product_url %}/enterprises/ENTERPRISE/enterprise_roles/new`, where ENTERPRISE is the name of your enterprise account. | +| Custom organization roles | [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/permissions-of-custom-organization-roles) | + +## 2. Identify two owners per account + +Decide who will serve as enterprise owners and organization owners. The "owner" role has full administrative access to an enterprise or organization account. + +We recommend having at least two owners per account. Although it is good practice to limit the number of people with this level of access, if an account only has one owner, the account's resources can become inaccessible if the owner is unreachable. + +## 3. Identify roles for administrative duties + +Identify predefined or custom roles that will help you delegate time-consuming administrative duties to other teams. This will help enterprise owners to focus on urgent or strategic work. + +It is unlikely that you can granularly assign every administrative duty in your enterprise to a specific team, so we recommend focusing on the most frequent and time-consuming tasks. Some examples of how you might use roles to delegate common tasks are: + +* **Auditing**: Use a custom role to give a team access to your audit logs without allowing them to access any other settings. +* **Authentication**: Use a custom role to give your identity provider administrators permission to manage SSO settings on {% data variables.product.github %}, so they can configure authentication independently. +{%- ifversion ent-security-manager %} +* **Security**: Use the enterprise security manager role to give security teams access to alerts and security data across the enterprise and organizations. +{%- endif %} + +Some administrative tasks are more sensitive than others. For example, if your enterprise uses enterprise teams to manage licensing, access, and roles, then being able to change membership of a team is a powerful action that you may want to restrict to a small group of people. + +## 4. Identify base permissions for non-administrators + +Consider if there are permissions that every member of your enterprise would benefit from. These can be added to a custom role that you assign to everyone. + +For example, regular users have limited visibility of your enterprise account by default. If you want more transparency, you may want to allow all employees to: + +* View other enterprise members and administrators so they know where to go for help +* View audit logs to see what people are doing in the enterprise + +## 5. Delegate work to apps + +Not all tasks are best-suited to humans. Identify frequent, time-consuming, and easily automated tasks, and plan to delegate these tasks to {% data variables.product.prodname_github_apps %}. + +{% data variables.product.prodname_github_apps %} provide scoped tokens for use in scripts and workflows. Although they use a different permissions system from the roles you assign to users, you can think about apps like humans with a role on {% data variables.product.github %}: + +* They have fine-grained permissions for specific tasks. +* They have scoped access to specific repositories and accounts. +* They have their own identity, which you can trace in audit logs. + +For more information about what apps can do, see [AUTOTITLE](/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps#understanding-what-type-of-github-app-to-build). + +{% ifversion copilot %} + +## 6. Assign tasks to agents + +Another way to delegate frequent, time-consuming tasks is to assign work to {% data variables.copilot.copilot_cloud_agent %}. You can define custom agents for specific roles in your enterprise. Custom agents are created using Markdown files called "agent profiles," which define the instructions and tools the agent needs to perform a task. For example, you could create a {% data variables.copilot.copilot_custom_agent_short %} for writing README files or generating unit tests. + +For more information, see [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/prepare-for-custom-agents). + +{% endif %} ## Next steps diff --git a/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/create-enterprise-teams.md b/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/create-enterprise-teams.md index 59ec5b72739f..4aaffb82d6d0 100644 --- a/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/create-enterprise-teams.md +++ b/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/create-enterprise-teams.md @@ -8,6 +8,7 @@ permissions: Enterprise owners redirect_from: - /admin/user-management/managing-users-in-your-enterprise/managing-organization-members-in-your-enterprise - /admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/managing-organization-members-in-your-enterprise + - /enterprise-onboarding/setting-up-organizations-and-teams/creating-teams contentType: how-tos category: - Manage accounts and repositories @@ -20,7 +21,63 @@ Adding a user to a team grants them the privileges associated with the team. Rem {% data reusables.enterprise.enterprise-teams-limits %} -{% data reusables.enterprise-onboarding.create-enterprise-teams %} +## 1. Navigate to the enterprise teams page + +{% data reusables.enterprise-accounts.access-enterprise %} +{% data reusables.enterprise-accounts.people-tab %} +1. In the left sidebar, click **{% octicon "people" aria-hidden="true" aria-label="people" %} Enterprise teams**. + +## 2. Create a team + +1. On the enterprise teams page, click **Create Enterprise team**. +1. Choose the team's name, description, and organization access. + + When you give a team access to organizations, members of the team are added directly to those organizations, without an invitation, and receive the same access as other organization members. + + * Outside collaborators{% ifversion not ghes %} and unaffiliated users{% endif %} in the team become standard enterprise members, meaning they have access to your enterprise's internal repositories{% ifversion not ghes %} and consume a {% data variables.product.prodname_enterprise %} license{% endif %}. + * Team members receive the base level of repository permissions for the organization. + * Organization administrators can give the team additional repository access and assign them organization-level roles, but **cannot** remove any permissions granted by enterprise administrators. + +1. Click **Create Enterprise team**. + +## 3. Add users + +There are multiple ways to add users to an enterprise team. + +* [Adding users manually](#adding-users-manually) +* [Syncing with an IdP group](#syncing-with-an-idp-group) ({% data variables.product.prodname_emus %} only) +* Using the [AUTOTITLE](/rest/enterprise-teams/enterprise-team-members) + +{% ifversion ghec %} +Enterprise teams can contain organization members, unaffiliated users, and outside collaborators. +{% endif %} + +### Adding users manually + +1. On the enterprise teams page, click the team you want to add users to. +1. Click **Add members**, then search for and select the users you want to add. +1. Click **Add**. + +### Syncing with an IdP group + +If you {% ifversion ghes %}have enabled SCIM on {% data variables.product.prodname_ghe_server %}{% else %}use {% data variables.product.prodname_emus %}{% endif %}, you can sync membership of an enterprise team to a group in your identity provider. That way, any changes made to the group in the IdP (such as adding or removing a user) will be synced to the enterprise team via SCIM. For details and requirements, see [AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/managing-team-memberships-with-identity-provider-groups). + +1. On the enterprise teams page, click the team you want to sync. +1. Ensure the team contains no manually assigned users. You can remove users by using the **{% octicon "kebab-horizontal" aria-hidden="true" aria-label="More member actions" %}** menu next to the user's name in the member list. +1. Next to the team's name, click **{% octicon "pencil" aria-hidden="true" aria-label="pencil" %} Edit**. +1. Under "Manage members", click **Identity provider group**. +1. Click **Select group**, then choose the external IdP group to sync to the team. Members from the IdP group will display in the team's member list. +1. Click **Update team**. + +#### Limits on IdP group sizes + +If an IdP group goes over the team size limit of 5,000 users, the team will stop being synced. + +For example: + +* An enterprise team is initially synced with an IdP group of 5 users. +* 5,000 more users are added to the IdP group. Because the IdP group now has 5,005 users, the group isn't synced and the enterprise team remains at 5 members. +* 5 users are removed from the IdP group to bring it to 5,000 users. Syncing resumes and the enterprise team now contains the same 5,000 users as the IdP group. {% ifversion ghes %} diff --git a/content/admin/managing-github-apps-for-your-enterprise/creating-github-apps-for-your-enterprise.md b/content/admin/managing-github-apps-for-your-enterprise/creating-github-apps-for-your-enterprise.md index 203721183325..94a66e9e5fba 100644 --- a/content/admin/managing-github-apps-for-your-enterprise/creating-github-apps-for-your-enterprise.md +++ b/content/admin/managing-github-apps-for-your-enterprise/creating-github-apps-for-your-enterprise.md @@ -7,12 +7,50 @@ permissions: Enterprise owners. shortTitle: Create a GitHub App redirect_from: - /admin/managing-your-enterprise-account/creating-github-apps-for-your-enterprise + - /enterprise-onboarding/github-apps/create-enterprise-apps contentType: how-tos category: - Enable GitHub features for your enterprise --- -{% data reusables.enterprise-onboarding.create-enterprise-apps %} +You can create a {% data variables.product.prodname_github_app %} under your enterprise account. The app can only be installed on{% ifversion enterprise-installed-apps %} your enterprise or{% endif %} organizations within your enterprise, and can only be authorized by members of your enterprise. The app can't be installed on user accounts. + +## Step 1: Registering a {% data variables.product.prodname_github_app %} + +To create a {% data variables.product.prodname_github_app %}, you must first register the app. See [AUTOTITLE](/apps/creating-github-apps/registering-a-github-app/registering-a-github-app). + +Apps can also be transferred to an enterprise from a member or organization. To transfer an app, see [AUTOTITLE](/apps/maintaining-github-apps/transferring-ownership-of-a-github-app). +{%- ifversion enterprise-app-manager %} + +### Step 1a: Adding an enterprise app manager + +Enterprise owners can add enterprise members to an app as an app manager. App managers can manage the app's settings and credentials, but cannot install the app. For more information, see [AUTOTITLE](/apps/maintaining-github-apps/about-github-app-managers).{% endif %} + +## Step 2: Building a {% data variables.product.prodname_github_app %} + +After registering a {% data variables.product.prodname_github_app %}, you will want to write code to make your {% data variables.product.prodname_github_app %} do something. For examples of how to write code, see: + +* [AUTOTITLE](/apps/creating-github-apps/writing-code-for-a-github-app/quickstart) +* [AUTOTITLE](/apps/creating-github-apps/writing-code-for-a-github-app/building-a-github-app-that-responds-to-webhook-events) +* [AUTOTITLE](/apps/creating-github-apps/writing-code-for-a-github-app/building-a-login-with-github-button-with-a-github-app) +* [AUTOTITLE](/apps/creating-github-apps/writing-code-for-a-github-app/building-a-cli-with-a-github-app) +* [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow) + +You should aim to follow best practices. See [AUTOTITLE](/apps/creating-github-apps/about-creating-github-apps/best-practices-for-creating-a-github-app). + +## Step 3: Authorizing or installing your {% data variables.product.prodname_github_app %} + +Once your {% data variables.product.prodname_github_app %} is registered, you'll need to make it available for use, either through **authorization** or **installation**, depending on the app’s purpose. + +Enterprise owners {% ifversion enterprise-app-manager %}and app managers {% endif %}can modify the permissions for apps owned by their enterprise at any time. Permissions changes will be automatically accepted by organizations in the enterprise{% ifversion enterprise-app-manager %} if the change was made by the enterprise owner. Otherwise, the changes will be accepted only where the app manager is also an organization owner, and an organization owner must accept the update request for all other organizations{% endif %}. + +### Step 3a: Authorizing your {% data variables.product.prodname_github_app %} + +Some {% data variables.product.prodname_github_apps %}, like {% data variables.product.prodname_copilot_short %} extensions, require **authorization** but do not need to be installed on an organization. Users in your enterprise can authorize the app to access resources within organizations. However, the app will only have access to {% data variables.product.github %} resources where it is installed. See [AUTOTITLE](/apps/using-github-apps/authorizing-github-apps). + +### Step 3b: Sharing your {% data variables.product.prodname_github_app %} via an installation link + +For apps that require installation to function, you can provide organization owners with an installation link. Once the app is installed, it will have access to the organization's resources. See [AUTOTITLE](/apps/sharing-github-apps/sharing-your-github-app#sharing-your-github-app-via-an-install-link). ## Step 4: Installing your {% data variables.product.prodname_github_app %} (if required) diff --git a/content/admin/managing-github-apps-for-your-enterprise/index.md b/content/admin/managing-github-apps-for-your-enterprise/index.md index 89e91d127d10..a081642133d0 100644 --- a/content/admin/managing-github-apps-for-your-enterprise/index.md +++ b/content/admin/managing-github-apps-for-your-enterprise/index.md @@ -6,6 +6,8 @@ children: - /creating-github-apps-for-your-enterprise - /adding-and-removing-github-app-managers-in-your-enterprise - /automate-installations +redirect_from: + - /enterprise-onboarding/github-apps shortTitle: GitHub Apps versions: feature: enterprise-apps-public-beta diff --git a/content/apps/using-github-apps/installing-a-github-app-on-your-enterprise.md b/content/apps/using-github-apps/installing-a-github-app-on-your-enterprise.md index 598243ed08b6..a95614d6c0a4 100644 --- a/content/apps/using-github-apps/installing-a-github-app-on-your-enterprise.md +++ b/content/apps/using-github-apps/installing-a-github-app-on-your-enterprise.md @@ -4,6 +4,8 @@ intro: 'You can install {% data variables.product.prodname_github_apps %} on you versions: feature: enterprise-installed-apps shortTitle: Install apps on your enterprise +redirect_from: + - /enterprise-onboarding/github-apps/install-enterprise-apps permissions: 'Enterprise owners can install {% data variables.product.prodname_github_apps %} on their enterprise. App managers cannot install apps at the enterprise level.' category: - Install and authorize apps diff --git a/content/code-security/concepts/code-quality/code-quality.md b/content/code-security/concepts/code-quality/code-quality.md index 4493ebe85200..69a0c51cfab7 100644 --- a/content/code-security/concepts/code-quality/code-quality.md +++ b/content/code-security/concepts/code-quality/code-quality.md @@ -64,4 +64,4 @@ It also performs AI-powered analysis on pull requests and on your repository's r * **For your enterprise:** Ensure repositories in your enterprise can enable {% data variables.product.prodname_code_quality_short %}. See [AUTOTITLE](/code-security/how-tos/secure-at-scale/configure-enterprise-security/configure-specific-tools/allow-github-code-quality-in-enterprise?utm_campaign=code-quality-ga-july-2026&utm_medium=docs&utm_source=docs-cq-intro-enable-cq-enterprise). * **For your repository or organization:** Turn on {% data variables.product.prodname_code_quality_short %} to start generating results. See [AUTOTITLE](/code-security/how-tos/maintain-quality-code/enable-code-quality?utm_campaign=code-quality-ga-july-2026&utm_medium=docs&utm_source=docs-cq-intro-enable-cq-repo). -* **On your pull request:** Learn how to fix code quality findings on your pull request. See [AUTOTITLE](/code-security/tutorials/improve-code-quality/catch-issues-before-merge). +* **On your pull request:** Learn how to fix code quality findings on your pull request. See [AUTOTITLE](/code-security/tutorials/improve-code-quality/catch-issues-before-merge?utm_campaign=code-quality-ga-july-2026&utm_medium=docs&utm_source=docs-cq-intro-fix-on-pr). diff --git a/content/copilot/concepts/agents/copilot-cli/autopilot.md b/content/copilot/concepts/agents/copilot-cli/autopilot.md index b58385c622e7..febe8dc6d35b 100644 --- a/content/copilot/concepts/agents/copilot-cli/autopilot.md +++ b/content/copilot/concepts/agents/copilot-cli/autopilot.md @@ -59,6 +59,20 @@ When entering autopilot mode, if you have not already granted {% data variables. You will get the best results from autopilot mode if you enable all permissions. If you choose to continue with limited permissions, {% data variables.product.prodname_copilot_short %} will automatically deny any tool requests that require approval, which may prevent it from completing certain tasks. You can change your mind later and grant full permissions, during an autopilot session, by using the `/allow-all` command (or its alias `/yolo`). +## Staying in autopilot mode between tasks + +By default, autopilot mode applies only to the current task. Once {% data variables.product.prodname_copilot_short %} determines that the task is complete, {% data variables.copilot.copilot_cli_short %} automatically switches back to the standard interactive mode. To run another task in autopilot mode, press Shift+Tab and cycle through the available modes until you re-enter autopilot mode, then enter your next prompt. + +If you regularly run several tasks in autopilot mode, you can configure the CLI to stay in autopilot mode after each task completes, by enabling the `stayInAutopilot` setting. You can do this in either of the following ways: + +* During an interactive session, enter `/settings stayInAutopilot true`. +* Add `"stayInAutopilot": true` to your user configuration file (`~/.copilot/settings.json`). For more information, see [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-config-dir-reference#user-settings-copilotsettingsjson). + +When this setting is enabled, {% data variables.product.prodname_copilot_short %} remains in autopilot mode after a task completes, so the next prompt you enter is also handled in autopilot mode. You can switch back to interactive mode at any time by pressing Shift+Tab. + +> [!NOTE] +> This setting only controls which mode you are in _after_ a task completes. It does not cause {% data variables.product.prodname_copilot_short %} to keep working after it has decided the task is done. Autopilot still stops when the task is complete, when a problem occurs, when you press Ctrl+C, or when the continuation limit is reached. + ## Comparing autopilot mode, `--allow-all`, and `--no-ask-user` `--allow-all`, and its alias `--yolo`, are permissions-related options that you can pass to the `copilot` command when you start an interactive session. For a full list of available options, see [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference#command-line-options). diff --git a/content/copilot/concepts/copilot-usage-metrics/copilot-metrics.md b/content/copilot/concepts/copilot-usage-metrics/copilot-metrics.md index 08425918fc93..c0206d421e44 100644 --- a/content/copilot/concepts/copilot-usage-metrics/copilot-metrics.md +++ b/content/copilot/concepts/copilot-usage-metrics/copilot-metrics.md @@ -28,7 +28,7 @@ category: Metrics are available through: -* The {% data variables.product.prodname_copilot_short %} usage metrics APIs, which provide detailed, exportable data at the enterprise, organization, and user levels. +* The {% data variables.product.prodname_copilot_short %} usage metrics APIs, which provide detailed, exportable data at the enterprise, organization, repository, and user levels. * The {% data variables.product.prodname_copilot_short %} usage metrics dashboard, which visualizes 28-day usage trends across your enterprise and organizations. * The code generation dashboard, which breaks down how code is being generated by users and agents across your enterprise and organizations. * The {% data variables.product.prodname_copilot_short %} usage metrics NDJSON export, which offers raw data for custom BI tools or long-term storage. @@ -57,7 +57,7 @@ The following API resources expose {% data variables.product.prodname_copilot_sh | API resource | Scope | Key capabilities | | --- | --- | --- | -| [AUTOTITLE](/rest/copilot/copilot-usage-metrics) | Advanced enterprise-, organization-, and user-level event telemetry | Provides unified telemetry across completions, chat, and agent modes. Includes usage and lines of code metrics across all IDE modes, languages, and models. Supports detailed breakdowns by feature, IDE, language, model, and user, and is the primary API resource being actively developed and maintained. | +| [AUTOTITLE](/rest/copilot/copilot-usage-metrics) | Advanced enterprise- and organization-scoped event telemetry with repository- and user-level reports | Provides unified telemetry across completions, chat, and agent modes. Includes usage and lines of code metrics across all IDE modes, languages, and models. Supports detailed breakdowns by feature, IDE, language, model, and user, as well as repository-level pull request activity reports, and is the primary API resource being actively developed and maintained. | | [AUTOTITLE](/rest/copilot/copilot-user-management) | License and seat assignment | Lists assigned {% data variables.product.prodname_copilot_short %} seats for an organization or enterprise, including license state, user association, and `last_activity_at`. This API resource is the source of truth for license and seat information. | ## How are metrics attributed across organizations? diff --git a/content/copilot/how-tos/copilot-sdk/index.md b/content/copilot/how-tos/copilot-sdk/index.md index 5c117b3c965b..227c147609d7 100644 --- a/content/copilot/how-tos/copilot-sdk/index.md +++ b/content/copilot/how-tos/copilot-sdk/index.md @@ -9,9 +9,9 @@ versions: ghec: '*' contentType: how-tos children: + - /getting-started - /auth - /features - - /getting-started - /hooks - /integrations - /observability @@ -22,4 +22,3 @@ children: - diff --git a/content/copilot/how-tos/github-copilot-app/agent-sessions.md b/content/copilot/how-tos/github-copilot-app/agent-sessions.md index e631dd158188..72fd90d0bab8 100644 --- a/content/copilot/how-tos/github-copilot-app/agent-sessions.md +++ b/content/copilot/how-tos/github-copilot-app/agent-sessions.md @@ -18,7 +18,7 @@ category: Each session in the {% data variables.copilot.github_copilot_app %} runs in its own isolated workspace, so you can run multiple sessions in parallel and make progress on several tasks without conflicts. 1. In the sidebar next to **Sessions**, click **+** to start a new session. -1. Choose a repository—you can use a local folder, choose from {% data variables.product.github %}, or clone from a URL. +1. Choose a project—you can use a folder already on your machine, choose from {% data variables.product.github %}, or clone from a Git URL for repositories hosted outside {% data variables.product.github %} (for example, on Azure DevOps) or for private repositories without app access. 1. From the dropdown under the prompt box, choose where the session should run: in a new working tree, in your local repository, or in a cloud sandbox. Cloud sandboxes for {% data variables.product.prodname_copilot_short %} (public preview) are fully isolated environments hosted by {% data variables.product.github %}. 1. Select a session mode, model, and reasoning effort from the dropdowns below the prompt field. If you choose **Auto** for the model, the app selects the optimal model for your task based on task complexity. 1. Describe the task in the prompt field. You can reference issues with `#`, add files with `@`, or use `/` for commands. diff --git a/content/copilot/how-tos/github-copilot-app/getting-started.md b/content/copilot/how-tos/github-copilot-app/getting-started.md index e186f1fdff93..3d101036017d 100644 --- a/content/copilot/how-tos/github-copilot-app/getting-started.md +++ b/content/copilot/how-tos/github-copilot-app/getting-started.md @@ -2,7 +2,7 @@ title: Getting started with the GitHub Copilot app shortTitle: Quickstart allowTitleToDifferFromFilename: true -intro: 'Sign in to the {% data variables.copilot.github_copilot_app %}, ask your first question in a quick chat, and then create a full agent session to make changes to your code.' +intro: 'Sign in to the {% data variables.copilot.github_copilot_app %}, connect a repository or local folder, and create your first agent session to make code changes.' product: '{% data reusables.gated-features.github-app %}
Download {% data variables.copilot.github_copilot_app %} {% octicon "link-external" height:16 %}' versions: feature: copilot @@ -16,12 +16,21 @@ category: For a conceptual overview of the {% data variables.copilot.github_copilot_app %}, see [AUTOTITLE](/copilot/concepts/agents/github-copilot-app). +In this quickstart, you will: + +1. Install and sign in to the {% data variables.copilot.github_copilot_app %}. +1. Connect a repository or local folder. +1. Make code changes in an agent session. + ## Prerequisites -* [Git](https://github.com/git-guides/install-git) installed on your computer. * A {% data variables.product.github %} account. -* A {% data variables.product.prodname_copilot_short %} plan. Alternatively, if using your own model provider, you will need required credentials such as an API key. For more information, see [AUTOTITLE](/copilot/how-tos/github-copilot-app/use-byok-models). -* If you use {% data variables.copilot.copilot_business_short %} or {% data variables.copilot.copilot_enterprise_short %}, your plan administrator must enable the **{% data variables.copilot.copilot_cli_short %}** policy. See [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-organization/manage-policies) or [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-enterprise-policies). +* Access to {% data variables.product.prodname_copilot_short %} or a configured model provider. + * If you use your own model provider, you will need provider credentials such as an API key. For setup steps, see [AUTOTITLE](/copilot/how-tos/github-copilot-app/use-byok-models). +* [Git](https://github.com/git-guides/install-git) installed on your computer. + +> [!NOTE] +> If you use {% data variables.copilot.copilot_business_short %} or {% data variables.copilot.copilot_enterprise_short %}, your plan administrator will need to enable the **{% data variables.copilot.copilot_cli_short %}** policy. For more information, see [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-organization/manage-policies) or [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-enterprise-policies). ## Installing the {% data variables.copilot.github_copilot_app %} @@ -34,56 +43,44 @@ For a conceptual overview of the {% data variables.copilot.github_copilot_app %} 1. Click **Sign in to {% data variables.product.github %}** and follow the prompts to authenticate. If you use {% data variables.product.prodname_ghe_server %}, choose **Use GitHub Enterprise** and enter your server address when prompted. 1. If you do not have a {% data variables.product.prodname_copilot_short %} plan, choose whether to sign up for a plan or continue with your own model provider. * If you choose to use your own model provider, select a provider, enter any required credentials, then click **Save and continue**. -1. When prompted, select one or more repositories based on your recent {% data variables.product.github %} activity. You can also add a local repository, or skip this step and add repositories later. +1. When prompted, select one or more repositories based on your recent {% data variables.product.github %} activity. You can also add a local folder or repository, or skip this step and add projects later. 1. Choose a theme, then complete onboarding to open the app. -## Connecting a repository +## Connecting a repository or folder -To work on code, you need at least one repository connected to the app. If you skipped repository setup during onboarding, or want to add more repositories later: +To work on code, you need at least one project connected to the app. A project can be a folder already on your machine, including a repository you've already cloned locally, or a repository you clone from {% data variables.product.github %} or another remote Git host such as Azure DevOps. Connecting a project unlocks the core app workflow: reading code, making edits, and opening pull requests from agent sessions. If you skipped project setup during onboarding, or want to add more projects later: 1. Click the **+** button in the sidebar next to "Sessions". 1. Under **Add project from**, choose one of the following: - * **Local folder or repository** — Select a folder already on your machine. - * **{% data variables.product.github %} repository** — Browse and clone a repository from {% data variables.product.github %}. - * **Repository URL** — Clone from any Git URL. - -## Orienting yourself - -The sidebar gives you access to the main areas of the app: - -* **[My work](https://github.com/copilot/app/launch?open=ghapp%3A%2F%2Fmywork)** — Browse and filter issues and pull requests from your repositories, check CI status, and leave reviews. -* **[Automations](https://github.com/copilot/app/launch?open=ghapp%3A%2F%2Fautomations)** — Saved agent tasks that run on a schedule or on demand. -* **Search** — Search across your repositories directly from the app. -* **Sessions** — Active agent sessions, grouped by repository. This also includes **Quick chats**, which are general chat conversations. - -## Starting a quick chat + * **Local folder or repository** — Select a folder already on your machine, including one that contains a repository you've already cloned locally. + * **{% data variables.product.github %} repository** — Browse and clone a repository from {% data variables.product.github %}. + * **Repository URL** — Clone from a Git URL for repositories hosted outside {% data variables.product.github %} (for example, on Azure DevOps) or for private repositories without app access. -The fastest way to try the {% data variables.copilot.github_copilot_app %} is with a quick chat. Quick chats let you ask questions and brainstorm without creating a branch or worktree. +## Making your first code changes -1. In the sidebar, click **+** next to "Quick chats" to open a new chat. -1. Type a question or prompt—for example, "Give me an overview of the octocat repository." -1. The agent responds in the conversation view. You can continue the conversation, ask follow-up questions, or start a new chat. - -## Creating your first session +1. Click **+** next to **Sessions**, then choose a connected folder or repository under **Start session in**. +1. Select a session mode from the dropdown below the prompt field—for example, **Interactive** to work collaboratively with the agent. +1. In the prompt box, paste this prompt: -When you are ready to make changes to code, create a session. You can start from an issue or describe a task directly. + ```copilot copy + Suggest a small low-risk code change in this repository, implement it, and explain the diff. + ``` -### Starting from an issue +1. Respond to any requests for input from the agent. After the agent makes changes, click **Changes** above the prompt box to view the diff. +1. Continue iterating in the same session until you are happy with the result. +1. If you want to keep the change, click **Create PR** to open a pull request for review. +1. If you create a pull request, click **PR** above the prompt box to view it directly in the app. -1. Click **[My work](https://github.com/copilot/app/launch?open=ghapp%3A%2F%2Fmywork)** in the sidebar. -1. Browse or filter to find an issue, then click it to view its details. -1. Click **New session**. The app creates a new session with the issue context already loaded. -1. Select a session mode from the dropdown below the prompt field—for example, **Plan** to have the agent propose a plan first, or **Interactive** to work collaboratively with the agent. -1. Prompt the agent with what you want it to do. If you chose **Plan** mode, the agent proposes a plan for you to review first; otherwise, the agent will start working on the issue and propose changes that you can iterate on. Follow along in the conversation view and provide feedback to steer the agent. +**Optional:** If you already have tasks you want to complete in your repository, you can start a session from an issue in **[My work](https://github.com/copilot/app/launch?open=ghapp%3A%2F%2Fmywork)**. For more information, see [AUTOTITLE](/copilot/how-tos/github-copilot-app/managing-issues-and-pull-requests). -### Starting from a task +## Orienting yourself -If you do not have an issue to work from, you can describe a task directly. +The sidebar gives you access to the main areas of the app: -1. In the sidebar, click **+** next to "Sessions" to start a new session, then select a repository. -1. Select a session mode from the dropdown below the prompt field—for example, **Interactive** to work collaboratively with the agent. -1. Describe a task—for example, "Fix the failing test in `utils.test.ts`" or "Add input validation to the signup form." -1. The agent will make changes based on your direction. Follow along in the conversation view and provide feedback to steer the agent. +* **[My work](https://github.com/copilot/app/launch?open=ghapp%3A%2F%2Fmywork)** — Browse and filter issues and pull requests from your repositories, check CI status, and leave reviews. +* **[Automations](https://github.com/copilot/app/launch?open=ghapp%3A%2F%2Fautomations)** — Saved agent tasks that run on a schedule or on demand. +* **Search** — Search across your repositories directly from the app. +* **Sessions** — Active agent sessions, grouped by project. This also includes **Quick chats**, which are general chat conversations. ## Next steps diff --git a/content/copilot/reference/copilot-cli-reference/cli-command-reference.md b/content/copilot/reference/copilot-cli-reference/cli-command-reference.md index 068af86570bc..32ac5df703ef 100644 --- a/content/copilot/reference/copilot-cli-reference/cli-command-reference.md +++ b/content/copilot/reference/copilot-cli-reference/cli-command-reference.md @@ -23,7 +23,7 @@ docsTeamMetrics: | `copilot help [TOPIC]` | Display help information. Help topics include: `billing`, `config`, `commands`, `environment`, `logging`, `monitoring`, `permissions`, and `providers`. | | `copilot init` | Initialize {% data variables.product.prodname_copilot_short %} custom instructions for this repository. | | `copilot login` | Authenticate with {% data variables.product.prodname_copilot_short %} via the OAuth device flow. Accepts `--host HOST` to specify the {% data variables.product.github %} host URL (default: `https://github.com`). | -| `copilot login` [OPTION] | Authenticate with {% data variables.product.prodname_copilot_short %} via the OAuth device flow. See [`copilot login` options](#copilot-login-options). | +| `copilot login [OPTION]` | Authenticate with {% data variables.product.prodname_copilot_short %} via the OAuth device flow. See [`copilot login` options](#copilot-login-options). | | `copilot mcp` | Manage MCP server configurations from the command line. | | `copilot plugin` | Manage plugins and plugin marketplaces. | | `copilot plugins list` | Non-interactively inspect every plugin, MCP server, skill, instruction source, and language server discovered for the current working directory—the same resources the in-CLI plugins dashboard shows. See [Using `copilot plugins list`](#using-copilot-plugins-list). | @@ -167,6 +167,7 @@ With `--skill`, pass either a skill name or the path to a custom skill directory | `@ FILENAME` | Include file contents in the context. | | `# NUMBER` | Include a {% data variables.product.github %} issue or pull request in the context. | | `! COMMAND` | Execute a command in your local shell, bypassing {% data variables.product.prodname_copilot_short %}. Enter `!` alone on an empty prompt to enter shell mode for running multiple shell commands in sequence. Press Esc or Ctrl+C on an empty prompt to exit shell mode. | +| `$` | Type a lone `$` at the prompt to hand the terminal over to a real interactive shell (`$SHELL` on Unix, `%COMSPEC%` on Windows) rooted at the session's working directory. Unlike `!` shell mode, this suspends the CLI UI entirely, so job control, full-screen apps, tab completion, and colors all work natively. Exit the shell (`exit`, or Ctrl+D on Unix) to return to the CLI. Only activates for a local, trusted, idle session on a real TTY. Can be disabled in enterprise managed settings. Disabled by default. Enable it with the `shellShortcut` setting—see [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-config-dir-reference#configuration-file-settings). | | `?` | Open quick help (on an empty prompt). Press again to dismiss and insert a literal `?`. | | Esc | Cancel the current operation. Press twice to interrupt the running turn, or to stop background agents when the main agent is idle. | | Ctrl+C | Cancel operation / clear input. Press twice to exit. | @@ -290,7 +291,7 @@ These are the slash commands you can use from within an interactive CLI session. | `/downgrade VERSION` | Download and restart into a specific CLI version. Available for team accounts. | | `/env` | Show loaded environment details (instructions, MCP servers, skills, agents, hooks, plugins, LSPs, extensions). | | `/every [INTERVAL PROMPT]`, `/every` | Schedule a recurring prompt, skill, or schedulable slash command for the current session (for example, `/every 1h run tests` or `/every 1d /chronicle standup`). With no arguments the schedule manager is displayed. {% data reusables.copilot.experimental %} | -| `/exit`, `/quit` | Exit the CLI. | +| `/exit`, `/quit` | Close the current session. If other sessions are running, this foregrounds the newest remaining one instead of quitting. Quits the CLI only when it is the last open session. `/exit print` always tears down the CLI and offers to dump the transcript. | | `/extensions [manage\|mode]`, `/extension` | Manage CLI extensions. | | `/experimental [on\|off\|show]` | Toggle, set, or show experimental features. | | `/feedback`, `/bug` | Provide feedback about the CLI. | @@ -308,10 +309,22 @@ These are the slash commands you can use from within an interactive CLI session. | `/logout` | Log out of {% data variables.product.prodname_copilot_short %}. | | `/lsp [show\|test\|reload\|logs\|help] [SERVER-NAME]` | Manage the language server configuration. The `logs` subcommand opens the live LSP services log panel. | | `/mcp [list\|show\|add\|edit\|delete\|disable\|enable\|auth\|reload\|search] [SERVER-NAME]` | Manage the MCP server configuration. `list` (alias `ls`) prints a plain-text list of configured servers with connection status and live state, and is read-only, so it can run while the agent is busy processing a turn; all other subcommands are blocked until the turn finishes. Sandboxed local servers show a `connected (sandboxed)` status. See [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers#managing-mcp-servers). | -| `/model [--repo\|--local] [MODEL]`, `/models` | Select the AI model you want to use, or choose **Auto**. `--repo`/`--local` pins the default model in repository settings instead of the current session. Press Tab on a model with a long-context variant to toggle its Context column between the default and long-context window. See [AUTOTITLE](/copilot/concepts/models/auto-model-selection). | +| `/model [--repo\|--local\|--session] [MODEL]`, `/models` | Select the AI model you want to use, or choose **Auto**. `--repo`/`--local` pins the default model in repository settings instead of the current session; `--session` (alias `-s`) changes the model, reasoning effort, or context window for the current session only, without touching saved settings. Press Tab on a model with a long-context variant to toggle its Context column between the default and long-context window. See [AUTOTITLE](/copilot/concepts/models/auto-model-selection). | | `/permissions [show\|reset]` | View or clear in-memory tool and path approvals for the current session. | | `/plan [PROMPT]` | Create an implementation plan before coding. | -| `/plugin [marketplace\|install\|uninstall\|update\|list] [ARGS...]` | Manage plugins and plugin marketplaces. `list` (alias `ls`, including bare `/plugin`) is read-only and can run while the agent is busy processing a turn; all other subcommands are blocked until the turn finishes. See [AUTOTITLE](/copilot/concepts/agents/about-plugins). | +| `/plugins` (alias `/plugin`) | Manage plugins, MCP servers, and skills; opens the plugins dashboard, or run with `--plugin`, `--mcp`, or `--skill` to open it focused on that tab. See [AUTOTITLE](/copilot/concepts/agents/about-plugins). | +| `/plugins help` | Show full `/plugins` command usage. | +| `/plugins install SOURCE` | Install a plugin from a marketplace spec, {% data variables.product.github %} repository, git URL, or local path. | +| `/plugins install --skill [--project] ` | Install a skill; `--project` scopes a file or URL install to this repository instead of your user account. | +| `/plugins update PLUGIN[@MARKETPLACE]` | Update an installed plugin. | +| `/plugins uninstall PLUGIN[@MARKETPLACE]` | Uninstall a plugin. | +| `/plugins list` (alias `/plugin ls`) | List installed plugins. | +| `/plugins enable\|disable\|remove --plugin\|--mcp\|--skill NAME` | Enable, disable, or remove/uninstall a plugin, MCP server, or skill by name; defaults to `--plugin` when no kind is given. | +| `/plugins marketplace add SOURCE` | Add a marketplace. | +| `/plugins marketplace remove NAME` | Remove a marketplace. | +| `/plugins marketplace list` | List registered marketplaces. | +| `/plugins marketplace browse NAME` | Browse plugins in a marketplace. | +| `/plugins mcp [SUBCOMMAND]` | Delegates to `/mcp`; manage MCP servers from the plugins dashboard. | | `/pr [view\|create\|fix\|auto\|automerge]` | Manage pull requests for the current branch. `auto` drives the pull request to green and stops; `automerge` (alias: `agentmerge`) drives the pull request to green and merges it. See [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli/manage-pull-requests). | | `/refine TEXT` | Rewrite a roughly composed prompt into a clear one for review. Run with no arguments (via Ctrl+X then `/refine`) to clean up the current input box. Can be particularly useful for prompts entered by speaking. | | `/remote [on\|off]` | Show the remote control status (if no argument provided), enable remote steering (`on`), or end the remote connection (`off`). See [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli/steer-remotely). | @@ -326,7 +339,7 @@ These are the slash commands you can use from within an interactive CLI session. | `/search [QUERY]`, `/find [QUERY]` | Search the conversation timeline. {% data reusables.copilot.experimental %} | | `/security-review [PROMPT]` | Run a focused security review of active local code changes and return prioritized vulnerability findings with remediation suggestions. This command is not a full repository security audit. | | `/session [info\|checkpoints [n]\|files\|plan\|rename [NAME]\|cleanup\|prune\|delete [ID]\|delete-all]`, `/sessions [info\|checkpoints [n]\|files\|plan\|rename [NAME]\|cleanup\|prune\|delete [ID]\|delete-all]` | Show session information and manage sessions. The `info` subcommand shows session details including the session link (when available). Subcommands: `info`, `checkpoints`, `files`, `plan`, `rename`, `cleanup`, `prune`, `delete`, `delete-all`. | -| `/settings [--repo\|--local] [show KEY\|KEY\|KEY VALUE]`,
`/config [--repo\|--local] [show KEY\|KEY\|KEY VALUE]` | Open the settings dialog, open it focused on a specific setting (`KEY`), set a setting inline (`KEY VALUE`), or display a setting's current value (`show KEY`). The dialog shows **User**, **Repo**, and **Repo (local)** tabs—switch with Tab/Shift+Tab; a setting overridden in another scope shows a badge naming which scope wins. Add `--repo` or `--local` to target `.github/copilot/settings.json` or `.github/copilot/settings.local.json` instead of the user settings file—for example, `/settings --repo model gpt-5.2`. Only [repo-overridable keys](/copilot/reference/copilot-cli-reference/cli-config-dir-reference#repository-settings-githubcopilotsettingsjson) can be set this way. Rows governed by an active organization or MDM managed policy render read-only with a `(managed)` tag. See [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/change-settings). | +| `/settings [--repo\|--local] [show KEY\|KEY\|KEY VALUE]`,
`/config [--repo\|--local] [show KEY\|KEY\|KEY VALUE]` | Open the settings dialog, open it focused on a specific setting (`KEY`), set a setting inline (`KEY VALUE`), or display a setting's current value (`show KEY`). `show` masks secret-named values (for example, tokens or API keys nested under a setting) instead of printing them in clear text. The dialog shows **User**, **Repo**, and **Repo (local)** tabs—switch with Tab/Shift+Tab; a setting overridden in another scope shows a badge naming which scope wins. Add `--repo` or `--local` to target `.github/copilot/settings.json` or `.github/copilot/settings.local.json` instead of the user settings file—for example, `/settings --repo model gpt-5.2`. Only [repo-overridable keys](/copilot/reference/copilot-cli-reference/cli-config-dir-reference#repository-settings-githubcopilotsettingsjson) can be set this way. Rows governed by an active organization or MDM managed policy render read-only with a `(managed)` tag. See [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/change-settings). | | `/share [link\|off\|file\|html\|gist\|research] [...]`, `/export [...]` | Share the current session. With no subcommand, generates a shareable {% data variables.product.github %} link when you're logged in and synced (falls back to Markdown file export otherwise). `off` stops sharing. `link` is an explicit alias for the default link flow; `link off` stops link sharing. `file [session\|research] [PATH]` exports to a Markdown file. `html [session\|research] [PATH]` exports to an HTML file. `gist [session\|research]` creates a {% data variables.product.github %} gist. `research [PATH]` exports the research report. | | `/skills [list\|info\|add\|remove\|reload] [ARGS...]` | Manage skills for enhanced capabilities. See [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/add-skills). | | `/statusline`, `/footer` | Configure which items appear in the status line. | @@ -412,7 +425,7 @@ For a complete list of available slash commands enter `/help` in the CLI's inter | `--plugin-dir=DIRECTORY` | Load a plugin from a local directory (can be used multiple times). | | `--remote` | Enable remote access to this session from {% data variables.product.prodname_dotcom_the_website %} and {% data variables.product.prodname_mobile %}. See [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli/steer-remotely). | | `--remote-export` | Export your session to {% data variables.product.prodname_dotcom_the_website %} and {% data variables.product.prodname_mobile %} (read-only; does not enable remote control). | -| `-r`, `--resume[=VALUE]` | Resume a previous interactive session by choosing from a list. Optionally specify a session ID, ID prefix, or session name. Name matching is exact and case-insensitive; falls back to the auto-generated summary when no explicit name matches. Conflicts with `--continue`. | +| `-r`, `--resume[=VALUE]` | Resume a previous interactive session by choosing from a list. Optionally specify a session ID, ID prefix, or session name. Name matching is exact and case-insensitive; falls back to the auto-generated summary when no explicit name matches. Conflicts with `--continue`. Bare `--resume` (no value) shows an interactive session picker, which requires a TTY. If multiple sessions exist and the picker can't be shown (for example under `-p`, a non-TTY `-i`, or piped stdin), the CLI exits with an error instead of silently starting a new session—pass an explicit `--resume=SESSION-ID` or use `--continue`. | | `-s`, `--silent` | Output only the agent response (without usage statistics), useful for scripting with `-p`. | | `--screen-reader` | Enable screen reader optimizations. | | `--secret-env-vars=VAR ...` | Redact an environment variable from shell and MCP server environments (can be used multiple times). For multiple variables, use a quoted, comma-separated list. The values in the `GITHUB_TOKEN` and `COPILOT_GITHUB_TOKEN` environment variables are redacted from output by default. | @@ -626,6 +639,10 @@ MCP servers provide additional tools to the CLI agent. Configure persistent serv Local (stdio) servers that spawn inside the sandbox (see the `/sandbox` slash command) show a `connected (sandboxed)` status in `copilot mcp list` and `/mcp list`, since remote (HTTP/SSE) servers are never sandboxed. {% data reusables.copilot.experimental %} +`copilot mcp list` and `/mcp list` mark a disabled server with a `(disabled)` suffix in text output, or `"enabled": false` per server in `--json` output. `copilot mcp get` shows a `Status: Enabled`/`Disabled` line. + +Toggling `/sandbox` restarts only local (stdio) MCP servers, since they spawn inside the sandbox. Remote (HTTP/SSE) servers stay connected. + ### `copilot mcp` subcommand Use `copilot mcp` to manage MCP server configurations from the command line without starting an interactive session. @@ -898,6 +915,20 @@ Remote skills are projected alongside local skills and follow the same name-base When two plugins provide skills with the same name, both coexist using plugin-qualified invocation names such as `/my-plugin/search` and `/other-plugin/search`. The bare name routes to the higher-priority plugin. This applies to skills only; commands keep the standard tier-based deduplication, where the higher-priority source wins. +### Installing a skill non-interactively + +Use `copilot plugins install --skill` to install a skill from a file, URL, or directory without opening an interactive session: + +```bash +# Install for your user account (default scope) +copilot plugins install --skill ./my-skill/SKILL.md + +# Install into the current project (.github/skills; file or URL skills only) +copilot plugins install --skill --scope project ./my-skill/SKILL.md +``` + +Installing a directory registers it as a custom skill source rather than copying it. Installing a file or URL copies the skill's content into your personal or project skills directory. The equivalent interactive command is `/plugins install --skill [--project] `. For the full option reference, see [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-plugin-reference#copilot-plugins-install-options). + ### Commands (alternative skill format) Commands are an alternative to skills stored as individual `.md` files in `.claude/commands/`. The command name is derived from the filename. Command files use a simplified format (no `name` field required) and support `argument-hint`, `description`, `allowed-tools`, and `disable-model-invocation`. Commands have lower priority than skills with the same name. @@ -1180,10 +1211,10 @@ The runtime emits a hierarchical span tree for each agent interaction. Each tree Wraps the entire agent invocation: all LLM calls and tool executions for one user message. -* **Top-level sessions** use span kind `CLIENT` (remote service invocation) with `server.address` and `server.port`. -* **Subagent invocations** (for example, explore, task) use span kind `INTERNAL` (in-process) without server attributes. +* Both **top-level sessions** and **subagent invocations** (for example, explore, task) use span kind `INTERNAL` (in-process); provider-facing inference is represented by child `CLIENT` `chat` spans. +* **Top-level sessions** additionally carry `server.address` and `server.port`; subagent invocations do not. -| Attribute | Description | Span kind | +| Attribute | Description | Scope | |-----------|-------------|-----------| | `gen_ai.operation.name` | `invoke_agent` | Both | | `gen_ai.provider.name` | Provider (for example, `github`, `anthropic`) | Both | @@ -1202,8 +1233,8 @@ Wraps the entire agent invocation: all LLM calls and tool executions for one use | `github.copilot.turn_count` | Number of LLM round-trips | Both | | `github.copilot.cost` | Monetary cost | Both | | `github.copilot.aiu` | AI units consumed | Both | -| `server.address` | Server hostname | `CLIENT` only | -| `server.port` | Server port | `CLIENT` only | +| `server.address` | Server hostname | Top-level only | +| `server.port` | Server port | Top-level only | | `error.type` | Error class name (on error) | Both | | `gen_ai.input.messages` | Full input messages as JSON (content capture only) | Both | | `gen_ai.output.messages` | Full output messages as JSON (content capture only) | Both | @@ -1268,6 +1299,8 @@ One span per tool call. Span kind: `INTERNAL`. | `gen_ai.client.token.usage` | Histogram | tokens | Token counts by type (`input`/`output`) | | `gen_ai.client.operation.time_to_first_chunk` | Histogram | s | Time to receive first streaming chunk | | `gen_ai.client.operation.time_per_output_chunk` | Histogram | s | Inter-chunk latency after first chunk | +| `gen_ai.invoke_agent.inference_calls` | Histogram | `{inference_call}` | Number of model calls made during one agent invocation, counted at provider dispatch (failed and partial calls included; requests blocked before dispatch excluded). Dimension: `gen_ai.agent.name`. | +| `gen_ai.invoke_agent.tool_calls` | Histogram | `{tool_call}` | Number of client-side tool calls made during one agent invocation (failed and partial calls included; synthetic CLI tool lifecycles and provider-executed server-side tools excluded). Dimension: `gen_ai.agent.name`. | #### Vendor-specific metrics diff --git a/content/copilot/reference/copilot-cli-reference/cli-config-dir-reference.md b/content/copilot/reference/copilot-cli-reference/cli-config-dir-reference.md index 8a972f552b27..4ecc3cbe87e0 100644 --- a/content/copilot/reference/copilot-cli-reference/cli-config-dir-reference.md +++ b/content/copilot/reference/copilot-cli-reference/cli-config-dir-reference.md @@ -476,19 +476,24 @@ These settings apply across all your sessions and repositories. You can use the | `proxyKerberosServicePrincipal` | `string` | unset | Service principal name (SPN) for Kerberos/Negotiate proxy authentication, overriding the derived `HTTP/`. | | `proxyUrl` | `string` | unset | Proxy URL for HTTP(S) requests (for example, `http://proxy.corp.example:3128`). Overridden by the `HTTP_PROXY` or `HTTPS_PROXY` environment variables (any casing). | | `remote` | `"on"` \| `"off"` | `"on"` | Controls session syncing and remote access. Set to `"off"` to keep session data local only and disable remote control. Can also be set with `--remote` or `--no-remote`. | +| `renderHexColors` | `boolean` | `true` | Show six-digit hex color codes written as inline code (for example, `` `#FF0000` ``) as color swatches. | | `renderMarkdown` | `boolean` | `true` | Render Markdown in terminal output. | | `remoteExport` | `boolean` | `true` | Export sessions remotely when session sync is available. Set to `false` to opt out of remote export by default. The `remoteSessions` setting when set to `true`, or the `--remote` flag, still enables export and steering regardless of this setting. | | `respectGitignore` | `boolean` | `true` | Exclude gitignored files from the `@` file mention picker. When `false`, the picker includes files normally excluded by `.gitignore`. | +| `sandbox.gitAuth` | `boolean` | `false` | Inject Git credentials into the sandbox so commands running inside it can authenticate with Git. | +| `sandbox.ghAuth` | `boolean` | `false` | Inject {% data variables.product.prodname_cli %} (`gh`) credentials into the sandbox so commands running inside it can authenticate with the {% data variables.product.prodname_cli %}. | +| `sandbox.userPolicy.seatbelt.keychainAccess` | `boolean` | `false` | macOS only. Grant sandboxed commands access to the system keychain. Can also be toggled from the `/sandbox` dialog. | | `screenReader` | `boolean` | `false` | Enable screen reader optimizations. | | `scrollbar` | `boolean` | `true` | Show the scrollbar in scrollable views. Set to `false` to hide it and use the full terminal width. | +| `shellShortcut` | `boolean` | `false` | Let a lone `$` at the prompt open an interactive shell rooted at the session's working directory (activates only for a local, trusted, idle session on a real TTY). User- or managed-scoped only—not repo-overridable. | | `showTimestamps` | `boolean` | `true` | Show dim `HH:mm` timestamps next to user messages in the timeline. | | `showTipsOnStartup` | `boolean` | `true` | Show a random command tip when the CLI starts. | | `skillDirectories` | `string[]` | `[]` | Additional directories to search for custom skill definitions (in addition to `~/.copilot/skills/`). | | `statusLine` | `object` | — | Custom status line display. `type`: must be `"command"`. `command`: path to an executable script that receives session JSON on stdin and prints status content to stdout. `padding`: optional number of left-padding spaces. | -| `stayInAutopilot` | `boolean` | `false` | Stay in autopilot mode after an autopilot task completes, instead of reverting to interactive mode. | +| `stayInAutopilot` | `boolean` | `false` | Remain in autopilot mode after each task completes. When enabled, the next prompt you enter after a task completes is also handled in autopilot mode. For more information, see [AUTOTITLE](/copilot/concepts/agents/copilot-cli/autopilot#staying-in-autopilot-mode-between-tasks). | | `storeTokenPlaintext` | `boolean` | `false` | Allow authentication tokens to be stored in plain text in `config.json` when no system keychain is available. | | `stream` | `boolean` | `true` | Enable streaming responses. | -| `streamerMode` | `boolean` | `false` | Hide preview model names and quota details. Useful when demonstrating {% data variables.copilot.copilot_cli_short %} or screen sharing. | +| `streamerMode` | `boolean` | `false` | Hide preview model names, quota details, prompt timestamps, and the update-available notice. Useful when demonstrating {% data variables.copilot.copilot_cli_short %} or screen sharing. | | `subagents.agents` | `object` | `{}` | Per-agent model configuration, keyed by agent name. Each value is an object with optional `model` (string), `effortLevel` (string), and `contextTier` (`"default"`, `"long_context"`, or `"inherit"`) fields. Set any field to `"inherit"` to use the parent session's value at dispatch time. Use the `/subagents` slash command to configure these settings interactively. | | `subagents.disabledSubagents` | `string[]` | `[]` | Agent names to prevent from being dispatched. Only the `rubber-duck` agent cannot be disabled via this setting. All other built-in agents—including `explore`, `task`, `code-review`, `general-purpose`, `research`, and `security-review`—can be disabled. | | `subagents.maxConcurrency` | `number` | plan-based | Maximum concurrent subagents for this session. Only honored for usage-based billing users; ignored for all other plans. Capped at `32`. See [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference#subagent-limits). | @@ -608,12 +613,53 @@ Only the following keys are supported in MDM managed settings. | Key | Description | |-----|-------------| +| `allowedMcpServers` | Allowlist of MCP servers users may load, matched by `serverUrl`, `serverCommand`, or `serverName`. Trusted first-party servers (for example, the built-in {% data variables.product.github %} MCP server) are always exempt. Leaving this key unset allows all non-default servers; an empty array denies all of them. See [Managed MCP server allow/deny list](#managed-mcp-server-allowdeny-list). | +| `deniedMcpServers` | Denylist of MCP servers that must never load, matched the same way as `allowedMcpServers`. A matching non-default server is blocked regardless of the allowlist—deny always wins. See [Managed MCP server allow/deny list](#managed-mcp-server-allowdeny-list). | | `enabledPlugins` | Enable or disable specific plugins | | `extraKnownMarketplaces` | Add trusted plugin marketplaces | | `model` | Set a default model for all users (overridden by the `--model` flag or a resumed-session model) | | `permissions` | Set managed permissions, including `disableBypassPermissionsMode` | -| `remoteControl` | Control whether sessions on this device can be controlled from other devices. `mode` is `"enabled"`, `"disabled"`, or `"requireSSO"` (requires `requiredSsoOrganizations` when set). | +| `remoteControl` | Control whether sessions on this device can be controlled from other devices. `mode` is `"enabled"`, `"disabled"`, or `"requireSSO"` (requires `githubDotComOrganizations` when set). | +| `shellShortcut` | Force-enable or force-disable the `$` interactive shell shortcut for all users. A managed value always overrides the user's own `shellShortcut` setting. | | `strictKnownMarketplaces` | Restrict plugins to known marketplaces | +| `telemetry` | Push baseline OpenTelemetry export configuration: `enabled`, `endpoint`, `protocol`, `headers`, `resourceAttributes`, `captureContent`, `lockCaptureContent`, and `serviceName`. See [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference#opentelemetry-monitoring). | + +> [!NOTE] +> When `remoteControl.mode` is `"requireSSO"`, list the allowed organizations in `remoteControl.githubDotComOrganizations`. The client must be SSO-authorized for at least one listed {% data variables.product.prodname_dotcom_the_website %} organization—it no longer needs to be authorized for all of them. + +## Managed MCP server allow/deny list + +Administrators can govern MCP servers directly through MDM managed settings, independent of the [enterprise MCP allowlist](/copilot/reference/copilot-cli-reference/cli-command-reference#enterprise-mcp-allowlist). + +Set `allowedMcpServers` and/or `deniedMcpServers` in a managed settings source: + +```json +{ + "allowedMcpServers": [ + { "serverUrl": "https://mcp.example.com/*" }, + { "serverCommand": ["npx", "-y", "@example/mcp-server"] } + ], + "deniedMcpServers": [ + { "serverName": "untrusted-server" } + ] +} +``` + +Each entry identifies a server by exactly one of the following matchers. + +| Matcher | Matches | Notes | +|---------|---------|-------| +| `serverUrl` | A remote (HTTP/SSE) server by URL | Supports `*` wildcards; scheme and host match case-insensitively, path case-sensitively. `${VAR}` references expand before matching. | +| `serverCommand` | A stdio server by its exact command and arguments, in order | `${VAR}` references expand before matching. | +| `serverName` | A server by its assigned label | Allowlist entries are restricted to `[A-Za-z0-9_-]+` (no wildcards); denylist entries accept any non-empty string. | + +Rules: + +* **Trusted first-party servers** (for example, the built-in {% data variables.product.github %} MCP server) are always exempt from both lists. +* **Unset `allowedMcpServers`** allows all non-default servers; an **empty array** blocks all of them (deny-all). +* **Unset or empty `deniedMcpServers`** blocks nothing. +* **Deny always wins**—a server matching `deniedMcpServers` is blocked even if it also matches `allowedMcpServers`. +* For remote servers, a match must come from a `serverUrl` entry; `serverName` only counts when no `serverUrl` entries exist. For stdio servers, a match must come from a `serverCommand` entry; `serverName` only counts when no `serverCommand` entries exist. ## Further reading diff --git a/content/copilot/reference/copilot-cli-reference/cli-plugin-reference.md b/content/copilot/reference/copilot-cli-reference/cli-plugin-reference.md index 94865a249d26..90f57339d622 100644 --- a/content/copilot/reference/copilot-cli-reference/cli-plugin-reference.md +++ b/content/copilot/reference/copilot-cli-reference/cli-plugin-reference.md @@ -30,10 +30,10 @@ You can use the following commands in the terminal to manage plugins for {% data | `copilot plugin update NAME` | Update a named plugin. Use `--all` to update all installed plugins at once. | | `copilot plugin enable NAME` | Enable a previously disabled plugin | | `copilot plugin disable NAME` | Disable a plugin without uninstalling it | -| `copilot plugin marketplace add SPECIFICATION` | Register a marketplace. Use `--name NAME` to set a custom local name. | +| `copilot plugin marketplace add SPECIFICATION` | Register a marketplace. The marketplace's own name, from its `marketplace.json` manifest, becomes its registration key—there is no option to set a custom local name. | | `copilot plugin marketplace list` | List registered marketplaces | | `copilot plugin marketplace browse NAME` | Browse marketplace plugins | -| `copilot plugin marketplace update NAME` | Re-fetch a marketplace's plugin catalog. Use `--all` to refresh every registered marketplace. | +| `copilot plugin marketplace update [NAME]` (alias `refresh`) | Re-fetch a marketplace's plugin catalog. Omit `NAME` to refresh the catalogs of every registered marketplace. | | `copilot plugin marketplace remove NAME` | Unregister a marketplace. Refused if plugins from the marketplace are still installed; pass `--force` to also uninstall those plugins. | Non-interactively, `copilot plugins enable NAME --plugin`, `copilot plugins disable NAME --plugin`, and `copilot plugins remove NAME --plugin` provide the same enable, disable, and uninstall operations. `--plugin` is the default kind and can be omitted for these three commands. See [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference#using-copilot-plugins-list) for the non-interactive `--mcp` and `--skill` kinds, which extend these commands to MCP servers and skills. @@ -48,6 +48,39 @@ Non-interactively, `copilot plugins enable NAME --plugin`, `copilot plugins disa | Git URL | `https://github.com/o/r.git` | Any Git URL | | Local path | `./my-plugin` or `/abs/path` | Local directory | +### `copilot plugins install` options + +In addition to installing a plugin from a specification, `copilot plugins install` can install an individual skill from a file, URL, or directory with `--skill`. A skill install isn't a plugin install and doesn't go through a marketplace—see [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference#skills-reference) for details on skills themselves. + +| Option | Description | +|------------------------|------------------------------------------------------------------------------------| +| `--plugin` | Install a plugin (default). | +| `--skill` | Install a skill from a local path or URL. | +| `--scope SCOPE` | For a file or URL `--skill` install: `user` (default) or `project`. `project` scopes the install to the current repository's `.github/skills` directory instead of your user account, and only applies to file or URL skill installs. | +| `--config-dir=DIRECTORY` | Path to the configuration directory. This option is deprecated. Use `COPILOT_HOME` instead. | + +Installing a directory registers it as a custom skill source rather than copying it; installing a file or URL copies the skill's content into your personal or project skills directory. + +MCP servers install from a policy-configured registry, which requires authentication and interactive secret entry. Use the `/plugins` dashboard (Online mode) or the `/mcp` slash command to add MCP servers instead of `copilot plugins install`. + +### `copilot plugins update` options + +| Option | Description | +|-----------|-----------------------------------------| +| `--all` | Update every installed plugin | + +### `copilot plugins marketplace` subcommands + +Built-in default marketplaces ship with the runtime and can't be removed. + +| Subcommand | Description | +|--------------------------|-------------------------------------------------------------------------------| +| `list [--json]` | List every registered marketplace, including built-in defaults | +| `add SOURCE` | Add a marketplace (`owner/repo`, `owner/repo#ref`, a URL, or a local path) | +| `remove NAME [--force]` | Remove a marketplace; `--force` also uninstalls plugins sourced from it | +| `browse NAME [--json]` | List the plugins offered by a marketplace's catalog | +| `update [NAME]` (alias `refresh`) | Refresh the plugin catalog for one marketplace, or all if `NAME` is omitted | + ## `plugin.json` All plugins consist of a plugin directory containing, at minimum, a manifest file named `plugin.json` located at the root of the plugin directory. See [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/plugins-creating). diff --git a/content/copilot/reference/copilot-usage-metrics/copilot-usage-metrics.md b/content/copilot/reference/copilot-usage-metrics/copilot-usage-metrics.md index 112c0bfcb2ba..9b9745813ed6 100644 --- a/content/copilot/reference/copilot-usage-metrics/copilot-usage-metrics.md +++ b/content/copilot/reference/copilot-usage-metrics/copilot-usage-metrics.md @@ -17,8 +17,9 @@ contentType: reference The {% data variables.product.prodname_copilot_short %} usage metrics dashboard and APIs display and export data using a consistent set of fields. This reference lists all available metrics and describes how to interpret their values in both dashboard visuals and NDJSON or API exports. * The {% data variables.product.prodname_copilot_short %} usage metrics dashboards are available at the **enterprise** and **organization** level. -* The {% data variables.product.prodname_copilot_short %} usage metrics APIs return reports scoped to the **enterprise**, **organization**, or **individual user** level, in different shapes depending on scope and granularity. +* The {% data variables.product.prodname_copilot_short %} usage metrics APIs return reports at the **enterprise** or **organization** scope, with aggregated, **repository-level**, and **individual user-level** report granularities. Shapes vary by scope and granularity. * Team-level metrics are not pre-aggregated; you construct them by joining the user-teams report with the per-user usage metrics report. See [AUTOTITLE](/copilot/reference/copilot-usage-metrics/team-level-metrics). +* Repository-level reports contain one record per repository with pull request activity on the requested day. See [Repository-level fields (API only)](#repository-level-fields-api-only) later in this article. For guidance on how to read and interpret these metrics, see [AUTOTITLE](/copilot/concepts/copilot-usage-metrics/copilot-metrics). @@ -71,6 +72,7 @@ Reports come in different shapes depending on their scope and granularity, so th * **Aggregated reports** (`enterprise-1-day` and `org-1-day`) contain one aggregated record per enterprise or organization, including active-user counts, `pull_requests`, and `totals_by_ai_adoption_phase`. They do not contain `user_id`, `user_login`, or the `used_*` indicators. * **28-day reports** (`enterprise-28-day` and `org-28-day`) wrap an array of daily aggregated records in a `day_totals` field, with the reporting window at the top level. * **User-teams reports** (`*-user-teams-1-day`) map users to the teams they belong to, so you can construct team-level metrics. +* **Repository-level reports** (`*-repos-1-day`) contain one record per repository with pull request activity for the day, including pull requests created by {% data variables.copilot.copilot_cloud_agent %} and reviewed by {% data variables.copilot.copilot_code-review_short %}. Organization-scope reports also include `organization_id` alongside `enterprise_id`. For example schemas of the data returned by the APIs, see [AUTOTITLE](/copilot/reference/copilot-usage-metrics/example-schema). @@ -190,6 +192,23 @@ Teams with fewer than 5 seated {% data variables.product.prodname_copilot_short | `team_id` | `integer` | No | Unique ID of the team the user belongs to. | | `slug` | `string` | No | URL-friendly identifier for the team. | +### Repository-level fields (API only) + +Repository-level reports show daily pull request creation, review, merge, and suggestion activity for repositories in an organization or enterprise, including pull requests created by {% data variables.copilot.copilot_cloud_agent %} and reviewed by {% data variables.copilot.copilot_code-review_short %}. Each row represents one repository that had pull request activity on the requested day; repositories with no activity are omitted. These reports focus on pull request lifecycle activity and can contain data even when IDE usage metrics are absent. + +These fields are returned by the daily repository-level report (`repos-1-day`), available via the REST API at the organization and enterprise scopes. For the endpoint URLs, response envelope, permissions, and download workflow, see [AUTOTITLE](/rest/copilot/copilot-usage-metrics). For example rows, see [AUTOTITLE](/copilot/reference/copilot-usage-metrics/example-schema#repository-level-schema-example). + +| Field | Type | Nullable | Description | +|:--|:--|:--|:--| +| `day` | `string` | No | Calendar day this record represents, in `YYYY-MM-DD` format. | +| `enterprise_id` | `string` | No | Unique ID of the enterprise. Populated in enterprise-scoped reports, and in organization-scoped reports for organizations owned by an enterprise. Empty for organizations not owned by an enterprise. | +| `organization_id` | `string` | No | Unique ID of the organization that owns the repository. Included in both enterprise- and organization-scoped reports. | +| `repo_id` | `integer` | No | Unique ID of the repository. | +| `repo_owner_name` | `string` | No | Login of the repository owner. | +| `repo_name` | `string` | No | Repository name. | +| `repo_visibility` | `string` | No | Repository visibility. Possible values are `PRIVATE`, `INTERNAL`, and `PUBLIC`. | +| `pull_requests` | `object` | No | Daily pull request activity for the repository. See [Pull request activity fields](#pull-request-activity-fields). | + ### Activity breakdown objects The `totals_by_*` fields are arrays of breakdown objects. The array is always present but can be empty. Within each object, the metric fields (`*_count` and `loc_*_sum`) follow the same definitions as the top-level per-user fields, and the dimension fields carry the values documented in [Breakdown dimension values](#breakdown-dimension-values). @@ -235,7 +254,7 @@ The `totals_by_cli` object contains the following nested fields when {% data var > [!IMPORTANT] > Organization- and enterprise-level reports may show different totals due to differences in user deduplication and attribution timing. For guidance on interpreting pull request metrics across scopes, see [AUTOTITLE](/copilot/concepts/copilot-usage-metrics/copilot-metrics#interpreting-pull-request-lifecycle-metrics-across-scopes). -The `pull_requests` object appears in aggregated enterprise and organization reports only. It captures daily pull request creation, review, merge, and suggestion activity at the enterprise or organization scope, including activity performed by {% data variables.product.prodname_copilot_short %}. +The `pull_requests` object appears in aggregated enterprise and organization reports, and in repository-level reports. It captures daily pull request creation, review, merge, and suggestion activity, including activity performed by {% data variables.copilot.copilot_cloud_agent %} and {% data variables.copilot.copilot_code-review_short %}. | Field | Type | Nullable | Description | |:--|:--|:--|:--| @@ -245,15 +264,15 @@ The `pull_requests` object appears in aggregated enterprise and organization rep | `pull_requests.median_minutes_to_merge` | `number` | Yes | Median time, in minutes, between pull request creation and merge for pull requests merged on this specific day.

Median is used to reduce the impact of outliers from unusually long-running pull requests. Null when no pull requests were merged that day. | | `pull_requests.total_suggestions` | `integer` | No | Total number of pull request review suggestions generated on this specific day, regardless of author. | | `pull_requests.total_applied_suggestions` | `integer` | No | Total number of pull request review suggestions that were applied on this specific day, regardless of author. | -| `pull_requests.total_created_by_copilot` | `integer` | No | Number of pull requests created by {% data variables.product.prodname_copilot_short %} on this specific day. | -| `pull_requests.total_reviewed_by_copilot` | `integer` | No | Number of pull requests reviewed by {% data variables.product.prodname_copilot_short %} on this specific day.

A pull request may be counted on multiple days if {% data variables.product.prodname_copilot_short %} reviews it on multiple days. | -| `pull_requests.total_merged_created_by_copilot` | `integer` | No | Number of pull requests created by {% data variables.product.prodname_copilot_short %} that were merged on this specific day. Each pull request is counted only on the day it is merged. | +| `pull_requests.total_created_by_copilot` | `integer` | No | Number of pull requests created by {% data variables.copilot.copilot_cloud_agent %} on this specific day. | +| `pull_requests.total_reviewed_by_copilot` | `integer` | No | Number of pull requests reviewed by {% data variables.copilot.copilot_code-review_short %} on this specific day.

A pull request may be counted on multiple days if {% data variables.copilot.copilot_code-review_short %} reviews it on multiple days. | +| `pull_requests.total_merged_created_by_copilot` | `integer` | No | Number of pull requests created by {% data variables.copilot.copilot_cloud_agent %} that were merged on this specific day. Each pull request is counted only on the day it is merged. | | `pull_requests.total_merged_reviewed_by_copilot` | `integer` | No | Number of pull requests that were both merged and reviewed by {% data variables.copilot.copilot_code-review_short %} during the reporting period. | -| `pull_requests.median_minutes_to_merge_copilot_authored` | `number` | Yes | Median time, in minutes, between pull request creation and merge for pull requests created by {% data variables.product.prodname_copilot_short %} and merged on this specific day. Null when no such pull requests were merged that day. | +| `pull_requests.median_minutes_to_merge_copilot_authored` | `number` | Yes | Median time, in minutes, between pull request creation and merge for pull requests created by {% data variables.copilot.copilot_cloud_agent %} and merged on this specific day. Null when no such pull requests were merged that day. | | `pull_requests.median_minutes_to_merge_copilot_reviewed` | `number` | Yes | Median time, in minutes, between pull request creation and merge, calculated only for pull requests reviewed by {% data variables.copilot.copilot_code-review_short %}. Null when no such pull requests were merged that day. | -| `pull_requests.total_copilot_suggestions` | `integer` | No | Number of pull request review suggestions generated by {% data variables.product.prodname_copilot_short %} on this specific day. | -| `pull_requests.total_copilot_applied_suggestions` | `integer` | No | Number of pull request review suggestions generated by {% data variables.product.prodname_copilot_short %} that were applied on this specific day. | -| `pull_requests.copilot_suggestions_by_comment_type` | `array` | No | Aggregated counts of {% data variables.product.prodname_copilot_short %} code review suggestions, broken down by the comment type {% data variables.product.prodname_copilot_short %} assigned (for example, `security` or `bug_risk`). Each entry includes `comment_type`, `total_copilot_suggestions`, and `total_copilot_applied_suggestions`. Always present but can be empty. Not available at the repository level. | +| `pull_requests.total_copilot_suggestions` | `integer` | No | Number of pull request review suggestions generated by {% data variables.copilot.copilot_code-review_short %} on this specific day. | +| `pull_requests.total_copilot_applied_suggestions` | `integer` | No | Number of pull request review suggestions generated by {% data variables.copilot.copilot_code-review_short %} that were applied on this specific day. | +| `pull_requests.copilot_suggestions_by_comment_type` | `array` | No | Aggregated counts of {% data variables.copilot.copilot_code-review_short %} suggestions, broken down by the assigned comment type (for example, `security` or `bug_risk`). Each entry includes `comment_type`, `total_copilot_suggestions`, and `total_copilot_applied_suggestions`. Always present but can be empty. | ### AI adoption phase fields diff --git a/content/copilot/reference/copilot-usage-metrics/example-schema.md b/content/copilot/reference/copilot-usage-metrics/example-schema.md index f4050a182336..9d2a996ed5b1 100644 --- a/content/copilot/reference/copilot-usage-metrics/example-schema.md +++ b/content/copilot/reference/copilot-usage-metrics/example-schema.md @@ -13,7 +13,7 @@ category: allowTitleToDifferFromFilename: true --- -The following are example schemas for the user-level and enterprise-level data returned by the {% data variables.product.prodname_copilot_short %} usage metrics endpoints. The actual data returned may vary based on the specific metrics being tracked and the level of aggregation. You can use these examples as a reference for understanding the structure of the data and how to interpret the various fields and metrics included in the API response. +The following are example schemas for the user-level, enterprise-level, and repository-level data returned by the {% data variables.product.prodname_copilot_short %} usage metrics endpoints. The actual data returned may vary based on the specific metrics being tracked and the level of aggregation. You can use these examples as a reference for understanding the structure of the data and how to interpret the various fields and metrics included in the API response. ## User-level schema example @@ -317,3 +317,13 @@ The following user-teams report examples are returned by the `user-teams-1-day` } ] ``` + +## Repository-level schema example + +The following repository-level report example is returned in the NDJSON files downloaded from the `repos-1-day` endpoints. Each row represents one repository with pull request activity on the requested day. Both enterprise- and organization-scoped rows populate `organization_id` (the organization that owns each repository). Enterprise-scoped rows also populate `enterprise_id`, and organization-scoped rows populate `enterprise_id` only for organizations owned by an enterprise. For the field reference, see [AUTOTITLE](/copilot/reference/copilot-usage-metrics/copilot-usage-metrics#repository-level-fields-api-only). + +```json copy +{"day":"2026-07-14","enterprise_id":"1001","organization_id":"2002","repo_id":900000001,"repo_owner_name":"octodemo-metrics","repo_name":"example-service-alpha","repo_visibility":"INTERNAL","pull_requests":{"total_reviewed":1,"total_created":1,"total_created_by_copilot":1,"total_reviewed_by_copilot":1,"total_merged":1,"median_minutes_to_merge":372.62,"total_suggestions":0,"total_applied_suggestions":0,"total_merged_created_by_copilot":1,"median_minutes_to_merge_copilot_authored":372.62,"total_copilot_suggestions":0,"total_copilot_applied_suggestions":0,"total_merged_reviewed_by_copilot":1,"median_minutes_to_merge_copilot_reviewed":372.62,"copilot_suggestions_by_comment_type":[]}} +{"day":"2026-07-14","enterprise_id":"1001","organization_id":"2002","repo_id":900000003,"repo_owner_name":"octodemo-metrics","repo_name":"example-service-gamma","repo_visibility":"INTERNAL","pull_requests":{"total_reviewed":1,"total_created":0,"total_created_by_copilot":0,"total_reviewed_by_copilot":1,"total_merged":1,"median_minutes_to_merge":1020.53,"total_suggestions":0,"total_applied_suggestions":1,"total_merged_created_by_copilot":0,"total_copilot_suggestions":0,"total_copilot_applied_suggestions":1,"total_merged_reviewed_by_copilot":1,"median_minutes_to_merge_copilot_reviewed":1020.53,"copilot_suggestions_by_comment_type":[{"comment_type":"spelling","total_copilot_suggestions":0,"total_copilot_applied_suggestions":1}]}} +{"day":"2026-07-14","organization_id":"3003","enterprise_id":"","repo_id":900000010,"repo_owner_name":"octodemo-metrics","repo_name":"example-service-delta","repo_visibility":"PRIVATE","pull_requests":{"total_reviewed":1,"total_created":0,"total_created_by_copilot":0,"total_reviewed_by_copilot":1,"total_merged":2,"median_minutes_to_merge":1332.96,"total_suggestions":1,"total_applied_suggestions":2,"total_merged_created_by_copilot":1,"median_minutes_to_merge_copilot_authored":1329.47,"total_copilot_suggestions":1,"total_copilot_applied_suggestions":2,"total_merged_reviewed_by_copilot":2,"median_minutes_to_merge_copilot_reviewed":1332.96,"copilot_suggestions_by_comment_type":[{"comment_type":"documentation","total_copilot_suggestions":1,"total_copilot_applied_suggestions":1},{"comment_type":"spelling","total_copilot_suggestions":0,"total_copilot_applied_suggestions":1}]}} +``` diff --git a/content/copilot/reference/copilot-usage-metrics/interpret-copilot-metrics.md b/content/copilot/reference/copilot-usage-metrics/interpret-copilot-metrics.md index 95eecdd103ba..ca924ab7a425 100644 --- a/content/copilot/reference/copilot-usage-metrics/interpret-copilot-metrics.md +++ b/content/copilot/reference/copilot-usage-metrics/interpret-copilot-metrics.md @@ -73,5 +73,5 @@ Use trends in usage, feature adoption, and language activity to guide enablement ## Next steps -* To access metrics programmatically, including enterprise, organization, and user-level records, see [AUTOTITLE](/rest/copilot/copilot-usage-metrics). +* To access metrics programmatically, including enterprise, organization, repository, and user-level records, see [AUTOTITLE](/rest/copilot/copilot-usage-metrics). * To construct team-level metrics from the per-user usage metrics report, see [AUTOTITLE](/copilot/reference/copilot-usage-metrics/team-level-metrics). diff --git a/content/copilot/reference/copilot-usage-metrics/reconciling-usage-metrics.md b/content/copilot/reference/copilot-usage-metrics/reconciling-usage-metrics.md index 463681d89343..13e9e4b5045b 100644 --- a/content/copilot/reference/copilot-usage-metrics/reconciling-usage-metrics.md +++ b/content/copilot/reference/copilot-usage-metrics/reconciling-usage-metrics.md @@ -19,8 +19,9 @@ category: The {% data variables.product.prodname_copilot_short %} usage metrics dashboard, APIs, and export files all use the same underlying telemetry data, but they aggregate and present it differently. Understanding these differences helps you reconcile numbers across sources and trust your analysis when preparing internal reports. * The {% data variables.product.prodname_copilot_short %} usage metrics dashboards are available at the **enterprise** and **organization** level. -* The {% data variables.product.prodname_copilot_short %} usage metrics APIs support **enterprise-, organization-, and user-level** records. +* The {% data variables.product.prodname_copilot_short %} usage metrics APIs support **enterprise-, organization-, repository-, and user-level** records. * Team-level totals are not pre-aggregated. They are constructed by joining the user-teams report with the per-user usage metrics report. See [AUTOTITLE](/copilot/reference/copilot-usage-metrics/team-level-metrics). +* Repository-level reports provide daily pull request activity for repositories with activity on the requested day. See [AUTOTITLE](/copilot/reference/copilot-usage-metrics/copilot-usage-metrics#repository-level-fields-api-only). ## Prerequisite diff --git a/content/copilot/reference/hooks-reference.md b/content/copilot/reference/hooks-reference.md index f717c684ddf2..949c769be069 100644 --- a/content/copilot/reference/hooks-reference.md +++ b/content/copilot/reference/hooks-reference.md @@ -471,6 +471,7 @@ Tools with no Claude equivalent keep their runtime names. cwd: string; transcriptPath: string; stopReason: "end_turn"; + stop_hook_active: boolean; // true when this turn was already forced to continue by a prior "block" decision from this hook } ``` @@ -484,6 +485,7 @@ Tools with no Claude equivalent keep their runtime names. cwd: string; transcript_path: string; stop_reason: "end_turn"; + stop_hook_active: boolean; } ``` @@ -620,6 +622,9 @@ The `preToolUse` hook can control tool execution by writing a JSON object to std | `decision` | `"block"`, `"allow"` | `"block"` forces another agent turn using `reason` as the prompt. | | `reason` | string | Prompt for the next turn when `decision` is `"block"`. | +> [!NOTE] +> **Runaway guard.** After 8 consecutive `block` continuations, the CLI overrides the hook and ends the turn anyway, to prevent an unbounded loop. Use the `stop_hook_active` input field on `agentStop` to detect that this turn was already forced to continue, and self-limit before hitting the cap. + ## `postToolUse` output The `postToolUse` hook can modify the tool result or inject additional context for the model by writing a JSON object to stdout. diff --git a/content/enterprise-onboarding/github-apps/automations-in-your-enterprise.md b/content/enterprise-onboarding/github-apps/automations-in-your-enterprise.md deleted file mode 100644 index c597789f9f4c..000000000000 --- a/content/enterprise-onboarding/github-apps/automations-in-your-enterprise.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Automations in your enterprise -shortTitle: Automations -intro: Learn how {% data variables.product.prodname_github_apps %}, external services, and {% data variables.product.prodname_actions %} work together to automate processes in your enterprise. -versions: - ghec: '*' -contentType: concepts -docsTeamMetrics: - - enterprise-onboarding ---- - -{% data reusables.enterprise-onboarding.automations %} - -## Next steps - -To create {% data variables.product.prodname_github_apps %} that can access enterprise-level resources and automate workflows, see [AUTOTITLE](/enterprise-onboarding/github-apps/create-enterprise-apps). diff --git a/content/enterprise-onboarding/github-apps/create-enterprise-apps.md b/content/enterprise-onboarding/github-apps/create-enterprise-apps.md deleted file mode 100644 index 193e78f954a1..000000000000 --- a/content/enterprise-onboarding/github-apps/create-enterprise-apps.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Creating enterprise apps -shortTitle: Create enterprise apps -intro: Create GitHub Apps that can access enterprise-level resources and automate workflows. -versions: - ghec: '*' -contentType: how-tos -docsTeamMetrics: - - enterprise-onboarding ---- - -{% data reusables.enterprise-onboarding.create-enterprise-apps %} - -## Next steps - -If your app uses enterprise permissions, you can install it on your enterprise. See [AUTOTITLE](/enterprise-onboarding/github-apps/install-enterprise-apps). diff --git a/content/enterprise-onboarding/github-apps/index.md b/content/enterprise-onboarding/github-apps/index.md deleted file mode 100644 index deee4ae77fa1..000000000000 --- a/content/enterprise-onboarding/github-apps/index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Automating processes with GitHub Apps -shortTitle: Automate with apps -intro: Automate processes across your enterprise. -versions: - ghec: '*' -children: - - /automations-in-your-enterprise - - /create-enterprise-apps - - /install-enterprise-apps -contentType: concepts -docsTeamMetrics: - - enterprise-onboarding ---- - diff --git a/content/enterprise-onboarding/github-apps/install-enterprise-apps.md b/content/enterprise-onboarding/github-apps/install-enterprise-apps.md deleted file mode 100644 index ef266ea27245..000000000000 --- a/content/enterprise-onboarding/github-apps/install-enterprise-apps.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Installing enterprise apps -shortTitle: Install enterprise apps -intro: Install GitHub Apps to build automations for the enterprise account. -versions: - ghec: '*' -contentType: how-tos -docsTeamMetrics: - - enterprise-onboarding ---- - -{% data reusables.enterprise-onboarding.install-enterprise-apps %} diff --git a/content/enterprise-onboarding/govern-people-and-repositories/about-enterprise-policies.md b/content/enterprise-onboarding/govern-people-and-repositories/about-enterprise-policies.md deleted file mode 100644 index 4a772c51668f..000000000000 --- a/content/enterprise-onboarding/govern-people-and-repositories/about-enterprise-policies.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: About enterprise policies -shortTitle: About enterprise policies -intro: Understand what policies are and why they are useful. -versions: - ghec: '*' -contentType: concepts -docsTeamMetrics: - - enterprise-onboarding ---- - -{% data reusables.enterprise-onboarding.about-policies %} - -You can view the policies available to your enterprise on the **Policies** tab in your enterprise settings. - -## Next steps - -You can apply governance policies to repositories at scale with custom properties. See [AUTOTITLE](/enterprise-onboarding/govern-people-and-repositories/create-custom-properties). diff --git a/content/enterprise-onboarding/govern-people-and-repositories/create-custom-properties.md b/content/enterprise-onboarding/govern-people-and-repositories/create-custom-properties.md deleted file mode 100644 index 454317d1712c..000000000000 --- a/content/enterprise-onboarding/govern-people-and-repositories/create-custom-properties.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Creating custom properties for repositories in your enterprise -shortTitle: Create custom properties -intro: Create and apply custom properties to categorize and manage repositories across your enterprise. -versions: - ghec: '*' -contentType: how-tos -docsTeamMetrics: - - enterprise-onboarding ---- - -{% data reusables.enterprise-onboarding.creating-custom-properties %} - -## Next steps - -Apply policies to repositories based on their custom properties. See [AUTOTITLE](/enterprise-onboarding/govern-people-and-repositories/create-repository-policies). diff --git a/content/enterprise-onboarding/govern-people-and-repositories/index.md b/content/enterprise-onboarding/govern-people-and-repositories/index.md index ea8c8ec6661b..51da6a28942e 100644 --- a/content/enterprise-onboarding/govern-people-and-repositories/index.md +++ b/content/enterprise-onboarding/govern-people-and-repositories/index.md @@ -5,11 +5,8 @@ intro: Implement policies, custom properties, and rulesets to govern users and r versions: ghec: '*' children: - - /about-enterprise-policies - - /create-custom-properties - /create-repository-policies - /protect-branches - - /using-the-audit-log-for-your-enterprise contentType: concepts docsTeamMetrics: - enterprise-onboarding diff --git a/content/enterprise-onboarding/govern-people-and-repositories/using-the-audit-log-for-your-enterprise.md b/content/enterprise-onboarding/govern-people-and-repositories/using-the-audit-log-for-your-enterprise.md deleted file mode 100644 index 624e857eb724..000000000000 --- a/content/enterprise-onboarding/govern-people-and-repositories/using-the-audit-log-for-your-enterprise.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Using the audit log for your enterprise -intro: Use the audit log to monitor activity in your enterprise. -versions: - ghec: '*' -shortTitle: Use the audit log -redirect_from: - - /enterprise-onboarding/feature-enhancements/about-the-audit-log-for-your-enterprise -contentType: concepts -docsTeamMetrics: - - enterprise-onboarding ---- - -{% data reusables.enterprise-onboarding.about-audit-logs %} diff --git a/content/enterprise-onboarding/index.md b/content/enterprise-onboarding/index.md index 0c17233ff213..e0906b0ceb90 100644 --- a/content/enterprise-onboarding/index.md +++ b/content/enterprise-onboarding/index.md @@ -16,38 +16,37 @@ journeyTracks: title: 'Setting up organizations and teams in your enterprise' description: 'Organize work effectively and ensure people have the access they need to resources and administrative settings.' guides: - - href: '/enterprise-onboarding/setting-up-organizations-and-teams/best-practices' + - href: '/admin/concepts/enterprise-best-practices/organize-work' - href: '/enterprise-onboarding/setting-up-organizations-and-teams/setting-up-an-organization' - - href: '/enterprise-onboarding/setting-up-organizations-and-teams/about-roles-in-an-enterprise' - - href: '/enterprise-onboarding/setting-up-organizations-and-teams/identify-role-requirements' - - href: '/enterprise-onboarding/setting-up-organizations-and-teams/creating-custom-roles' - - href: '/enterprise-onboarding/setting-up-organizations-and-teams/about-teams-in-an-enterprise' - - href: '/enterprise-onboarding/setting-up-organizations-and-teams/creating-teams' - - href: '/enterprise-onboarding/setting-up-organizations-and-teams/assigning-roles-to-teams-and-users' - - href: '/enterprise-onboarding/setting-up-organizations-and-teams/use-innersource' + - href: '/admin/concepts/enterprise-fundamentals/roles-in-an-enterprise' + - href: '/admin/managing-accounts-and-repositories/managing-roles-in-your-enterprise/identify-role-requirements' + - href: '/admin/managing-accounts-and-repositories/managing-roles-in-your-enterprise/create-custom-roles' + - href: '/admin/concepts/enterprise-fundamentals/teams-in-an-enterprise' + - href: '/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/create-enterprise-teams' + - href: '/admin/managing-accounts-and-repositories/managing-roles-in-your-enterprise/assign-roles' + - href: '/admin/concepts/enterprise-best-practices/use-innersource' - id: 'govern_people_and_repositories' title: 'Governing people and repositories' description: 'Implement policies, custom properties, and rulesets to govern users and repositories across your enterprise.' guides: - - href: '/enterprise-onboarding/govern-people-and-repositories/about-enterprise-policies' - - href: '/enterprise-onboarding/govern-people-and-repositories/create-custom-properties' + - href: '/admin/concepts/security-and-compliance/enterprise-policies' + - href: '/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/managing-custom-properties-for-repositories-in-your-enterprise' - href: '/enterprise-onboarding/govern-people-and-repositories/create-repository-policies' - href: '/enterprise-onboarding/govern-people-and-repositories/protect-branches' - - href: '/enterprise-onboarding/govern-people-and-repositories/using-the-audit-log-for-your-enterprise' + - href: '/admin/concepts/security-and-compliance/audit-log-for-an-enterprise' - id: 'github_apps' title: 'Automating processes with GitHub Apps' description: 'Create and install apps to automate processes securely in your enterprise and organizations.' guides: - - href: '/enterprise-onboarding/github-apps/automations-in-your-enterprise' - - href: '/enterprise-onboarding/github-apps/create-enterprise-apps' - - href: '/enterprise-onboarding/github-apps/install-enterprise-apps' + - href: '/admin/concepts/enterprise-fundamentals/automations-in-your-enterprise' + - href: '/admin/managing-github-apps-for-your-enterprise/creating-github-apps-for-your-enterprise' + - href: '/apps/using-github-apps/installing-a-github-app-on-your-enterprise' versions: ghec: '*' children: - /getting-started-with-your-enterprise - /setting-up-organizations-and-teams - /govern-people-and-repositories - - /github-apps redirect_from: - /enterprise-onboarding/feature-enhancements docsTeamMetrics: diff --git a/content/enterprise-onboarding/setting-up-organizations-and-teams/about-roles-in-an-enterprise.md b/content/enterprise-onboarding/setting-up-organizations-and-teams/about-roles-in-an-enterprise.md deleted file mode 100644 index 99a6430e1db3..000000000000 --- a/content/enterprise-onboarding/setting-up-organizations-and-teams/about-roles-in-an-enterprise.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: About roles in an enterprise -shortTitle: About roles -intro: Understand the different role types in an enterprise and how they control access and permissions. -versions: - ghec: '*' -redirect_from: - - /enterprise-onboarding/feature-enhancements/about-access-permissions-on-github -contentType: concepts -docsTeamMetrics: - - enterprise-onboarding ---- - -{% data reusables.enterprise-onboarding.about-roles %} - -## Next steps - -Now that you understand roles, plan which roles will be required for your teams to do their jobs on {% data variables.product.github %}. See [AUTOTITLE](/enterprise-onboarding/setting-up-organizations-and-teams/identify-role-requirements). diff --git a/content/enterprise-onboarding/setting-up-organizations-and-teams/about-teams-in-an-enterprise.md b/content/enterprise-onboarding/setting-up-organizations-and-teams/about-teams-in-an-enterprise.md deleted file mode 100644 index 16e189693cd2..000000000000 --- a/content/enterprise-onboarding/setting-up-organizations-and-teams/about-teams-in-an-enterprise.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: About teams in an enterprise -shortTitle: About teams -intro: Discover how teams help organize users, manage repository access, and streamline collaboration across your enterprise. -versions: - ghec: '*' -redirect_from: - - /enterprise-onboarding/setting-up-organizations-and-teams/managing-organization-members -contentType: concepts -docsTeamMetrics: - - enterprise-onboarding ---- - -{% data reusables.enterprise-onboarding.about-teams %} - -## Next steps - -To get started with teams, see [AUTOTITLE](/enterprise-onboarding/setting-up-organizations-and-teams/creating-teams). diff --git a/content/enterprise-onboarding/setting-up-organizations-and-teams/assigning-roles-to-teams-and-users.md b/content/enterprise-onboarding/setting-up-organizations-and-teams/assigning-roles-to-teams-and-users.md deleted file mode 100644 index d2d418789a87..000000000000 --- a/content/enterprise-onboarding/setting-up-organizations-and-teams/assigning-roles-to-teams-and-users.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Assigning roles to teams and users -shortTitle: Assign roles -intro: Assign enterprise roles to manage access and permissions. -versions: - ghec: '*' -contentType: how-tos -docsTeamMetrics: - - enterprise-onboarding ---- - -{% data reusables.enterprise-onboarding.assign-roles %} - -## Next steps - -Learn how to set up a culture of innersource in your enterprise to allow teams to collaborate and work efficiently. See [AUTOTITLE](/enterprise-onboarding/setting-up-organizations-and-teams/use-innersource). diff --git a/content/enterprise-onboarding/setting-up-organizations-and-teams/best-practices.md b/content/enterprise-onboarding/setting-up-organizations-and-teams/best-practices.md deleted file mode 100644 index 34e0bc9a2199..000000000000 --- a/content/enterprise-onboarding/setting-up-organizations-and-teams/best-practices.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Best practices for organizing work in your enterprise -intro: Structure your enterprise and organizations for the best developer experience. -versions: - ghec: '*' -shortTitle: Best practices -redirect_from: - - /enterprise-onboarding/setting-up-organizations-and-teams/best-practices-for-organizations-in-your-enterprise -contentType: how-tos -docsTeamMetrics: - - enterprise-onboarding ---- - -{% data reusables.enterprise-onboarding.best-practices %} - -## Next steps - -Create the organizations you need to divide up work effectively. See [AUTOTITLE](/enterprise-onboarding/setting-up-organizations-and-teams/setting-up-an-organization). diff --git a/content/enterprise-onboarding/setting-up-organizations-and-teams/creating-custom-roles.md b/content/enterprise-onboarding/setting-up-organizations-and-teams/creating-custom-roles.md deleted file mode 100644 index 6b07613cdf8f..000000000000 --- a/content/enterprise-onboarding/setting-up-organizations-and-teams/creating-custom-roles.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Creating custom roles -shortTitle: Create custom roles -intro: Create custom organization roles with fine-grained permissions tailored to your enterprise needs. -versions: - ghec: '*' -contentType: how-tos -docsTeamMetrics: - - enterprise-onboarding ---- - -{% data reusables.enterprise-onboarding.create-custom-roles %} - -## Next steps - -You can manage role assignments at scale using teams. Learn about teams in your enterprise and organizations in [AUTOTITLE](/enterprise-onboarding/setting-up-organizations-and-teams/about-teams-in-an-enterprise). diff --git a/content/enterprise-onboarding/setting-up-organizations-and-teams/creating-teams.md b/content/enterprise-onboarding/setting-up-organizations-and-teams/creating-teams.md deleted file mode 100644 index 8e0b17bd7297..000000000000 --- a/content/enterprise-onboarding/setting-up-organizations-and-teams/creating-teams.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Creating enterprise teams -intro: Use teams to manage permissions and access. -versions: - ghec: '*' -shortTitle: Create teams -permissions: Enterprise owners or organization owners -allowTitleToDifferFromFilename: true -contentType: how-tos -docsTeamMetrics: - - enterprise-onboarding ---- - -{% data reusables.enterprise-onboarding.create-enterprise-teams %} - -## Next steps - -Next, assign roles to teams to manage their access to settings and resources. See [AUTOTITLE](/enterprise-onboarding/setting-up-organizations-and-teams/assigning-roles-to-teams-and-users). diff --git a/content/enterprise-onboarding/setting-up-organizations-and-teams/identify-role-requirements.md b/content/enterprise-onboarding/setting-up-organizations-and-teams/identify-role-requirements.md deleted file mode 100644 index e285c59dca31..000000000000 --- a/content/enterprise-onboarding/setting-up-organizations-and-teams/identify-role-requirements.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Identifying the roles required by your enterprise -intro: Use teams to manage permissions, notifications, and code ownership in your organizations. -versions: - ghec: '*' -shortTitle: Identify role requirements -contentType: how-tos -docsTeamMetrics: - - enterprise-onboarding ---- - -{% data reusables.enterprise-onboarding.identify-role-requirements %} - -## Next steps - -Now that you've planned which roles will help your teams be productive and secure on GitHub, create custom roles for the permissions you need. Later, you will create teams to manage role assignments at scale. [AUTOTITLE](/enterprise-onboarding/setting-up-organizations-and-teams/creating-custom-roles). diff --git a/content/enterprise-onboarding/setting-up-organizations-and-teams/index.md b/content/enterprise-onboarding/setting-up-organizations-and-teams/index.md index 50eff93e503e..1b897ca84b39 100644 --- a/content/enterprise-onboarding/setting-up-organizations-and-teams/index.md +++ b/content/enterprise-onboarding/setting-up-organizations-and-teams/index.md @@ -5,15 +5,7 @@ versions: ghec: '*' shortTitle: Set up organizations and teams children: - - /best-practices - /setting-up-an-organization - - /about-roles-in-an-enterprise - - /identify-role-requirements - - /creating-custom-roles - - /about-teams-in-an-enterprise - - /creating-teams - - /assigning-roles-to-teams-and-users - - /use-innersource docsTeamMetrics: - enterprise-onboarding --- diff --git a/content/enterprise-onboarding/setting-up-organizations-and-teams/use-innersource.md b/content/enterprise-onboarding/setting-up-organizations-and-teams/use-innersource.md deleted file mode 100644 index 92eecb7b719e..000000000000 --- a/content/enterprise-onboarding/setting-up-organizations-and-teams/use-innersource.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Using innersource in your enterprise -shortTitle: Use innersource -intro: Help dispersed teams to collaborate by setting up open source–style workflows in your enterprise, without compromising on security. -versions: - ghec: '*' -contentType: concepts -allowTitleToDifferFromFilename: true -docsTeamMetrics: - - enterprise-onboarding ---- - -{% data reusables.enterprise-onboarding.use-innersource %} - -## Next steps - -Now that you've set up organizations and teams, learn how to stay compliant and secure by setting up governance policies for your users and repositories. See [AUTOTITLE](/enterprise-onboarding/govern-people-and-repositories/about-enterprise-policies). diff --git a/content/index.md b/content/index.md index 6fa6f3010d9c..c0d2da00db54 100644 --- a/content/index.md +++ b/content/index.md @@ -7,7 +7,7 @@ featuredLinks: - /repositories/creating-and-managing-repositories - /get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax popular: - - /pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests + - /pull-requests/reference/pull-requests - /authentication - /copilot/how-tos/get-code-suggestions/get-ide-code-suggestions - /get-started/git-basics/managing-remote-repositories @@ -84,7 +84,6 @@ children: - desktop - early-access - support - - contributing - github-models - nonprofit @@ -179,21 +178,22 @@ externalProducts: electron: id: electron name: Electron - href: 'https://electronjs.org/docs/latest' + href: https://electronjs.org/docs/latest external: true codeql: id: codeql name: CodeQL query writing - href: 'https://codeql.github.com/docs' + href: https://codeql.github.com/docs external: true npm: id: npm name: npm - href: 'https://docs.npmjs.com/' + href: https://docs.npmjs.com/ external: true gh-wa: id: gh-wa name: GitHub Well-Architected - href: 'https://wellarchitected.github.com/' + href: https://wellarchitected.github.com/ external: true --- + diff --git a/content/nonprofit/index.md b/content/nonprofit/index.md index 2e5436185d0f..4a6a1d804669 100644 --- a/content/nonprofit/index.md +++ b/content/nonprofit/index.md @@ -10,6 +10,7 @@ layout: discovery-landing includedCategories: - Apply for nonprofit benefits - Contribute to open source for good + - Submit a project for volunteer pods carousels: recommended: - /nonprofit/quickstart @@ -17,7 +18,7 @@ carousels: - /nonprofit/nonprofit-enterprise-plan/getting-started-with-discounted-github-enterprise-cloud - /nonprofit/troubleshooting/frequently-asked-questions - /nonprofit/contributing-to-open-source-for-good/contributing-to-an-open-source-for-good-project - - /nonprofit/contributing-to-open-source-for-good/adding-an-open-source-project + - /nonprofit/project-pods versions: fpt: '*' children: @@ -25,6 +26,7 @@ children: - /nonprofit-teams-plan - /nonprofit-enterprise-plan - /contributing-to-open-source-for-good + - /project-pods - /troubleshooting --- diff --git a/content/nonprofit/project-pods/creating-a-volunteering-project.md b/content/nonprofit/project-pods/creating-a-volunteering-project.md new file mode 100644 index 000000000000..8eeead2a0b3a --- /dev/null +++ b/content/nonprofit/project-pods/creating-a-volunteering-project.md @@ -0,0 +1,137 @@ +--- +title: Creating a Project Pod for volunteer groups +allowTitleToDifferFromFilename: true +shortTitle: Submit a project for a volunteer pod +intro: 'Learn how to submit a skills-based volunteering project for your nonprofit organization in Project Pods.' +product: "GitHub for Nonprofits" +contentType: tutorials +versions: + fpt: '*' +--- + +## Introduction + +Project Pods is a collaborative space where verified nonprofits can publish short-term, skills-based open source projects and small volunteer groups can team up to build meaningful solutions. The projects will then appear on [For Good First Issue](https://forgoodfirstissue.github.com/) in the "For Teams" section. + +Project Pods are designed for teams, companies, and community circles looking for mission-driven projects that need real technical support on an end to end engagement. Each Pod includes a curated project issue with a clear impact goal, and all the context a group needs to start contributing quickly. + +In this guide, you'll learn how to prepare and submit a project for your nonprofit, what to expect during the review process, and how to set your project up for successful volunteer engagement. + +## Prerequisites + +Before you submit a project, make sure: + +* Your nonprofit is a verified member of **GitHub for Nonprofits**. If you haven't joined yet, see [AUTOTITLE](/nonprofit/quickstart) to apply. +* You have a clear project scope that can be completed by a small team within a defined timeframe. +* You have a GitHub repository (or are ready to create one) where volunteers will contribute. + +> [!NOTE] +> Organizations that are not part of GitHub for Nonprofits can still add individual issues to the For Good First Issue list, but Project Pods are exclusively available to verified nonprofits. + +## Understanding Project Pods + +A Project Pod is a structured volunteering engagement with the following characteristics: + +* Small team: Typically 1 to 20 volunteers to ensure focus and effective collaboration. +* Volunteers contribute their technical, design, or project management skills to solve real problems with a clear end outcome. +* Impact-oriented: Projects address tangible challenges defined by your organization with a tangible deliverable. +* Short-term: Designed to be completed within a defined timeframe for a day, a week, or a number of sprints. +* Collaborative: Pods work together in an open source environment using tools for coordination and contribution. + +## Step 1: Prepare your project + +Before filling out the intake form, gather the following information about your project. The more context you provide, the easier it is for volunteer teams to understand your needs and start contributing. + +### Define the problem + +Write a clear description of the problem your project addresses. Explain why it matters to your nonprofit and the communities you serve. Volunteers are more likely to engage with projects where they can see the real-world impact of their contribution. + +### Identify deliverables and outcomes + +Define what "project done" looks like. Examples: + +* "A working data dashboard that visualizes clean water access by region" +* "An updated documentation site with multilingual support in a low resourced region" +* "A mobile responsive redesign of our donation page" + +Specific deliverables help volunteer teams scope their work and stay focused. + +### List the skills you need + +Identify the types of skills your project requires. These may include: + +* Software development (specify languages and frameworks) +* UX/UI design +* Documentation and technical writing +* Data analysis +* Project management + +### Specify the technology and tools + +List the programming languages, frameworks, platforms, and tools used in your project. This helps volunteer teams assess whether the project matches their skill set. + +### Estimate the time commitment + +Project Pods are designed for short-term engagement. Indicate whether your project is: + +* A **1-day sprint** — focused tasks that can be completed in a single working session +* A **1-week project** — a set of related tasks spanning several days +* An **ongoing short-term engagement** — recurring tasks over a few weeks with a clear end date + +### Prepare your repository + +Your GitHub repository is where volunteers will work. Before submitting, make sure it includes: + +* A **README** that explains the project, its purpose, and how to get started +* A **CONTRIBUTING** file with guidelines for how to contribute +* Any supporting files such as design mockups, architecture diagrams, or project briefs +* Use labels **Project Complete**, **Project Claimed**, **Project Open for Volunteers** for your Project Issue + +If you don't have an existing repository, you can create one and link to it in your submission. You can also link to external documentation or assets. + +## Step 2: Submit the Project Intake Form + +1. Go to [GitHub for Nonprofits](https://github.com/solutions/industry/nonprofits) +1. Select the approved nonprofit GitHub Organization the project will support +1. If you haven't joined yet, see [AUTOTITLE](/nonprofit/quickstart) to apply. +1. Under 'Request Volunteer Developers' section, select **Create Volunteer Request** +1. Complete the intake form with the information you prepared: + + | Field | What to provide | + | --- | --- | + | **About Your Nonprofit** | Description of your nonprofit's mission and the technologies you use. | + | **Project Request** | What problem does this project address? Why is it important to your nonprofit and the people you serve? | + | **Describe the development work needed** | Describe the project deliverables and outcomes. What do you hope to achieve? Be specific on the outcome. Include the skills needed such as software development, UX/UI design, documentation, data analysis, project management, etc. | + | **Primary programming language/technology** | Programming languages, frameworks, platforms. | + | **Number of Volunteers Needed** | Typically 3 to 20 per Pod. | + | **Organization website** | Link to your organization's repository or website. | + | **Project Issue Link** | Share the project link where additional details of your project. Ensure the issue is labeled with **Project Complete**, **Project Claimed**, **Project Open for Volunteers** | + +1. Click **Submit Request** to send your project for review. + +## Step 3: Review process + +After you submit your project, the GitHub Social Impact team will review it. Here's what to expect: + +* **If accepted**: Your project will be listed on the Project Pods page on For Good First Issue, where corporations, community groups, and individual volunteer teams can discover and sign up for it. GitHub Social Impact will support sharing the project with volunteers. +* **If revisions are needed**: You'll receive constructive feedback on how to improve your project for resubmission. Common reasons for revision requests include: + * Unclear goals or deliverables + * Lack of defined tasks or issues in the repository + * Insufficient information about required skills or technology + +> [!NOTE] +> A revision request does not mean your idea is not valuable. It means adjustments will help volunteers engage more effectively. You are welcome to revise and resubmit at any time. + +## Step 4: Working with your volunteer Pod + +Once your project is listed and a volunteer team picks it up by submitting a comment on the issue. All contributions remain open source in your repository for ongoing use. + +### Communication + +Pods work together in an open source environment using your GitHub repository as the primary workspace. Volunteers will interact through issues, pull requests, and discussions in your repository. + +### Your role as project owner + +* Be responsive: Answer questions in issues and review pull requests in a timely manner. Volunteers are donating their time — quick feedback keeps them engaged. +* Provide context: If volunteers ask about your mission or the people you serve, share what you can. Understanding the impact motivates better work. +* Scope changes clearly: If priorities shift during the engagement, update the issues and communicate with the team. diff --git a/content/nonprofit/project-pods/frequently-asked-questions.md b/content/nonprofit/project-pods/frequently-asked-questions.md new file mode 100644 index 000000000000..ca4053cf0eba --- /dev/null +++ b/content/nonprofit/project-pods/frequently-asked-questions.md @@ -0,0 +1,90 @@ +--- +title: Frequently asked questions +intro: 'Find answers to common questions about submitting, joining, and participating in Project Pods.' +versions: + fpt: '*' +shortTitle: Frequently asked questions +category: + - Submit a project for volunteer pods +--- +## For nonprofits + +### Who can submit a project? + +Any verified nonprofit that is part of the [GitHub for Nonprofits](https://nonprofits.github.com/) program. Your organization must be a 501(c)(3) or equivalent nonprofit that is nongovernmental, nonacademic, noncommercial, and nonpolitical in nature. If you haven't joined yet, see [AUTOTITLE](/nonprofit/quickstart) to apply. + +### What kinds of projects are a good fit for Project Pods? + +Projects that have a clear problem, defined deliverables, and can be completed by a small team in a short timeframe. Examples include building a data dashboard, redesigning a website for accessibility, setting up CI/CD pipelines, creating documentation, or developing a new feature for an existing open source tool. The best projects are ones where a volunteer team can make meaningful progress without needing months of onboarding. The more context you provide, the faster volunteer teams can start contributing. At minimum, include a clear problem statement, specific deliverables, the skills and technologies involved, and an estimated time commitment. Projects with well-labeled issues, a contributing guide, and a descriptive README attract volunteers faster. + +### What kinds of projects are not a good fit? + +Projects that require long-term, ongoing maintenance with no clear end point, projects that involve sensitive or proprietary data that can't be shared in an open source repository, or projects that need a single specialized expert rather than a collaborative team. If your project doesn't fit the Pod model, you can still list individual issues on [For Good First Issue](https://forgoodfirstissue.github.com/) for solo contributors. + +### What happens after we submit? + +The GitHub Social Impact team reviews your submission. If accepted, your project is listed on the Project Pods page for volunteer teams to discover. If revisions are needed, you'll receive specific feedback on what to adjust. You can revise and resubmit at any time. + +### Why would a project submission be sent back for revisions? + +Common reasons include unclear goals or deliverables, lack of defined tasks or issues in the repository, or insufficient information about required skills and technology. A revision request means your project needs a few adjustments before it is ready for volunteer teams to pick up. Ensure that project details are specific enough for a team to act on, your repository includes a README and contributing guide, and issues are labeled and scoped for contributors. You are welcome to revise and resubmit at any time. + +### How long does the review process take? + +Reviews are typically completed within two weeks. You'll receive an email notification when your project has been reviewed. + +### How are volunteers matched to our project? + +Once your project is approved, it's listed on the Project Pods page where volunteer teams browse available projects and choose ones that fit their skills and interests. Each listing shows the skills needed, technology stack, and time commitment so teams can self-select. Volunteers join as a group, through a corporate team running a volunteer day, a coding bootcamp cohort, or a community circle looking for a project. Groups then respond to the project issue to be connected for a project kickoff. + +### Are there any costs for nonprofits? + +No. Participation in Project Pods is completely free. + +### What is our role once volunteers start working? + +You are the project owner. Your primary responsibilities are to select the project volunteer team, answer questions in issues and pull requests, review contributions in a timely manner, and provide context about your mission and the mission you serve. Volunteers are donating their time, so responsive communication keeps them engaged and productive. + +### What if the volunteer team doesn't finish the project? + +Project Pods are short-term engagements. If additional work remains, you can extend the project timeline, recruit another Pod, or continue the work internally. All contributions stay in your repository for ongoing use. + +### Can we submit more than one project? + +Yes. You can submit multiple projects. Each one goes through the same review process and is listed independently on the Project Pods page. + +### What if we don't have a full project yet? + +If your organization has individual tasks or issues that could use a contributor but you're not ready to scope a full team-based project, you can list them directly on [For Good First Issue](https://forgoodfirstissue.github.com/). Add your repository and label issues with 'good first issue' or 'help wanted'. Individual developers browsing the site can discover and pick them up on their own. When you're ready to scope a larger project for a team, come back and submit a Project Pod. + +--- + +## For volunteers and teams + +### Who can join a Project Pod? + +Anyone. Corporate volunteer teams, coding bootcamp cohorts, university groups, community circles, or a group of friends. You don't need to be part of a specific organization to participate. + +### How do we find a project to work on? + +Visit the [For Good First Issue Project Pods](https://forgoodfirstissue.github.com/) page and browse listed projects. Each listing includes the problem description, skills needed, technology stack, estimated time commitment, and a link to the GitHub repository. + +### How are volunteers matched to projects? + +There's no formal matching process. Volunteer teams browse available projects and choose ones that align with their skills and interests by replying to the Project Pod issue. + +### What is the typical time commitment? + +It varies by project. Some Pods are designed for a single-day sprint, others span a week, and some involve short-term tasks over a few weeks. Each project listing specifies the estimated time commitment. + +### What if we can't finish the project? + +Communicate with the nonprofit project owner. Let them know what you've completed, what remains, and any context that would help the next team pick up where you left off. All contributions are valuable, even partial ones. Open source means someone else can continue the work. + +### Is there any cost to participate? + +No. Project Pods are completely free for volunteers. + +### Can our company use Project Pods for a corporate volunteer event? + +Yes. Project Pods are designed for exactly this use case. A corporate team can browse available projects, select one that fits their team size and skill set, and complete it during a volunteer day, hackathon, or sprint. Each project listing provides all the context your team needs to get started. diff --git a/content/nonprofit/project-pods/index.md b/content/nonprofit/project-pods/index.md new file mode 100644 index 000000000000..77ed54303584 --- /dev/null +++ b/content/nonprofit/project-pods/index.md @@ -0,0 +1,12 @@ +--- +title: Creating a Project Pod for volunteer groups +allowTitleToDifferFromFilename: true +intro: Learn how to submit a skills-based volunteering project for your nonprofit organization in Project Pods. +versions: + fpt: '*' +shortTitle: Connect your project with developers +children: + - /creating-a-volunteering-project + - /frequently-asked-questions +--- + diff --git a/content/nonprofit/quickstart.md b/content/nonprofit/quickstart.md index 3b8d759ab463..b21a95788826 100644 --- a/content/nonprofit/quickstart.md +++ b/content/nonprofit/quickstart.md @@ -24,6 +24,7 @@ In this guide, you’ll get started with GitHub and sign up for accounts and dis ### Creating a free personal account {% data reusables.accounts.create-account %} + 1. Follow the prompts to create your free personal account. ### Creating an organization @@ -31,6 +32,7 @@ In this guide, you’ll get started with GitHub and sign up for accounts and dis {% data reusables.user-settings.access_settings %} {% data reusables.user-settings.organizations %} {% data reusables.organizations.new-organization %} + 1. Follow the prompts to create a free organization. For more information, see [Get Started](/get-started/learning-about-github/types-of-github-accounts). diff --git a/content/organizations/managing-organization-settings/renaming-an-organization.md b/content/organizations/managing-organization-settings/renaming-an-organization.md index 6937d1208a65..a9608062624f 100644 --- a/content/organizations/managing-organization-settings/renaming-an-organization.md +++ b/content/organizations/managing-organization-settings/renaming-an-organization.md @@ -47,4 +47,4 @@ After changing your organization's name: ## Further reading -* [AUTOTITLE](/pull-requests/committing-changes-to-your-project/troubleshooting-commits/why-are-my-commits-linked-to-the-wrong-user) +* [AUTOTITLE](/pull-requests/committing-changes-to-your-project/troubleshooting-commits#commits-are-linked-to-the-wrong-user) diff --git a/content/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/about-merge-conflicts.md b/content/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/about-merge-conflicts.md deleted file mode 100644 index 5c8e957d6d78..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/about-merge-conflicts.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: About merge conflicts -intro: 'Merge conflicts happen when you merge branches that have competing commits, and Git needs your help to decide which changes to incorporate in the final merge.' -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/addressing-merge-conflicts/about-merge-conflicts - - /articles/about-merge-conflicts - - /github/collaborating-with-issues-and-pull-requests/about-merge-conflicts - - /github/about-merge-conflicts - - /github/collaborating-with-pull-requests/addressing-merge-conflicts/about-merge-conflicts -versions: - fpt: '*' - ghec: '*' - ghes: '*' -category: - - Merge and close pull requests ---- -Git can often resolve differences between branches and merge them automatically. Usually, the changes are on different lines, or even in different files, which makes the merge simple for computers to understand. However, sometimes there are competing changes that Git can't resolve without your help. Often, merge conflicts happen when people make different changes to the same line of the same file, or when one person edits a file and another person deletes the same file. - -You must resolve all merge conflicts before you can merge a pull request on {% data variables.product.github %}. If you have a merge conflict between the compare branch and base branch in your pull request, you can view a list of the files with conflicting changes above the **Merge pull request** button. The **Merge pull request** button is deactivated until you've resolved all conflicts between the compare branch and base branch. - -## Resolving merge conflicts - -To resolve a merge conflict, you must manually edit the conflicted file to select the changes that you want to keep in the final merge. There are a couple of different ways to resolve a merge conflict: - -* If your merge conflict is caused by competing line changes, such as when people make different changes to the same line of the same file on different branches in your Git repository, you can resolve it on {% data variables.product.github %} using the conflict editor. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-on-github). -* For all other types of merge conflicts, you must resolve the merge conflict in a local clone of the repository and push the change to your branch on {% data variables.product.github %}. You can use the command line or a tool like [{% data variables.product.prodname_desktop %}](https://desktop.github.com/) to push the change. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-using-the-command-line). -{% ifversion copilot %} -* For any type of merge conflict, if you have access to {% data variables.copilot.copilot_cloud_agent %} and it is enabled for the repository, you can click **Fix with {% data variables.product.prodname_copilot_short %}** in the merge box to have {% data variables.product.prodname_copilot_short %} resolve the conflicts for you. {% data variables.product.prodname_copilot_short %} will analyze the conflicting changes, resolve the conflicts, and verify that the build, tests, and linter still pass. For more information, see [AUTOTITLE](/copilot/how-tos/use-copilot-agents/cloud-agent/make-changes-to-an-existing-pr#resolving-merge-conflicts). -{% endif %} - -If you have a merge conflict on the command line, you cannot push your local changes to {% data variables.product.github %} until you resolve the merge conflict locally on your computer. If you try merging branches on the command line that have a merge conflict, you'll get an error message. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-using-the-command-line). - -```shell -$ git merge BRANCH-NAME -> Auto-merging styleguide.md -> CONFLICT (content): Merge conflict in styleguide.md -> Automatic merge failed; fix conflicts and then commit the result -``` - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-using-the-command-line) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-on-github) diff --git a/content/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/index.md b/content/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/index.md deleted file mode 100644 index 137bb43795fc..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/index.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Addressing merge conflicts -intro: 'If your changes have merge conflicts with the base branch, you must address the merge conflicts before you can merge your pull request''s changes.' -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/addressing-merge-conflicts - - /articles/addressing-merge-conflicts - - /github/collaborating-with-pull-requests/addressing-merge-conflicts -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /about-merge-conflicts - - /resolving-a-merge-conflict-on-github - - /resolving-a-merge-conflict-using-the-command-line -shortTitle: Address merge conflicts ---- - diff --git a/content/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-on-github.md b/content/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-on-github.md deleted file mode 100644 index bce9af325e09..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-on-github.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: Resolving a merge conflict on GitHub -intro: 'You can resolve simple merge conflicts that involve competing line changes on GitHub, using the conflict editor.' -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-on-github - - /articles/resolving-a-merge-conflict-on-github - - /github/collaborating-with-issues-and-pull-requests/resolving-a-merge-conflict-on-github - - /github/resolving-a-merge-conflict-on-github - - /github/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-on-github -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Resolve merge conflicts -category: - - Merge and close pull requests ---- -You can only resolve merge conflicts on {% data variables.product.github %} that are caused by competing line changes, such as when people make different changes to the same line of the same file on different branches in your Git repository. For all other types of merge conflicts, you must resolve the conflict locally on the command line. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-using-the-command-line). - -{% ifversion copilot %} - -If you have access to {% data variables.copilot.copilot_cloud_agent %} and it is enabled for the repository, you can click **Fix with {% data variables.product.prodname_copilot_short %}** in the merge box to have {% data variables.product.prodname_copilot_short %} resolve the merge conflicts automatically. {% data variables.product.prodname_copilot_short %} will analyze the conflicting changes, resolve the conflicts, and verify that the build, tests, and linter still pass. For more information, see [AUTOTITLE](/copilot/how-tos/use-copilot-agents/cloud-agent/make-changes-to-an-existing-pr#resolving-merge-conflicts). - -{% endif %} - -{% ifversion ghes %} -If a site administrator disables the merge conflict editor for pull requests between repositories, you cannot use the conflict editor on {% data variables.product.prodname_ghe_server %} and must resolve merge conflicts on the command line. For example, if the merge conflict editor is disabled, you cannot use it on a pull request between a fork and upstream repository. -{% endif %} - -> [!WARNING] -> When you resolve a merge conflict on {% data variables.product.github %}, the entire [base branch](/get-started/learning-about-github/github-glossary#base-branch) of your pull request is merged into the [head branch](/get-started/learning-about-github/github-glossary#head-branch). Make sure you really want to commit to this branch. If the head branch is the default branch of your repository, you'll be given the option of creating a new branch to serve as the head branch for your pull request. If the head branch is protected you won't be able to merge your conflict resolution into it, so you'll be prompted to create a new head branch. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches). - -{% data reusables.repositories.sidebar-pr %} -1. In the "Pull Requests" list, click the pull request with a merge conflict that you'd like to resolve. -1. Near the bottom of your pull request, click **Resolve conflicts**. - - ![Screenshot of a warning that a pull request has a merge conflict. The "Resolve merge conflicts" button is outlined in dark orange.](/assets/images/help/pull_requests/resolve-merge-conflicts-button.png) - - > [!NOTE] - > If the **Resolve conflicts** button is deactivated, your pull request's merge conflict is too complex to resolve on {% data variables.product.github %}{% ifversion ghes %} or the site administrator has disabled the conflict editor for pull requests between repositories{% endif %}. You must resolve the merge conflict using an alternative Git client, or by using Git on the command line. For more information see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-using-the-command-line). - -{% data reusables.pull_requests.decide-how-to-resolve-competing-line-change-merge-conflict %} -1. If you have more than one merge conflict in your file, scroll down to the next set of conflict markers and repeat steps four and five to resolve your merge conflict. -1. Once you've resolved all the conflicts in the file, click **Mark as resolved**. - - ![Screenshot of the editor to resolve a merge conflict in a pull request. The "Mark as resolved" button is outlined in dark orange.](/assets/images/help/pull_requests/mark-as-resolved-button.png) - -1. If you have more than one file with a conflict, select the next file you want to edit on the left side of the page under "conflicting files" and repeat steps four through seven until you've resolved all of your pull request's merge conflicts. -1. Once you've resolved all your merge conflicts, click **Commit merge**. This merges the entire base branch into your head branch. - - ![Screenshot of the editor to resolve a merge conflict in a pull request. The "Commit merge" button is outlined in dark orange.](/assets/images/help/pull_requests/merge-conflict-commit-changes.png) - -1. If prompted, review the branch that you are committing to. - - If the head branch is the default branch of the repository, you can choose either to update this branch with the changes you made to resolve the conflict, or to create a new branch and use this as the head branch of the pull request. - - If you choose to create a new branch, enter a name for the branch. - - If the head branch of your pull request is protected you must create a new branch. You won't get the option to update the protected branch. - - Click **Create branch and update my pull request** or **I understand, continue updating BRANCH**. The button text corresponds to the action you are performing. -1. To merge your pull request, click **Merge pull request**. For more information about other pull request merge options, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request). - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges) diff --git a/content/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-using-the-command-line.md b/content/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-using-the-command-line.md deleted file mode 100644 index f7d9e9aa5c88..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-using-the-command-line.md +++ /dev/null @@ -1,145 +0,0 @@ ---- -title: Resolving a merge conflict using the command line -intro: You can resolve merge conflicts using the command line and a text editor. -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-using-the-command-line - - /articles/resolving-a-merge-conflict-from-the-command-line - - /articles/resolving-a-merge-conflict-using-the-command-line - - /github/collaborating-with-issues-and-pull-requests/resolving-a-merge-conflict-using-the-command-line - - /github/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-using-the-command-line -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Resolve merge conflicts in Git -category: - - Merge and close pull requests ---- -Merge conflicts occur when competing changes are made to the same line of a file, or when one person edits a file and another person deletes the same file. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/about-merge-conflicts). - -> [!TIP] -> You can use the conflict editor on {% data variables.product.github %} to resolve competing line change merge conflicts between branches that are part of a pull request. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-on-github). - -## Competing line change merge conflicts - -To resolve a merge conflict caused by competing line changes, you must choose which changes to incorporate from the different branches in a new commit. - -For example, if you and another person both edited the file `styleguide.md` on the same lines in different branches of the same Git repository, you'll get a merge conflict error when you try to merge these branches. You must resolve this merge conflict with a new commit before you can merge these branches. - -{% data reusables.command_line.open_the_multi_os_terminal %} -1. Navigate into the local Git repository that has the merge conflict. - - ```shell - cd REPOSITORY-NAME - ``` - -1. Generate a list of the files affected by the merge conflict. In this example, the file _styleguide.md_ has a merge conflict. - - ```shell - $ git status - > # On branch branch-b - > # You have unmerged paths. - > # (fix conflicts and run "git commit") - > # - > # Unmerged paths: - > # (use "git add ..." to mark resolution) - > # - > # both modified: styleguide.md - > # - > no changes added to commit (use "git add" and/or "git commit -a") - ``` - -1. Open your favorite text editor, such as [{% data variables.product.prodname_vscode %}](https://code.visualstudio.com/), and navigate to the file that has merge conflicts. -1. To see the beginning of the merge conflict in your file, search the file for the conflict marker `<<<<<<<`. When you open the file in your text editor, you'll see the changes from the HEAD or base branch after the line `<<<<<<< HEAD`. Next, you'll see `=======`, which divides your changes from the changes in the other branch, followed by `>>>>>>> BRANCH-NAME`. In this example, one person wrote "open an issue" in the base or HEAD branch and another person wrote "ask your question in IRC" in the compare branch or `branch-a`. - - ```text - If you have questions, please - <<<<<<< HEAD - open an issue - ======= - ask your question in IRC. - >>>>>>> branch-a - ``` - -{% data reusables.pull_requests.decide-how-to-resolve-competing-line-change-merge-conflict %} In this example, both changes are incorporated into the final merge: - - ```shell - If you have questions, please open an issue or ask in our IRC channel if it's more urgent. - ``` - -1. Add or stage your changes. - - ```shell - git add . - ``` - -1. Commit your changes with a comment. - - ```shell - git commit -m "Resolve merge conflict by incorporating both suggestions" - ``` - -You can now merge the branches on the command line or [push your changes to your remote repository](/get-started/using-git/pushing-commits-to-a-remote-repository) on {% data variables.product.github %} and [merge your changes](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request) in a pull request. - -## Removed file merge conflicts - -To resolve a merge conflict caused by competing changes to a file, where a person deletes a file in one branch and another person edits the same file, you must choose whether to delete or keep the removed file in a new commit. - -For example, if you edited a file, such as `README.md`, and another person removed the same file in another branch in the same Git repository, you'll get a merge conflict error when you try to merge these branches. You must resolve this merge conflict with a new commit before you can merge these branches. - -{% data reusables.command_line.open_the_multi_os_terminal %} -1. Navigate into the local Git repository that has the merge conflict. - - ```shell - cd REPOSITORY-NAME - ``` - -1. Generate a list of the files affected by the merge conflict. In this example, the file `README.md` has a merge conflict. - - ```shell - $ git status - > # On branch main - > # Your branch and 'origin/main' have diverged, - > # and have 1 and 2 different commits each, respectively. - > # (use "git pull" to merge the remote branch into yours) - > # You have unmerged paths. - > # (fix conflicts and run "git commit") - > # - > # Unmerged paths: - > # (use "git add/rm ..." as appropriate to mark resolution) - > # - > # deleted by us: README.md - > # - > # no changes added to commit (use "git add" and/or "git commit -a") - ``` - -1. Open your favorite text editor, such as [{% data variables.product.prodname_vscode %}](https://code.visualstudio.com/), and navigate to the file that has merge conflicts. -1. Decide if you want to keep the removed file. You may want to view the latest changes made to the removed file in your text editor. - - To add the removed file back to your repository: - - ```shell - git add README.md - ``` - - To remove this file from your repository: - - ```shell - $ git rm README.md - > README.md: needs merge - > rm 'README.md' - ``` - -1. Commit your changes with a comment. - - ```shell - $ git commit -m "Resolve merge conflict by keeping README.md file" - > [branch-d 6f89e49] Merge branch 'branch-c' into branch-d - ``` - -You can now merge the branches on the command line or [push your changes to your remote repository](/get-started/using-git/pushing-commits-to-a-remote-repository) on {% data variables.product.github %} and [merge your changes](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request) in a pull request. - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/about-merge-conflicts) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/checking-out-pull-requests-locally) diff --git a/content/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/index.md b/content/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/index.md deleted file mode 100644 index 858faff8bb41..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/index.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Collaborating on repositories with code quality features -intro: 'Workflow quality features like statuses, {% ifversion ghes %}pre-receive hooks, {% endif %}protected branches, and required status checks help collaborators make contributions that meet conditions set by organization and repository administrators.' -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/collaborating-on-repositories-with-code-quality-features - - /articles/collaborating-on-repositories-with-code-quality-features-enabled - - /articles/collaborating-on-repositories-with-code-quality-features - - /github/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /about-status-checks - - /troubleshooting-required-status-checks - - /working-with-pre-receive-hooks -shortTitle: Code quality features ---- diff --git a/content/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/troubleshooting-required-status-checks.md b/content/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/troubleshooting-required-status-checks.md deleted file mode 100644 index 8ea2fc31d185..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/troubleshooting-required-status-checks.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -title: Troubleshooting required status checks -intro: You can check for common errors and resolve issues with required status checks. -product: '{% data reusables.gated-features.protected-branches %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /github/administering-a-repository/troubleshooting-required-status-checks - - /github/administering-a-repository/defining-the-mergeability-of-pull-requests/troubleshooting-required-status-checks - - /repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/troubleshooting-required-status-checks -shortTitle: Required status checks -category: - - Merge and close pull requests ---- -If you have a check and a status with the same name, and you select that name as a required status check, both the check and the status are required. For more information, see [AUTOTITLE](/rest/checks). - -> [!NOTE] -> To be required, status checks must have completed successfully within the chosen repository during the past seven days. - -After you enable required status checks, your branch may need to be up-to-date with the base branch before merging. This ensures that your branch has been tested with the latest code from the base branch. If your branch is out of date, you'll need to merge the base branch into your branch. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-status-checks-before-merging). - -> [!NOTE] -> You can also bring your branch up to date with the base branch using Git rebase. For more information, see [AUTOTITLE](/get-started/using-git/about-git-rebase). - -You won't be able to push local changes to a protected branch until all required status checks pass. Instead, you'll receive an error message similar to the following. - -```shell -remote: error: GH006: Protected branch update failed for refs/heads/main. -remote: error: Required status check "ci-build" is failing -``` - -> [!NOTE] -> Pull requests that are up-to-date and pass required status checks can be merged locally and pushed to the protected branch. This can be done without status checks running on the merge commit itself. - -## Required check needs to succeed against the latest commit SHA - -In order for a pull request to be merged, all required checks must pass against the latest commit SHA. This ensures that the most recent changes are validated and meet the required standards before merging. Checks that were triggered using a previous commit SHA will not be used as part of required checks. Successful check statuses are: `success`, `skipped`, and `neutral`. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks). - -## Conflicts between head commit and test merge commit - -Sometimes, the results of the status checks for the test merge commit and head commit will conflict. If the test merge commit has a status, the test merge commit must pass. Otherwise, the status of the head commit must pass before you can merge the branch. - -If there is a conflict between the test merge commit and head commit, the checks for the test merge commit are shown in the pull request status checks box. This is indicated in the pull request status box by a line starting with `Showing checks for the merge commit`. For more information about test merge commits, see [AUTOTITLE](/rest/pulls/pulls#get-a-pull-request). - -## Handling skipped but required checks - -> [!WARNING] -> If a workflow is skipped due to [path filtering](/actions/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore), [branch filtering](/actions/using-workflows/workflow-syntax-for-github-actions#onpull_requestpull_request_targetbranchesbranches-ignore) or a [commit message](/actions/managing-workflow-runs/skipping-workflow-runs), then checks associated with that workflow will remain in a "Pending" state. A pull request that requires those checks to be successful will be blocked from merging. -> -> {% data reusables.pull_requests.path-filtering-required-workflows %} -> -> If, however, a job within a workflow is skipped due to a conditional, it will report its status as "Success". For more information, see [AUTOTITLE](/actions/using-jobs/using-conditions-to-control-job-execution). -> -> When a job fails, any jobs that depend on the failed job are skipped and do not report a failure. A pull request that requires the check may not be blocked. To use a required check on a job that depends on other jobs, use the `always()` conditional expression in addition to `needs`, see [AUTOTITLE](/actions/using-jobs/using-jobs-in-a-workflow#defining-prerequisite-jobs). - -### Example - -The following example shows a workflow that requires a "Successful" completion status for the `build` job, but the workflow will be skipped if the pull request does not change any files in the `scripts` directory. - -```yaml -name: ci -on: - pull_request: - paths: - - 'scripts/**' -jobs: - build: - runs-on: ubuntu-latest - strategy: - matrix: - node-version: [12.x, 14.x, 16.x] - steps: - - uses: {% data reusables.actions.action-checkout %} - - name: Use Node.js {% raw %}${{ matrix.node-version }}{% endraw %} - uses: {% data reusables.actions.action-setup-node %} - with: - node-version: {% raw %}${{ matrix.node-version }}{% endraw %} - cache: 'npm' - - run: npm ci - - run: npm run build --if-present - - run: npm test -``` - -Due to [path filtering](/actions/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore), a pull request that only changes a file in the root of the repository will not trigger this workflow and is blocked from merging. On the pull request, you would see "Waiting for status to be reported." - -{% data reusables.pull_requests.path-filtering-required-workflows %} - -### Status checks with {% data variables.product.prodname_actions %} and a Merge queue - -You **must** use the `merge_group` event to trigger your {% data variables.product.prodname_actions %} workflow when a pull request is added to a merge queue. - -> [!NOTE] -> {% data reusables.actions.merge-group-event-with-required-checks %} - -A workflow that reports a check which is required by the target branch's protections would look like this: - -```yaml -on: - pull_request: - merge_group: -``` - -For more information on the `merge_group` event, see [AUTOTITLE](/actions/using-workflows/events-that-trigger-workflows#merge_group). - -## Required status checks from unexpected sources - -It's also possible for a protected branch to require a status check from a specific {% data variables.product.prodname_github_app %}. If you see a message similar to the following, then you should verify that the check listed in the merge box was set by the expected app. - -```text -Required status check "build" was not set by the expected {% data variables.product.prodname_github_app %}. -``` diff --git a/content/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/working-with-pre-receive-hooks.md b/content/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/working-with-pre-receive-hooks.md deleted file mode 100644 index 7f1f1babef16..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/working-with-pre-receive-hooks.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Working with pre-receive hooks -intro: '*Pre-receive hooks* enforce rules for contributions before commits may be pushed to a repository.' -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/collaborating-on-repositories-with-code-quality-features/working-with-pre-receive-hooks - - /articles/working-with-pre-receive-hooks - - /github/collaborating-with-issues-and-pull-requests/working-with-pre-receive-hooks - - /github/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/working-with-pre-receive-hooks -versions: - ghes: '*' -shortTitle: Pre-receive hooks -category: - - Merge and close pull requests ---- -Pre-receive hooks run tests on code pushed to a repository to ensure contributions meet repository or organization policy. If the commit contents pass the tests, the push will be accepted into the repository. If the commit contents do not pass the tests, the push will not be accepted. - -If your push isn't accepted, you'll see an error message corresponding to the failed pre-receive hook. - -```shell -$ git push -Counting objects: 3, done. -Delta compression using up to 4 threads. -Compressing objects: 100% (2/2), done. -Writing objects: 100% (3/3), 916 bytes | 0 bytes/s, done. -Total 3 (delta 0), reused 0 (delta 0) -remote: always_reject.sh: failed with exit status 1 -remote: error: rejecting all pushes -To https://54.204.174.51/hodor/nope.git - ! [remote rejected] main -> main (pre-receive hook declined) -error: failed to push some refs to 'https://54.204.174.51/hodor/nope.git' -``` - -Your {% data variables.product.prodname_ghe_server %} site administrator can create and remove pre-receive hooks for your organization or repository, and may allow organization or repository administrators to enable or disable pre-receive hooks. For more information, see [AUTOTITLE](/admin/policies/enforcing-policy-with-pre-receive-hooks). diff --git a/content/pull-requests/collaborating-with-pull-requests/getting-started/about-collaborative-development-models.md b/content/pull-requests/collaborating-with-pull-requests/getting-started/about-collaborative-development-models.md deleted file mode 100644 index 593b08814316..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/getting-started/about-collaborative-development-models.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: About collaborative development models -intro: The way you use pull requests depends on the type of development model you use in your project. You can use the fork and pull model or the shared repository model. -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/getting-started/about-collaborative-development-models - - /articles/types-of-collaborative-development-models - - /articles/about-collaborative-development-models - - /github/collaborating-with-issues-and-pull-requests/about-collaborative-development-models - - /github/collaborating-with-pull-requests/getting-started/about-collaborative-development-models -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Collaborative development -category: - - Create pull requests ---- -## Fork and pull model - -In the fork and pull model, anyone can fork an existing ("upstream") repository to which they have read access and the owner of the upstream repository allows it. Be aware that a fork and its upstream share the same git data. This means that all content uploaded to a fork is accessible from the upstream and all other forks of that upstream. You do not need permission from the upstream repository to push to a fork that you created. You can optionally allow anyone with push access to the upstream repository to make changes to your pull request branch. This model is popular with open-source projects as it reduces the amount of friction for new contributors and allows people to work independently without upfront coordination. - -> [!TIP] -> {% data reusables.open-source.open-source-guide-general %} {% data reusables.open-source.open-source-learning %} - -## Shared repository model - -In the shared repository model, collaborators are granted push access to a single shared repository and topic branches are created when changes need to be made. Pull requests are useful in this model as they initiate code review and general discussion about a set of changes before the changes are merged into the main development branch. This model is more prevalent with small teams and organizations collaborating on private projects. - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork) diff --git a/content/pull-requests/collaborating-with-pull-requests/getting-started/helping-others-review-your-changes.md b/content/pull-requests/collaborating-with-pull-requests/getting-started/helping-others-review-your-changes.md deleted file mode 100644 index 3bdb6e290bc6..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/getting-started/helping-others-review-your-changes.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: Helping others review your changes -intro: 'You can use pull requests to provide clear context for your changes and keep your team informed, improving collaboration and the quality of reviews.' -redirect_from: - - /pull-requests/collaborating-with-pull-requests/getting-started/best-practices-for-pull-requests -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Help others review your changes -category: - - Create pull requests ---- - -When you create a pull request, you’re asking your team to review your changes and provide feedback. This guide provides best practices for creating pull requests that are easy to review and keep your team informed, so that you can improve collaboration and the quality of reviews. - -## Making your changes easy to review - -Clear context in your pull requests helps reviewers quickly see what you’ve changed and why it matters. This makes the review process faster and smoother, with less back-and-forth, and helps your team give better feedback and make confident decisions. For information on creating a pull request, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request). - -### Write small pull requests - -Aim to create small, focused pull requests that fulfill a single purpose. Smaller pull requests are easier and faster to review and merge, leave less room to introduce bugs, and provide a clearer history of changes. - -### Provide context and guidance - -Write clear titles and descriptions for your pull requests so that reviewers can quickly understand what the pull request does. In the pull request body, include: - -* The purpose of the pull request -* An overview of what changed -* Links to any additional context such as tracking issues or previous conversations - -To help reviewers, share the type of feedback you need. For example, do you need a quick look or a deeper critique?{% ifversion copilot %} Additionally, you can use {% data variables.product.prodname_copilot %} to generate a summary of your pull request. See [Use {% data variables.product.prodname_copilot %} to generate pull request summaries](#use-github-copilot-to-generate-pull-request-summaries), later in this article.{% endif %} - -If your pull request consists of changes to multiple files, provide guidance to reviewers about the order in which to review the files. Recommend where to start and how to proceed with the review. - -### Review your own pull request first - -Review, build, and test your own pull request before submitting it. This will allow you to catch errors or typos that you may have missed, before others start reviewing. - -### Review for security - -There are various tools available that can help you review your pull request for potential security issues before others review it. Reviewing for security helps to catch and resolve security issues early, and lets you highlight unresolved risks for others to review and advise on. For example, you can: - -* Check the dependency diff to see if your pull request is introducing vulnerable dependencies. See [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-dependency-changes-in-a-pull-request). -* Check the {% data variables.product.prodname_advisory_database %} to find additional context and information on vulnerable dependencies. -* Investigate and resolve any failing security checks or workflows, such as the dependency review action or the {% data variables.product.prodname_code_scanning %} results check. See [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review#about-the-dependency-review-action) and [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/triaging-code-scanning-alerts-in-pull-requests#about-code-scanning-as-a-pull-request-check).{% ifversion code-scanning-autofix %} -* If your repository has set up {% data variables.product.prodname_code_scanning %} as a pull request check, use {% data variables.copilot.copilot_autofix %} to suggest fixes for security vulnerabilities in your code. See [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/triaging-code-scanning-alerts-in-pull-requests#working-with-copilot-autofix-suggestions-for-alerts-on-a-pull-request).{% endif %} - -## Keeping your team informed - -Pull requests can do more than just document code changes—they’re also a powerful way to keep your team and manager informed about the status of your work. By making your progress visible in your pull requests, you can reduce the need for separate updates and ensure everyone stays aligned. - -{% ifversion copilot %} - -### Use {% data variables.product.prodname_copilot %} to generate pull request summaries - -> [!NOTE] {% data reusables.copilot.copilot-requires-subscription %} - -You can use {% data variables.product.prodname_copilot_short %} to generate a summary of a pull request on {% data variables.product.github %}. You can use the summary to help reviewers understand your changes. - -1. On {% data variables.product.github %}, create a pull request or navigate to an existing pull request. - - > [!NOTE] {% data variables.product.prodname_copilot_short %} does not take into account any existing content in the pull request description, so it is best to start with a blank description. - -1. Navigate to the text field where you want to add the pull request summary. - - * If you're creating a new pull request, use the "Add a description" field. - * If you're adding a description to an existing pull request, edit the opening comment. - * If you're adding a summary as a comment, navigate to the "Add a comment" section at the bottom of the pull request page. - -1. In the header of the text field, select {% octicon "copilot" aria-label="Copilot actions" %}, then click **Summary**. - - ![Screenshot of the form for creating a pull request. A Copilot icon is highlighted, and a box appears with the "Summary" command.](/assets/images/help/copilot/copilot-description-suggestion.png) - -1. Wait for {% data variables.product.prodname_copilot_short %} to produce the summary, then check over the results carefully. -1. Add any additional context that will help people viewing your pull request. -1. When you're happy with the description, click **Create pull request** on a new pull request, or **Update comment** if you're editing an existing description. - -> [!TIP] You can also use {% data variables.copilot.copilot_chat_short %} to turn your work into a discussion or blog post. See [AUTOTITLE](/copilot/copilot-chat-cookbook/documenting-code/writing-discussions-or-blog-posts). - -{% endif %} - -### Link to related issues or projects - -Connect your pull request to relevant issues or project boards to show how your work fits into the larger project. - -* Add keywords like `Closes ISSUE-LINK` in your description to automatically link and close the issue when the pull request is merged. -* Use {% data variables.product.prodname_projects_v2 %} to track your work and link to the project from your pull request, making progress easy to track in one place. See [AUTOTITLE](/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects). - -### Highlight the status with labels - -Add a status label to your pull request to show whether it’s ready for review, blocked, or in progress. This helps reviewers understand the state of your work at a glance. For more information, see [AUTOTITLE](/issues/using-labels-and-milestones-to-track-work/managing-labels). diff --git a/content/pull-requests/collaborating-with-pull-requests/getting-started/index.md b/content/pull-requests/collaborating-with-pull-requests/getting-started/index.md deleted file mode 100644 index 7597f96c0950..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/getting-started/index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Getting started -shortTitle: Getting started -intro: 'Learn about the {% data variables.product.prodname_dotcom %} flow and different ways to collaborate on and discuss your projects.' -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/getting-started - - /github/collaborating-with-issues-and-pull-requests/overview - - /github/collaborating-with-pull-requests/getting-started -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /about-collaborative-development-models - - /helping-others-review-your-changes - - /managing-and-standardizing-pull-requests ---- diff --git a/content/pull-requests/collaborating-with-pull-requests/getting-started/managing-and-standardizing-pull-requests.md b/content/pull-requests/collaborating-with-pull-requests/getting-started/managing-and-standardizing-pull-requests.md deleted file mode 100644 index e7535d7088b9..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/getting-started/managing-and-standardizing-pull-requests.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Managing and standardizing pull requests -intro: 'Use these steps to manage and standardize the pull requests that contributors create in your repository.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Manage and standardize pull requests -category: - - Create pull requests ---- - -If you are a repository maintainer, there are several ways that you can manage and standardize the pull requests that contributors create in your repository. These steps can help you ensure that pull requests are reviewed by the right people, and that they meet your repository's standards. - -## Using pull request templates - -Pull request templates let you customize and standardize the information you'd like to be included when someone creates a pull request in your repository. When you add a pull request template to your repository, project contributors will automatically see the template's contents in the pull request body. For more information, see [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository). - -You can use pull request templates to standardize the review process for your repository. For example, you can include a list of tasks that you would like authors to complete before merging their pull requests, by adding a task list to the template. For more information, see [AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting/about-task-lists). - -You can request that contributors include an issue reference in their pull request body, so that merging the pull request will automatically close the issue. For more information, see [AUTOTITLE](/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue). - -## Defining code owners - -You may want to make sure that specific individuals always review changes to certain code or files in your repository. For example, you may want to ensure that a member of the security team always reviews changes to your `SECURITY.md` file or `dependabot.yml` file. - -You can define individuals or teams that you consider responsible for code or files in a repository to be code owners. Code owners will automatically be requested for review when someone opens a pull request that modifies the files that they own. You can define code owners for specific types of files or directories, as well as for different branches in a repository. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners). - -## Using protected branches - -You can use protected branches to prevent pull requests from being merged into important branches, such as `main`, until certain conditions are met. For example, you can require an approving review, or require that all status checks are passing. See [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches). - -## Using rulesets - -Working alongside protected branches, rulesets let you enforce policies across your repository, such as requiring status checks or workflows to pass before a pull request can be merged. - -Rulesets are especially useful for maintaining repository security when combined with other automated security checks. For example: -* You can use rulesets to enforce the dependency review action, a workflow that blocks pull requests that are introducing vulnerable dependencies into your codebase. See [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/enforcing-dependency-review-across-an-organization). -* If your repository is configured with {% data variables.product.prodname_code_scanning %}, you can use rulesets to set {% data variables.product.prodname_code_scanning %} merge protection, which prevents pull requests from being merged if there is a {% data variables.product.prodname_code_scanning %} alert of a certain severity, or if a {% data variables.product.prodname_code_scanning %} analysis is still in progress. See [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/set-code-scanning-merge-protection). - -## Using push rulesets - -{% data reusables.repositories.push-rulesets-overview %} - -For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets#push-rulesets). - -## Using automated tools to review code styling - -Use automated tools, such as linters, in your repository's pull requests to maintain consistent styling and make code more understandable. Using automated tools to catch smaller problems like typos or styling leaves more time for reviewers to focus on the substance of a pull request. - -For example, you can use {% data variables.product.prodname_actions %} to set up code linters that can run on pull requests as part of your continuous integration (CI) workflow. For more information, see [AUTOTITLE](/actions/automating-builds-and-tests/about-continuous-integration). diff --git a/content/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges.md b/content/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges.md deleted file mode 100644 index 7c33b631ebc3..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: About pull request merges -intro: 'You can [merge pull requests](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request) by retaining all the commits in a feature branch, squashing all commits into a single commit, or by rebasing individual commits from the `head` branch onto the `base` branch.' -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges - - /articles/about-pull-request-merge-squashing - - /articles/about-pull-request-merges - - /github/collaborating-with-issues-and-pull-requests/about-pull-request-merges - - /github/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges -versions: - fpt: '*' - ghes: '*' - ghec: '*' -category: - - Merge and close pull requests ---- -## Merge your commits - -{% data reusables.pull_requests.default_merge_option %} - -## Squash and merge your commits - -{% data reusables.pull_requests.squash_and_merge_summary %} - -### Merge message for a squash merge - -When you squash and merge, {% data variables.product.prodname_dotcom %} generates a default commit message, which you can edit. Depending on how the repository is configured and the number of commits in the pull request, not including merge commits, this message may include the pull request title, pull request description, or information about the commits. - -| Number of commits | Summary | Description | -| ----------------- | ------- | ----------- | -| One commit | The title of the commit message for the single commit, followed by the pull request number | The body text of the commit message for the single commit | -| More than one commit | The pull request title, followed by the pull request number | A list of the commit messages for all of the squashed commits, in date order | - -People with maintainer or admin access to a repository can configure their repository's default merge message for all squashed commits to use the pull request title, the pull request title and commit details, or the pull request title and description. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/configuring-commit-squashing-for-pull-requests). - -### Squashing and merging a long-running branch - -If you plan to continue work on the [head branch](/get-started/learning-about-github/github-glossary#head-branch) of a pull request after the pull request is merged, we recommend you don't squash and merge the pull request. - -When you create a pull request, {% data variables.product.prodname_dotcom %} identifies the most recent commit that is on both the head branch and the [base branch](/get-started/learning-about-github/github-glossary#base-branch): the common ancestor commit. When you squash and merge the pull request, {% data variables.product.prodname_dotcom %} creates a commit on the base branch that contains all of the changes you made on the head branch since the common ancestor commit. - -Because this commit is only on the base branch and not the head branch, the common ancestor of the two branches remains unchanged. If you continue to work on the head branch, then create a new pull request between the two branches, the pull request will include all of the commits since the common ancestor, including commits that you squashed and merged in the previous pull request. If there are no conflicts, you can safely merge these commits. However, this workflow makes merge conflicts more likely. If you continue to squash and merge pull requests for a long-running head branch, you will have to resolve the same conflicts repeatedly. - -## Rebase and merge your commits - -{% data reusables.pull_requests.rebase_and_merge_summary %} - -You aren't able to automatically rebase and merge when: -* The pull request has merge conflicts. -* Rebasing the commits from the base branch into the head branch runs into conflicts. -* Rebasing the commits is considered "unsafe," such as when a rebase is possible without merge conflicts but would produce a different result than a merge would. - -If you still want to rebase the commits but can't rebase and merge automatically, you must: -* Rebase the topic branch (or head branch) onto the base branch locally on the command line -* [Resolve any merge conflicts on the command line](/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-using-the-command-line). -* Force-push the rebased commits to the pull request's topic branch (or remote head branch). - -Anyone with write permissions in the repository, can then [merge the changes](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request) using the rebase and merge button. - -## Indirect merges - -A pull request can be merged automatically if its head branch is directly or indirectly merged into the base branch externally. In other words, if the head branch's tip commit becomes reachable from the tip of the target branch. For example: - -* Branch `main` is at commit **C**. -* Branch `feature` has been branched off of `main` and is currently at commit **D**. This branch has a pull request targeting `main`. -* Branch `feature_2` is branched off of `feature` and is now at commit **E**. This branch also has a pull request targeting `main`. - -If pull request **E** --> `main` is merged first, pull request **D** --> `main` will be marked as merged _automatically_ because all of the commits from `feature` are now reachable from `main`. Merging `feature_2` into `main` and pushing `main` to the server from the command line will mark _both_ pull requests as merged. - -Indirect merges can only occur either when the commits in the pull request's head branch are pushed directly to the repository's default branch, or when the commits in the pull request's head branch are present in another pull request and are merged into the repository's default branch using the **Create a merge commit** option. - -If a pull request containing commits present in another pull request's head branch is merged using the **Squash and merge** or **Rebase and merge** options, a new commit is created on the base branch and the other pull request will not be automatically merged. - -Pull requests that are merged indirectly are marked as `merged` even if [branch protection rules](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#about-branch-protection-rules) have not been satisfied. - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts) diff --git a/content/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/index.md b/content/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/index.md deleted file mode 100644 index 28966f048fde..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/index.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Incorporating changes from a pull request -intro: 'You can propose changes to your work on {% data variables.product.github %} through pull requests. Learn how to create, manage, and merge pull requests.' -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/incorporating-changes-from-a-pull-request - - /articles/incorporating-changes-from-a-pull-request - - /github/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /about-pull-request-merges - - /merging-a-pull-request - - /automatically-merging-a-pull-request - - /merging-a-pull-request-with-a-merge-queue - - /closing-a-pull-request - - /reverting-a-pull-request -shortTitle: Incorporate changes ---- - diff --git a/content/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request.md b/content/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request.md deleted file mode 100644 index 3367f2ec9bf7..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: Merging a pull request -intro: Merge a pull request into the upstream branch when work is completed. Anyone with push access to the repository can complete the merge. -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request - - /articles/merging-a-pull-request - - /github/collaborating-with-issues-and-pull-requests/merging-a-pull-request - - /github/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request -versions: - fpt: '*' - ghes: '*' - ghec: '*' -category: - - Merge and close pull requests ---- -## About pull request merges - -In a pull request, you propose that changes you've made on a head branch should be merged into a base branch. By default, any pull request can be merged at any time, unless the head branch is in conflict with the base branch. However, there may be restrictions on when you can merge a pull request into a specific branch. For example, you may only be able to merge a pull request into the default branch if required status checks are passing. Repository administrators can add constraints like this to branches using branch protection rules. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches). - -{% data reusables.repositories.rulesets-alternative %} - -{% data reusables.pull_requests.you-can-auto-merge %} - -If the pull request has merge conflicts, or if you'd like to test the changes before merging, you can [check out the pull request locally](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/checking-out-pull-requests-locally) and merge it using the command line. - -You can't merge a draft pull request. For more information about draft pull requests, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests). - -The repository may be configured so that the head branch for a pull request is automatically deleted when you merge a pull request. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-the-automatic-deletion-of-branches). - -> [!NOTE] -> {% data reusables.pull_requests.retargeted-on-branch-deletion %} -> For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches#working-with-branches). - -Pull requests are merged using [the `--no-ff` option](https://git-scm.com/docs/git-merge#_fast_forward_merge), except for [pull requests with squashed or rebased commits](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges), which are merged using the fast-forward option. - -{% data reusables.pull_requests.close-issues-using-keywords %} - -If you decide you don't want the changes in a topic branch to be merged to the upstream branch, you can [close the pull request](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/closing-a-pull-request) without merging. - -## Merging a pull request - -{% webui %} - -{% data reusables.repositories.sidebar-pr %} -1. In the "Pull Requests" list, click the pull request you'd like to merge. -1. Scroll down to the bottom of the pull request. Depending on the merge options enabled for your repository, you can: - - * [Merge all of the commits into the base branch](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges) by clicking **Merge pull request**. If the **Merge pull request** option is not shown, click the merge dropdown menu and select **Create a merge commit**. - - ![Screenshot of the merge options for a pull request. The arrow to expand the dropdown is outlined in dark orange.](/assets/images/help/pull_requests/merge-pull-request-options.png) - - * [Squash the commits into one commit](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges#squash-and-merge-your-pull-request-commits) by clicking the merge dropdown menu, selecting **Squash and merge** and then clicking **Squash and merge**. - - * [Rebase the commits individually onto the base branch](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges#rebase-and-merge-your-pull-request-commits) by clicking the merge dropdown menu, selecting **Rebase and merge** and then clicking **Rebase and merge**. - - > [!NOTE] - > Rebase and merge will always update the committer information and create new commit SHAs. For more information, see [About pull request merges](/articles/about-pull-request-merges#rebase-and-merge-your-pull-request-commits). - -1. If prompted, type a commit message, or accept the default message. - - {% data reusables.pull_requests.default-commit-message-squash-merge %} -{% data reusables.files.choose-commit-email %} - - > [!NOTE] - > The email selector is not available for rebase merges, which do not create a merge commit{% ifversion squash-merge-email %}. For squash merges, the email selector is only shown if you are the pull request author and you have more than one email address associated with your account.{% else %}, or for squash merges, which credit the user who created the pull request as the author of the squashed commit.{% endif %} - -1. Click **Confirm merge**, **Confirm squash and merge**, or **Confirm rebase and merge**. -1. Optionally, [delete the branch](/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/deleting-and-restoring-branches-in-a-pull-request). This keeps the list of branches in your repository tidy. - -{% endwebui %} - -{% cli %} - -{% data reusables.cli.cli-learn-more %} - -To merge a pull request, use the `gh pr merge` subcommand. Replace `pull-request` with the number, URL, or head branch of the pull request. - -```shell -gh pr merge PULL-REQUEST -``` - -Follow the interactive prompts to complete the merge. For more information about the merge methods that you can choose, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges). - -Alternatively, you can use flags to skip the interactive prompts. For example, this command will squash the commits into a single commit with the commit message "my squash commit", merge the squashed commit into the base branch, and then delete the local and remote branch. - -```shell -gh pr merge 523 --squash --body "my squash commit" --delete-branch -``` - -{% endcli %} - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/reverting-a-pull-request) -* [AUTOTITLE](/desktop/keeping-your-local-repository-in-sync-with-github/syncing-your-branch) using {% data variables.product.prodname_desktop %} -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts) diff --git a/content/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/reverting-a-pull-request.md b/content/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/reverting-a-pull-request.md deleted file mode 100644 index ac420eb09645..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/reverting-a-pull-request.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Reverting a pull request -intro: You can revert a pull request after it's been merged to the upstream branch. -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/incorporating-changes-from-a-pull-request/reverting-a-pull-request - - /github/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/reverting-a-pull-request - - /articles/reverting-a-pull-request - - /github/collaborating-with-issues-and-pull-requests/reverting-a-pull-request -versions: - fpt: '*' - ghes: '*' - ghec: '*' -category: - - Merge and close pull requests ---- -## About reverting a pull request - -Reverting a pull request on {% data variables.product.github %} creates a new pull request that contains one revert of the merge commit from the original merged pull request. To revert pull requests, you must have [write permissions](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization) in the repository. - -## Reverting a pull request - -> [!NOTE] -> You may need to revert the individual commits in your pull request if either of the following is true. -> -> * Reverting the pull request causes merge conflicts -> * The original pull request was not originally merged on {% data variables.product.github %}. For example, someone could have merged the pull request using a fast-forward merge on the command line. -> -> For more information about using Git to manually revert individual commits, see [Git revert](https://git-scm.com/docs/git-revert.html) in the Git documentation. - -{% data reusables.repositories.sidebar-pr %} -1. In the "Pull Requests" list, click the pull request you'd like to revert. -1. Near the bottom of the pull request, click **Revert**. If the **Revert** option isn't displayed, you'll need to ask the repository administrator for write permissions. - - ![Screenshot of a pull request's timeline. The "Revert" button is outlined in dark orange.](/assets/images/help/pull_requests/revert-pull-request-link.png) - -1. Merge the resulting pull request. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request). diff --git a/content/pull-requests/collaborating-with-pull-requests/index.md b/content/pull-requests/collaborating-with-pull-requests/index.md deleted file mode 100644 index 9d430a206f01..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/index.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Collaborating with pull requests -intro: 'Track and discuss changes in issues, then propose and review changes in pull requests.' -redirect_from: - - /github/collaborating-with-issues-and-pull-requests - - /categories/63/articles - - /categories/collaborating - - /categories/collaborating-on-projects-using-pull-requests - - /categories/collaborating-on-projects-using-issues-and-pull-requests - - /categories/collaborating-with-issues-and-pull-requests - - /github/collaborating-with-pull-requests -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /getting-started - - /working-with-forks - - /collaborating-on-repositories-with-code-quality-features - - /proposing-changes-to-your-work-with-pull-requests - - /addressing-merge-conflicts - - /reviewing-changes-in-pull-requests - - /incorporating-changes-from-a-pull-request -shortTitle: Collaborate with pull requests ---- - diff --git a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches.md b/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches.md deleted file mode 100644 index 0a2476e41dfb..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: About branches -intro: 'Use a branch to isolate development work without affecting other branches in the repository. Each repository has one default branch, and can have multiple other branches. You can merge a branch into another branch using a pull request.' -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches - - /articles/working-with-protected-branches - - /articles/about-branches - - /github/collaborating-with-issues-and-pull-requests/about-branches - - /github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches -versions: - fpt: '*' - ghes: '*' - ghec: '*' -category: - - Create pull requests ---- -## About branches - -Branches allow you to develop features, fix bugs, or safely experiment with new ideas in a contained area of your repository. - -You always create a branch from an existing branch. Typically, you might create a new branch from the default branch of your repository. You can then work on this new branch in isolation from changes that other people are making to the repository. A branch you create to build a feature is commonly referred to as a feature branch or topic branch. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository). - -You can also use a branch to publish a {% data variables.product.prodname_pages %} site. For more information, see [AUTOTITLE](/pages/getting-started-with-github-pages/about-github-pages). - -You must have write access to a repository to create a branch, open a pull request, or delete and restore branches in a pull request. For more information, see [AUTOTITLE](/get-started/learning-about-github/access-permissions-on-github). - -## About the default branch - -{% data reusables.branches.new-repo-default-branch %} The default branch is the branch that {% data variables.product.prodname_dotcom %} displays when anyone visits your repository. The default branch is also the initial branch that Git checks out locally when someone clones the repository. {% data reusables.branches.default-branch-automatically-base-branch %} - -By default, {% data variables.product.github %} names the default branch `main` in any new repository. - -{% data reusables.branches.change-default-branch %} - -{% data reusables.branches.set-default-branch %} - -## Working with branches - -Once you're satisfied with your work, you can open a pull request to merge the changes in the current branch (the _head_ branch) into another branch (the _base_ branch). For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests). - -After a pull request has been merged, or closed, you can delete the head branch as this is no longer needed. You must have write access in the repository to delete branches. You can't delete branches that are directly associated with open pull requests. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/deleting-and-restoring-branches-in-a-pull-request). - -{% data reusables.pull_requests.retargeted-on-branch-deletion %} -The following diagrams illustrate this. - -Here someone has created a branch called `feature1` from the `main` branch, and you've then created a branch called `feature2` from `feature1`. There are open pull requests for both branches. The arrows indicate the current base branch for each pull request. At this point, `feature1` is the base branch for `feature2`. If the pull request for `feature2` is merged now, the `feature2` branch will be merged into `feature1`. - -![Diagram that shows a feature1 branch with a pull request targeting main, and a feature2 branch with a pull request targeting feature1.](/assets/images/help/branches/pr-retargeting-diagram1.png) - -In the next diagram, someone has merged the pull request for `feature1` into the `main` branch, and they have deleted the `feature1` branch. As a result, {% data variables.product.prodname_dotcom %} has automatically retargeted the pull request for `feature2` so that its base branch is now `main`. - -![Diagram that shows both feature1 and feature2 branches with pull requests targeting main.](/assets/images/help/branches/pr-retargeting-diagram2.png) - -Now when you merge the `feature2` pull request, it'll be merged into the `main` branch. - -## Working with protected branches - -Repository administrators or custom roles with the "edit repository rules" permission can enable protections on a branch. If you're working on a branch that's protected, you won't be able to delete or force push to the branch. Repository administrators can additionally enable several other protected branch settings to enforce various workflows before a branch can be merged. - -> [!NOTE] -> If you're a repository administrator, you can merge pull requests on branches with branch protections enabled even if the pull request does not meet the requirements, unless branch protections have been set to "Include administrators." - -To see if your pull request can be merged, look in the merge box at the bottom of the pull request's **Conversation** tab. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches). - -When a branch is protected: - -* You won't be able to delete or force push to the branch. -* If required status checks are enabled on the branch, you won't be able to merge changes into the branch until all of the required CI tests pass. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks). -* If required pull request reviews are enabled on the branch, you won't be able to merge changes into the branch until all requirements in the pull request review policy have been met. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request). -* If required review from a code owner is enabled on a branch, and a pull request modifies code that has an owner, a code owner must approve the pull request before it can be merged. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners). -* If required commit signing is enabled on a branch, you won't be able to push any commits to the branch that are not signed and verified. For more information, see [AUTOTITLE](/authentication/managing-commit-signature-verification/about-commit-signature-verification) and [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-signed-commits). -* If you use {% data variables.product.prodname_dotcom %}'s conflict editor to fix conflicts for a pull request that you created from a protected branch, {% data variables.product.prodname_dotcom %} helps you to create an alternative branch for the pull request, so that your resolution of the conflicts can be merged. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-on-github). - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) -* [AUTOTITLE](/get-started/learning-about-github/github-glossary#branch) in the {% data variables.product.prodname_dotcom %} glossary -* [Branches in a Nutshell](https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell) in the Git documentation diff --git a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-comparing-branches-in-pull-requests.md b/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-comparing-branches-in-pull-requests.md deleted file mode 100644 index b24ce8799018..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-comparing-branches-in-pull-requests.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -title: About comparing branches in pull requests -intro: Pull requests display diffs to compare the changes you made in your topic branch against the base branch that you want to merge your changes into. -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-comparing-branches-in-pull-requests - - /articles/about-comparing-branches-in-pull-requests - - /github/collaborating-with-issues-and-pull-requests/about-comparing-branches-in-pull-requests - - /github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-comparing-branches-in-pull-requests -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Compare branches -category: - - Create pull requests ---- - -> [!NOTE] -> When creating your pull request, you can change the base branch that you're comparing your changes against. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request#changing-the-branch-range-and-destination-repository). - -You can view proposed changes in a pull request in the Files changed tab. -![Screenshot of the tabs for a pull request. The "Files changed" tab is outlined in dark orange.](/assets/images/help/pull_requests/pull-request-tabs-changed-files.png) - -Rather than viewing the commits themselves, you can view the proposed changes as they'll appear in the files once the pull request is merged. The files appear in alphabetical order within the Files changed tab. Additions to the files appear in green and are prefaced by a `+` sign while content that has been removed appears in red and is prefaced by a `-` sign. - -## Diff view options - -> [!TIP] -> If you're having a hard time understanding the context of a change, you can click **View** in the Files changed tab to view the whole file with the proposed changes. - -You have several options for viewing a diff: -* The unified view shows updated and existing content together in a linear view. -* The split view shows old content on one side and new content on the other side. -* The rich diff view shows a preview of how the changes will look once the pull request is merged. -* The source view shows the changes in source without the formatting of the rich diff view. - -You can also choose to ignore whitespace changes to get a more accurate view of the substantial changes in a pull request. - -![Screenshot of the "Files changed" tab for a pull request. The "Diff view" menu is outlined in dark orange.](/assets/images/help/pull_requests/diff-settings-menu.png) - -To simplify reviewing changes in a large pull request, you can filter the diff to only show selected file types, show files you are a CODEOWNER of, hide files you have already viewed, or hide deleted files. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/filtering-files-in-a-pull-request). - -![Screenshot of the file filter dropdown menu. The menu is expanded and outlined in dark orange.](/assets/images/help/pull_requests/file-filter-menu.png) - -You can also use the diff view to see which dependencies you are introducing or changing with your pull request, and whether the dependency versions contain security vulnerabilities. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-dependency-changes-in-a-pull-request#reviewing-dependencies-in-a-pull-request). - -## Reasons diffs will not display - -* You've exceeded the total limit of files or certain file types. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/repository-limits#diff-limits). -* Your file matches a rule in the repository's _.gitattributes_ file to block that file from displaying by default. For more information, see [AUTOTITLE](/repositories/working-with-files/managing-files/customizing-how-changed-files-appear-on-github). - -## Three-dot and two-dot Git diff comparisons - -There are two comparison methods for the `git diff` command; two-dot (`git diff A..B`) and three-dot (`git diff A...B`). Pull requests on {% data variables.product.prodname_dotcom %} show a three-dot diff. - -### Three-dot Git diff comparison - -The three-dot comparison shows the difference between the latest common commit of both branches (merge base) and the most recent version of the topic branch. - -### Two-dot Git diff comparison - -The two-dot comparison shows the difference between the latest state of the base branch (for example, `main`) and the most recent version of the topic branch. - -To see two committish references in a two-dot diff comparison on {% data variables.product.prodname_dotcom %}, you can edit the URL of your repository's "Comparing changes" page. For more information, see the [Git Glossary for "committish"](https://git-scm.com/docs/gitglossary#gitglossary-aiddefcommit-ishacommit-ishalsocommittish) from the _Pro Git_ book site. - -{% data reusables.repositories.two-dot-diff-comparison-example-urls %} - -A two-dot diff compares two Git committish references, such as SHAs or OIDs (Object IDs), directly with each other. On {% data variables.product.prodname_dotcom %}, the Git committish references in a two-dot diff comparison must be pushed to the same repository or its forks. - -If you want to simulate a two-dot diff in a pull request and see a comparison between the most recent versions of each branch, you can merge the base branch into your topic branch, which updates the last common ancestor between your branches. - -For more information about Git commands to compare changes, see [Git diff options](https://git-scm.com/docs/git-diff#git-diff-emgitdiffemltoptionsgtltcommitgtltcommitgt--ltpathgt82308203) from the _Pro Git_ book site. - -## About three-dot comparison on {% data variables.product.prodname_dotcom %} - -Since the three-dot comparison compares with the merge base, it is focusing on "what a pull request introduces." - -When you use a two-dot comparison, the diff changes when the base branch is updated, even if you haven't made any changes to the topic branch. Additionally, a two-dot comparison focuses on the base branch. This means that anything you add is displayed as missing from the base branch, as if it was a deletion, and vice versa. As a result, the changes the topic branch introduces become ambiguous. - -In contrast, by comparing the branches using the three-dot comparison, changes in the topic branch are always in the diff if the base branch is updated, because the diff shows all of the changes since the branches diverged. - -### Merging often - -To avoid getting confused, merge the base branch (for example, `main`) into your topic branch frequently. By merging the base branch, the diffs shown by two-dot and three-dot comparisons are the same. We recommend merging a pull request as soon as possible. This encourages contributors to make pull requests smaller, which is recommended in general. - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks) diff --git a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests.md b/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests.md deleted file mode 100644 index 21c975095e10..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: About pull requests -intro: 'Pull requests let you propose, review, and merge code changes.' -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests - - /articles/using-pull-requests - - /articles/about-pull-requests - - /github/collaborating-with-issues-and-pull-requests/about-pull-requests - - /github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests -versions: - fpt: '*' - ghes: '*' - ghec: '*' -category: - - Create pull requests ---- - -Pull requests are proposals to merge code changes into a project. A pull request is {% data variables.product.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 {% octicon "link-external" height:16 aria-label="link-external" %} - -## 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. - -The **Merge status** of a pull request can be viewed directly in the header from anywhere in the pull request page. Click to open the details so you can quickly identify blockers, missing approvals, and get your pull request ready to merge. - -## 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. - -{% data reusables.pull_requests.mark-ready-review %} You can convert a pull request to a draft at any time. See [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request). - -## Pull request refs and merge branches - -When you open a pull request, {% data variables.product.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 changes. To fetch it locally: - -```shell -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 {% data variables.product.prodname_actions %} uses the merge branch, see [AUTOTITLE](/actions/reference/workflows-and-actions/events-that-trigger-workflows#how-the-merge-branch-affects-your-workflow). - -## 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 - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request) diff --git a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/committing-changes-to-a-pull-request-branch-created-from-a-fork.md b/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/committing-changes-to-a-pull-request-branch-created-from-a-fork.md deleted file mode 100644 index 37b282b1c1bc..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/committing-changes-to-a-pull-request-branch-created-from-a-fork.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: Committing changes to a pull request branch created from a fork -intro: You can commit changes on a pull request branch that was created from a fork of your repository with permission from the pull request creator. -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests/committing-changes-to-a-pull-request-branch-created-from-a-fork - - /articles/committing-changes-to-a-pull-request-branch-created-from-a-fork - - /github/collaborating-with-issues-and-pull-requests/committing-changes-to-a-pull-request-branch-created-from-a-fork - - /github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/committing-changes-to-a-pull-request-branch-created-from-a-fork -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Commit to PR branch from fork -category: - - Create pull requests ---- -You can only make commits on pull request branches that: -* Are opened in a repository that you have push access to and that were created from a fork of that repository -* Are on a user-owned fork -* Have permission granted from the pull request creator -* Don't have [branch restrictions](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#restrict-who-can-push-to-matching-branches) that will prevent you from committing - -Only the user who created the pull request can give you permission to push commits to the user-owned fork. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork). - -> [!NOTE] -> You can also make commits to a pull request branch from a fork of your repository through {% data variables.location.product_location %} by creating your own copy (or fork) of the fork of your repository and committing changes to the same head branch that the original pull request changes were created on. For some general guidelines, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork). - -1. On {% data variables.product.github %}, navigate to the main page of the fork (or copy of your repository) where the pull request branch was created. -{% data reusables.repositories.copy-clone-url %} -{% data reusables.command_line.open_the_multi_os_terminal %} - - > [!TIP] - > If you prefer to clone the fork using {% data variables.product.prodname_desktop %}, then see [AUTOTITLE](/repositories/creating-and-managing-repositories/cloning-a-repository#cloning-a-repository-to-github-desktop). - -1. Change the current working directory to the location where you want to download the cloned directory. - - ```shell - cd open-source-projects - ``` - -1. Type `git clone`, and then paste the URL you copied in Step 3. - - ```shell - git clone https://{% data variables.product.product_url %}/USERNAME/FORK-OF-THE-REPOSITORY - ``` - -1. Press **Enter**. Your local clone will be created. - - ```shell - $ git clone https://{% data variables.product.product_url %}/USERNAME/FORK-OF-THE-REPOSITORY - > Cloning into `FORK-OF-THE-REPOSITORY`... - > remote: Counting objects: 10, done. - > remote: Compressing objects: 100% (8/8), done. - > remove: Total 10 (delta 1), reused 10 (delta 1) - > Unpacking objects: 100% (10/10), done. - ``` - - > [!TIP] - > The error message "fatal: destination path 'REPOSITORY-NAME' already exists and is not an empty directory" means that your current working directory already contains a repository with the same name. To resolve the error, you must clone the fork in a different directory. - -1. Navigate into your new cloned repository. - - ```shell - cd FORK-OF-THE-REPOSITORY - ``` - -1. Switch branches to the compare branch of the pull request where the original changes were made. If you navigate to the original pull request, you'll see the compare branch at the top of the pull request. - - In this example, the compare branch is `test-branch`: - - ```shell - git checkout TEST-BRANCH - ``` - - > [!TIP] - > For more information about pull request branches, including examples, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request#changing-the-branch-range-and-destination-repository). - -1. At this point, you can do anything you want with this branch. You can push new commits to it, run some local tests, or merge other branches into the branch. Make modifications as you like. -1. After you commit your changes to the head branch of the pull request you can push your changes up to the original pull request directly. In this example, the head branch is `test-branch`: - - ```shell - $ git push origin test-branch - > Counting objects: 32, done. - > Delta compression using up to 8 threads. - > Compressing objects: 100% (26/26), done. - > Writing objects: 100% (29/29), 74.94 KiB | 0 bytes/s, done. - > Total 29 (delta 8), reused 0 (delta 0) - > To https://{% data variables.product.product_url %}/USERNAME/FORK-OF-THE-REPOSITORY.git - > 12da2e9..250e946 TEST-BRANCH -> TEST-BRANCH - ``` - -Your new commits will be reflected on the original pull request on {% data variables.location.product_location %}. - -## Further Reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks) diff --git a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request.md b/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request.md deleted file mode 100644 index 232b28af1a3c..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request.md +++ /dev/null @@ -1,197 +0,0 @@ ---- -title: Creating a pull request -intro: 'Create a pull request to propose and collaborate on changes to a repository. These changes are proposed in a *branch*, which ensures that the default branch only contains finished and approved work.' -permissions: 'Anyone with read access to a repository can create a pull request. {% data reusables.enterprise-accounts.emu-permission-propose %}' -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request - - /articles/creating-a-pull-request - - /github/collaborating-with-issues-and-pull-requests/creating-a-pull-request -versions: - fpt: '*' - ghes: '*' - ghec: '*' -category: - - Create pull requests ---- - -If you want to create a new branch for your pull request and do not have write permissions to the repository, you can fork the repository first. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) and [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks). - -You can specify which branch you'd like to merge your changes into when you create your pull request. Pull requests can only be opened between two branches that are different. - -{% data reusables.pull_requests.perms-to-open-pull-request %} - -{% data reusables.pull_requests.close-issues-using-keywords %} - -## Changing the branch range and destination repository - -By default, pull requests are based on the parent repository's default branch. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches#about-the-default-branch). - -If the default parent repository isn't correct, you can change both the parent repository and the branch with the drop-down lists. You can also swap your head and base branches with the drop-down lists to establish diffs between reference points. References here must be branch names in your GitHub repository. - -![Screenshot of a pull request. The dropdown to edit the compare branch is expanded.](/assets/images/help/pull_requests/pull-request-review-edit-branch.png) - -When thinking about branches, remember that the _base branch_ is **where** changes should be applied, the _head branch_ contains **what** you would like to be applied. - -When you change the base repository, you also change notifications for the pull request. Everyone that can push to the base repository will receive an email notification and see the new pull request in their dashboard the next time they sign in. - -When you change any of the information in the branch range, the Commit and Files changed preview areas will update to show your new range. - -> [!TIP] -> * Using the compare view, you can set up comparisons across any timeframe. For more information, see [AUTOTITLE](/pull-requests/committing-changes-to-your-project/viewing-and-comparing-commits/comparing-commits). -> * Project maintainers can add a pull request template for a repository. Templates include prompts for information in the body of a pull request. For more information, see [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests/about-issue-and-pull-request-templates). - -## Creating the pull request - -{% webui %} - -{% data reusables.repositories.navigate-to-repo %} -1. In the "Branch" menu, choose the branch that contains your commits. - - ![Screenshot of the branch dropdown menu on the main page of a repository.](/assets/images/help/pull_requests/branch-dropdown.png) - -{% data reusables.repositories.new-pull-request %} -1. Use the _base_ branch dropdown menu to select the branch you'd like to merge your changes into, then use the _compare_ branch drop-down menu to choose the topic branch you made your changes in. -{% data reusables.repositories.pr-title-description %} -{% data reusables.repositories.create-pull-request %} - -{% data reusables.repositories.asking-for-review %} - -After your pull request has been reviewed, it can be [merged into the repository](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request). - -{% endwebui %} - -{% cli %} - -{% data reusables.cli.cli-learn-more %} - -To create a pull request, use the `gh pr create` subcommand. - -```shell -gh pr create -``` - -To assign a pull request to an individual, use the `--assignee` or `-a` flags. You can use `@me` to self-assign the pull request. - -```shell -gh pr create --assignee "@octocat" -``` - -To specify the branch into which you want the pull request merged, use the `--base` or `-B` flags. To specify the branch that contains commits for your pull request, use the `--head` or `-H` flags. - -```shell -gh pr create --base my-base-branch --head my-changed-branch -``` - -To include a title and body for the new pull request, use the `--title` and `--body` flags. - -```shell -gh pr create --title "The bug is fixed" --body "Everything works again" -``` - -To mark a pull request as a draft, use the `--draft` flag. - -```shell -gh pr create --draft -``` - -To add a labels or milestones to the new pull request, use the `--label` and `--milestone` flags. - -```shell -gh pr create --label "bug,help wanted" --milestone octocat-milestone -``` - -To add the new pull request to a specific project, use the `--project` flag. - -```shell -gh pr create --project octocat-project -``` - -To assign an individual or team as reviewers, use the `--reviewer` flag. - -```shell -gh pr create --reviewer monalisa,hubot --reviewer myorg/team-name -``` - -To create the pull request in your default web browser, use the `--web` flag. - -```shell -gh pr create --web -``` - -{% endcli %} - -{% desktop %} - -1. Click **Preview Pull Request**. {% data variables.product.prodname_desktop %} will open a preview dialog showing the diff of the changes between your current branch and the base branch. - - {% mac %} - - ![Screenshot of the "No local changes" view. A button, labeled "Preview Pull Request", is highlighted with an orange outline.](/assets/images/help/desktop/mac-preview-pull-request.png) - - {% endmac %} - - {% windows %} - - ![Screenshot of the "No local changes" view. A button, labeled "Preview Pull Request", is highlighted with an orange outline.](/assets/images/help/desktop/windows-preview-pull-request.png) - - {% endwindows %} - - Alternatively, to go straight to {% data variables.product.prodname_dotcom %} to create your pull request, select the dropdown icon and click **Create Pull Request**. - -1. Confirm that the branch in the **base:** dropdown menu is the branch where you want to merge your changes. - - ![Screenshot of the "Open a Pull Request" dialog window. A button with a dropdown icon, labeled "base: development", is outlined in orange.](/assets/images/help/desktop/base-branch-selection.png) - - {% data variables.product.prodname_desktop %} will advise you whether the current branch can be automatically merged into the base branch. - - ![Screenshot of the "Open a Pull Request" dialog window. A status label stating "Can't automatically merge" is highlighted with an orange outline.](/assets/images/help/desktop/preview-dialog-merge-status.png) - -1. Click **Create Pull Request**. {% data variables.product.prodname_desktop %} will open your default browser to take you to {% data variables.product.prodname_dotcom %}. -{% data reusables.repositories.pr-title-description %} -{% data reusables.repositories.create-pull-request %} - -{% enddesktop %} - -{% ifversion fpt or ghec %} - -{% codespaces %} - -1. Once you've committed changes to your local copy of the repository, click the **Create Pull Request** icon. -![Screenshot of the top of the "Source Control" side bar. The pull request icon is highlighted with a dark orange outline.](/assets/images/help/codespaces/codespaces-commit-pr-button.png) -1. Check that the local branch and repository you're merging from, and the remote branch and repository you're merging into, are correct. Then give the pull request a title and a description. -![Screenshot of the "{% data variables.product.prodname_dotcom %} Pull Request" side bar with a form for creating a pull request, including "Title" and "Description" fields.](/assets/images/help/codespaces/codespaces-commit-pr.png) -1. Click **Create**. - -For more information on creating pull requests in {% data variables.product.prodname_github_codespaces %}, see [AUTOTITLE](/codespaces/developing-in-codespaces/using-github-codespaces-for-pull-requests). - -{% endcodespaces %} - -{% endif %} - -## Making changes to files in your pull request - -After you have opened your pull request, you can continue making changes to the files by adding new commits to your head branch. - -{% webui %} - -You can also make changes to files on the {% data variables.product.github %} website. - -1. On {% data variables.product.github %}, navigate to a pull request in a repository. -{% data reusables.repositories.changed-files %} -1. Scroll down to the file you want to make changes to. - * If the pull request has a lot of files, you can use the filter to locate the file. See [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/filtering-files-in-a-pull-request). -1. Above the file you want to change, click {% octicon "kebab-horizontal" aria-label="Show options" %}. - ![Screenshot of the options above a file on the "File changed" tab. The "Show options" button is highlighted with an orange rectangle.](/assets/images/help/pull_requests/menu-on-pull-request-file.png) -1. In the menu, click **Edit file**. -1. Make your changes in the editor and when committing your change, choose to commit directly back to your head branch. - -{% endwebui %} - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/keeping-your-pull-request-in-sync-with-the-base-branch) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-base-branch-of-a-pull-request) -* [AUTOTITLE](/issues/tracking-your-work-with-issues/creating-an-issue) -* [AUTOTITLE](/issues/tracking-your-work-with-issues/assigning-issues-and-pull-requests-to-other-github-users) -* [AUTOTITLE](/get-started/writing-on-github) diff --git a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/keeping-your-pull-request-in-sync-with-the-base-branch.md b/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/keeping-your-pull-request-in-sync-with-the-base-branch.md deleted file mode 100644 index 6a3ce11aad7c..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/keeping-your-pull-request-in-sync-with-the-base-branch.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: Keeping your pull request in sync with the base branch -intro: 'After you open a pull request, you can update the head branch, which contains your changes, with any changes that have been made in the base branch.' -permissions: People with write permissions to the repository to which the head branch of the pull request belongs can update the head branch with changes that have been made in the base branch. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Update the head branch -category: - - Create pull requests ---- - -## About keeping your pull request in sync - -Before merging your pull requests, other changes may get merged into the base branch causing your pull request's head branch to be out of sync. Updating your pull request with the latest changes from the base branch can help catch problems prior to merging. - -You can update a pull request's head branch from the command line or the pull request page. The **Update branch** button is displayed when all of these are true: - -* There are no merge conflicts between the pull request branch and the base branch. -* The pull request branch is not up to date with the base branch. -* The base branch requires branches to be up to date before merging or the setting to always suggest updating branches is enabled. - -> [!NOTE] You may not be able to update using the `Update branch` button if the HEAD branch of your pull request is a protected branch. - -For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches), [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets) and [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-suggestions-to-update-pull-request-branches). - -If there are changes to the base branch that cause merge conflicts in your pull request branch, you will not be able to update the branch until all conflicts are resolved. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/about-merge-conflicts). - -From the pull request page you can update your pull request's branch using a traditional merge or by rebasing. A traditional merge results in a merge commit that merges the base branch into the head branch of the pull request. Rebasing applies the changes from _your_ branch onto the latest version of the base branch. The result is a branch with a linear history, since no merge commit is created. - -## Updating your pull request branch - -{% data reusables.repositories.sidebar-pr %} -1. In the "Pull requests" list, click the pull request you'd like to update. -1. In the merge section near the bottom of the page, you can: - * Click **Update branch** to perform a traditional merge. - - ![Screenshot of the merge section for a pull request.](/assets/images/help/pull_requests/pull-request-update-branch-with-dropdown.png) - - * Click the update branch drop down menu, click **Update with rebase**, and then click **Rebase branch** to update by rebasing on the base branch. - - ![Screenshot of the merge section of a pull request. The dropdown menu is expanded, showing "Update with merge commit" and "Update with rebase" options.](/assets/images/help/pull_requests/pull-request-update-branch-rebase-option.png) - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/committing-changes-to-a-pull-request-branch-created-from-a-fork) diff --git a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/requesting-a-pull-request-review.md b/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/requesting-a-pull-request-review.md deleted file mode 100644 index b17309e3689b..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/requesting-a-pull-request-review.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Requesting a pull request review -intro: 'After you create a pull request, you can ask a specific person to review the changes you''ve proposed. If you''re an organization member, you can also request a specific team to review your changes.' -product: '{% data reusables.gated-features.multiple-pr-reviewers %}' -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests/requesting-a-pull-request-review - - /articles/requesting-a-pull-request-review - - /github/collaborating-with-issues-and-pull-requests/requesting-a-pull-request-review - - /github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/requesting-a-pull-request-review -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Request a PR review -category: - - Create pull requests ---- - -Repositories belong to a personal account (a single individual owner) or an organization account (a shared account with numerous collaborators or maintainers). For more information, see [AUTOTITLE](/get-started/learning-about-github/types-of-github-accounts). Owners and collaborators on a repository owned by a personal account can assign pull request reviews. Organization members with triage permissions can also assign a reviewer for a pull request. - -To assign a reviewer to a pull request, you will need write access to the repository. For more information about repository access, see [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization). If you have write access, you can assign anyone who has read access to the repository as a reviewer. - -Organization members with write access can also assign a pull request review to any person or team with read access to a repository. The requested reviewer or team will receive a notification that you asked them to review the pull request. If you request a review from a team and code review assignment is enabled, specific members will be requested and the team will be removed as a reviewer. For more information, see [AUTOTITLE](/organizations/organizing-members-into-teams/managing-code-review-settings-for-your-team). - -> [!NOTE] -> Pull request authors can't request reviews unless they are either a repository owner or collaborator with write access to the repository. - -{% ifversion copilot %} - -## Requesting reviews from collaborators and organization members - -{% endif %} - -You can request a review from either a suggested or specific person. Suggested reviewers are based on [git blame data](/repositories/working-with-files/using-files/viewing-a-file). If you request a review, other people with read access to the repository can still review your pull request. Once someone has reviewed your pull request and you've made the necessary changes, you can re-request review from the same reviewer. If the requested reviewer does not submit a review, and the pull request meets the repository's [mergeability requirements](/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests), you can still merge the pull request. - -{% data reusables.repositories.sidebar-pr %} -1. In the list of pull requests, click the pull request that you'd like to ask a specific person or a team to review. -1. To request a review from a suggested person under **Reviewers**, next to their username, click **Request**. - - ![Screenshot of the "Reviewers" section of a pull request's sidebar. To the right of @octocat, a "Request" link is outlined in dark orange.](/assets/images/help/pull_requests/request-suggested-review.png) - -1. Optionally, to request a review from someone other than a suggested person, click **Reviewers**. - - If you know the name of the person or team you'd like a review from, type the username of the person or the name of the team you're asking to review your changes. Click their team name or username to request a review. - -1. After your pull request is reviewed and you've made the necessary changes, you can ask a reviewer to re-review your pull request. Navigate to **Reviewers** in the right sidebar and click {% octicon "sync" aria-label="Re-request review" %} next to the reviewer's name whose review you'd like. - - ![Screenshot of the "Reviewers" section of a pull request's sidebar. To the right of @octocat, a sync icon is outlined in dark orange.](/assets/images/help/pull_requests/request-re-review.png) - -{% ifversion copilot %} - -## Requesting a review from {% data variables.product.prodname_copilot %} - -You can also request that {% data variables.product.prodname_copilot_short %} reviews your code and provides feedback and suggested changes on your work. See [AUTOTITLE](/copilot/using-github-copilot/code-review/using-copilot-code-review). - -{% endif %} - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews) diff --git a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/using-query-parameters-to-create-a-pull-request.md b/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/using-query-parameters-to-create-a-pull-request.md deleted file mode 100644 index c1aab59703a0..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/using-query-parameters-to-create-a-pull-request.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Using query parameters to create a pull request -intro: Use query parameters to create custom URLs to open pull requests with pre-populated fields. -redirect_from: - - /github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/using-query-parameters-to-create-a-pull-request -versions: - fpt: '*' - ghes: '*' - ghec: '*' -category: - - Create pull requests ---- - -You can use query parameters to open pull requests. Query parameters are optional parts of a URL you can customize to share a specific web page view, such as search filter results or a pull request template on {% data variables.product.prodname_dotcom %}. To create your own query parameters, you must match the key and value pair. For more information on creating pull request templates, see [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository). - -You must have the proper permissions for any action to use the equivalent query parameter. For example, you must have permission to add a label to a pull request to use the `labels` query parameter. For more information, see [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization). - -If you create an invalid URL using query parameters, or if you don’t have the proper permissions, the URL will return a `404 Not Found` error page. If you create a URL that exceeds the server limit, the URL will return a `414 URI Too Long` error page. - -Query parameter | Example ---- | --- -`quick_pull` | `https://github.com/octo-org/octo-repo/compare/main...my-branch?quick_pull=1` creates a pull request that compares the base branch `main` and head branch `my-branch`. The `quick_pull=1` query brings you directly to the "Open a pull request" page. -`title` | `https://github.com/octo-org/octo-repo/compare/main...my-branch?quick_pull=1&labels=bug&title=Bug+fix` creates a pull request with the label "bug" and title "Bug fix." -`body` | `https://github.com/octo-org/octo-repo/compare/main...my-branch?quick_pull=1&title=Bug+fix&body=Describe+the+fix.` creates a pull request with the title "Bug fix" and the comment "Describe the fix" in the pull request body. -`labels` | `https://github.com/octo-org/octo-repo/compare/main...my-branch?quick_pull=1&labels=help+wanted,bug` creates a pull request with the labels "help wanted" and "bug". -`milestone` | `https://github.com/octo-org/octo-repo/compare/main...my-branch?quick_pull=1&milestone=testing+milestones` creates a pull request with the milestone "testing milestones." -`assignees` | `https://github.com/octo-org/octo-repo/compare/main...my-branch?quick_pull=1&assignees=octocat` creates a pull request and assigns it to @octocat. -`projects` | `https://github.com/octo-org/octo-repo/compare/main...my-branch?quick_pull=1&title=Bug+fix&projects=octo-org/1` creates a pull request with the title "Bug fix" and adds it to the organization's project 1. -`template` | `https://github.com/octo-org/octo-repo/compare/main...my-branch?quick_pull=1&template=issue_template.md` creates a pull request with a template in the pull request body. The `template` query parameter works with templates stored in a `PULL_REQUEST_TEMPLATE` subdirectory within the root, `docs/` or `.github/` directory in a repository. For more information, see [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests). - diff --git a/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews.md b/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews.md deleted file mode 100644 index c65c7ffdacd7..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: About pull request reviews -intro: 'Collaborate on pull requests to improve code quality.' -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews - - /articles/about-pull-request-reviews - - /github/collaborating-with-issues-and-pull-requests/about-pull-request-reviews - - /github/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: About PR reviews -category: - - Review pull requests ---- - -Pull request reviews are one of the primary ways people collaborate on {% data variables.product.github %}. Reviewers can comment on changes, suggest improvements, and approve or request changes before code is merged. This collaborative process enables teams to ensure code quality and share knowledge. - -{% raw %}View pull requests awaiting your review{% endraw %} - -## Reviewing pull requests - -Anyone with read access can review and comment on proposed changes. When submitting a review, choose one of three statuses: - -* **Comment**: Share feedback without approving or requesting changes. -* **Approve**: Approve the changes for merging. -* **Request changes**: Identify issues that must be fixed before merging. - -You can comment on specific lines, suggest changes for authors to apply directly, and discuss implementation approaches. Reviews appear in the conversation timeline and merge box. Mark conversation threads as resolved to track addressed feedback. - -## Requesting reviews - -Repository owners and collaborators can request reviews from specific people or teams. When you define code owners in a CODEOWNERS file, they're automatically requested as reviewers when a pull request modifies their code. You can re-request reviews after making significant changes. - -## Required reviews - -Repository administrators can require approvals before pull requests are merged, ensuring code quality and preventing accidental merges. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-pull-request-reviews-before-merging). - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/requesting-a-pull-request-review) -* Learn more in the [Review pull requests](https://github.com/skills/review-pull-requests?ref_product=github&ref_type=engagement&ref_style=text) {% data variables.product.prodname_learning %} course diff --git a/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/approving-a-pull-request-with-required-reviews.md b/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/approving-a-pull-request-with-required-reviews.md deleted file mode 100644 index b1a2ebcc3edc..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/approving-a-pull-request-with-required-reviews.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Approving a pull request with required reviews -intro: 'If your repository requires reviews, pull requests must have a specific number of approving reviews from people with _write_ or _admin_ permissions in the repository before they can be merged.' -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/reviewing-changes-in-pull-requests/approving-a-pull-request-with-required-reviews - - /articles/approving-a-pull-request-with-required-reviews - - /github/collaborating-with-issues-and-pull-requests/approving-a-pull-request-with-required-reviews - - /github/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/approving-a-pull-request-with-required-reviews -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Required reviews -category: - - Review pull requests ---- -For more information about required reviews, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-pull-request-reviews-before-merging). - -You can comment on a pull request, approve the changes, or request improvements before approving. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request). - -{% data reusables.search.requested_reviews_search %} - -> [!TIP] -> If a pull request you approved has changed significantly, you can dismiss your review. The pull request will need a new review before it can be merged. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/dismissing-a-pull-request-review). - -{% data reusables.repositories.sidebar-pr %} -{% data reusables.repositories.choose-pr-review %} -{% data reusables.repositories.changed-files %} -1. Review the changes in the pull request, and optionally, comment on specific lines or files. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request#starting-a-review). -{% data reusables.repositories.review-changes %} -{% data reusables.repositories.review-summary-comment %} -1. Select **Approve** to approve merging the changes proposed in the pull request. -{% data reusables.repositories.submit-review %} - -{% data reusables.repositories.request-changes-tips %} - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request) diff --git a/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/filtering-files-in-a-pull-request.md b/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/filtering-files-in-a-pull-request.md deleted file mode 100644 index 6dd12604a887..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/filtering-files-in-a-pull-request.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Filtering files in a pull request -intro: 'To help you quickly review changes in a large pull request, you can filter changed files or use the file tree to navigate between files.' -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/reviewing-changes-in-pull-requests/filtering-files-in-a-pull-request - - /articles/filtering-files-in-a-pull-request-by-file-type - - /articles/filtering-files-in-a-pull-request - - /github/collaborating-with-issues-and-pull-requests/filtering-files-in-a-pull-request - - /github/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/filtering-files-in-a-pull-request -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Filter files -category: - - Review pull requests ---- -You can filter files in a pull request by file extension type, such as `.html` or `.js`, lack of an extension, code ownership, or dotfiles. You can also use the file tree to filter by file path, navigate between files, or see a high level view of the changed files. - -## Using the file filter dropdown - -> [!TIP] -> To simplify your pull request diff view, you can also temporarily hide deleted files or files you have already viewed in the pull request diff from the file filter drop-down menu. - -{% data reusables.repositories.sidebar-pr %} -1. In the list of pull requests, click the pull request you'd like to filter. -{% data reusables.repositories.changed-files %} -1. Use the File filter dropdown menu, and select, deselect, or click the desired filters. - - ![Screenshot of the view options for a pull request. The file filter option is outlined in dark orange.](/assets/images/help/pull_requests/file-filter-option.png) - -1. Optionally, to clear the filter selection, under the **Files changed** tab, click **Clear filters**. - - ![Screenshot of the view options for a pull request. The "Clear filters" option is outlined in dark orange.](/assets/images/help/pull_requests/clear-file-filter.png) - -## Using the file tree - -{% data reusables.repositories.sidebar-pr %} -1. In the list of pull requests, click the pull request you'd like to filter. -{% data reusables.repositories.changed-files %} - -1. Click on a file in the file tree to view the corresponding file diff. If the file tree is hidden, click {% octicon "sidebar-collapse" aria-label="The sidebar collapse icon" %} to display the file tree. - - > [!NOTE] - > The file tree will not display if your screen width is too narrow or if the pull request only includes one file. - - ![Screenshot of the "Files changed" tab of a pull request. In the left sidebar, the file tree is outlined in dark orange.](/assets/images/help/repository/file-tree.png) -1. To filter by file path, enter part or all of the file path in the **Filter changed files** search box. Alternatively, use the file filter dropdown. For more information, see [Using the file filter dropdown](#using-the-file-filter-dropdown). - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-comparing-branches-in-pull-requests) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/finding-changed-methods-and-functions-in-a-pull-request) diff --git a/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/finding-changed-methods-and-functions-in-a-pull-request.md b/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/finding-changed-methods-and-functions-in-a-pull-request.md deleted file mode 100644 index de7ca8a610f1..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/finding-changed-methods-and-functions-in-a-pull-request.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: Finding changed methods and functions in a pull request -intro: 'You can quickly find proposed changes to a method or function in a pull request in *.go*, *.js*, *.ts*, *.py*, *.php*, and *.rb* files.' -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/reviewing-changes-in-pull-requests/finding-changed-methods-and-functions-in-a-pull-request - - /articles/finding-changed-methods-and-functions-in-a-pull-request - - /github/collaborating-with-issues-and-pull-requests/finding-changed-methods-and-functions-in-a-pull-request - - /github/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/finding-changed-methods-and-functions-in-a-pull-request -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Methods & functions -category: - - Review pull requests ---- -Anyone with read access to a repository can see a summary list of the functions and methods changes in certain files of a pull request. - -The summary list of methods and functions is created from these supported file types: -* Go -* JavaScript (includes TypeScript, Flow, and other types of JavaScript) -* PHP -* Python -* Ruby - -{% data reusables.repositories.sidebar-pr %} -1. In the list of pull requests, click the pull request where you'd like to find the changed functions and methods. -{% data reusables.repositories.changed-files %} -1. To see a summary list of the changed functions and methods, click **Jump to {% octicon "triangle-down" aria-hidden="true" aria-label="triangle-down" %}**. - - ![Screenshot of the "Files changed" tab for a pull request. The "Jump to" option is outlined in dark orange.](/assets/images/help/pull_requests/jump-to-menu.png) - -1. Select the changed function or method from the drop-down menu. You can also enter the name of the function or method to filter results. - - > [!NOTE] - > If you don't see the functions or methods you expected, confirm that your code compiles and doesn't contain errors. Only functions and methods changed in this pull request and found in _.go_, _.js_, _.ts_, _.py_, _.php_, and _.rb_ files appear in the drop-down menu. - -1. You'll be redirected to the first line of the function or method you selected. - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-comparing-branches-in-pull-requests) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/filtering-files-in-a-pull-request) diff --git a/content/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks.md b/content/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks.md deleted file mode 100644 index 24faad799ea5..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: About forks -intro: A fork is a new repository that shares code and visibility settings with the original "upstream" repository. -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/working-with-forks/about-forks - - /articles/about-forks - - /github/collaborating-with-issues-and-pull-requests/about-forks - - /github/collaborating-with-pull-requests/working-with-forks/about-forks -versions: - fpt: '*' - ghes: '*' - ghec: '*' -category: - - Work with forks ---- - -## About forks - -Forks are like independent copies of repositories. Unlike branches, forks give you more freedom to experiment without affecting the original project. Unlike cloned or duplicated repositories, changes from forks can be merged back into the upstream repository via pull requests, similar to a branch. - -When you view a forked repository on {% data variables.product.github %}, the upstream repository is indicated below the name of the fork. - -![Screenshot of a repository's page on GitHub. Below the name of the repository, "mona/docs", the text "forked from github/docs" is outlined in orange.](/assets/images/help/pull_requests/fork-path.png) - -## What makes forks distinct from branches - -Each fork is a complete repository with its own: - -* Branches -* Members and discussions -* Issues and pull requests -* Actions and projects -* Tags, labels, and wikis - -## When to use a fork - -There are times when a fork may be a better fit for your task than a branch would be. A fork might be better: - -* To experiment safely without affecting the original project -* To create separate space for discussions unrelated to a project's main goals -* When you might want to make your work an independent repository later - -## Which repositories can be forked? - -{% data reusables.repositories.you-can-fork %} - -## Next steps - -For instructions for forking a repository, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo). - -For more information about when you can create forks, and the permission and visibility settings of forks, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/about-permissions-and-visibility-of-forks). diff --git a/content/pull-requests/collaborating-with-pull-requests/working-with-forks/about-permissions-and-visibility-of-forks.md b/content/pull-requests/collaborating-with-pull-requests/working-with-forks/about-permissions-and-visibility-of-forks.md deleted file mode 100644 index cb325784f847..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/working-with-forks/about-permissions-and-visibility-of-forks.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: About permissions and visibility of forks -shortTitle: Permissions and visibility -intro: 'The permissions and visibility of forks depend on whether the upstream repository is public or private, {% ifversion fpt %}and whether it is owned by an organization{% else %}whether it is owned by an organization, and the policies of your enterprise{% endif %}.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -category: - - Work with forks ---- - -## About permissions for creating forks - -{% data reusables.repositories.you-can-fork %} - -* If you fork a private repository that belongs to a personal account, external collaborators also get access to the fork. -* If you fork a private {% ifversion ghec or ghes %}or internal {% endif %}repository that belongs to an organization, teams within the organization get access to the fork, but external collaborators do not. -* {% ifversion ghes %} You can add an external collaborator to a fork of a private repository that belongs to an organization if you are an owner of that organization or if your organization allows repository administrators to invite external collaborators.{% endif %}{% ifversion fpt or ghec %} You can add an external collaborator to a fork of a private repository owned by an organization if you are an organization owner, or if your organization allows repository administrators to invite external collaborators, and the external collaborator also has access to the upstream repository.{% endif %} -{% ifversion ghec or ghes %} * You can add an external collaborator to a fork of an internal repository that belongs to an organization if the external collaborator also has access to the upstream repository.{% endif %} - -{% ifversion fpt or ghec %} - -If you're a member of an {% data variables.enterprise.prodname_emu_enterprise %}, there are further restrictions on the repositories you can fork. {% ifversion ghec %}{% data reusables.enterprise-accounts.emu-forks %}{% endif %} For more information, see [AUTOTITLE](/enterprise-cloud@latest/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-enterprise-managed-users){% ifversion fpt %} in the {% data variables.product.prodname_ghe_cloud %} documentation.{% else %}.{% endif %} - -{% endif %} - -Organizations can allow or prevent the forking of any private repositories owned by the organization{% ifversion ghec or ghes %}, and enterprises can enforce policies to specify where members can create forks of private or internal repositories. Policies control the options available to the enterprise's organizations{% endif %}. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/managing-the-forking-policy-for-your-organization){% ifversion fpt %}.{% else %} and [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise#enforcing-a-policy-for-forking-private-or-internal-repositories).{% endif %} - -## About visibility of forks - -A fork is a new repository that shares code and visibility settings with the upstream repository. All forks of public repositories are public. You cannot change the visibility of a fork. - -All repositories belong to a repository network. A repository network contains the upstream repository, the upstream repository's direct forks, and all forks of those forks. All forks in the repository network have the same visibility setting. For more information, see [AUTOTITLE](/repositories/viewing-activity-and-data-for-your-repository/understanding-connections-between-repositories). - -If you delete a repository or change the repository's visibility settings, you will affect the repository's forks. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/what-happens-to-forks-when-a-repository-is-deleted-or-changes-visibility) - -If you delete a fork, any code contributions of that fork will still be accessible to the repository network. - -## About permissions of forks - -{% data reusables.repositories.private_forks_inherit_permissions %} - -Public forks do not inherit the permissions structure of the upstream repository. - -When you fork a public repository to your personal account, you can allow repository maintainers to push to your pull request branch. This includes giving them permission to make commits or delete the branch. - -This speeds up collaboration by letting maintainers: -* Make direct commits to your branch -* Run tests locally before merging -You cannot give push permissions to a fork owned by an organization. - -For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork). - -### About push rulesets for forked repositories - -{% data reusables.repositories.rulesets-push-rulesets-fork-network-information %} - -For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets#push-rulesets). - -### Important security considerations - -If you work with forks, or if you're the owner of a repository or organization that allows forking, it's important to be aware of the following security considerations. - -* Forks have their own permissions separate from the upstream repository. -* The owners of a repository that has been forked have read permission to all forks in the repository's network. -* Organization owners of a repository that has been forked have admin permission to forks created in personal user namespaces, including the ability to delete the fork and its branches. -* Organization owners of a repository that has been forked have read permission to forks created in organizations, but do not have the ability to delete the fork or its branches. -* Forks created in another organization will not be deleted when individual access is removed from the upstream repository. -* Commits to any repository in a network can be accessed from any repository in the same network, including the upstream repository, even after a fork is deleted. - -### About forks within an organization - -Forks within the same organization copy the collaborators and team settings of their upstream repositories. If a repository is owned by an organization: - -* That organization controls the permissions of its forks. -* Any teams from the upstream permission structure that exist and are visible in the target organization or user namespace will have their permissions copied. -* Admin permissions remain with the upstream owner, except when a user forks into a different organization. -* If that repository is forked to a user namespace, the organization maintains admin permissions and any teams with access maintain access. - -{% ifversion ghec or ghes %} - -### About forks within an enterprise - -Internal repositories only support a single level of forking, it is not possible to fork a private fork of an internal repository. This is intentional to simplify access and management for internal repositories which have enterprise-wide access. This differs from the behavior of public and private repositories, that allow nested forking. - -{% endif %} diff --git a/content/pull-requests/collaborating-with-pull-requests/working-with-forks/what-happens-to-forks-when-a-repository-is-deleted-or-changes-visibility.md b/content/pull-requests/collaborating-with-pull-requests/working-with-forks/what-happens-to-forks-when-a-repository-is-deleted-or-changes-visibility.md deleted file mode 100644 index d5c4da2c6cce..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/working-with-forks/what-happens-to-forks-when-a-repository-is-deleted-or-changes-visibility.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: What happens to forks when a repository is deleted or changes visibility? -intro: Deleting your repository or changing its visibility affects that repository's forks. -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/working-with-forks/what-happens-to-forks-when-a-repository-is-deleted-or-changes-visibility - - /articles/changing-the-visibility-of-a-network - - /articles/what-happens-to-forks-when-a-repository-is-deleted-or-changes-visibility - - /github/collaborating-with-issues-and-pull-requests/what-happens-to-forks-when-a-repository-is-deleted-or-changes-visibility - - /github/collaborating-with-pull-requests/working-with-forks/what-happens-to-forks-when-a-repository-is-deleted-or-changes-visibility -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Deleted or changes visibility -category: - - Work with forks ---- -{% data reusables.repositories.deleted_forks_from_private_repositories_warning %} - -## Deleting a private repository - -When you delete a private repository, all of its private forks are also deleted. - -## Deleting a public repository - -When you delete a public repository, the oldest, active public fork is chosen to be the new upstream repository. All other repositories are forked off of this new upstream and subsequent pull requests go to this new upstream repository. - -## Private forks and permissions - -{% data reusables.repositories.private_forks_inherit_permissions %} - -## Changing a public repository to a private repository - -If a public repository is made private, its public forks are split off into a new network. As with deleting a public repository, one of the existing public forks is chosen to be the new upstream repository and all other repositories are forked off of this new upstream. Subsequent pull requests go to this new upstream repository. - -In other words, a public repository's forks will remain public in their own separate repository network even after the upstream repository is made private. This allows the fork owners to continue to work and collaborate without interruption. If public forks were not moved into a separate network in this way, the owners of those forks would need to get the appropriate [access permissions](/get-started/learning-about-github/access-permissions-on-github) to pull changes from and submit pull requests to the (now private) upstream repository—even though they didn't need those permissions before. - -> [!WARNING] -> * Making a public repository private will permanently remove stars and watchers associated to users that will no longer have access to this repository. If you decide to make the repository public in the future, it will not be possible to restore these stars and watchers, and this will affect its repository rankings. -> * Dependency graph and {% data variables.product.prodname_dependabot_alerts %} will remain enabled with permission to perform read-only analysis on this repository. Any custom {% data variables.product.prodname_dependabot %} alert rules will be disabled unless {% data variables.product.prodname_code_security %} is enabled for this repository. -> * {% data variables.product.prodname_code_scanning_caps %} will become unavailable unless {% data variables.product.prodname_code_security %} is enabled for this repository. -> * Current forks will remain public and will be detached from this repository. - -{% ifversion ghes %} -If a public repository has anonymous Git read access enabled and the repository is made private, all of the repository's forks will lose anonymous Git read access and return to the default disabled setting. If a forked repository is made public, repository administrators can re-enable anonymous Git read access. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/enabling-anonymous-git-read-access-for-a-repository). -{% endif %} - -### Deleting the private repository - -If a public repository is made private and then deleted, its public forks will continue to exist in a separate network. - -## Changing a private repository to a public repository - -When a private repository is made public, all the commits in that repository, including any commits previously pushed to private forks of that repository, will be migrated to a new public repository network and become visible to everyone. Any previously created private forks will remain private but will become disconnected from the original repository that was made public. Each private fork will become a separate private repository and create its own independent network of repositories. Any new changes made to these networks will not be accessible from the original repository that was made public. - -### Deleting the public repository - -If a private repository is made public and then deleted, its private forks will continue to exist as standalone private repositories in separate networks. - -{% ifversion ghes or ghec %} - -## Changing the visibility of an internal repository - -If the policy for your enterprise permits forking, any fork of an internal repository will be private. If you change the visibility of an internal repository, any fork owned by an organization or personal account will remain private. - -### Deleting the internal repository - -If you change the visibility of an internal repository and then delete the repository, the forks will continue to exist in a separate network. - -{% endif %} - -## Further reading - -* [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/setting-repository-visibility) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks) -* [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-the-forking-policy-for-your-repository) -* [AUTOTITLE](/organizations/managing-organization-settings/managing-the-forking-policy-for-your-organization) -* [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise#enforcing-a-policy-on-forking-private-or-internal-repositories) diff --git a/content/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/about-commits.md b/content/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/about-commits.md deleted file mode 100644 index deb685c40808..000000000000 --- a/content/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/about-commits.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: About commits -intro: You can save small groups of meaningful changes as commits. -redirect_from: - - /articles/why-are-my-commits-in-the-wrong-order - - /github/committing-changes-to-your-project/why-are-my-commits-in-the-wrong-order - - /github/committing-changes-to-your-project/about-commits - - /github/committing-changes-to-your-project/creating-and-editing-commits/about-commits - - /pull-requests/committing-changes-to-your-project/viewing-and-comparing-commits/commit-branch-and-tag-labels -versions: - fpt: '*' - ghes: '*' - ghec: '*' -category: - - Commit changes ---- -## About commits - -{% data reusables.commits.about-commits %} - -If the repository you are committing to has compulsory commit signoffs enabled, and you are committing via the web interface, you will automatically sign off on the commit as part of the commit process. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-the-commit-signoff-policy-for-your-repository). - -You can add a co-author on any commits you collaborate on. For more information, see [AUTOTITLE](/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-with-multiple-authors). - -{% ifversion fpt or ghec %} -You can also create a commit on behalf of an organization. For more information, see [AUTOTITLE](/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-on-behalf-of-an-organization).{% endif %} - -Rebasing allows you to change a series of commits and can modify the order of the commits in your timeline. For more information, see [AUTOTITLE](/get-started/using-git/about-git-rebase). - -## About commit branches and tag labels - -You can see which branch a commit is on by looking at the labels beneath the commit on the commit page. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.navigate-to-commit-page %} -{% data reusables.repositories.navigate-to-commit %} -1. To see what branch the commit is on, check the label below the commit message. - - ![Screenshot of a commit summary. A branch icon and "main" are highlighted with an orange outline.](/assets/images/help/commits/commit-branch-indicator.png) - -If your commit is not on the default branch (`main`), the label will show the branches which contain the commit. If the commit is part of an unmerged pull request, you can click the link to go to the pull request. - -Once the commit is on the default branch, any tags that contain the commit will be shown and the default branch will be the only branch listed. For more information on tags, see [Git Basics - Tagging](https://git-scm.com/book/en/v2/Git-Basics-Tagging) in the Git documentation. - -![Screenshot of a commit summary. The tag icon and "v2.3.4" are highlighted with an orange outline.](/assets/images/help/commits/commit-tag-label.png) - -## Using the file tree - -You can use the file tree to navigate between files in a commit. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.navigate-to-commit-page %} -{% data reusables.repositories.navigate-to-commit %} -1. Click on a file in the file tree to view the corresponding file diff. If the file tree is hidden, click {% octicon "sidebar-collapse" aria-label="The sidebar collapse icon" %} to display the file tree. - - > [!NOTE] - > The file tree will not display if your screen width is too narrow or if the commit only includes one file. - - ![Screenshot of the "Files changed" tab of a pull request. In the left sidebar, the file tree is outlined in dark orange.](/assets/images/help/repository/file-tree.png) -1. To filter by file path, enter part or all of the file path in the **Filter changed files** search box. - -## Further reading - -* [AUTOTITLE](/desktop/making-changes-in-a-branch/committing-and-reviewing-changes-to-your-project-in-github-desktop#about-commits) on {% data variables.product.prodname_desktop %} diff --git a/content/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/changing-a-commit-message.md b/content/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/changing-a-commit-message.md deleted file mode 100644 index 19a001e3a0e5..000000000000 --- a/content/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/changing-a-commit-message.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: Changing a commit message -redirect_from: - - /articles/can-i-delete-a-commit-message - - /articles/changing-a-commit-message - - /github/committing-changes-to-your-project/changing-a-commit-message - - /github/committing-changes-to-your-project/creating-and-editing-commits/changing-a-commit-message -intro: 'If a commit message contains unclear, incorrect, or sensitive information, you can amend it locally and push a new commit with a new message to {% data variables.product.github %}. You can also change a commit message to add missing information.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -category: - - Commit changes ---- -## Rewriting the most recent commit message - -You can change the most recent commit message using the `git commit --amend` command. - -In Git, the text of the commit message is part of the commit. Changing the commit message will change the commit ID—i.e., the SHA1 checksum that names the commit. Effectively, you are creating a new commit that replaces the old one. - -## Commit has not been pushed online - -If the commit only exists in your local repository and has not been pushed to {% data variables.location.product_location %}, you can amend the commit message with the `git commit --amend` command. - -1. On the command line, navigate to the repository that contains the commit you want to amend. -1. Type `git commit --amend` and press **Enter**. -1. In your text editor, edit the commit message, and save the commit. - * You can add a co-author by adding a trailer to the commit. For more information, see [AUTOTITLE](/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-with-multiple-authors). -{% ifversion fpt or ghec %} - * You can create commits on behalf of your organization by adding a trailer to the commit. For more information, see [AUTOTITLE](/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-on-behalf-of-an-organization). -{% endif %} - -The new commit and message will appear on {% data variables.location.product_location %} the next time you push. - -> [!TIP] -> You can change the default text editor for Git by changing the `core.editor` setting. For more information, see [Basic Client Configuration](https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration#_basic_client_configuration) in the Git manual. - -## Amending older or multiple commit messages - -If you have already pushed the commit to {% data variables.location.product_location %}, you will have to force push a commit with an amended message. - -> [!WARNING] -> We strongly discourage force pushing, since this changes the history of your repository. If you force push, people who have already cloned your repository will have to manually fix their local history. For more information, see [Recovering from upstream rebase](https://git-scm.com/docs/git-rebase#_recovering_from_upstream_rebase) in the Git manual. - -**Changing the message of the most recently pushed commit** - -1. Follow the [steps above](/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/changing-a-commit-message#commit-has-not-been-pushed-online) to amend the commit message. -1. Use the `push --force-with-lease` command to force push over the old commit. - - ```shell - git push --force-with-lease origin EXAMPLE-BRANCH - ``` - -**Changing the message of older or multiple commit messages** - -If you need to amend the message for multiple commits or an older commit, you can use interactive rebase, then force push to change the commit history. - -1. On the command line, navigate to the repository that contains the commit you want to amend. -1. Use the `git rebase -i HEAD~n` command to display a list of the last `n` commits in your default text editor. - - ```shell - # Displays a list of the last 3 commits on the current branch - $ git rebase -i HEAD~3 - ``` - - The list will look similar to the following: - - ```shell - pick e499d89 Delete CNAME - pick 0c39034 Better README - pick f7fde4a Change the commit message but push the same commit. - - # Rebase 9fdb3bd..f7fde4a onto 9fdb3bd - # - # Commands: - # p, pick = use commit - # r, reword = use commit, but edit the commit message - # e, edit = use commit, but stop for amending - # s, squash = use commit, but meld into previous commit - # f, fixup = like "squash", but discard this commit's log message - # x, exec = run command (the rest of the line) using shell - # - # These lines can be re-ordered; they are executed from top to bottom. - # - # If you remove a line here THAT COMMIT WILL BE LOST. - # - # However, if you remove everything, the rebase will be aborted. - # - # Note that empty commits are commented out - ``` - -1. Replace `pick` with `reword` before each commit message you want to change. - - ```shell - pick e499d89 Delete CNAME - reword 0c39034 Better README - reword f7fde4a Change the commit message but push the same commit. - ``` - -1. Save and close the commit list file. -1. In each resulting commit file, type the new commit message, save the file, and close it. -1. When you're ready to push your changes to GitHub, use the push --force command to force push over the old commit. - - ```shell - git push --force origin EXAMPLE-BRANCH - ``` - -For more information on interactive rebase, see [Interactive mode](https://git-scm.com/docs/git-rebase#_interactive_mode) in the Git manual. - -> [!NOTE] -> As before, amending the commit message will result in a new commit with a new ID. However, in this case, every commit that follows the amended commit will also get a new ID because each commit also contains the ID of its parent. - -> [!WARNING] -> If you have included sensitive information in a commit message, force pushing a commit with an amended commit may not remove the original commit from {% data variables.product.github %}. The old commit will not be a part of a subsequent clone; however, it may still be cached on {% data variables.product.github %} and accessible via the commit ID. You must contact {% data variables.contact.contact_support %} with the old commit ID to have it purged from the remote repository. - -## Further reading - -* [AUTOTITLE](/authentication/managing-commit-signature-verification/signing-commits) diff --git a/content/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-on-behalf-of-an-organization.md b/content/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-on-behalf-of-an-organization.md deleted file mode 100644 index df0e355ef36c..000000000000 --- a/content/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-on-behalf-of-an-organization.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: Creating a commit on behalf of an organization -intro: 'You can create commits on behalf of an organization by adding a trailer to the commit''s message. Commits attributed to an organization include an `on-behalf-of` badge on {% data variables.product.github %}.' -redirect_from: - - /articles/creating-a-commit-on-behalf-of-an-organization - - /github/committing-changes-to-your-project/creating-a-commit-on-behalf-of-an-organization - - /github/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-on-behalf-of-an-organization -versions: - fpt: '*' - ghec: '*' -shortTitle: On behalf of an organization -category: - - Commit changes ---- - -To create commits on behalf of an organization: - -* You must be a member of the organization indicated in the trailer. -* You must sign the commit. -* Your commit email and the organization email must be in a domain verified by the organization. -* Your commit message must end with the commit trailer `on-behalf-of: @org `. - * `org` is the organization's login. - * `name@organization.com` is in the organization's domain. - -Organizations can use the `name@organization.com` email as a public point of contact for open source efforts. - -## Creating commits with an `on-behalf-of` badge on the command line - -1. Type your commit message and a short, meaningful description of your changes. After your commit description, instead of a closing quotation, add two empty lines. - - ```shell - $ git commit -m "Refactor usability tests. - > - > - ``` - - > [!TIP] - > If you're using a text editor on the command line to type your commit message, ensure there are two newlines between the end of your commit description and the `on-behalf-of:` commit trailer. - -1. On the next line of the commit message, type `on-behalf-of: @org `, then a closing quotation mark. - - ```shell - $ git commit -m "Refactor usability tests. - > - > - on-behalf-of: @ORG NAME@ORGANIZATION.COM" - ``` - -The new commit, message, and badge will appear on {% data variables.product.prodname_dotcom %} the next time you push. For more information, see [AUTOTITLE](/get-started/using-git/pushing-commits-to-a-remote-repository). - -## Creating commits with an `on-behalf-of` badge on {% data variables.product.github %} - -After you've made changes in a file using the web editor on {% data variables.product.github %}, you can create a commit on behalf of your organization by adding an `on-behalf-of:` trailer to the commit's message. - -1. Click **Commit changes...** -1. In the "Commit message" field, type a short, meaningful commit message that describes the changes you made. -1. In the text box below your commit message, add `on-behalf-of: @org `. -1. Click **Commit changes** or **Propose changes**. - -The new commit, message, and badge will appear on {% data variables.product.prodname_dotcom %}. - -## Further reading - -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/viewing-contributions-on-your-profile) -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/why-are-my-contributions-not-showing-up-on-my-profile) -* [AUTOTITLE](/repositories/viewing-activity-and-data-for-your-repository/viewing-a-projects-contributors) -* [AUTOTITLE](/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/changing-a-commit-message) diff --git a/content/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-with-multiple-authors.md b/content/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-with-multiple-authors.md deleted file mode 100644 index af1828d926b6..000000000000 --- a/content/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-with-multiple-authors.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: Creating a commit with multiple authors -intro: 'You can attribute a commit to more than one author by adding one or more `Co-authored-by` trailers to the commit''s message. Co-authored commits are visible on {% data variables.product.github %}{% ifversion ghes %} and can be included in the profile contributions graph and the repository''s statistics{% endif %}.' -redirect_from: - - /articles/creating-a-commit-with-multiple-authors - - /github/committing-changes-to-your-project/creating-a-commit-with-multiple-authors - - /github/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-with-multiple-authors -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: With multiple authors -category: - - Commit changes ---- -## Required co-author information - -Before you can add a co-author to a commit, you must know the appropriate email to use for each co-author. For the co-author's commit to count as a contribution, you must use the email associated with their account on {% data variables.location.product_location %}. - -{% ifversion fpt or ghec %} - -If a person chooses to keep their email address private, you should use their {% data variables.product.github %}-provided `no-reply` email to protect their privacy. Otherwise, the co-author's email will be available to the public in the commit message. If you want to keep your email private, you can choose to use a {% data variables.product.github %}-provided `no-reply` email for Git operations and ask other co-authors to list your `no-reply` email in commit trailers. - -For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address). - -> [!TIP] -> You can help a co-author find their preferred email address by sharing this information: -> * To find your {% data variables.product.github %}-provided `no-reply` email, navigate to your email settings page under "Keep my email address private." -> * To find the email you used to configure Git on your computer, run `git config user.email` on the command line. - -{% endif %} - -## Creating co-authored commits using {% data variables.product.prodname_desktop %} - -You can use {% data variables.product.prodname_desktop %} to create a commit with a co-author. For more information, see [AUTOTITLE](/desktop/making-changes-in-a-branch/committing-and-reviewing-changes-to-your-project-in-github-desktop#write-a-commit-message-and-push-your-changes) and [{% data variables.product.prodname_desktop %}](https://desktop.github.com). - -## Creating co-authored commits on the command line - -{% data reusables.pull_requests.collect-co-author-commit-git-config-info %} - -1. Type your commit message and a short, meaningful description of your changes. After your commit description, instead of a closing quotation, add an empty line. - - ```shell - $ git commit -m "Refactor usability tests. - > - > - ``` - - > [!TIP] - > If you're using a text editor on the command line to type your commit message, ensure there is a blank line (two consecutive newlines) between the end of your commit description and the `Co-authored-by:` commit trailer. - -1. On the next line of the commit message, type `Co-authored-by: name ` with specific information for each co-author. After the co-author information, add a closing quotation mark. - - If you're adding multiple co-authors, give each co-author their own line and `Co-authored-by:` commit trailer. Do not add blank lines between each co-author line. - - ```shell - $ git commit -m "Refactor usability tests. - > - > Co-authored-by: NAME - > Co-authored-by: ANOTHER-NAME " - ``` - -The new commit and message will appear on {% data variables.location.product_location %} the next time you push. For more information, see [AUTOTITLE](/get-started/using-git/pushing-commits-to-a-remote-repository). - -## Creating co-authored commits on {% data variables.product.github %} - -After you've made changes in a file using the web editor on {% data variables.product.github %}, you can create a co-authored commit by adding a `Co-authored-by:` trailer to the commit's message. - -{% data reusables.pull_requests.collect-co-author-commit-git-config-info %} -1. Click **Commit changes...** -1. In the "Commit message" field, type a short, meaningful commit message that describes the changes you made. -1. In the text box below your commit message, add `Co-authored-by: name ` with specific information for each co-author. If you're adding multiple co-authors, give each co-author their own line and `Co-authored-by:` commit trailer. -1. Click **Commit changes** or **Propose changes**. - -The new commit and message will appear on {% data variables.location.product_location %}. - -## Further reading - -{% ifversion ghes %} -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/viewing-contributions-on-your-profile) -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/why-are-my-contributions-not-showing-up-on-my-profile){% endif %} -* [AUTOTITLE](/repositories/viewing-activity-and-data-for-your-repository/viewing-a-projects-contributors) -* [AUTOTITLE](/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/changing-a-commit-message) -* [AUTOTITLE](/desktop/making-changes-in-a-branch/committing-and-reviewing-changes-to-your-project-in-github-desktop#4-write-a-commit-message-and-push-your-changes) in the {% data variables.product.prodname_desktop %} documentation diff --git a/content/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/index.md b/content/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/index.md deleted file mode 100644 index e2b3c15ee67e..000000000000 --- a/content/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/index.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Creating and editing commits -intro: '' -redirect_from: - - /articles/creating-and-editing-commits - - /github/committing-changes-to-your-project/creating-and-editing-commits -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /about-commits - - /creating-a-commit-with-multiple-authors - - /creating-a-commit-on-behalf-of-an-organization - - /changing-a-commit-message -shortTitle: Create & edit commits ---- - diff --git a/content/pull-requests/committing-changes-to-your-project/index.md b/content/pull-requests/committing-changes-to-your-project/index.md deleted file mode 100644 index 5670a0f729fe..000000000000 --- a/content/pull-requests/committing-changes-to-your-project/index.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Committing changes to your project -intro: You can manage code changes in a repository by grouping work into commits. -redirect_from: - - /categories/21/articles - - /categories/commits - - /categories/committing-changes-to-your-project - - /github/committing-changes-to-your-project -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /creating-and-editing-commits - - /viewing-and-comparing-commits - - /troubleshooting-commits -shortTitle: Commit changes to your project ---- diff --git a/content/pull-requests/committing-changes-to-your-project/troubleshooting-commits/commit-exists-on-github-but-not-in-my-local-clone.md b/content/pull-requests/committing-changes-to-your-project/troubleshooting-commits/commit-exists-on-github-but-not-in-my-local-clone.md deleted file mode 100644 index 473219ac1cc6..000000000000 --- a/content/pull-requests/committing-changes-to-your-project/troubleshooting-commits/commit-exists-on-github-but-not-in-my-local-clone.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -title: Commit exists on GitHub but not in my local clone -intro: 'Sometimes a commit will be viewable on {% data variables.product.github %}, but will not exist in your local clone of the repository.' -redirect_from: - - /articles/commit-exists-on-github-but-not-in-my-local-clone - - /github/committing-changes-to-your-project/commit-exists-on-github-but-not-in-my-local-clone - - /github/committing-changes-to-your-project/troubleshooting-commits/commit-exists-on-github-but-not-in-my-local-clone -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Commit missing in local clone -category: - - Commit changes ---- -When you use `git show` to view a specific commit on the command line, you may get a fatal error. - -For example, you may receive a `bad object` error locally: - -```shell -$ git show 1095ff3d0153115e75b7bca2c09e5136845b5592 -> fatal: bad object 1095ff3d0153115e75b7bca2c09e5136845b5592 -``` - -However, when you view the commit on {% data variables.location.product_location %}, you'll be able to see it without any problems: - -`github.com/ACCOUNT/REPOSITORY/commit/1095ff3d0153115e75b7bca2c09e5136845b5592` - -There are several possible explanations: - -* The local repository is out of date. -* The branch that contains the commit was deleted, so the commit is no longer referenced. -* Someone force pushed over the commit. - -## The local repository is out of date - -Your local repository may not have the commit yet. To get information from your remote repository to your local clone, use `git fetch`: - -```shell -git fetch REMOTE -``` - -This safely copies information from the remote repository to your local clone without making any changes to the files you have checked out. -You can use `git fetch upstream` to get information from a repository you've forked, or `git fetch origin` to get information from a repository you've only cloned. - -> [!TIP] -> For more information, read about [managing remotes and fetching data](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes) in the [Pro Git](https://git-scm.com/book) book. - -## The branch that contained the commit was deleted - -If a collaborator on the repository has deleted the branch containing the commit -or has force pushed over the branch, the missing commit may have been orphaned -(i.e. it cannot be reached from any reference) and therefore will not be fetched -into your local clone. - -Fortunately, if any collaborator has a local clone of the repository with the -missing commit, they can push it back to {% data variables.product.github %}. They need to make sure the commit -is referenced by a local branch and then push it as a new branch to {% data variables.product.github %}. - -Let's say that the person still has a local branch (call it `B`) that contains -the commit. This might be tracking the branch that was force pushed or deleted -and they simply haven't updated yet. To preserve the commit, they can push that -local branch to a new branch (call it `recover-B`) on {% data variables.product.github %}. For this example, -let's assume they have a remote named `upstream` via which they have push access -to `github.com/ACCOUNT/REPOSITORY`. - -The other person runs: - -```shell -$ git branch recover-B B -# Create a new local branch referencing the commit -$ git push upstream B:recover-B -# Push local B to new upstream branch, creating new reference to commit -``` - -Now, _you_ can run: - -```shell -$ git fetch upstream recover-B -# Fetch commit into your local repository. -``` - -## Avoid force pushes - -Avoid force pushing to a repository unless absolutely necessary. This is especially true if more than one person can push to the repository. If someone force pushes to a repository, the force push may overwrite commits that other people based their work on. Force pushing changes the repository history and can corrupt pull requests. - -## Further reading - -* ["Working with Remotes" from the _Pro Git_ book](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes) -* ["Data Recovery" from the _Pro Git_ book](https://git-scm.com/book/en/v2/Git-Internals-Maintenance-and-Data-Recovery) diff --git a/content/pull-requests/committing-changes-to-your-project/troubleshooting-commits/index.md b/content/pull-requests/committing-changes-to-your-project/troubleshooting-commits/index.md deleted file mode 100644 index 0438b2669030..000000000000 --- a/content/pull-requests/committing-changes-to-your-project/troubleshooting-commits/index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Troubleshooting commits -intro: '' -redirect_from: - - /articles/troubleshooting-commits - - /github/committing-changes-to-your-project/troubleshooting-commits -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /commit-exists-on-github-but-not-in-my-local-clone - - /why-are-my-commits-linked-to-the-wrong-user - - /my-commit-is-blocked-by-push-protection ---- - diff --git a/content/pull-requests/committing-changes-to-your-project/troubleshooting-commits/my-commit-is-blocked-by-push-protection.md b/content/pull-requests/committing-changes-to-your-project/troubleshooting-commits/my-commit-is-blocked-by-push-protection.md deleted file mode 100644 index d45b24fa69db..000000000000 --- a/content/pull-requests/committing-changes-to-your-project/troubleshooting-commits/my-commit-is-blocked-by-push-protection.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: My commit is blocked by push protection -intro: 'To keep your repository secure, push protection prevents you from accidentally committing secrets to the repository.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Commit blocked by push protection -category: - - Commit changes ---- - -## Understanding why push protection has blocked your commit - -Leaked secrets can pose serious security risks to your repository and your supply chain. Push protection prevents you from accidentally introducing secrets to your codebase where they could be exploited by malicious actors. - -If the repository you're contributing to on {% data variables.product.github %} is secured by push protection, you'll encounter a push protection block whenever you: - -* **Push commits** containing recognized secrets **from the command line** to the remote repository. -* **Commit changes** or upload files containing recognized secrets to a repository in the **{% data variables.product.github %} UI**. -* **Make certain requests** containing recognized secrets in **the REST API**. - -## Resolving a push protection block - -In order to resolve the block, you should remove the secret from the commit (or request). If you believe the secret is safe to push, you may be able to bypass the block. For more information on how to remove the secret or, if necessary, bypass the block, see: - -* [AUTOTITLE](/code-security/secret-scanning/working-with-secret-scanning-and-push-protection/working-with-push-protection-from-the-command-line) -* [AUTOTITLE](/code-security/secret-scanning/working-with-secret-scanning-and-push-protection/working-with-push-protection-in-the-github-ui) -* [AUTOTITLE](/code-security/secret-scanning/working-with-secret-scanning-and-push-protection/working-with-push-protection-from-the-rest-api) - -## Further reading - -* [AUTOTITLE](/code-security/secret-scanning/introduction/about-push-protection) -* [AUTOTITLE](/code-security/secret-scanning/introduction/supported-secret-scanning-patterns) diff --git a/content/pull-requests/committing-changes-to-your-project/troubleshooting-commits/why-are-my-commits-linked-to-the-wrong-user.md b/content/pull-requests/committing-changes-to-your-project/troubleshooting-commits/why-are-my-commits-linked-to-the-wrong-user.md deleted file mode 100644 index 65a07c679a71..000000000000 --- a/content/pull-requests/committing-changes-to-your-project/troubleshooting-commits/why-are-my-commits-linked-to-the-wrong-user.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: Why are my commits linked to the wrong user? -redirect_from: - - /articles/how-do-i-get-my-commits-to-link-to-my-github-account - - /articles/why-are-my-commits-linked-to-the-wrong-user - - /github/committing-changes-to-your-project/why-are-my-commits-linked-to-the-wrong-user - - /github/committing-changes-to-your-project/troubleshooting-commits/why-are-my-commits-linked-to-the-wrong-user -intro: '{% data variables.product.github %} uses the email address in the commit header to link the commit to a {% data variables.product.github %} user. If your commits are being linked to another user, or not linked to a user at all, you may need to change your local Git configuration settings, add an email address to your account email settings, or do both.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Linked to wrong user -category: - - Commit changes ---- - -> [!NOTE] -> If your commits are linked to another user, that does not mean the user can access your repository. A user can only access a repository you own if you add them as a collaborator or add them to a team that has access to the repository. - -## Commits are linked to another user - -If your commits are linked to another user, that means the email address in your local Git configuration settings is connected to that user's {% data variables.product.github %} account. In this case, you can change the email in your local Git configuration settings and add the new email address to your account to link future commits. - -1. To change the email address in your local Git configuration, follow the steps in [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address#setting-your-commit-email-address-in-git). If you work on multiple machines, you will need to change this setting on each one. -1. Add the email address from step 2 to your account settings by following the steps in [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/adding-an-email-address-to-your-github-account). - -Commits you make from this point forward will be linked to your account. - -## Commits are not linked to any user - -If your commits are not linked to any user, the commit author's name will not be rendered as a link to a user profile. To check the email address used for those commits and connect commits to your account, take the following steps. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.navigate-to-commit-page %} -{% data reusables.repositories.navigate-to-commit %} -1. To read a message about why the commit is not linked, hover over the blue {% octicon "question" aria-label="Question mark" %} to the right of the username. - - * **Unrecognized author (with email address)** If you see this message with an email address, the address you used to author the commit is not connected to your {% data variables.product.github %} account. To link your commits, [add the email address to your GitHub email settings](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/adding-an-email-address-to-your-github-account). If the email address has a Gravatar associated with it, the Gravatar will be displayed next to the commit, rather than the default gray Octocat. - * **Unrecognized author (no email address)** If you see this message without an email address, you used a generic email address that can't be connected to your {% data variables.product.github %} account. You will need to [set your commit email address in Git](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address), then [add the new address to your GitHub email settings](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/adding-an-email-address-to-your-github-account) to link your future commits. Old commits will not be linked. - * **Invalid email** The email address in your local Git configuration settings is either blank or not formatted as an email address. You will need to [set your commit email address in Git](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address), then [add the new address to your GitHub email settings](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/adding-an-email-address-to-your-github-account) to link your future commits. Old commits will not be linked. - -> [!WARNING] -> If your local Git configuration contained a generic email address, or an email address that was already attached to another user's account, then your previous commits will not be linked to your account. While Git does allow you to change the email address used for previous commits, we strongly discourage this, especially in a shared repository. - -## Further reading - -* [AUTOTITLE](/search-github/searching-on-github/searching-commits) diff --git a/content/pull-requests/committing-changes-to-your-project/viewing-and-comparing-commits/comparing-commits.md b/content/pull-requests/committing-changes-to-your-project/viewing-and-comparing-commits/comparing-commits.md deleted file mode 100644 index 22c3687f4a93..000000000000 --- a/content/pull-requests/committing-changes-to-your-project/viewing-and-comparing-commits/comparing-commits.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Comparing commits -intro: 'You can compare the state of your repository across branches, tags, commits, forks, and dates.' -redirect_from: - - /articles/comparing-commits-across-time - - /github/committing-changes-to-your-project/comparing-commits-across-time - - /github/committing-changes-to-your-project/comparing-commits - - /github/committing-changes-to-your-project/viewing-and-comparing-commits/comparing-commits -versions: - fpt: '*' - ghes: '*' - ghec: '*' -category: - - Commit changes ---- -To compare different versions of your repository, append `/compare` to your repository's path. - -We'll demonstrate the power of Compare by looking at the compare page for [a fork of the Linguist repo](https://github.com/octocat/linguist), which is at [https://github.com/octocat/linguist/compare/master...octocat:master](https://github.com/octocat/linguist/compare/master...octocat:master). - -Every repository's Compare view contains two drop down menus: `base` and `compare`. - -`base` should be considered the starting point of your comparison, and `compare` is the endpoint. During a comparison, you can always change your `base` and `compare` points by clicking on **Edit**. - -## Comparing branches - -The most common use of Compare is to compare branches, such as when you're starting a new pull request. You'll always be taken to the branch comparison view when starting [a new pull request](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request). - -To compare branches, you can select a branch name from the `compare` drop down menu at the top of the page. - -Here's an example of a [comparison between two branches](https://github.com/octocat/linguist/compare/master...octocat:an-example-comparison-for-docs). - -## Comparing tags - -Comparing release tags will show you changes to your repository since the last release. -For more information, see [AUTOTITLE](/repositories/releasing-projects-on-github/comparing-releases). - -To compare tags, you can select a tag name from the `compare` drop-down menu at the top of the page. - -Here's an example of a [comparison between two tags](https://github.com/octocat/linguist/compare/v2.2.0...octocat:v2.3.3). - -> [!NOTE] -> If a branch and a tag have the same name, the branch will be used when comparing commits. You can compare the tag specifically by adding `tags/` to the tag name. - -## Comparing commits - -You can also compare two arbitrary commits in your repository or its forks on {% data variables.product.prodname_dotcom %} in a two-dot diff comparison. - -To quickly compare two commits or Git Object IDs (OIDs) directly with each other in a two-dot diff comparison on {% data variables.product.prodname_dotcom %}, edit the URL of your repository's "Comparing changes" page. - -{% data reusables.repositories.two-dot-diff-comparison-example-urls %} - -To learn more about other comparison options, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-comparing-branches-in-pull-requests#three-dot-and-two-dot-git-diff-comparisons). - -## Comparing across forks - -You can compare your base repository and any forked repository. This is the view that's presented when a user performs a Pull Request to a project. - -To compare branches on different repositories, preface the branch names with user names. For example, by specifying `octocat:main` for `base` and `octo-org:main` for `compare`, you can compare the `main` branch of the repositories respectively owned by `octocat` and `octo-org`. - -You can also preface the branch name with a user name and a repository name. For example, specifying `octocat:awesome-app:main` would use the `main` branch in the `octocat/awesome-app` repository. This can be useful in large organizations, where you might have an upstream repository and a fork both owned by the organization. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks). - -Here's an example of a [comparison between two repositories](https://github.com/github-linguist/linguist/compare/master...octocat:master). - -## Comparisons across commits - -You can compare a single commit in Git to the commit's predecessors using two types of notation. - -| Notation | Meaning | Example | Comparison | -| :-: | :- | :- | :- | -| `^` | One commit prior. Repeat the `^` character to indicate one more commit further back in the history. | `96d29b7^^^^^`

Represents the commit five commits prior to `96d29b7`. | [View comparison](https://github.com/octocat/linguist/compare/octocat:96d29b7%5E%5E%5E%5E%5E...octocat:96d29b7) | -| `~N` | N commit(s) prior. | `96d29b7~5`

Represents the commit five commits prior to `96d29b7`. | [View comparison](https://github.com/octocat/linguist/compare/octocat:96d29b7%7E5...octocat:96d29b7) | - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-base-branch-of-a-pull-request) diff --git a/content/pull-requests/committing-changes-to-your-project/viewing-and-comparing-commits/differences-between-commit-views.md b/content/pull-requests/committing-changes-to-your-project/viewing-and-comparing-commits/differences-between-commit-views.md deleted file mode 100644 index 3831ff9894ee..000000000000 --- a/content/pull-requests/committing-changes-to-your-project/viewing-and-comparing-commits/differences-between-commit-views.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Differences between commit views -intro: You might observe differences in commit history depending on the chosen viewing method. -redirect_from: - - /articles/differences-between-commit-views - - /github/committing-changes-to-your-project/differences-between-commit-views - - /github/committing-changes-to-your-project/viewing-and-comparing-commits/differences-between-commit-views -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Commit views -category: - - Commit changes ---- -On {% data variables.product.github %}, you can see the commit history of a repository by: - -* Navigating to [the commits page](https://github.com/rust-lang/rust/commits/main) of a repository by clicking the clock icon with the number of commits at the top of the main repository view. -* Navigating to [the commit history for a specific file](https://github.com/rust-lang/rust/commits/main/README.md) by clicking on a file, then clicking **History**, to get. - -These two commit views may show _different_ information at times. The history for a single file may omit commits found on the repository's commit history. - -Git has several different ways of showing the history of a repository. When Git shows the history of a single file, it simplifies history by omitting -commits that did not change the file. Instead of looking at every commit to -decide whether it touched the file, Git will omit a whole branch if that branch, -when merged, did not impact the final contents of the file. Any commits on the -branch that touched the file will not be shown. - -For a file's commit history, {% data variables.product.github %} explicitly follows this simple strategy. It makes the history simpler by removing commits that didn't contribute to the final result. For example, if a side branch made a change and then reverted it, that commit would not show up in the branch history. This makes reviewing branches more efficient, since you only see the commits that affect the file. - -This truncated view might not always contain the information you're -after. If you want to see the entire history, {% data variables.product.github %} provides a view with more -information on a repository's commits page. - -For more information on how Git considers commit history, see [the "History Simplification"](https://git-scm.com/docs/git-log#_history_simplification) section of the `git log` help article. - -## Further reading - -* [AUTOTITLE](/authentication/managing-commit-signature-verification/signing-commits) -* [AUTOTITLE](/search-github/searching-on-github/searching-commits) diff --git a/content/pull-requests/committing-changes-to-your-project/viewing-and-comparing-commits/index.md b/content/pull-requests/committing-changes-to-your-project/viewing-and-comparing-commits/index.md deleted file mode 100644 index 4f165177ce96..000000000000 --- a/content/pull-requests/committing-changes-to-your-project/viewing-and-comparing-commits/index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Viewing and comparing commits -intro: '' -redirect_from: - - /articles/viewing-and-comparing-commits - - /github/committing-changes-to-your-project/viewing-and-comparing-commits -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /comparing-commits - - /differences-between-commit-views -shortTitle: View & compare commits ---- - diff --git a/content/pull-requests/concepts/deploying-code.md b/content/pull-requests/concepts/deploying-code.md new file mode 100644 index 000000000000..432b7e0864c7 --- /dev/null +++ b/content/pull-requests/concepts/deploying-code.md @@ -0,0 +1,66 @@ +--- +title: Deploying code +shortTitle: Deploy code +intro: 'Validate pre-deployment checks, choose merge strategies, and manage branches effectively when deploying code.' +versions: + fpt: '*' + ghes: '*' + ghec: '*' +contentType: concepts +--- + +The final step for a pull request is to get finished work into the deployment branch. This usually means merging your changes into the release or main branch. Before that happens, you will need to confirm that the change meets the project's requirements. + +## Validating pre-deployment checks + +Before you merge, you will confirm that the change is safe to deploy. **Status checks** show whether commits meet the conditions set for the repository, such as continuous integration builds, tests, code scanning, or deployment checks. They help you and reviewers understand whether a pull request is ready to merge. + +Repositories often require certain conditions before a pull request can merge, including: + +* Required status checks that must pass, such as application health and readiness checks run by your deployment pipeline. +* Required reviews or code owner approvals. +* Merge conflicts must be resolved. + +Protected branches enforce these requirements so deployment branches stay stable. + +Not all checks are the same. Rich checks created by products like {% data variables.product.prodname_actions %} can report detailed logs and annotations, while simpler commit statuses can be posted by a variety of connected systems. Understanding these helps you interpret why a pull request is or isn't ready. + +## Merging code into the release or main branch + +When the requirements are met, you merge the pull request to bring its commits into the base branch. You can also automate merging so a pull request merges as soon as its requirements are met. Pull requests offer different merge strategies depending on how you want the repository history to look: + +* **Merge commit** preserves every commit from the pull request branch and adds an explicit merge point. +* **Squash and merge** combines all commits into a single commit for a concise history. +* **Rebase and merge** adds each commit onto the base branch for a linear history without a merge commit. + +The best strategy depends on how much detail your team wants to preserve. + +## Enforcing requirements at scale + +As merging gets busier, teams add controls to keep merges safe and predictable: + +* **Rulesets and branch protections** can require an up-to-date branch, signed commits, linear history, or specific status checks before merging. +* A **merge queue** lets a high-traffic protected branch accept many pull requests without breaking. It tests each one against the latest version of the base branch and merges them in order once checks pass. When a branch uses a merge queue, the available merge options differ from a standard merge. + +> [!NOTE] +> {% data reusables.gated-features.merge-queue %} + +## Connecting merges to deployment + +Merging is often the trigger that ships code. {% data variables.product.prodname_actions %} can run deployment workflows when a pull request merges into a release or main branch. **Deployment environments** add another layer of pre-deployment safety: you can require specific reviewers, wait timers, or branch restrictions before a deployment proceeds, and these are surfaced alongside your other checks. + +## Recovering after a merge + +Even with checks in place, some merges need to be undone. You can revert a merged pull request to create a new pull request that reverses the changes. Be aware, a pull request can be marked as merged *indirectly* on rare occasions, if its commits reach the base branch through another path. This can bypass the protections on that specific pull request. See [AUTOTITLE](/pull-requests/how-tos/merge-and-close-pull-requests/reverting-a-pull-request) and [AUTOTITLE](/pull-requests/reference/pull-request-merges#indirect-merges). + +## Closing pull requests that won't be merged + +Not every pull request should merge. If a change is no longer needed or is superseded by other work, you can close the pull request without merging it. Closing keeps the discussion and history for reference while signaling that the change will not move forward. + +After a pull request is merged or closed, its head branch is often no longer needed. Deleting unused branches keeps the repository easier to navigate. + +## Further reading + +* [AUTOTITLE](/pull-requests/how-tos/merge-and-close-pull-requests/merging-a-pull-request) +* [AUTOTITLE](/pull-requests/reference/status-checks) +* [AUTOTITLE](/actions/how-tos/deploy/configure-and-manage-deployments/manage-environments) diff --git a/content/pull-requests/concepts/giving-reviews.md b/content/pull-requests/concepts/giving-reviews.md new file mode 100644 index 000000000000..355c7ec349aa --- /dev/null +++ b/content/pull-requests/concepts/giving-reviews.md @@ -0,0 +1,48 @@ +--- +title: Giving reviews +shortTitle: Give reviews +intro: 'Provide feedback on pull requests by commenting on changes, suggesting edits, and approving or requesting updates before merging code.' +versions: + fpt: '*' + ghes: '*' + ghec: '*' +contentType: concepts +--- + +Reviewing pull requests is one of the main ways people collaborate on {% data variables.product.github %}. When you review a peer's work, you help catch issues early, share knowledge, and decide whether a change is ready to merge. + +## Commenting on changes + +Anyone with read access can review and comment on proposed changes. As a reviewer, you can: + +* Leave general feedback on the overall pull request. +* Comment on specific lines to ask questions or explain concerns. +* Suggest exact changes that the author can apply with a single click. + +Review conversations appear in the pull request timeline so the whole team can follow the discussion and track decisions. + +## Requesting changes and approving + +When you finish a review, you submit it with a decision that tells the author what to do next: + +* **Comment** leaves general feedback without explicitly approving or requesting changes. +* **Approve** signals that the changes are ready to merge. +* **Request changes** flags feedback that the author should address before the pull request merges. + +## Reviewing changes with more depth + +Thorough reviews go beyond reading the diff top to bottom. {% data variables.product.github %} gives you tools to review large or complex changes with precision: + +* **Review one file at a time**, mark each file as **Viewed** to collapse it, and use the progress bar to track how much of the pull request you've covered. +* **Assess security and dependencies.** Dependency review shows how a pull request changes dependencies and whether it introduces known vulnerabilities, and code scanning surfaces alerts on the proposed changes. +{% ifversion fpt or ghec %} +* **Automate reviews with {% data variables.product.prodname_copilot_short %}.** {% data variables.product.prodname_copilot_short %} can perform automated code reviews on a pull request, comment on specific lines, and suggest changes, helping you catch common issues before a human reviewer looks at the code. +{% endif %} + +## Further reading + +* [AUTOTITLE](/pull-requests/get-started/reviewing-pull-requests-quickstart) +* [AUTOTITLE](/pull-requests/how-tos/review-pull-requests/reviewing-dependency-changes-in-a-pull-request) +{% ifversion fpt or ghec %} +* [AUTOTITLE](/copilot/concepts/agents/code-review). +{% endif %} diff --git a/content/pull-requests/concepts/helping-others-review-your-changes.md b/content/pull-requests/concepts/helping-others-review-your-changes.md new file mode 100644 index 000000000000..88a476323aaf --- /dev/null +++ b/content/pull-requests/concepts/helping-others-review-your-changes.md @@ -0,0 +1,79 @@ +--- +title: Helping others review your changes +intro: Create clear, focused pull requests that improve collaboration, streamline reviews, and keep your team informed about your changes. +redirect_from: + - /pull-requests/collaborating-with-pull-requests/getting-started/best-practices-for-pull-requests + - /pull-requests/collaborating-with-pull-requests/getting-started/helping-others-review-your-changes +versions: + fpt: '*' + ghes: '*' + ghec: '*' +shortTitle: Help others review your changes +category: + - Create pull requests +contentType: concepts +--- + +When you create a pull request, you’re asking others to review your changes and provide feedback. Pull requests that are focused, clear, and easy to follow help reviewers give better feedback and make confident suggestions. + +## Making your changes easy to review + +Clear context helps reviewers quickly understand what changed and why it matters. It reduces back-and-forth, makes review faster, and helps your team focus on the most important parts of the change. + +### Write small pull requests + +Small, focused pull requests are easier to review and safer to merge. They help reviewers understand the purpose of the change, spot issues more quickly, and follow the history of the project later. + +When a change grows large, consider splitting it into smaller pull requests that each serve one purpose. + +### Provide context and guidance + +A clear title and description help reviewers understand the problem, the approach, and the result. Good context often explains why the change is needed, what changed, and where reviewers should pay special attention. + +Guidance is especially helpful when a pull request touches many files or requires a specific review order. For example, you can point reviewers to the most important files first or explain what type of feedback would be most useful. You can also use {% data variables.product.prodname_copilot %} to generate a summary of your pull request. + +### Review your own pull request first + +Reviewing your own pull request before asking others to review it helps you catch mistakes early. It also shows reviewers that the pull request is ready for their attention. + +A self-review can include reading the diff, checking for accidental changes, and making sure relevant builds or tests have run. + +### Review for security + +Security reviews help catch risk before a pull request is merged. This is especially important when a pull request changes dependencies, authentication, permissions, workflows, or code that handles sensitive data. + +{% data variables.product.github %} can surface security information in pull requests, such as dependency changes, dependency review results, and {% data variables.product.prodname_code_scanning %} checks. Use these signals to resolve issues early or to highlight risks that need reviewer attention. + +If your repository has {% data variables.product.prodname_code_scanning %} set up as a check, {% data variables.copilot.copilot_autofix %} can suggest fixes for security vulnerabilities. + +## Keeping your team informed + +Pull requests can do more than document code changes—they’re also a way to keep your team informed about the status of your work. Visible progress helps reduce separate status updates and keeps everyone aligned. + +{% ifversion fpt or ghec %} + +### Use {% data variables.product.prodname_copilot %} to generate pull request summaries + +> [!NOTE] +> {% data variables.product.prodname_copilot_short %} features require a {% data variables.product.prodname_copilot_short %} plan. See [AUTOTITLE](/copilot/get-started/plans). + +{% data variables.product.prodname_copilot_short %} can generate a pull request summary on {% data variables.product.github %}. A generated summary can help reviewers understand the main changes, but you should review it carefully and add context that only you know. + +Summaries are most useful when they explain the purpose of the change, call out important files, and highlight anything reviewers should examine closely. + +{% endif %} + +### Link to related issues or projects + +Connecting a pull request to issues or projects shows how the work fits into the larger project. Links help reviewers understand priority, track progress, and find related discussions. + +Use issue-closing keywords when a pull request should close an issue after merging. You can also link to {% data variables.product.prodname_projects_v2 %} so people can track work in one place. + +### Highlight the status with labels + +Status labels help reviewers understand whether a pull request is ready for review, blocked, or still in progress. Clear labels make it easier for people to prioritize reviews and avoid reviewing work before it is ready. + +## Further reading +* [AUTOTITLE](/pull-requests/concepts/resolving-reviews) +* [AUTOTITLE](/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue) +* [AUTOTITLE](/issues/using-labels-and-milestones-to-track-work/managing-labels) diff --git a/content/pull-requests/concepts/index.md b/content/pull-requests/concepts/index.md new file mode 100644 index 000000000000..8d8143cf0899 --- /dev/null +++ b/content/pull-requests/concepts/index.md @@ -0,0 +1,22 @@ +--- +title: Concepts for pull requests +redirect_from: + - /pull-requests/collaborating-with-pull-requests/getting-started + - /github/collaborating-with-issues-and-pull-requests/getting-started + - /github/collaborating-with-issues-and-pull-requests/overview + - /github/collaborating-with-pull-requests/getting-started +shortTitle: Concepts +intro: 'Understand the foundational concepts of pull requests, including branches, forks, commits, reviews, and merges to streamline collaboration on {% data variables.product.github %}.' +versions: + fpt: '*' + ghes: '*' + ghec: '*' +children: + - /writing-code-for-a-project + - /helping-others-review-your-changes + - /giving-reviews + - /resolving-reviews + - /deploying-code +contentType: concepts +--- + diff --git a/content/pull-requests/concepts/resolving-reviews.md b/content/pull-requests/concepts/resolving-reviews.md new file mode 100644 index 000000000000..9c2c12b3c0aa --- /dev/null +++ b/content/pull-requests/concepts/resolving-reviews.md @@ -0,0 +1,59 @@ +--- +title: Resolving reviews +shortTitle: Resolve reviews +intro: 'Address review feedback by comparing changes, updating code, and resolving comments to prepare your pull request for merging.' +versions: + fpt: '*' + ghes: '*' + ghec: '*' +contentType: concepts +--- + +After you open a pull request, reviewers leave feedback that helps improve your code before it merges. Resolving that feedback means understanding each comment, making the changes it calls for, and ensuring you've addressed everything. + +## Understanding review feedback + +Reviewers can leave general feedback, comment on specific lines, and propose exact changes as suggestions. Reviews appear in the pull request timeline so you can follow the discussion and see which comments still need a response. Depending on repository settings, a reviewer can also approve your pull request or request changes that you should address before merging. + +Before you change anything, read each comment to understand its intent. A comment might point out a bug, ask a question, request a different approach, or suggest an edit you can accept directly. + +If you have access to {% data variables.product.prodname_copilot_short %}, it can help you interpret review comments and propose fixes, which is useful when a pull request has many comments to work through. + +## Implementing changes and fixing code + +When you address feedback, you can: + +* Apply a reviewer's suggested change directly, which commits the suggestion to your branch. +* Make broader edits locally and push new commits to the branch. + +Most feedback is resolved by updating your code and pushing new commits to the pull request branch. As you address feedback, mark conversations as resolved so both you and your reviewers can track what is done and what still needs attention. + +When required reviewers have approved and no requested changes remain, your pull request is ready to move toward merging. Because the pull request tracks the branch, each new commit updates the pull request and re-runs any automated checks. + +## Working through feedback efficiently + +On larger or more scrutinized pull requests, a few practices help you address feedback quickly: + +* **Batch accepting suggestions** by adding suggested changes to a batch so several accepted changes land in a single commit instead of one commit per suggestion. +* **Resolve any merge conflicts** proactively so that you can merge quickly once your pull request review is resolved. +* **Re-request reviews** after you make substantial changes, so reviewers know the pull request is ready for another look. +* **Understand required reviews.** When a branch requires approvals or code owner sign-off, a "request changes" review or a dismissed approval can block merging until it's resolved. +* **Track out-of-scope feedback** by opening an issue that links back to the comment, rather than expanding the pull request. + +## Tools to help you resolve reviews + +You don't have to work through feedback by hand alone: + +* **Check out the pull request locally** or open it in **{% data variables.product.prodname_github_codespaces %}** to reproduce problems and test fixes before you push. +* **Address security findings** raised during review. Code scanning alerts on your changes appear in the pull request so you can fix them before merging. +{% ifversion fpt or ghec %} +* **Use {% data variables.product.prodname_copilot_short %}** to interpret feedback, answer questions, propose fixes, and resolve merge conflicts with agents. +{% endif %} + +## Further reading + +* [AUTOTITLE](/pull-requests/concepts/deploying-code) +* [AUTOTITLE](/pull-requests/how-tos/review-pull-requests/incorporating-feedback-in-your-pull-request) +{% ifversion fpt or ghec %} +* [AUTOTITLE](/copilot/concepts/agents/cloud-agent/about-cloud-agent) +{% endif %} diff --git a/content/pull-requests/concepts/writing-code-for-a-project.md b/content/pull-requests/concepts/writing-code-for-a-project.md new file mode 100644 index 000000000000..f520d701cc39 --- /dev/null +++ b/content/pull-requests/concepts/writing-code-for-a-project.md @@ -0,0 +1,70 @@ +--- +title: Writing code for a project +shortTitle: Write code +intro: 'Use branches, forks, commits, and pull requests to safely write, refine, and propose code changes for collaborative projects.' +versions: + fpt: '*' + ghes: '*' + ghec: '*' +contentType: concepts +--- + +When you contribute to a project, you need a safe place to write and refine code before it affects your main code base. Branches, forks, commits, and pull requests work together to give you that space, so you can experiment, check in work incrementally, and propose finished changes for review. + +## Isolating your work with branches and forks + +Most work starts by creating an isolated copy of the code that you can change freely. + +* Use a **branch** when you have write access to a repository. A branch lets you develop a feature, fix a bug, or experiment in a contained area of the repository without affecting other branches. You create a branch from an existing branch, usually the default branch. +* Use a **fork** when you do not have write access, or when you want full independence from the original project. A fork is a separate repository that shares code and visibility settings with the original "upstream" repository. It has its own branches, issues, and pull requests. With a fork, you can also open pull requests for the upstream repository. + +A branch is usually the simplest choice when you already collaborate in a shared repository. A fork is often the best choice for open source contributions, where you may not have write access to the upstream repository. + +## Checking in work with commits + +As you write code, you save small, meaningful groups of changes as **commits**. Each commit records a snapshot of your work along with a message describing what changed, which makes it easier to track history, review changes, and understand how the code evolved. + +Committing frequently on your branch or fork lets you: + +* Break a larger change into reviewable steps. +* Roll back to an earlier state if an experiment does not work out. +* Give reviewers a clear history of how you arrived at the final change. + +## Proposing changes with pull requests + +When your work is ready to share, you open a **pull request** to propose merging your changes into the base branch. A pull request brings together your commits, a description of the change, and the tools reviewers need to discuss and evaluate it before it merges. + +You can open a pull request while work is still in progress by creating a draft pull request, which shares your changes without formally requesting review. This is useful when you want early feedback or want to run automated checks against your code. + +## Keeping your code current and optimized + +While a pull request is open, the base branch can keep changing as other people merge their work. To keep your changes clean and reduce conflicts, you can: + +* Merge or rebase the base branch into your branch frequently so your diff stays focused on what your change introduces. {% data variables.product.github %} shows a three-dot diff by default, which compares your branch against the point where it diverged from the base. +* Rebase to tidy a messy commit history—reordering, combining, or rewording commits—before you ask for review. +* Resolve merge conflicts when Git cannot automatically combine competing changes. + +## Working within repository controls + +Experienced contributors work within the guardrails a repository defines. These controls shape where you can push, who must approve your work, and what must pass before it merges. + +* **Protected branches and rulesets** can block direct pushes to important branches, require linear history or signed commits, and require status checks or reviews before merging. +* **Code owners** are automatically requested for review when your change touches files they own, so plan for their approval on sensitive areas. +* **Push rulesets** can apply across a fork network, restricting file paths, sizes, or names in every fork. +* **Pre-receive hooks** let administrators on {% data variables.product.prodname_ghe_server %} enforce policy checks on the server before commits are accepted. + +## An integrated toolchain + +Pull requests connect your code to the automation and services that help you write code quickly and securely. + + +{% ifversion fpt or ghec %}* **{% data variables.product.prodname_copilot %}** can help you write, debug, and optimize code. {% endif %} +* **{% data variables.product.prodname_code_scanning_caps %}** and **{% data variables.product.prodname_dependabot %}** surface security issues and vulnerable dependencies as your changes move through a pull request, so you can apply secure coding practices early. +* **{% data variables.product.prodname_actions %}** can run continuous integration on every push to your pull request, building and testing your changes automatically. + +## Further reading + +* [AUTOTITLE](/pull-requests/how-tos/create-pull-requests/creating-a-pull-request) +{% ifversion fpt or ghec %} +* [AUTOTITLE](/copilot/get-started/quickstart) +{% endif %} diff --git a/content/pull-requests/get-started/about-forks.md b/content/pull-requests/get-started/about-forks.md new file mode 100644 index 000000000000..4b5f234fc7a9 --- /dev/null +++ b/content/pull-requests/get-started/about-forks.md @@ -0,0 +1,44 @@ +--- +title: About forks +shortTitle: About forks +intro: 'Use forks to make changes in your own copy of a repository and propose them back to the original project.' +versions: + fpt: '*' + ghes: '*' + ghec: '*' +contentType: get-started +category: + - Work with forks +--- + +A fork is a copy of a repository that you own, connected to the original repository, called the upstream repository. A fork lets you make changes in your own space without affecting the upstream project, and propose those changes back with a pull request. + +## Why use a fork + +A fork gives you an independent place to work while staying connected to the original project. Forks are useful when you want to: + +* Contribute to a project where you don't have write access. +* Experiment with changes without affecting the upstream repository. +* Explore a new direction that might become independent later. +* Keep your own branches, issues, and pull requests separate from the upstream project. + +## Forks and branches + +Forks and branches both give you a place to work on changes, but they work differently: + +* A **branch** lives inside a single repository. Use a branch when you have write access and collaborate in a shared repository. +* A **fork** is a separate repository with its own settings, permissions, and collaboration space. Use a fork when you need independence from the upstream repository, or when you don't have write access. + +Because a fork is its own repository, it gives you more independence than a branch. Because it stays connected to the upstream repository, your changes can still flow back through pull requests. + +## How forks connect to the upstream repository + +A fork shares its history with the upstream repository, so the two can exchange changes through pull requests. A fork also has its own visibility and permissions, which are tied to the upstream repository and the repository network it belongs to. + +For most contributors, this connection stays in the background: you fork a repository, work in your copy, and open a pull request when you're ready to propose your changes. + +## Further reading + +* [AUTOTITLE](/pull-requests/how-tos/work-with-forks/fork-a-repo) +* [AUTOTITLE](/pull-requests/concepts/writing-code-for-a-project) +* [AUTOTITLE](/pull-requests/reference/forks) diff --git a/content/pull-requests/get-started/about-pull-requests.md b/content/pull-requests/get-started/about-pull-requests.md new file mode 100644 index 000000000000..5fd4c44b0c4a --- /dev/null +++ b/content/pull-requests/get-started/about-pull-requests.md @@ -0,0 +1,58 @@ +--- +title: About pull requests +shortTitle: About pull requests +intro: 'Use pull requests to propose, discuss, and merge changes on {% data variables.product.github %}.' +versions: + fpt: '*' + ghes: '*' + ghec: '*' +contentType: get-started +category: + - Create pull requests +--- + +A pull request proposes merging code changes from one branch into another. As a collaborative feature, pull requests give you a place to discuss and review work before it becomes part of a project. + +## Why use pull requests + +Pull requests turn a set of code changes into a conversation. Instead of merging work directly, you propose it so that collaborators can weigh in. This helps you and your team maintain high quality and secure code, in a few ways: + +* Catch bugs and problems early, before they reach the main branch. +* Discuss and improve changes together, with feedback tied to specific lines. +* Keep a clear, reviewable history of what changed and why. + +## What you can do with pull requests + +Pull requests make your changes easy to review and validate. With a pull request, you can: + +* Propose changes from a branch or a fork. +* Discuss and review the proposed changes, line by line. +* Run automated checks, such as tests, builds, and code scanning, against the changes. +* Respond to feedback and update the pull request as it evolves. +* Merge the changes once reviews and required checks are satisfied. + +## Key parts of a pull request + +A pull request gathers everything you and your reviewers need into one place: + +* **Conversation** shows the description, comments, reviews, and a timeline of activity. +* **Commits** shows how the branch changed over time. +* **Checks** shows the results of automated tests, builds, and other validations. +* **Files changed** shows the diff that reviewers comment on. +* The **merge box** summarizes whether you can merge your changes or not. It shows what may still need to happen, such as required reviews or checks, before a pull request can be merged. + +## How pull requests fit your workflow + +Whether you're proposing changes or reviewing someone else's, a pull request follows a few stages: + +* **Branch or fork** the repository to create an isolated place to work. +* **Commit** your changes as you go, building up a history of your work. +* **Open a pull request** to propose merging your changes into the base branch. +* **Review and discuss** the changes with collaborators, making updates as needed. +* **Merge** the pull request when it's ready. + +## Next steps + +* [AUTOTITLE](/pull-requests/get-started/pull-request-quickstart) +* [AUTOTITLE](/pull-requests/get-started/reviewing-pull-requests-quickstart) +* [AUTOTITLE](/pull-requests/concepts/writing-code-for-a-project) diff --git a/content/pull-requests/get-started/index.md b/content/pull-requests/get-started/index.md new file mode 100644 index 000000000000..151e8a025ec8 --- /dev/null +++ b/content/pull-requests/get-started/index.md @@ -0,0 +1,16 @@ +--- +title: Get started with pull requests +shortTitle: Get started +intro: Propose, review, and merge your first changes with pull requests. +versions: + fpt: '*' + ghes: '*' + ghec: '*' +children: + - /about-pull-requests + - /about-forks + - /pull-request-quickstart + - /reviewing-pull-requests-quickstart +contentType: get-started +--- + diff --git a/content/pull-requests/get-started/pull-request-quickstart.md b/content/pull-requests/get-started/pull-request-quickstart.md new file mode 100644 index 000000000000..150780e53172 --- /dev/null +++ b/content/pull-requests/get-started/pull-request-quickstart.md @@ -0,0 +1,185 @@ +--- +title: Quickstart for pull requests +shortTitle: Pull request quickstart +intro: 'Propose your first change and take it all the way from your first commit to a merged pull request.' +allowTitleToDifferFromFilename: true +versions: + fpt: '*' + ghes: '*' + ghec: '*' +contentType: get-started +category: + - Create pull requests +--- + +A pull request proposes changes on a branch separate from the main code base so others can review the changes before they are merged. This quickstart walks you through the simplest path to a pull request. You'll create a branch, make and commit changes, open a pull request, respond to feedback, and merge. + +You can follow along on the {% data variables.product.github %} website or with {% data variables.product.prodname_cli %} by selecting one of the tabs above. + +## Branch or fork the repository + +You'll start by creating an isolated place to work. + +{% webui %} + +1. On {% data variables.product.github %}, navigate to the main page of the repository you want to propose changes for. +1. Optionally, if you don't have write access, you'll need a fork. Click **Fork** in the top-right corner and follow the steps. Then, continue in your fork of the repository. +1. Click the branch selector menu at the top of the file list. It probably says **main**. Type a new branch name and click **Create branch _new-branch-name_ from main**. + +{% endwebui %} + +{% cli %} + +1. To use {% data variables.product.prodname_cli %}, you'll need to install it first. See [AUTOTITLE](/github-cli/github-cli/quickstart). + +1. Clone the repository. Or, fork the repository and clone it locally at the same time. + * If you have write access to the repository, clone the repository: + + ```shell + gh repo clone OWNER/REPO + ``` + + * If you don't have write access, you'll create a **fork** first and clone it all at once. + + ```shell + gh repo fork OWNER/REPO --clone + ``` + +1. Change to the cloned repository directory. + + ```shell + cd REPO + ``` + +1. Create and switch to a new branch. + + ```shell + git checkout -b YOUR-BRANCH-NAME + ``` + +{% endcli %} + +## Author or edit your code + +Make your changes on the branch. For your first pull request, keep the change focused and simple. Smaller pull requests are faster to review and easier to merge. + +Try one of the following to make your changes: + +* Edit files locally in your IDE or a text editor. +* Edit a file directly on {% data variables.product.github %} by browsing to it and clicking {% octicon "pencil" aria-label="Edit this file" %}. + +## Commit frequently + +Save your work in small, meaningful commits. Each commit records a snapshot and a message describing the change. + +{% cli %} + +```shell +git add . +git commit -m "Describe your change" +git push --set-upstream origin YOUR-BRANCH-NAME +``` + +{% endcli %} + +{% webui %} + +When you edit a file on {% data variables.product.github %} and are ready to commit, you'll enter a commit message and commit directly to your branch. + +1. Click **Commit changes...**. +1. In the **Commit message** box, enter a short description of the changes you made. +1. Select the branch you're working on. +1. Click **Propose changes**. + +Your change will be added and committed to the branch. + +{% endwebui %} + +## Open your pull request + +When your branch has the changes you want to propose, open a pull request against the base branch. + +{% webui %} + +1. On the main page of the repository, click **{% octicon "git-pull-request" aria-label="The pull request icon" %} Pull requests**, then click **New pull request**. +1. For the **base** branch, main is probably already selected and is typically the base branch you'll merge into. +1. For the **compare** branch, select the branch that contains your changes. +1. Click **Create pull request**. +1. Enter a title and a description that explains what you changed and why. +1. You can create a pull request that's ready to review or one that's in a draft state. + * If it's ready for review, click **Create pull request**. + * To share a work in progress, use the dropdown and select **Create draft pull request**. + +{% endwebui %} + +{% cli %} + +You can create a pull request that's ready to review or one that's in a draft state. +* If it's ready for review: + + ```shell + gh pr create + ``` + +* To share a work in progress + + ```shell + gh pr create --draft + ``` + +Then, follow the prompts to set the base branch, title, and description. + +{% endcli %} + + +If you make further commits to the same branch, they will be automatically added to your pull request. + +## Request a review + +To request a review via the **Reviewers** box, you need write access to the repository and you can request a review from a person or team with read access to the repository. If you request a review the person or team will receive a notification. In some cases, you'll see suggested reviewers that you can select from. + +If the **Reviewers** box is unavailable to you, you can: +* Check the readme for the repository for their guidance on pull request reviews and follow their instructions. +* If you know a person who can do the review for you, reach out to them and share the link to your pull request. + +## Address review feedback + +Reviewers may comment, suggest changes, or request changes before a pull request can be merged. + +* To accept a reviewer's suggestion, click **Commit suggestion** (or batch several and click **Commit suggestions**). +* To make broader changes, edit your code and push new commits to the same branch. The pull request updates automatically and will re-run any checks. +* Mark each conversation as **Resolved** once you've addressed it. + +## Merge and deploy + +Once required reviews and status checks pass, merge the pull request to bring your changes into the base branch. If you decide not to merge the changes, you can close the pull request instead. + +> [!TIP] +> Different repositories may have different requirements for merging. Review any relevant guidance and follow its instructions. + +{% webui %} + +1. At the bottom of the pull request, click **Merge pull request**. +1. Click **Confirm** to complete the merge. +1. (Optional) Delete the head branch to keep the repository tidy. + +{% endwebui %} + +{% cli %} + +```shell +gh pr merge +``` + +Follow the prompts to pick a merge method and optionally delete the branch. + +{% endcli %} + +## Next steps + +After your first pull request, try reviewing someone else's work. See [AUTOTITLE](/pull-requests/get-started/reviewing-pull-requests-quickstart). + +## Further reading + +* [AUTOTITLE](/pull-requests/concepts/writing-code-for-a-project) +* [AUTOTITLE](/pull-requests/reference/pull-requests) diff --git a/content/pull-requests/get-started/reviewing-pull-requests-quickstart.md b/content/pull-requests/get-started/reviewing-pull-requests-quickstart.md new file mode 100644 index 000000000000..ad2640c33f94 --- /dev/null +++ b/content/pull-requests/get-started/reviewing-pull-requests-quickstart.md @@ -0,0 +1,53 @@ +--- +title: Quickstart for reviewing pull requests +shortTitle: Review quickstart +intro: 'Review a pull request by leaving comments, making suggestions, and approving or requesting changes.' +allowTitleToDifferFromFilename: true +versions: + fpt: '*' + ghes: '*' + ghec: '*' +contentType: get-started +category: + - Review pull requests +--- + +Pull request reviews are how teams catch issues early and keep code quality high. This quickstart walks you through each of the main tools for a review: +* Comment on code +* Suggest specific edits +* Submit your review and approve or request changes + +## Comment on the changes + +Anyone with read access to a repository can review and comment on a pull request. + +1. On {% data variables.product.github %}, navigate to the pull request. +1. Read through the pull request summary and any relevant comments or issues to build context for reviewing. +1. Click the **Files changed** tab. +1. Hover over the line you want to comment on and click {% octicon "plus" aria-label="Add a comment" %}. To comment on multiple lines, click and drag to select them. +1. Type your comment, then click **Start a review** to save it as pending until you finish reviewing. Pending comments are visible only to you until you submit the review. + +## Make code suggestions + +When you know the exact change you'd like, suggest it so the author can apply it in one click. + +1. On the **Files changed** tab, start a comment on the line or lines you want to change. +1. In the comment toolbar, click {% octicon "diff" aria-label="Insert a suggestion" %} to insert a suggestion block, then edit the code inside it to show your proposed change. +1. Click **Start a review** or **Add review comment** to include the suggestion in your review. + +## Submit your review + +Finish by submitting your review with a decision that tells the author what to do next. + +1. Click **Review changes**. +1. Add a summary comment. +1. Select a decision, then click **Submit review**: + + * **Comment** leaves feedback without explicitly approving or requesting changes. + * **Approve** signals that the changes are ready to merge. + * **Request changes** flags feedback the author must address before merging. + +## Next steps + +* [AUTOTITLE](/pull-requests/concepts/giving-reviews) +* [AUTOTITLE](/pull-requests/reference/pull-request-reviews) \ No newline at end of file diff --git a/content/pull-requests/how-tos/commit-changes/changing-a-commit-message.md b/content/pull-requests/how-tos/commit-changes/changing-a-commit-message.md new file mode 100644 index 000000000000..ba10b20fc976 --- /dev/null +++ b/content/pull-requests/how-tos/commit-changes/changing-a-commit-message.md @@ -0,0 +1,84 @@ +--- +title: Changing a commit message +redirect_from: + - /articles/can-i-delete-a-commit-message + - /articles/changing-a-commit-message + - /github/committing-changes-to-your-project/changing-a-commit-message + - /github/committing-changes-to-your-project/creating-and-editing-commits/changing-a-commit-message + - /pull-requests/committing-changes-to-your-project/creating-and-editing-commits/changing-a-commit-message +intro: Amend unclear, incorrect, or sensitive commit messages locally and push updated commits to {% data variables.product.github %}, including steps for editing recent or older commits. +versions: + fpt: '*' + ghes: '*' + ghec: '*' +category: + - Commit changes +contentType: how-tos +shortTitle: Change a commit message +--- + +## Rewriting the most recent commit message + +Changing a commit message creates a new commit ID. If the commit has already been pushed, you must force push the rewritten history. + +## Commit has not been pushed online + +If the commit only exists in your local repository, amend the commit message locally. + +1. On the command line, navigate to the repository that contains the commit you want to amend. +1. Type `git commit --amend` and press **Enter**. +1. In your text editor, edit the commit message, and save the commit. + * To add a co-author, add a trailer to the commit. See [AUTOTITLE](/pull-requests/how-tos/commit-changes/creating-a-commit-with-multiple-authors). +{% ifversion fpt or ghec %} + * To create commits on behalf of your organization, add a trailer to the commit. See [AUTOTITLE](/pull-requests/how-tos/commit-changes/creating-a-commit-with-multiple-authors#creating-a-commit-on-behalf-of-an-organization). +{% endif %} +1. Push the commit to {% data variables.location.product_location %}. + +## Amending older or multiple commit messages + +If you have already pushed the commit, use caution before rewriting history. Force pushing can disrupt collaborators who have based work on the old commits. + +### Changing the message of the most recently pushed commit + +1. Follow the steps in [Commit has not been pushed online](#commit-has-not-been-pushed-online) to amend the commit message. +1. Force push over the old commit. + + ```shell + git push --force-with-lease origin EXAMPLE-BRANCH + ``` + +### Changing the message of older or multiple commit messages + +Use interactive rebase to change older or multiple commit messages. + +1. On the command line, navigate to the repository that contains the commits you want to amend. +1. Start an interactive rebase for the last `n` commits. + + ```shell + git rebase -i HEAD~n + ``` + +1. In the commit list, replace `pick` with `reword` before each commit message you want to change. + + ```shell + pick e499d89 Delete CNAME + reword 0c39034 Better README + reword f7fde4a Change the commit message + ``` + +1. Save and close the commit list file. +1. In each commit message file that opens, enter the new message, then save and close the file. +1. Force push the rewritten history. + + ```shell + git push --force-with-lease origin EXAMPLE-BRANCH + ``` + +See [Interactive mode](https://git-scm.com/docs/git-rebase#_interactive_mode) in the Git manual. + +> [!WARNING] +> If a commit message included sensitive information, force pushing an amended commit might not remove the original commit from {% data variables.product.github %}. Contact {% data variables.contact.contact_support %} with the old commit ID to have it purged from the remote repository. + +## Further reading + +* [AUTOTITLE](/authentication/managing-commit-signature-verification/signing-commits) diff --git a/content/pull-requests/how-tos/commit-changes/committing-changes-to-a-pull-request-branch-created-from-a-fork.md b/content/pull-requests/how-tos/commit-changes/committing-changes-to-a-pull-request-branch-created-from-a-fork.md new file mode 100644 index 000000000000..5d9df7c32bd9 --- /dev/null +++ b/content/pull-requests/how-tos/commit-changes/committing-changes-to-a-pull-request-branch-created-from-a-fork.md @@ -0,0 +1,62 @@ +--- +title: Committing changes to a pull request branch created from a fork +intro: Commit changes to a pull request branch created from a fork by obtaining the necessary permissions and using Git commands effectively. +redirect_from: + - /pull-requests/how-tos/create-pull-requests/committing-changes-to-a-pull-request-branch-created-from-a-fork + - /github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests/committing-changes-to-a-pull-request-branch-created-from-a-fork + - /articles/committing-changes-to-a-pull-request-branch-created-from-a-fork + - /github/collaborating-with-issues-and-pull-requests/committing-changes-to-a-pull-request-branch-created-from-a-fork + - /github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/committing-changes-to-a-pull-request-branch-created-from-a-fork + - /pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/committing-changes-to-a-pull-request-branch-created-from-a-fork +versions: + fpt: '*' + ghes: '*' + ghec: '*' +shortTitle: Commit to PR branch from fork +category: + - Commit changes +contentType: how-tos +--- + +To commit to a pull request branch created from a fork, you need push access to the base repository, permission from the pull request creator, and a user-owned fork without branch restrictions that prevent your push. Only the pull request creator can allow edits to their fork. See [AUTOTITLE](/pull-requests/how-tos/work-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork). + +1. On {% data variables.product.github %}, navigate to the fork where the pull request branch was created. +{% data reusables.repositories.copy-clone-url %} +1. Open your terminal or Git Bash. +1. Change the current working directory to the location where you want to clone the fork. + + ```shell + cd open-source-projects + ``` + +1. Clone the fork, then navigate into the cloned repository. + + ```shell + git clone https://{% data variables.product.product_url %}/USERNAME/FORK-OF-THE-REPOSITORY + cd FORK-OF-THE-REPOSITORY + ``` + +1. Check out the pull request's compare branch. To find the compare branch, open the pull request and check the branch shown at the top of the page. + + ```shell + git checkout TEST-BRANCH + ``` + +1. Make your changes, then stage and commit them. + + ```shell + git add . + git commit -m "YOUR-COMMIT-MESSAGE" + ``` + +1. Push your commit to the pull request branch. + + ```shell + git push origin TEST-BRANCH + ``` + +Your new commits appear on the original pull request on {% data variables.location.product_location %}. + +## Further reading + +* [AUTOTITLE](/pull-requests/reference/forks) diff --git a/content/pull-requests/how-tos/commit-changes/comparing-commits.md b/content/pull-requests/how-tos/commit-changes/comparing-commits.md new file mode 100644 index 000000000000..72199954f52e --- /dev/null +++ b/content/pull-requests/how-tos/commit-changes/comparing-commits.md @@ -0,0 +1,85 @@ +--- +title: Comparing commits +intro: Compare branches, tags, commits, forks, and dates to analyze changes and track repository history effectively. +redirect_from: + - /articles/comparing-commits-across-time + - /github/committing-changes-to-your-project/comparing-commits-across-time + - /github/committing-changes-to-your-project/comparing-commits + - /github/committing-changes-to-your-project/viewing-and-comparing-commits/comparing-commits + - /articles/differences-between-commit-views + - /github/committing-changes-to-your-project/differences-between-commit-views + - /github/committing-changes-to-your-project/viewing-and-comparing-commits/differences-between-commit-views + - /pull-requests/committing-changes-to-your-project/viewing-and-comparing-commits/differences-between-commit-views + - /pull-requests/committing-changes-to-your-project/viewing-and-comparing-commits/comparing-commits +versions: + fpt: '*' + ghes: '*' + ghec: '*' +category: + - Commit changes +contentType: how-tos +shortTitle: Compare commits +--- + +To compare different versions of your repository, append `/compare` to your repository's path. The compare page uses `base` as the starting point and `compare` as the endpoint. + +## Comparing branches + +Use the Compare view to compare branches or start a pull request. + +1. Navigate to `https://{% data variables.product.product_url %}/OWNER/REPOSITORY/compare`. +1. Use the `base` dropdown menu to select the branch you want to compare against. +1. Use the `compare` dropdown menu to select the branch that contains the changes. +1. Review the commits and changed files in the comparison. + +See [AUTOTITLE](/pull-requests/reference/branches). + +## Comparing tags + +Compare release tags to review changes between releases. See [AUTOTITLE](/repositories/releasing-projects-on-github/comparing-releases). + +1. Navigate to `https://{% data variables.product.product_url %}/OWNER/REPOSITORY/compare`. +1. Select the older tag from the `base` dropdown menu. +1. Select the newer tag from the `compare` dropdown menu. +1. Review the commits and changed files in the comparison. + +> [!NOTE] +> If a branch and a tag have the same name, the branch is used. To compare the tag, add `tags/` before the tag name. + +## Comparing commits + +You can compare two commits or Git Object IDs (OIDs) directly by editing the compare URL. + +1. Navigate to the repository's compare page. +1. In the URL, enter the older commit as the base and the newer commit as the compare point. + +{% data reusables.repositories.two-dot-diff-comparison-example-urls %} + +See [AUTOTITLE](/pull-requests/reference/branches#three-dot-and-two-dot-git-diff-comparisons). + +## Comparing across forks + +Use owner-qualified branch names to compare branches across forks. + +1. Navigate to the base repository's compare page. +1. Click **compare across forks** if the option is shown. +1. Select the base repository and branch. +1. Select the head fork and compare branch. + +You can also edit the URL directly. For example, use `octocat:main` as `base` and `octo-org:main` as `compare` to compare the `main` branches of repositories owned by `octocat` and `octo-org`. See [AUTOTITLE](/pull-requests/reference/forks). + +## Comparisons across commits + +To compare a commit with earlier commits, use Git's `^` or `~N` notation in the compare URL. For example, `96d29b7~5...96d29b7` compares `96d29b7` with the commit five commits before it. + +## Differences between commit views + +The repository commit history and a single file's commit history can show different results. A file's history shows commits that affected that file, while the repository history shows the broader branch history. If a file's history does not include the commit you need, use the repository's commits page instead. + +See [the "History Simplification"](https://git-scm.com/docs/git-log#_history_simplification) section of the `git log` documentation. + +## Further reading + +* [AUTOTITLE](/pull-requests/how-tos/create-pull-requests/changing-the-base-branch-of-a-pull-request) +* [AUTOTITLE](/authentication/managing-commit-signature-verification/signing-commits) +* [AUTOTITLE](/search-github/searching-on-github/searching-commits) diff --git a/content/pull-requests/how-tos/commit-changes/creating-a-commit-with-multiple-authors.md b/content/pull-requests/how-tos/commit-changes/creating-a-commit-with-multiple-authors.md new file mode 100644 index 000000000000..24606b958033 --- /dev/null +++ b/content/pull-requests/how-tos/commit-changes/creating-a-commit-with-multiple-authors.md @@ -0,0 +1,118 @@ +--- +title: Creating a commit with multiple authors or on behalf of an organization +allowTitleToDifferFromFilename: true +intro: Attribute commits to multiple authors or organizations using trailers in commit messages for better collaboration and transparency. +redirect_from: + - /articles/creating-a-commit-with-multiple-authors + - /github/committing-changes-to-your-project/creating-a-commit-with-multiple-authors + - /github/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-with-multiple-authors + - /articles/creating-a-commit-on-behalf-of-an-organization + - /github/committing-changes-to-your-project/creating-a-commit-on-behalf-of-an-organization + - /github/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-on-behalf-of-an-organization + - /pull-requests/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-on-behalf-of-an-organization + - /pull-requests/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-with-multiple-authors +versions: + fpt: '*' + ghes: '*' + ghec: '*' +shortTitle: Create a commit with multiple authors +category: + - Commit changes +contentType: how-tos +--- + +## Creating a commit with multiple authors + +Add one or more `Co-authored-by` trailers to a commit message to attribute a commit to multiple authors. + +### Required co-author information + +Before adding a co-author, get the email address they want used in the trailer. For the commit to count as a contribution, use an email address associated with their account on {% data variables.location.product_location %}. + +If a co-author keeps their email address private, use their {% data variables.product.github %}-provided `no-reply` email. See [AUTOTITLE](/account-and-profile/how-tos/email-preferences/setting-your-commit-email-address). + +### Creating co-authored commits using {% data variables.product.prodname_desktop %} + +You can use {% data variables.product.prodname_desktop %} to create a commit with a co-author. See [AUTOTITLE](/desktop/making-changes-in-a-branch/committing-and-reviewing-changes-to-your-project-in-github-desktop#write-a-commit-message-and-push-your-changes) and [{% data variables.product.prodname_desktop %}](https://desktop.github.com). + +### Creating co-authored commits on the command line + +{% data reusables.pull_requests.collect-co-author-commit-git-config-info %} + +1. Type your commit message and a short, meaningful description of your changes. After your commit description, add an empty line instead of a closing quotation mark. + + ```shell + $ git commit -m "Refactor usability tests. + > + > + ``` + +1. Add one `Co-authored-by: name ` line for each co-author, then add the closing quotation mark. + + ```shell + $ git commit -m "Refactor usability tests. + > + > Co-authored-by: NAME + > Co-authored-by: ANOTHER-NAME " + ``` + +The new commit and message appear on {% data variables.location.product_location %} after you push. See [AUTOTITLE](/get-started/using-git/pushing-commits-to-a-remote-repository). + +### Creating co-authored commits on {% data variables.product.github %} + +After you make changes in a file using the web editor on {% data variables.product.github %}, add co-author trailers before you commit. + +{% data reusables.pull_requests.collect-co-author-commit-git-config-info %} +1. Click **Commit changes...** +1. In the "Commit message" field, type a short, meaningful commit message that describes the changes you made. +1. In the text box below your commit message, add one `Co-authored-by: name ` line for each co-author. +1. Click **Commit changes** or **Propose changes**. + +The new commit and message appear on {% data variables.location.product_location %}. + +## Creating a commit on behalf of an organization + +> [!NOTE] +> Creating a commit on behalf of an organization is not available on {% data variables.product.prodname_ghe_server %}. + +Add an `on-behalf-of:` trailer to a signed commit to attribute it to an organization. To use the trailer, you must be a member of the organization, and both your commit email and the organization email must be in a domain verified by the organization. + +### Creating commits with an `on-behalf-of` badge on the command line + +1. Type your commit message and a short, meaningful description of your changes. After your commit description, add two empty lines instead of a closing quotation mark. + + ```shell + $ git commit -m "Refactor usability tests. + > + > + ``` + +1. Add `on-behalf-of: @org `, then add the closing quotation mark. + + ```shell + $ git commit -m "Refactor usability tests. + > + > + on-behalf-of: @ORG NAME@ORGANIZATION.COM" + ``` + +The new commit, message, and badge appear on {% data variables.product.prodname_dotcom %} after you push. See [AUTOTITLE](/get-started/using-git/pushing-commits-to-a-remote-repository). + +### Creating commits with an `on-behalf-of` badge on {% data variables.product.github %} + +After you make changes in a file using the web editor on {% data variables.product.github %}, add the organization trailer before you commit. + +1. Click **Commit changes...** +1. In the "Commit message" field, type a short, meaningful commit message that describes the changes you made. +1. In the text box below your commit message, add `on-behalf-of: @org `. +1. Click **Commit changes** or **Propose changes**. + +The new commit, message, and badge appear on {% data variables.product.prodname_dotcom %}. + +## Further reading + +* [AUTOTITLE](/account-and-profile/how-tos/contribution-settings/viewing-contributions-on-your-profile) +* [AUTOTITLE](/account-and-profile/how-tos/contribution-settings/troubleshooting-missing-contributions) +* [AUTOTITLE](/repositories/viewing-activity-and-data-for-your-repository/viewing-a-projects-contributors) +* [AUTOTITLE](/pull-requests/how-tos/commit-changes/changing-a-commit-message) +* [AUTOTITLE](/desktop/making-changes-in-a-branch/committing-and-reviewing-changes-to-your-project-in-github-desktop#write-a-commit-message-and-push-your-changes) in the {% data variables.product.prodname_desktop %} documentation diff --git a/content/pull-requests/how-tos/commit-changes/index.md b/content/pull-requests/how-tos/commit-changes/index.md new file mode 100644 index 000000000000..09f81591ed3c --- /dev/null +++ b/content/pull-requests/how-tos/commit-changes/index.md @@ -0,0 +1,30 @@ +--- +title: Commit changes +redirect_from: + - /pull-requests/committing-changes-to-your-project + - /categories/21/articles + - /categories/commits + - /categories/committing-changes-to-your-project + - /github/committing-changes-to-your-project + - /pull-requests/committing-changes-to-your-project/creating-and-editing-commits + - /articles/creating-and-editing-commits + - /github/committing-changes-to-your-project/creating-and-editing-commits + - /pull-requests/committing-changes-to-your-project/viewing-and-comparing-commits + - /articles/viewing-and-comparing-commits + - /github/committing-changes-to-your-project/viewing-and-comparing-commits +shortTitle: Commit changes +intro: Create, modify, compare, and troubleshoot branches and commits to streamline collaboration in your pull requests. +versions: + fpt: '*' + ghes: '*' + ghec: '*' +children: + - /managing-branches-within-your-repository + - /committing-changes-to-a-pull-request-branch-created-from-a-fork + - /creating-a-commit-with-multiple-authors + - /changing-a-commit-message + - /comparing-commits + - /troubleshooting-commits +contentType: how-tos +--- + diff --git a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository.md b/content/pull-requests/how-tos/commit-changes/managing-branches-within-your-repository.md similarity index 60% rename from content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository.md rename to content/pull-requests/how-tos/commit-changes/managing-branches-within-your-repository.md index ae9815947711..ba67ee24169f 100644 --- a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository.md +++ b/content/pull-requests/how-tos/commit-changes/managing-branches-within-your-repository.md @@ -1,26 +1,29 @@ --- -title: Creating and deleting branches within your repository -intro: 'You can create or delete branches directly on {% data variables.product.github %}.' +title: Managing branches within your repository +intro: Create new branches for development and delete unused branches directly on {% data variables.product.github %}. redirect_from: - /github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository - /articles/deleting-branches-in-a-pull-request - /articles/creating-and-deleting-branches-within-your-repository - /github/collaborating-with-issues-and-pull-requests/creating-and-deleting-branches-within-your-repository + - /pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository + - /pull-requests/how-tos/create-pull-requests/creating-and-deleting-branches-within-your-repository versions: fpt: '*' ghes: '*' ghec: '*' -shortTitle: Create & delete branches +shortTitle: Manage branches category: - Create pull requests +contentType: how-tos --- ## Creating a branch -You can create a branch in different ways on {% data variables.product.github %}. +Create a branch for a separate place to work on changes before opening a pull request. > [!NOTE] -> You can only create a branch in a repository to which you have push access. +> You can only create a branch in a repository to which you have write access. ### Creating a branch via the branches overview @@ -30,9 +33,7 @@ You can create a branch in different ways on {% data variables.product.github %} ![Screenshot of the "Branches" page for a repository. A green button, labeled "New branch", is highlighted with an orange outline.](/assets/images/help/branches/new-branch-button.png) 1. Under "Branch name", type a name for the branch. -1. Under "Branch source", choose a source for your branch. - * If your repository is a fork, select the repository dropdown menu and click your fork or the upstream repository. - * Select the branch dropdown menu and click a branch. +1. Under "Branch source", choose the repository and branch to base your new branch on. 1. Click **Create branch**. ### Creating a branch using the branch dropdown @@ -42,36 +43,38 @@ You can create a branch in different ways on {% data variables.product.github %} ![Screenshot of the file tree view for a repository. A dropdown menu for branches is outlined in dark orange.](/assets/images/help/branches/file-tree-view-branch-dropdown.png) -1. Optionally, if you want to create the new branch from a branch other than the default branch of the repository, click another branch, then select the branch dropdown menu again. +1. Optionally, to create the new branch from a branch other than the default branch of the repository, click another branch. Then, select the branch dropdown menu again. 1. In the "Find or create a branch..." text field, type a unique name for your new branch, then click **Create branch**. ![Screenshot of the branch selector dropdown menu. "Create branch: new-branch" is highlighted with an orange outline.](/assets/images/help/branches/create-branch-text.png) ### Creating a branch for an issue -You can create a branch to work on an issue directly from the issue page and get started right away. For more information, see [AUTOTITLE](/issues/tracking-your-work-with-issues/creating-a-branch-for-an-issue). +You can create a branch to work on an issue directly from the issue page. See [AUTOTITLE](/issues/tracking-your-work-with-issues/using-issues/creating-a-branch-for-an-issue). ## Deleting a branch +Delete branches that you no longer need, such as branches for merged or closed work. + {% data reusables.pull_requests.automatically-delete-branches %} > [!NOTE] -> If the branch you want to delete is the repository's default branch, you must choose a new default branch before deleting the branch. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/changing-the-default-branch). +> If the branch you want to delete is the repository's default branch, choose a new default branch first. See [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/changing-the-default-branch). -If the branch you want to delete is associated with an open pull request, you must merge or close the pull request before deleting the branch. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request) or [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/closing-a-pull-request). +If the branch is associated with an open pull request, merge or close the pull request before deleting the branch. {% data reusables.repositories.navigate-to-repo %} {% data reusables.repositories.navigate-to-branches %} 1. Next to the branch that you want to delete, click {% octicon "trash" aria-label="The trash icon" %} . ![Screenshot of a branch in the branch list. A trash icon is highlighted with an orange outline.](/assets/images/help/branches/branches-delete.png) -1. If the branch is associated with at least one open pull request, deleting the branch will close the pull requests. Read the warning, then click **Delete**. +1. If the branch is associated with at least one open pull request, deleting the branch closes the pull requests. Read the warning, then click **Delete**. {% data reusables.pull_requests.retargeted-on-branch-deletion %} -For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches#working-with-branches). +See [AUTOTITLE](/pull-requests/reference/branches). ## Further reading -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches) +* [AUTOTITLE](/pull-requests/reference/branches) * [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/viewing-branches-in-your-repository) * [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/deleting-and-restoring-branches-in-a-pull-request) diff --git a/content/pull-requests/how-tos/commit-changes/troubleshooting-commits.md b/content/pull-requests/how-tos/commit-changes/troubleshooting-commits.md new file mode 100644 index 000000000000..3b7432df44b4 --- /dev/null +++ b/content/pull-requests/how-tos/commit-changes/troubleshooting-commits.md @@ -0,0 +1,112 @@ +--- +title: Troubleshooting commits +shortTitle: Troubleshoot commits +intro: Resolve common commit issues like incorrect user links, missing local commits, and push protection blocks. +redirect_from: + - /articles/troubleshooting-commits + - /github/committing-changes-to-your-project/troubleshooting-commits + - /articles/how-do-i-get-my-commits-to-link-to-my-github-account + - /articles/why-are-my-commits-linked-to-the-wrong-user + - /github/committing-changes-to-your-project/why-are-my-commits-linked-to-the-wrong-user + - /github/committing-changes-to-your-project/troubleshooting-commits/why-are-my-commits-linked-to-the-wrong-user + - /pull-requests/committing-changes-to-your-project/troubleshooting-commits/why-are-my-commits-linked-to-the-wrong-user + - /articles/commit-exists-on-github-but-not-in-my-local-clone + - /github/committing-changes-to-your-project/commit-exists-on-github-but-not-in-my-local-clone + - /github/committing-changes-to-your-project/troubleshooting-commits/commit-exists-on-github-but-not-in-my-local-clone + - /pull-requests/committing-changes-to-your-project/troubleshooting-commits/commit-exists-on-github-but-not-in-my-local-clone + - /pull-requests/committing-changes-to-your-project/troubleshooting-commits/my-commit-is-blocked-by-push-protection + - /pull-requests/committing-changes-to-your-project/troubleshooting-commits +versions: + fpt: '*' + ghes: '*' + ghec: '*' +category: + - Commit changes +contentType: how-tos +--- + +## Commits are linked to the wrong user + +{% data variables.product.github %} links a commit to a user by matching the email address in the commit header to an email address on a {% data variables.product.github %} account. If your commits are linked to the wrong user or no user, update your Git email settings and add the email address to your account. + +> [!NOTE] +> If your commits are linked to another user, that does not give them access to your repository. + +### Commits are linked to another user + +1. Change the email address in your local Git configuration by following [AUTOTITLE](/account-and-profile/how-tos/email-preferences/setting-your-commit-email-address#setting-your-commit-email-address-in-git). If you work on multiple machines, change this setting on each one. +1. Add the email address to your account by following [AUTOTITLE](/account-and-profile/how-tos/email-preferences/adding-an-email-address-to-your-github-account). + +Future commits that use the email address will be linked to your account. + +### Commits are not linked to any user + +To find out why a commit is not linked, inspect the commit on {% data variables.product.github %}. + +{% data reusables.repositories.navigate-to-repo %} +{% data reusables.repositories.navigate-to-commit-page %} +{% data reusables.repositories.navigate-to-commit %} +1. Hover over the blue {% octicon "question" aria-label="Question mark" %} to the right of the username. +1. Use the message to decide what to update: + * **Unrecognized author (with email address):** Add the shown email address to your {% data variables.product.github %} account. + * **Unrecognized author (no email address):** Set your commit email address in Git, then add that address to your {% data variables.product.github %} account. + * **Invalid email:** Set a valid commit email address in Git, then add that address to your {% data variables.product.github %} account. + +Old commits might not be linked after you update your email settings. See [AUTOTITLE](/account-and-profile/how-tos/email-preferences/setting-your-commit-email-address). + +## A commit exists on GitHub but not in your local clone + +If `git show COMMIT-SHA` returns an error locally but the commit is visible on {% data variables.product.github %}, your local clone may be out of date or the commit may no longer be referenced by a branch. + +### The local repository is out of date + +Fetch information from the remote repository. + +```shell +git fetch REMOTE +``` + +Use `git fetch upstream` for a fork's upstream repository, or `git fetch origin` for the repository you cloned. + +### The branch that contained the commit was deleted + +If the branch was deleted or force pushed, ask a collaborator who still has the commit locally to push it to a new branch. + +```shell +git branch recover-B B +git push upstream B:recover-B +``` + +Then, fetch the recovered branch. + +```shell +git fetch upstream recover-B +``` + +### Avoid force pushes + +Avoid force pushing unless necessary, especially when more than one person can push to the repository. Force pushing rewrites repository history and can disrupt collaborators or corrupt pull requests. + +## A commit is blocked by push protection + +Push protection blocks commits, uploads, or API requests that contain supported secrets. + +### Understanding why push protection has blocked your commit + +If push protection blocks your work, {% data variables.product.github %} detected a supported secret in your commit or request. Remove the secret before trying again. + +### Resolving a push protection block + +1. Review the push protection message to identify the secret and where it appears. +1. Remove the secret from the commit, file upload, or API request. +1. Try the push, commit, upload, or request again. +1. If you believe the secret is safe to push, follow the bypass steps for your workflow: + * [AUTOTITLE](/code-security/how-tos/secure-your-secrets/work-with-leak-prevention/push-protection-on-the-command-line) + * [AUTOTITLE](/code-security/how-tos/secure-your-secrets/work-with-leak-prevention/push-protection-in-the-github-ui) + * [AUTOTITLE](/code-security/concepts/secret-security/push-protection-from-the-rest-api) + +## Further reading + +* [AUTOTITLE](/search-github/searching-on-github/searching-commits) +* [AUTOTITLE](/code-security/concepts/secret-security/push-protection) +* [AUTOTITLE](/code-security/reference/secret-security/supported-secret-scanning-patterns) diff --git a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-base-branch-of-a-pull-request.md b/content/pull-requests/how-tos/create-pull-requests/changing-the-base-branch-of-a-pull-request.md similarity index 55% rename from content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-base-branch-of-a-pull-request.md rename to content/pull-requests/how-tos/create-pull-requests/changing-the-base-branch-of-a-pull-request.md index 10546049d626..5de43db00454 100644 --- a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-base-branch-of-a-pull-request.md +++ b/content/pull-requests/how-tos/create-pull-requests/changing-the-base-branch-of-a-pull-request.md @@ -1,11 +1,12 @@ --- title: Changing the base branch of a pull request -intro: 'After a pull request is opened, you can change the base branch to compare the changes in the pull request against a different branch.' +intro: Modify the base branch of an open pull request to compare changes against a different branch and ensure accurate updates. redirect_from: - /github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-base-branch-of-a-pull-request - /articles/changing-the-base-branch-of-a-pull-request - /github/collaborating-with-issues-and-pull-requests/changing-the-base-branch-of-a-pull-request - /github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-base-branch-of-a-pull-request + - /pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-base-branch-of-a-pull-request versions: fpt: '*' ghes: '*' @@ -13,26 +14,27 @@ versions: shortTitle: Change the base branch category: - Create pull requests +contentType: how-tos --- > [!WARNING] -> When you change the base branch of your pull request, some commits may be removed from the timeline. Review comments may also become outdated, as the line of code that the comment referenced may no longer be part of the changes in the pull request. +> When you change the base branch of your pull request, some commits may be removed from the timeline. Review comments may also become outdated because the line of code that the comment referenced may no longer be part of the changes in the pull request. {% data reusables.repositories.sidebar-pr %} -1. In the "Pull Requests" list, click the pull request you'd like to modify. +1. In the "Pull Requests" list, click the pull request you want to modify. 1. Next to the pull request title, click **Edit title** {% octicon "pencil" aria-label="Edit title" %}. -1. In the base branch drop-down menu, select the base branch you'd like to [compare changes against](/pull-requests/committing-changes-to-your-project/viewing-and-comparing-commits/comparing-commits#comparing-branches). +1. In the base branch drop-down menu, select the base branch you'd like to [compare changes against](/pull-requests/how-tos/commit-changes/comparing-commits#comparing-branches). ![Screenshot of a pull request title. The dropdown to change the base branch is outlined in dark orange.](/assets/images/help/pull_requests/pull-request-edit-base-branch.png) 1. Read the information about changing the base branch and click **Change base**. > [!TIP] -> When you open a pull request, {% data variables.product.github %} will set the base to the commit that branch references. If the branch is updated in the future, {% data variables.product.github %} will not update the base branch's commit. +> When you open a pull request, {% data variables.product.github %} sets the base to the commit that branch references. If the branch is updated in the future, {% data variables.product.github %} does not update the base branch's commit. ## Further reading -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request) +* [AUTOTITLE](/pull-requests/how-tos/create-pull-requests/creating-a-pull-request) +* [AUTOTITLE](/pull-requests/reference/pull-requests) +* [AUTOTITLE](/pull-requests/how-tos/review-pull-requests/reviewing-proposed-changes-in-a-pull-request) diff --git a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request.md b/content/pull-requests/how-tos/create-pull-requests/changing-the-stage-of-a-pull-request.md similarity index 59% rename from content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request.md rename to content/pull-requests/how-tos/create-pull-requests/changing-the-stage-of-a-pull-request.md index c9ade7970c80..008ad41a2d60 100644 --- a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request.md +++ b/content/pull-requests/how-tos/create-pull-requests/changing-the-stage-of-a-pull-request.md @@ -1,39 +1,43 @@ --- title: Changing the stage of a pull request -intro: You can mark a draft pull request as ready for review or convert a pull request to a draft. +intro: Mark a draft pull request as ready for review or convert an open pull request back to a draft to manage your workflow effectively. permissions: People with write permissions to a repository and pull request authors can change the stage of a pull request. redirect_from: - /github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request - /articles/changing-the-stage-of-a-pull-request - /github/collaborating-with-issues-and-pull-requests/changing-the-stage-of-a-pull-request - /github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request + - /pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request versions: fpt: '*' ghes: '*' ghec: '*' -shortTitle: Change the state +shortTitle: Draft pull requests category: - Create pull requests +contentType: how-tos --- ## Marking a pull request as ready for review {% data reusables.pull_requests.mark-ready-review %} > [!TIP] -> You can also mark a pull request as ready for review using the {% data variables.product.prodname_cli %}. For more information, see [`gh pr ready`](https://cli.github.com/manual/gh_pr_ready) in the {% data variables.product.prodname_cli %} documentation. +> You can also mark a pull request as ready for review using the {% data variables.product.prodname_cli %}. See [`gh pr ready`](https://cli.github.com/manual/gh_pr_ready) in the {% data variables.product.prodname_cli %} documentation. {% data reusables.repositories.sidebar-pr %} -1. In the "Pull requests" list, click the pull request you'd like to mark as ready for review. +1. In the "Pull requests" list, click the pull request you want to mark as ready for review. 1. In the merge box, click **Ready for review**. ![Screenshot of the merge box in a pull request. The "Ready for review" button is outlined in dark orange.](/assets/images/help/pull_requests/ready-for-review-button.png) ## Converting a pull request to a draft -You can convert a pull request to a draft at any time. For example, if you accidentally opened a pull request instead of a draft, or if you've received feedback on your pull request that needs to be addressed, you can convert the pull request to a draft to indicate further changes are needed. No one can merge the pull request until you mark the pull request as ready for review again. People who are already subscribed to notifications for the pull request will not be unsubscribed when you convert the pull request to a draft. +You can convert a pull request to a draft at any time. For example, if you accidentally opened a pull request instead of a draft, or if you've received feedback on your pull request that you need to address, you can convert the pull request to a draft to indicate further changes are needed. + +No one can merge the pull request until you mark the pull request as ready for review again. People who are already subscribed to notifications for the pull request will not be unsubscribed when you convert the pull request to a draft. {% data reusables.repositories.sidebar-pr %} -1. In the "Pull requests" list, click the pull request you'd like to convert to a draft. +1. In the "Pull requests" list, click the pull request you want to convert to a draft. 1. In the right sidebar, under "Reviewers," click **Convert to draft**. ![Screenshot of the "Reviewers" section in the right sidebar of a pull request. The "Convert to draft" link is outlined in dark orange.](/assets/images/help/pull_requests/convert-to-draft-link.png) @@ -42,4 +46,4 @@ You can convert a pull request to a draft at any time. For example, if you accid ## Further reading -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) +* [AUTOTITLE](/pull-requests/reference/pull-requests) diff --git a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork.md b/content/pull-requests/how-tos/create-pull-requests/creating-a-pull-request-from-a-fork.md similarity index 52% rename from content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork.md rename to content/pull-requests/how-tos/create-pull-requests/creating-a-pull-request-from-a-fork.md index 565d82402dc3..85aa77ee7a1c 100644 --- a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork.md +++ b/content/pull-requests/how-tos/create-pull-requests/creating-a-pull-request-from-a-fork.md @@ -1,12 +1,13 @@ --- title: Creating a pull request from a fork -intro: You can create a pull request to propose changes you've made to a fork of an upstream repository. +intro: Create a pull request from a fork to propose changes to an upstream repository and collaborate on code effectively. redirect_from: - /github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork - /articles/creating-a-pull-request-from-a-fork - /github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork - /github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork -permissions: 'Anyone with write access to a repository can create a pull request from a user-owned fork. {% data reusables.enterprise-accounts.emu-permission-propose %}' + - /pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork +permissions: Anyone with write access to a repository can create a pull request from a user-owned fork. {% data reusables.enterprise-accounts.emu-permission-propose %} versions: fpt: '*' ghes: '*' @@ -14,15 +15,12 @@ versions: shortTitle: Create a PR from a fork category: - Create pull requests +contentType: how-tos --- -If your pull request compares your topic branch with a branch in the upstream repository as the base branch, then your topic branch is also called the "compare branch" of the pull request. -For example: -* Your topic branch (also known as “feature branch”) is the branch where you’re making your changes in your forked repository (e.g. `my-topic-branch`). -* The base branch is the branch in the upstream (central) repository that you want to merge your changes into (e.g. `main`). -* The pull request compares the changes proposed by the topic branch (`my-topic-branch`) with the base branch (`main`), so `my-topic-branch` is known as the “compare branch”. +Before creating a pull request from a fork, fork the upstream repository and push your changes to a branch in your fork. See [AUTOTITLE](/pull-requests/how-tos/work-with-forks/fork-a-repo). -For more information about pull request branches, including examples, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request#changing-the-branch-range-and-destination-repository). +In a pull request from a fork, the base branch is where you want to merge your changes, and the compare branch is the branch in your fork that contains your changes. See [AUTOTITLE](/pull-requests/how-tos/create-pull-requests/creating-a-pull-request#creating-the-pull-request). {% data reusables.pull_requests.perms-to-open-pull-request %} @@ -32,11 +30,11 @@ For more information about pull request branches, including examples, see [AUTOT ![Screenshot of the page to open a pull request. The "compare across forks" link is outlined in dark orange.](/assets/images/help/pull_requests/compare-across-forks-link.png) -1. In the "base branch" dropdown menu, select the branch of the upstream repository you'd like to merge changes into. +1. In the "base branch" dropdown menu, select the branch of the upstream repository where you want to merge changes. ![Screenshot of the page to open a new pull request. The dropdown menus for choosing the base repository and branch are outlined in dark orange.](/assets/images/help/pull_requests/choose-base-fork-and-branch.png) -1. In the "head fork" dropdown menu, select your fork, then use the "compare branch" drop-down menu to select the branch you made your changes in. +1. In the "head fork" dropdown menu, select your fork. Then, use the "compare branch" dropdown menu to select the branch where you made your changes. ![Screenshot of the page to open a new pull request. The dropdown menus for choosing the head repository and compare branch are outlined in dark orange.](/assets/images/help/pull_requests/choose-head-fork-compare-branch.png) @@ -49,5 +47,5 @@ For more information about pull request branches, including examples, see [AUTOT ## Further reading -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork) +* [AUTOTITLE](/pull-requests/how-tos/work-with-forks) +* [AUTOTITLE](/pull-requests/how-tos/work-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork) diff --git a/content/pull-requests/how-tos/create-pull-requests/creating-a-pull-request.md b/content/pull-requests/how-tos/create-pull-requests/creating-a-pull-request.md new file mode 100644 index 000000000000..1334abd3ef92 --- /dev/null +++ b/content/pull-requests/how-tos/create-pull-requests/creating-a-pull-request.md @@ -0,0 +1,170 @@ +--- +title: Creating a pull request +intro: Create a pull request to propose changes to the code in a repository. +permissions: 'Anyone with read access to a repository can create a pull request.
{% data reusables.enterprise-accounts.emu-permission-propose %}' +redirect_from: + - /github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request + - /articles/creating-a-pull-request + - /github/collaborating-with-issues-and-pull-requests/creating-a-pull-request + - /pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request +versions: + fpt: '*' + ghes: '*' + ghec: '*' +shortTitle: Create a pull request +category: + - Create pull requests +contentType: how-tos +--- + +If you want to create a new branch for your pull request but don't have write permissions to the repository, you can fork the repository first. See [AUTOTITLE](/pull-requests/how-tos/create-pull-requests/creating-a-pull-request-from-a-fork) and [AUTOTITLE](/pull-requests/reference/forks). + +When you create your pull request, you can specify which branch you want to merge your changes into. Pull requests can only be opened between two different branches. + +{% data reusables.pull_requests.perms-to-open-pull-request %} + +{% data reusables.pull_requests.close-issues-using-keywords %} + +## Creating the pull request + +{% webui %} + +{% data reusables.repositories.navigate-to-repo %} +1. In the "Branch" menu, choose the branch that contains your commits. + + ![Screenshot of the branch dropdown menu on the main page of a repository.](/assets/images/help/pull_requests/branch-dropdown.png) + +{% data reusables.repositories.new-pull-request %} +1. Use the _base_ branch dropdown menu to select the branch where you want to merge your changes. Then, use the _compare_ branch dropdown menu to choose the topic branch where you made your changes. +{% data reusables.repositories.pr-title-description %} +{% data reusables.repositories.create-pull-request %} + +{% data reusables.repositories.asking-for-review %} + +After your pull request has been reviewed, it can be merged into the repository. See [AUTOTITLE](/pull-requests/how-tos/merge-and-close-pull-requests/merging-a-pull-request). + +{% endwebui %} + +{% cli %} + +{% data reusables.cli.cli-learn-more %} + +To create a pull request, use the `gh pr create` subcommand. + +```shell +gh pr create +``` + +To assign a pull request to an individual, use the `--assignee` or `-a` flags. You can use `@me` to self-assign the pull request. + +```shell +gh pr create --assignee "@octocat" +``` + +To specify the branch into which you want the pull request merged, use the `--base` or `-B` flags. To specify the branch that contains commits for your pull request, use the `--head` or `-H` flags. + +```shell +gh pr create --base my-base-branch --head my-changed-branch +``` + +To include a title and body for the new pull request, use the `--title` and `--body` flags. + +```shell +gh pr create --title "The bug is fixed" --body "Everything works again" +``` + +To mark a pull request as a draft, use the `--draft` flag. + +```shell +gh pr create --draft +``` + +To add labels or milestones to the new pull request, use the `--label` and `--milestone` flags. + +```shell +gh pr create --label "bug,help wanted" --milestone octocat-milestone +``` + +To add the new pull request to a specific project, use the `--project` flag. + +```shell +gh pr create --project octocat-project +``` + +To assign an individual or team as reviewers, use the `--reviewer` flag. + +```shell +gh pr create --reviewer monalisa,hubot --reviewer myorg/team-name +``` + +To create the pull request in your default web browser, use the `--web` flag. + +```shell +gh pr create --web +``` + +{% endcli %} + +{% desktop %} + +1. Click **Preview Pull Request**. {% data variables.product.prodname_desktop %} opens a preview dialog that shows the diff of the changes between your current branch and the base branch. + + Alternatively, to go straight to {% data variables.product.prodname_dotcom %} to create your pull request, select the dropdown icon and click **Create Pull Request**. + +1. Confirm that the branch in the **base:** dropdown menu is the branch where you want to merge your changes. + + ![Screenshot of the "Open a Pull Request" dialog window. A button with a dropdown icon, labeled "base: development", is outlined in orange.](/assets/images/help/desktop/base-branch-selection.png) + + {% data variables.product.prodname_desktop %} tells you whether the current branch can be automatically merged into the base branch. + + ![Screenshot of the "Open a Pull Request" dialog window. A status label stating "Can't automatically merge" is highlighted with an orange outline.](/assets/images/help/desktop/preview-dialog-merge-status.png) + +1. Click **Create Pull Request**. {% data variables.product.prodname_desktop %} opens your default browser and takes you to {% data variables.product.prodname_dotcom %}. +{% data reusables.repositories.pr-title-description %} +{% data reusables.repositories.create-pull-request %} + +{% enddesktop %} + +{% ifversion fpt or ghec %} + +{% codespaces %} + +1. After you commit changes to your local copy of the repository, click the **Create Pull Request** icon. +![Screenshot of the top of the "Source Control" side bar. The pull request icon is highlighted with a dark orange outline.](/assets/images/help/codespaces/codespaces-commit-pr-button.png) +1. Check that the local branch and repository you're merging from, and the remote branch and repository you're merging into, are correct. Then, give the pull request a title and a description. +![Screenshot of the "{% data variables.product.prodname_dotcom %} Pull Request" side bar with a form for creating a pull request, including "Title" and "Description" fields.](/assets/images/help/codespaces/codespaces-commit-pr.png) +1. Click **Create**. + +For more information on creating pull requests in {% data variables.product.prodname_github_codespaces %}, see [AUTOTITLE](/codespaces/developing-in-a-codespace/using-github-codespaces-for-pull-requests). + +{% endcodespaces %} + +{% endif %} + +## Making changes to files in your pull request + +After you open your pull request, you can continue changing files by adding new commits to your head branch. + +{% webui %} + +You can also make changes to files on the {% data variables.product.github %} website. + +1. On {% data variables.product.github %}, navigate to a pull request in a repository. +{% data reusables.repositories.changed-files %} +1. Scroll down to the file you want to make changes to. + * If the pull request has a lot of files, you can use the filter to locate the file. +1. Above the file you want to change, click {% octicon "kebab-horizontal" aria-label="Show options" %}. + ![Screenshot of the options above a file on the "File changed" tab. The "Show options" button is highlighted with an orange rectangle.](/assets/images/help/pull_requests/menu-on-pull-request-file.png) +1. In the menu, click **Edit file**. +1. Make your changes in the editor. When you commit your change, choose to commit directly back to your head branch. + +{% endwebui %} + +## Further reading + +* [AUTOTITLE](/pull-requests/how-tos/create-pull-requests/creating-a-pull-request-from-a-fork) +* [AUTOTITLE](/pull-requests/how-tos/create-pull-requests/keeping-your-pull-request-in-sync-with-the-base-branch) +* [AUTOTITLE](/pull-requests/how-tos/create-pull-requests/changing-the-base-branch-of-a-pull-request) +* [AUTOTITLE](/issues/tracking-your-work-with-issues/using-issues/creating-an-issue) +* [AUTOTITLE](/issues/tracking-your-work-with-issues/using-issues/assigning-issues-and-pull-requests-to-other-github-users) +* [AUTOTITLE](/get-started/writing-on-github) diff --git a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/index.md b/content/pull-requests/how-tos/create-pull-requests/index.md similarity index 51% rename from content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/index.md rename to content/pull-requests/how-tos/create-pull-requests/index.md index 42562e848dda..7846973d5271 100644 --- a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/index.md +++ b/content/pull-requests/how-tos/create-pull-requests/index.md @@ -1,27 +1,23 @@ --- -title: Proposing changes to your work with pull requests -intro: 'After you add changes to a topic branch or fork, you can open a pull request to ask your collaborators or the repository administrator to review your changes before merging them into the project.' +title: Create pull requests redirect_from: + - /pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests - /github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests - /articles/proposing-changes-to-your-work-with-pull-requests - /github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests +shortTitle: Create pull requests +intro: Create pull requests, manage branches, keep them in sync, and request reviews for collaborative development. versions: fpt: '*' ghes: '*' ghec: '*' children: - - /about-branches - - /creating-and-deleting-branches-within-your-repository - - /about-pull-requests - - /about-comparing-branches-in-pull-requests - /creating-a-pull-request - /creating-a-pull-request-from-a-fork - - /using-query-parameters-to-create-a-pull-request - /changing-the-stage-of-a-pull-request - /requesting-a-pull-request-review - /keeping-your-pull-request-in-sync-with-the-base-branch - /changing-the-base-branch-of-a-pull-request - - /committing-changes-to-a-pull-request-branch-created-from-a-fork -shortTitle: Propose changes +contentType: how-tos --- diff --git a/content/pull-requests/how-tos/create-pull-requests/keeping-your-pull-request-in-sync-with-the-base-branch.md b/content/pull-requests/how-tos/create-pull-requests/keeping-your-pull-request-in-sync-with-the-base-branch.md new file mode 100644 index 000000000000..e878a571c4eb --- /dev/null +++ b/content/pull-requests/how-tos/create-pull-requests/keeping-your-pull-request-in-sync-with-the-base-branch.md @@ -0,0 +1,44 @@ +--- +title: Keeping your pull request in sync with the base branch +intro: Update your pull request branch with changes from the base branch to resolve conflicts and ensure compatibility before merging. +permissions: People with write permissions to the repository to which the head branch of the pull request belongs can update the head branch with changes that have been made in the base branch. +versions: + fpt: '*' + ghes: '*' + ghec: '*' +shortTitle: Update the head branch +category: + - Create pull requests +redirect_from: + - /pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/keeping-your-pull-request-in-sync-with-the-base-branch +contentType: how-tos +--- + +## About keeping your pull request in sync + +Before merging, update your pull request branch with changes from the base branch to catch conflicts or test failures early. You can update the branch from the pull request page when there are no merge conflicts and the branch is behind the base branch. + +> [!NOTE] +> You may not be able to use the `Update branch` button if the HEAD branch of your pull request is a protected branch. See [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches). + +If changes to the base branch cause merge conflicts in your pull request branch, resolve the conflicts before updating the branch. See [AUTOTITLE](/pull-requests/reference/merge-conflicts). + +From the pull request page, you can update by merging the base branch into your head branch or by rebasing your changes onto the latest base branch. Rebasing creates a linear history without a merge commit. See [AUTOTITLE](/pull-requests/reference/branches#three-dot-and-two-dot-git-diff-comparisons). + +## Updating your pull request branch + +{% data reusables.repositories.sidebar-pr %} +1. In the "Pull requests" list, click the pull request you want to update. +1. In the merge section near the bottom of the page, choose how to update the branch: + * Click **Update branch** to perform a traditional merge. + + ![Screenshot of the merge section for a pull request.](/assets/images/help/pull_requests/pull-request-update-branch-with-dropdown.png) + + * Click the update branch dropdown menu, click **Update with rebase**, then click **Rebase branch** to update by rebasing on the base branch. + + ![Screenshot of the merge section of a pull request. The dropdown menu is expanded, showing "Update with merge commit" and "Update with rebase" options.](/assets/images/help/pull_requests/pull-request-update-branch-rebase-option.png) + +## Further reading + +* [AUTOTITLE](/pull-requests/reference/pull-requests) +* [AUTOTITLE](/pull-requests/how-tos/create-pull-requests/changing-the-stage-of-a-pull-request) diff --git a/content/pull-requests/how-tos/create-pull-requests/requesting-a-pull-request-review.md b/content/pull-requests/how-tos/create-pull-requests/requesting-a-pull-request-review.md new file mode 100644 index 000000000000..1abd31f3144c --- /dev/null +++ b/content/pull-requests/how-tos/create-pull-requests/requesting-a-pull-request-review.md @@ -0,0 +1,54 @@ +--- +title: Requesting a pull request review +intro: Request reviews for your pull requests from individuals or teams to ensure thorough feedback and collaboration. +product: '{% data reusables.gated-features.multiple-pr-reviewers %}' +redirect_from: + - /github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests/requesting-a-pull-request-review + - /articles/requesting-a-pull-request-review + - /github/collaborating-with-issues-and-pull-requests/requesting-a-pull-request-review + - /github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/requesting-a-pull-request-review + - /pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/requesting-a-pull-request-review +versions: + fpt: '*' + ghes: '*' + ghec: '*' +shortTitle: Request a PR review +category: + - Create pull requests +contentType: how-tos +--- + +To request a review, you need write access to the repository. You can request a review from a person or team with read access to the repository, and they receive a notification. For complete details on permissions for requesting reviews, see [AUTOTITLE](/pull-requests/reference/pull-request-reviews#requesting-and-requiring-reviews). + +## Requesting reviews from collaborators and organization members + +Suggested reviewers are based on [git blame data](/repositories/working-with-files/using-files/viewing-and-understanding-files). After someone reviews your pull request and you make changes, you can request another review from the same reviewer. + +{% data reusables.repositories.sidebar-pr %} +1. In the list of pull requests, click the pull request that you want a specific person or team to review. +1. To request a review from a suggested person under **Reviewers**, next to their username, click **Request**. + + ![Screenshot of the "Reviewers" section of a pull request's sidebar. To the right of @octocat, a "Request" link is outlined in dark orange.](/assets/images/help/pull_requests/request-suggested-review.png) + +1. Optionally, to request a review from someone other than a suggested person, click **Reviewers**. + + If you know the name of the person or team you want a review from, type the username of the person or the name of the team you're asking to review your changes. Click their team name or username to request a review. + +1. After your pull request is reviewed and you make the necessary changes, you can ask a reviewer to review your pull request again. Navigate to **Reviewers** in the right sidebar and click {% octicon "sync" aria-label="Re-request review" %} next to the reviewer's name whose review you want. + + ![Screenshot of the "Reviewers" section of a pull request's sidebar. To the right of @octocat, a sync icon is outlined in dark orange.](/assets/images/help/pull_requests/request-re-review.png) + +{% ifversion fpt or ghec %} + +## Requesting a review from {% data variables.product.prodname_copilot %} + +> [!NOTE] +> {% data variables.product.prodname_copilot_short %} features require a {% data variables.product.prodname_copilot_short %} plan. See [AUTOTITLE](/copilot/get-started/plans). + +You can also request that {% data variables.product.prodname_copilot_short %} review your code and provide feedback and suggested changes on your work. See [AUTOTITLE](/copilot/how-tos/use-copilot-agents/request-a-code-review/use-code-review). + +{% endif %} + +## Further reading + +* [AUTOTITLE](/pull-requests/reference/pull-request-reviews) diff --git a/content/pull-requests/how-tos/index.md b/content/pull-requests/how-tos/index.md new file mode 100644 index 000000000000..71ad1484bcc9 --- /dev/null +++ b/content/pull-requests/how-tos/index.md @@ -0,0 +1,16 @@ +--- +title: How-tos for pull requests +shortTitle: How-tos +intro: 'Create, review, merge, and close pull requests, manage commits, and collaborate effectively using forks.' +versions: + fpt: '*' + ghes: '*' + ghec: '*' +children: + - /commit-changes + - /create-pull-requests + - /review-pull-requests + - /merge-and-close-pull-requests + - /work-with-forks +contentType: how-tos +--- diff --git a/content/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/automatically-merging-a-pull-request.md b/content/pull-requests/how-tos/merge-and-close-pull-requests/automatically-merging-a-pull-request.md similarity index 52% rename from content/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/automatically-merging-a-pull-request.md rename to content/pull-requests/how-tos/merge-and-close-pull-requests/automatically-merging-a-pull-request.md index 06c7d51021c8..870ed8b48ee3 100644 --- a/content/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/automatically-merging-a-pull-request.md +++ b/content/pull-requests/how-tos/merge-and-close-pull-requests/automatically-merging-a-pull-request.md @@ -1,6 +1,6 @@ --- title: Automatically merging a pull request -intro: You can increase development velocity by enabling auto-merge for a pull request so that the pull request will merge automatically when all merge requirements are met. +intro: Enable or disable auto-merge for pull requests to streamline your workflow and automatically merge changes once all requirements are met. product: '{% data reusables.gated-features.auto-merge %}' versions: fpt: '*' @@ -10,19 +10,17 @@ redirect_from: - /github/collaborating-with-issues-and-pull-requests/incorporating-changes-from-a-pull-request/automatically-merging-a-pull-request - /github/collaborating-with-issues-and-pull-requests/automatically-merging-a-pull-request - /github/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/automatically-merging-a-pull-request + - /pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/automatically-merging-a-pull-request shortTitle: Merge PR automatically category: - Merge and close pull requests +contentType: how-tos --- ## About auto-merge -If you enable auto-merge for a pull request, the pull request will merge automatically when all required reviews are met and all required status checks have passed. Auto-merge helps you avoid waiting around for requirements to be met, so you can move on to other tasks. +Auto-merge merges a pull request automatically after all required reviews and status checks pass. Before you use auto-merge, it must be enabled for the repository. See [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-auto-merge-for-pull-requests-in-your-repository). -Before you can use auto-merge with a pull request, auto-merge must be enabled for the repository. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-auto-merge-for-pull-requests-in-your-repository). - -After you enable auto-merge for a pull request, if someone who does not have write permissions to the repository pushes new changes to the head branch or switches the base branch of the pull request, auto-merge will be disabled. For example, if a maintainer enables auto-merge for a pull request from a fork, auto-merge will be disabled after a contributor pushes new changes to the pull request. - -You can provide feedback about auto-merge through a [{% data variables.product.prodname_github_community %} discussion](https://github.com/orgs/community/discussions/categories/pull-requests). +Auto-merge is disabled if someone without write permissions pushes new changes to the head branch or switches the base branch. ## Enabling auto-merge @@ -32,8 +30,8 @@ People with write permissions to a repository can enable auto-merge for a pull r {% data reusables.repositories.navigate-to-repo %} {% data reusables.repositories.sidebar-pr %} -1. In the "Pull Requests" list, click the pull request you'd like to auto-merge. -1. Optionally, to choose a merge method, select the {% octicon "triangle-down" aria-label="Select the merge method" %} dropdown menu, then click a merge method. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges). +1. In the "Pull Requests" list, click the pull request you want to auto-merge. +1. Optionally, select the {% octicon "triangle-down" aria-label="Select the merge method" %} dropdown menu, then click a merge method. See [AUTOTITLE](/pull-requests/reference/pull-request-merges). ![Screenshot of the merge box of a pull request. A dropdown menu, labeled with a downward-facing triangle, is outlined in dark orange.](/assets/images/help/pull_requests/enable-auto-merge-drop-down.png) @@ -56,5 +54,5 @@ People with write permissions to a repository and pull request authors can disab {% data reusables.repositories.navigate-to-repo %} {% data reusables.repositories.sidebar-pr %} -1. In the "Pull Requests" list, click the pull request you'd like to disable auto-merge for. +1. In the "Pull Requests" list, click the pull request for which you want to disable auto-merge. 1. In the merge box, click **Disable auto-merge**. diff --git a/content/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/closing-a-pull-request.md b/content/pull-requests/how-tos/merge-and-close-pull-requests/closing-a-pull-request.md similarity index 53% rename from content/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/closing-a-pull-request.md rename to content/pull-requests/how-tos/merge-and-close-pull-requests/closing-a-pull-request.md index 5cfb6a890630..b81b8e49af8f 100644 --- a/content/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/closing-a-pull-request.md +++ b/content/pull-requests/how-tos/merge-and-close-pull-requests/closing-a-pull-request.md @@ -1,23 +1,26 @@ --- title: Closing a pull request -intro: 'You may choose to *close* a pull request without [merging it into the upstream branch](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request). This can be handy if the changes proposed in the branch are no longer needed, or if another solution has been proposed in another branch.' +intro: Close a pull request without merging it to manage unnecessary changes or address alternative solutions in other branches. redirect_from: - /github/collaborating-with-issues-and-pull-requests/incorporating-changes-from-a-pull-request/closing-a-pull-request - /articles/closing-a-pull-request - /github/collaborating-with-issues-and-pull-requests/closing-a-pull-request - /github/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/closing-a-pull-request + - /pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/closing-a-pull-request versions: fpt: '*' ghes: '*' ghec: '*' +shortTitle: Close a pull request category: - Merge and close pull requests +contentType: how-tos --- > [!TIP] -> If you opened a pull request with the wrong base branch, rather than closing it out and opening a new one, you can instead change the base branch. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-base-branch-of-a-pull-request). +> If you opened a pull request with the wrong base branch, instead of closing it and opening a new one, you can change the base branch. See [AUTOTITLE](/pull-requests/how-tos/create-pull-requests/changing-the-base-branch-of-a-pull-request). {% data reusables.repositories.sidebar-pr %} -1. In the "Pull Requests" list, click the pull request you'd like to close. +1. In the "Pull Requests" list, click the pull request you want to close. 1. At the bottom of the pull request, below the comment box, click **Close pull request**. 1. Optionally, [delete the branch](/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/deleting-and-restoring-branches-in-a-pull-request). This keeps the list of branches in your repository tidy. diff --git a/content/pull-requests/how-tos/merge-and-close-pull-requests/index.md b/content/pull-requests/how-tos/merge-and-close-pull-requests/index.md new file mode 100644 index 000000000000..001f24d42cb5 --- /dev/null +++ b/content/pull-requests/how-tos/merge-and-close-pull-requests/index.md @@ -0,0 +1,34 @@ +--- +title: Merge and close pull requests +redirect_from: + - /pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts + - /github/collaborating-with-issues-and-pull-requests/addressing-merge-conflicts + - /articles/addressing-merge-conflicts + - /github/collaborating-with-pull-requests/addressing-merge-conflicts + - /pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features + - /github/collaborating-with-issues-and-pull-requests/collaborating-on-repositories-with-code-quality-features + - /articles/collaborating-on-repositories-with-code-quality-features-enabled + - /articles/collaborating-on-repositories-with-code-quality-features + - /github/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features + - /pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request + - /github/collaborating-with-issues-and-pull-requests/incorporating-changes-from-a-pull-request + - /articles/incorporating-changes-from-a-pull-request + - /github/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request +shortTitle: Merge and close +intro: 'Merge, revert, and close pull requests, resolve merge conflicts, and troubleshoot status checks effectively on {% data variables.product.github %}.' +versions: + fpt: '*' + ghes: '*' + ghec: '*' +children: + - /resolving-a-merge-conflict-on-github + - /resolving-a-merge-conflict-using-the-command-line + - /troubleshooting-required-status-checks + - /merging-a-pull-request + - /merging-a-pull-request-with-a-merge-queue + - /automatically-merging-a-pull-request + - /reverting-a-pull-request + - /closing-a-pull-request +contentType: how-tos +--- + diff --git a/content/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request-with-a-merge-queue.md b/content/pull-requests/how-tos/merge-and-close-pull-requests/merging-a-pull-request-with-a-merge-queue.md similarity index 62% rename from content/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request-with-a-merge-queue.md rename to content/pull-requests/how-tos/merge-and-close-pull-requests/merging-a-pull-request-with-a-merge-queue.md index 662eba9f8ecc..2820d28e062d 100644 --- a/content/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request-with-a-merge-queue.md +++ b/content/pull-requests/how-tos/merge-and-close-pull-requests/merging-a-pull-request-with-a-merge-queue.md @@ -1,6 +1,6 @@ --- title: Merging a pull request with a merge queue -intro: 'If a merge queue is required by the branch protection setting for the branch, you can add your pull requests to a merge queue and {% data variables.product.github %} will merge the pull requests for you once all required checks have passed.' +intro: 'Use merge queues in {% data variables.product.github %} to streamline pull request merging, ensure required checks pass, and manage queue operations effectively.' versions: fpt: '*' ghec: '*' @@ -9,16 +9,17 @@ shortTitle: Merge PR with merge queue redirect_from: - /pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/adding-a-pull-request-to-the-merge-queue - /github/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/adding-a-pull-request-to-the-merge-queue + - /pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request-with-a-merge-queue defaultTool: webui product: '{% data reusables.gated-features.merge-queue %}' category: - Merge and close pull requests +contentType: how-tos --- ## About merge queues -{% data reusables.pull_requests.merge-queue-overview %} -{% data reusables.pull_requests.merge-queue-references %} +A merge queue helps merge pull requests into a busy protected branch after required checks pass. See [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue). ## Adding a pull request to a merge queue @@ -30,7 +31,7 @@ category: {% data reusables.repositories.navigate-to-repo %} {% data reusables.repositories.sidebar-pr %} -1. In the "Pull Requests" list, click the pull request you would like to add to a merge queue. +1. In the "Pull Requests" list, click the pull request you want to add to a merge queue. 1. Click **Merge when ready** to add the pull request to the merge queue. Alternatively, if you are an administrator, you can: @@ -39,7 +40,7 @@ category: ![Screenshot of the merge queue options for a pull request.](/assets/images/help/pull_requests/merge-queue-options.png) > [!NOTE] - > You can click **Merge when ready** whenever you're ready to merge your proposed changes. {% data variables.product.github %} will automatically add the pull request to the merge queue once required approval and status checks conditions are met. + > You can click **Merge when ready** before all requirements pass. {% data variables.product.github %} adds the pull request to the queue when requirements are met. 1. Confirm you want to add the pull request to the merge queue by clicking **Confirm merge when ready**. @@ -47,7 +48,7 @@ category: {% cli %} -With {% data variables.product.prodname_cli %}, you can use the `gh pr merge` command to add a pull request to a merge queue. If you are targeting a branch that requires a merge queue, this command automatically adds the pull request to the queue if required checks have passed. If required checks have not passed, this command enables auto-merge for the pull request. For more information, see [`gh pr merge`](https://cli.github.com/manual/gh_pr_merge) in the {% data variables.product.prodname_cli %} manual. +With {% data variables.product.prodname_cli %}, use the `gh pr merge` command to add a pull request to a merge queue. If you are targeting a branch that requires a merge queue, this command automatically adds the pull request to the queue if required checks have passed. If required checks have not passed, this command enables auto-merge for the pull request. See [`gh pr merge`](https://cli.github.com/manual/gh_pr_merge) in the {% data variables.product.prodname_cli %} manual. {% endcli %} @@ -62,13 +63,13 @@ To remove a pull request from a merge queue, you must navigate to the repository {% data reusables.repositories.navigate-to-repo %} {% data reusables.repositories.sidebar-pr %} -1. In the "Pull Requests" list, click the pull request you would like to remove from a merge queue. +1. In the "Pull Requests" list, click the pull request you want to remove from a merge queue. 1. To remove the pull request from the queue, click **Remove from queue**. ![Screenshot of the merge queue message at the bottom of a pull request. The "Remove from queue" button is outlined in dark orange.](/assets/images/help/pull_requests/remove-from-queue-button.png) -Alternatively, you can navigate to the merge queue page for the base branch, click **...** next to the pull request you want to remove, and select **Remove from queue**. For information on how to get to the merge queue page for the base branch, see the section below. +Alternatively, you can navigate to the merge queue page for the base branch, click **...** next to the pull request you want to remove, and select **Remove from queue**. For information about getting to the merge queue page for the base branch, see the section below. ## Viewing merge queues @@ -84,11 +85,11 @@ You can view the merge queue for a base branch in various places on {% data vari {% endwebui %} -* On the **Branches** page for the repository. We recommend you use this route if you don't have or don't know about a pull request already in a queue, and if you want to see what's in that queue. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/viewing-branches-in-your-repository). +* On the **Branches** page for the repository. We recommend this route if you don't have or don't know about a pull request already in a queue, and if you want to see what's in that queue. See [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/viewing-branches-in-your-repository). ![Screenshot of the "Branches" page for a repository. A link, labeled "33 pull requests queued to merge," is outlined in dark orange.](/assets/images/help/pull_requests/merge-queue-branches-page.png) -* On the pull request page when merge queue is required for merging, scroll to the bottom of the timeline and click the **merge queue** link. +* On the pull request page, when a merge queue is required for merging, scroll to the bottom of the timeline and click the **merge queue** link. ![Screenshot of the merge queue message at the bottom of a pull request. The "merge queue" link is outlined in dark orange.](/assets/images/help/pull_requests/merge-queue-link.png) @@ -98,6 +99,6 @@ You can view the merge queue for a base branch in various places on {% data vari ## Understanding why your pull request was removed from the merge queue -{% data reusables.pull_requests.merge-queue-reject %} +A pull request can be removed from the merge queue if it no longer meets merge requirements or if a queue check fails. {% data reusables.pull_requests.merge-queue-removal-reasons %} diff --git a/content/pull-requests/how-tos/merge-and-close-pull-requests/merging-a-pull-request.md b/content/pull-requests/how-tos/merge-and-close-pull-requests/merging-a-pull-request.md new file mode 100644 index 000000000000..2dd7ec38da36 --- /dev/null +++ b/content/pull-requests/how-tos/merge-and-close-pull-requests/merging-a-pull-request.md @@ -0,0 +1,101 @@ +--- +title: Merging a pull request +intro: Merge pull requests into the upstream branch, choose merge methods, and meet repository requirements like reviews or status checks. +redirect_from: + - /github/collaborating-with-issues-and-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request + - /articles/merging-a-pull-request + - /github/collaborating-with-issues-and-pull-requests/merging-a-pull-request + - /github/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request + - /pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request +versions: + fpt: '*' + ghes: '*' + ghec: '*' +shortTitle: Merge a pull request +category: + - Merge and close pull requests +contentType: how-tos +--- +## About pull request merges + +Merge a pull request when the proposed changes are ready and any repository requirements are satisfied. You can't merge a draft pull request. + +Repository rules or branch protection may require reviews, status checks, or an up-to-date branch before merging. See [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches). + +{% data reusables.repositories.rulesets-alternative %} + +{% data reusables.pull_requests.you-can-auto-merge %} + +If the base branch requires a merge queue, the available merge options differ from those described here. See [AUTOTITLE](/pull-requests/how-tos/merge-and-close-pull-requests/merging-a-pull-request-with-a-merge-queue). + +If the pull request has merge conflicts, or if you want to test changes first, [check out the pull request locally](/pull-requests/how-tos/review-pull-requests/checking-out-pull-requests-locally). + +The repository may automatically delete the head branch after merging. See [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-the-automatic-deletion-of-branches). + +> [!NOTE] +> {% data reusables.pull_requests.retargeted-on-branch-deletion %} + +Pull requests use [the `--no-ff` option](https://git-scm.com/docs/git-merge#_fast_forward_merge), except squashed or rebased pull requests, which use fast-forward merging. + +{% data reusables.pull_requests.close-issues-using-keywords %} + +If you don't want to merge the changes, you can [close the pull request](/pull-requests/how-tos/merge-and-close-pull-requests/closing-a-pull-request). + +## Merging a pull request + +{% webui %} + +{% data reusables.repositories.sidebar-pr %} +1. In the "Pull Requests" list, click the pull request you want to merge. +1. Scroll down to the bottom of the pull request. Depending on the merge options enabled for your repository, choose a merge method: + + * [Merge all commits into the base branch](/pull-requests/reference/pull-request-merges) by clicking **Merge pull request**. If the option is not shown, click the merge dropdown menu and select **Create a merge commit**. + + ![Screenshot of the merge options for a pull request. The arrow to expand the dropdown is outlined in dark orange.](/assets/images/help/pull_requests/merge-pull-request-options.png) + + * [Squash the commits into one commit](/pull-requests/reference/pull-request-merges#squash-and-merge-your-pull-request-commits) by clicking the merge dropdown menu, selecting **Squash and merge**, and then clicking **Squash and merge**. + + * [Rebase the commits individually onto the base branch](/pull-requests/reference/pull-request-merges#rebase-and-merge-your-pull-request-commits) by clicking the merge dropdown menu, selecting **Rebase and merge**, and then clicking **Rebase and merge**. + + > [!NOTE] + > Rebase and merge will always update the committer information and create new commit SHAs. See [About pull request merges](/pull-requests/reference/pull-request-merges#rebase-and-merge-your-pull-request-commits). + +1. If prompted, type a commit message, or accept the default message. + + {% data reusables.pull_requests.default-commit-message-squash-merge %} +{% data reusables.files.choose-commit-email %} + + > [!NOTE] + > The email selector is not available for rebase merges, which do not create a merge commit{% ifversion squash-merge-email %}. For squash merges, the email selector is only shown if you are the pull request author and you have more than one email address associated with your account.{% else %}, or for squash merges, which credit the user who created the pull request as the author of the squashed commit.{% endif %} + +1. Click **Confirm merge**, **Confirm squash and merge**, or **Confirm rebase and merge**. +1. Optionally, [delete the branch](/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/deleting-and-restoring-branches-in-a-pull-request). This keeps the list of branches in your repository tidy. + +{% endwebui %} + +{% cli %} + +{% data reusables.cli.cli-learn-more %} + +To merge a pull request, use the `gh pr merge` subcommand. Replace `pull-request` with the number, URL, or head branch of the pull request. + +```shell +gh pr merge PULL-REQUEST +``` + +Follow the interactive prompts to complete the merge. See [AUTOTITLE](/pull-requests/reference/pull-request-merges). + +Alternatively, you can use flags to skip the interactive prompts. For example, this command squashes the commits into a single commit with the commit message "my squash commit", merges the squashed commit into the base branch, and then deletes the local and remote branch. + +```shell +gh pr merge 523 --squash --body "my squash commit" --delete-branch +``` + +{% endcli %} + +## Further reading + +* [AUTOTITLE](/pull-requests/how-tos/merge-and-close-pull-requests/reverting-a-pull-request) +* [AUTOTITLE](/desktop/working-with-your-remote-repository-on-github-or-github-enterprise/syncing-your-branch-in-github-desktop) using {% data variables.product.prodname_desktop %} +* [AUTOTITLE](/pull-requests/reference/pull-request-merges) +* [AUTOTITLE](/pull-requests/how-tos/merge-and-close-pull-requests) diff --git a/content/pull-requests/how-tos/merge-and-close-pull-requests/resolving-a-merge-conflict-on-github.md b/content/pull-requests/how-tos/merge-and-close-pull-requests/resolving-a-merge-conflict-on-github.md new file mode 100644 index 000000000000..9e1ce4bb0146 --- /dev/null +++ b/content/pull-requests/how-tos/merge-and-close-pull-requests/resolving-a-merge-conflict-on-github.md @@ -0,0 +1,60 @@ +--- +title: Resolving a merge conflict on GitHub +intro: Resolve simple merge conflicts directly on {% data variables.product.github %} using the conflict editor or handle complex cases via the command line. +redirect_from: + - /github/collaborating-with-issues-and-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-on-github + - /articles/resolving-a-merge-conflict-on-github + - /github/collaborating-with-issues-and-pull-requests/resolving-a-merge-conflict-on-github + - /github/resolving-a-merge-conflict-on-github + - /github/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-on-github + - /pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-on-github +versions: + fpt: '*' + ghes: '*' + ghec: '*' +shortTitle: Resolve merge conflicts +category: + - Merge and close pull requests +contentType: how-tos +--- +You can resolve simple competing line change conflicts on {% data variables.product.github %}. For other conflicts, use the command line. See [AUTOTITLE](/pull-requests/how-tos/merge-and-close-pull-requests/resolving-a-merge-conflict-using-the-command-line). + +{% ifversion fpt or ghec %} +If {% data variables.copilot.copilot_cloud_agent %} is enabled for the repository, you can click **Fix with {% data variables.product.prodname_copilot_short %}** in the merge box to have {% data variables.product.prodname_copilot_short %} resolve conflicts automatically. See [AUTOTITLE](/copilot/how-tos/use-copilot-agents/cloud-agent/use-cloud-agent-on-github#resolving-merge-conflicts). +{% endif %} + +{% ifversion ghes %} +If a site administrator disables the merge conflict editor for pull requests between repositories, resolve merge conflicts on the command line. +{% endif %} + +> [!WARNING] +> Resolving conflicts on {% data variables.product.github %} merges the entire [base branch](/get-started/learning-about-github/github-glossary#base-branch) into the [head branch](/get-started/learning-about-github/github-glossary#head-branch). If the head branch is the default or protected branch, you may be prompted to create a new head branch. See [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches). + +{% data reusables.repositories.sidebar-pr %} +1. In the "Pull Requests" list, click the pull request with a merge conflict that you want to resolve. +1. Near the bottom of your pull request, click **Resolve conflicts**. + + ![Screenshot of a warning that a pull request has a merge conflict. The "Resolve merge conflicts" button is outlined in dark orange.](/assets/images/help/pull_requests/resolve-merge-conflicts-button.png) + + > [!NOTE] + > If **Resolve conflicts** is deactivated, resolve the conflict using another Git client or the command line. See [AUTOTITLE](/pull-requests/how-tos/merge-and-close-pull-requests/resolving-a-merge-conflict-using-the-command-line). + +{% data reusables.pull_requests.decide-how-to-resolve-competing-line-change-merge-conflict %} +1. If your file has more than one merge conflict, scroll down to the next set of conflict markers and repeat steps four and five to resolve the conflict. +1. After you've resolved all the conflicts in the file, click **Mark as resolved**. + + ![Screenshot of the editor to resolve a merge conflict in a pull request. The "Mark as resolved" button is outlined in dark orange.](/assets/images/help/pull_requests/mark-as-resolved-button.png) + +1. If more than one file has a conflict, select the next file you want to edit on the left side of the page under "conflicting files" and repeat steps four through seven until you've resolved all merge conflicts in your pull request. +1. After you've resolved all your merge conflicts, click **Commit merge**. This merges the entire base branch into your head branch. + + ![Screenshot of the editor to resolve a merge conflict in a pull request. The "Commit merge" button is outlined in dark orange.](/assets/images/help/pull_requests/merge-conflict-commit-changes.png) + +1. If prompted, review the branch that you are committing to. You can update the head branch or, if available, create a new branch for the pull request. If the head branch is protected, you must create a new branch. + + Click **Create branch and update my pull request** or **I understand, continue updating BRANCH**. +1. To merge your pull request, click **Merge pull request**. See [AUTOTITLE](/pull-requests/how-tos/merge-and-close-pull-requests/merging-a-pull-request). + +## Further reading + +* [AUTOTITLE](/pull-requests/reference/pull-request-merges) diff --git a/content/pull-requests/how-tos/merge-and-close-pull-requests/resolving-a-merge-conflict-using-the-command-line.md b/content/pull-requests/how-tos/merge-and-close-pull-requests/resolving-a-merge-conflict-using-the-command-line.md new file mode 100644 index 000000000000..48af16cf050f --- /dev/null +++ b/content/pull-requests/how-tos/merge-and-close-pull-requests/resolving-a-merge-conflict-using-the-command-line.md @@ -0,0 +1,141 @@ +--- +title: Resolving a merge conflict using the command line +intro: Resolve merge conflicts using the command line by identifying conflicting changes, editing files, and committing resolutions. +redirect_from: + - /github/collaborating-with-issues-and-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-using-the-command-line + - /articles/resolving-a-merge-conflict-from-the-command-line + - /articles/resolving-a-merge-conflict-using-the-command-line + - /github/collaborating-with-issues-and-pull-requests/resolving-a-merge-conflict-using-the-command-line + - /github/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-using-the-command-line + - /pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-using-the-command-line +versions: + fpt: '*' + ghes: '*' + ghec: '*' +shortTitle: Resolve merge conflicts in Git +category: + - Merge and close pull requests +contentType: how-tos +--- +Merge conflicts happen when competing changes are made to the same line of a file, or when one person edits a file and another person deletes the same file. See [AUTOTITLE](/pull-requests/reference/merge-conflicts). + +> [!TIP] +> You can use the conflict editor on {% data variables.product.github %} to resolve competing line change merge conflicts between branches that are part of a pull request. See [AUTOTITLE](/pull-requests/how-tos/merge-and-close-pull-requests/resolving-a-merge-conflict-on-github). + +## Competing line change merge conflicts + +When competing changes affect the same lines, choose which changes to keep, then commit the resolution. + +1. Open your terminal or Git Bash. +1. Navigate into the local Git repository that has the merge conflict. + + ```shell + cd REPOSITORY-NAME + ``` + +1. List the files affected by the merge conflict. In this example, the file _styleguide.md_ has a merge conflict. + + ```shell + $ git status + > # On branch branch-b + > # You have unmerged paths. + > # (fix conflicts and run "git commit") + > # + > # Unmerged paths: + > # (use "git add ..." to mark resolution) + > # + > # both modified: styleguide.md + > # + > no changes added to commit (use "git add" and/or "git commit -a") + ``` + +1. Open your preferred text editor, such as [{% data variables.product.prodname_vscode %}](https://code.visualstudio.com/), and navigate to the file that has merge conflicts. +1. Search the file for the conflict marker `<<<<<<<`. The changes from the HEAD or base branch appear after `<<<<<<< HEAD`, followed by `=======`, then the changes from the other branch and `>>>>>>> BRANCH-NAME`. + + ```text + If you have questions, please + <<<<<<< HEAD + open an issue + ======= + ask your question in IRC. + >>>>>>> branch-a + ``` + +{% data reusables.pull_requests.decide-how-to-resolve-competing-line-change-merge-conflict %} For example, you can keep both changes: + + ```shell + If you have questions, please open an issue or ask in our IRC channel if it's more urgent. + ``` + +1. Stage your changes. + + ```shell + git add . + ``` + +1. Commit your changes with a comment. + + ```shell + git commit -m "Resolve merge conflict by incorporating both suggestions" + ``` + +You can now merge the branches on the command line or [push your changes to your remote repository](/get-started/using-git/pushing-commits-to-a-remote-repository) on {% data variables.product.github %} and [merge your changes](/pull-requests/how-tos/merge-and-close-pull-requests/merging-a-pull-request) in a pull request. + +## Removed file merge conflicts + +When one branch deletes a file and another branch edits the same file, choose whether to keep or delete the file, then commit the resolution. + +1. Open your terminal or Git Bash. +1. Navigate into the local Git repository that has the merge conflict. + + ```shell + cd REPOSITORY-NAME + ``` + +1. List the files affected by the merge conflict. In this example, the file `README.md` has a merge conflict. + + ```shell + $ git status + > # On branch main + > # Your branch and 'origin/main' have diverged, + > # and have 1 and 2 different commits each, respectively. + > # (use "git pull" to merge the remote branch into yours) + > # You have unmerged paths. + > # (fix conflicts and run "git commit") + > # + > # Unmerged paths: + > # (use "git add/rm ..." as appropriate to mark resolution) + > # + > # deleted by us: README.md + > # + > # no changes added to commit (use "git add" and/or "git commit -a") + ``` + +1. Open your preferred text editor, such as [{% data variables.product.prodname_vscode %}](https://code.visualstudio.com/), and navigate to the file that has merge conflicts. +1. Decide whether to keep the removed file. To add it back to your repository: + + ```shell + git add README.md + ``` + + To remove this file from your repository: + + ```shell + $ git rm README.md + > README.md: needs merge + > rm 'README.md' + ``` + +1. Commit your changes with a comment. + + ```shell + $ git commit -m "Resolve merge conflict by keeping README.md file" + > [branch-d 6f89e49] Merge branch 'branch-c' into branch-d + ``` + +With merge conflicts resolved, you can now push your changes to your remote repository on {% data variables.product.github %} or merge your pull request into its base branch. + +## Further reading + +* [AUTOTITLE](/pull-requests/reference/merge-conflicts) +* [AUTOTITLE](/pull-requests/how-tos/review-pull-requests/checking-out-pull-requests-locally) diff --git a/content/pull-requests/how-tos/merge-and-close-pull-requests/reverting-a-pull-request.md b/content/pull-requests/how-tos/merge-and-close-pull-requests/reverting-a-pull-request.md new file mode 100644 index 000000000000..2fa3bb13bcf5 --- /dev/null +++ b/content/pull-requests/how-tos/merge-and-close-pull-requests/reverting-a-pull-request.md @@ -0,0 +1,34 @@ +--- +title: Reverting a pull request +intro: Create a new pull request to revert a previously merged pull request and address merge conflicts if they arise. +redirect_from: + - /github/collaborating-with-issues-and-pull-requests/incorporating-changes-from-a-pull-request/reverting-a-pull-request + - /github/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/reverting-a-pull-request + - /articles/reverting-a-pull-request + - /github/collaborating-with-issues-and-pull-requests/reverting-a-pull-request + - /pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/reverting-a-pull-request +versions: + fpt: '*' + ghes: '*' + ghec: '*' +shortTitle: Revert a pull request +category: + - Merge and close pull requests +contentType: how-tos +--- +## About reverting a pull request + +Reverting a merged pull request creates a new pull request that reverts the original merge commit. You must have [write permissions](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization) in the repository. + +## Reverting a pull request + +> [!NOTE] +> You may need to revert individual commits if reverting the pull request causes merge conflicts or if the original pull request was not merged on {% data variables.product.github %}. See [Git revert](https://git-scm.com/docs/git-revert.html) in the Git documentation. + +{% data reusables.repositories.sidebar-pr %} +1. In the "Pull Requests" list, click the pull request you want to revert. +1. Near the bottom of the pull request, click **Revert**. If the **Revert** option isn't displayed, you need to ask the repository administrator for write permissions. + + ![Screenshot of a pull request's timeline. The "Revert" button is outlined in dark orange.](/assets/images/help/pull_requests/revert-pull-request-link.png) + +1. Merge the resulting pull request. See [AUTOTITLE](/pull-requests/how-tos/merge-and-close-pull-requests/merging-a-pull-request). diff --git a/content/pull-requests/how-tos/merge-and-close-pull-requests/troubleshooting-required-status-checks.md b/content/pull-requests/how-tos/merge-and-close-pull-requests/troubleshooting-required-status-checks.md new file mode 100644 index 000000000000..c4c7e31a47b6 --- /dev/null +++ b/content/pull-requests/how-tos/merge-and-close-pull-requests/troubleshooting-required-status-checks.md @@ -0,0 +1,116 @@ +--- +title: Troubleshooting required status checks +intro: Resolve common errors and unblock merging or pushing to protected branches by troubleshooting required status checks. +product: '{% data reusables.gated-features.protected-branches %}' +versions: + fpt: '*' + ghes: '*' + ghec: '*' +redirect_from: + - /github/administering-a-repository/troubleshooting-required-status-checks + - /github/administering-a-repository/defining-the-mergeability-of-pull-requests/troubleshooting-required-status-checks + - /repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/troubleshooting-required-status-checks + - /pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/troubleshooting-required-status-checks +shortTitle: Troubleshoot status checks +category: + - Merge and close pull requests +contentType: how-tos +--- +Use these checks when a required status check blocks merging or pushing to a protected branch. See [AUTOTITLE](/pull-requests/reference/status-checks). + +* A required status check must have completed successfully in the chosen repository during the past seven days. +* If a check and a commit status have the same name, both must pass when that name is required. See [AUTOTITLE](/rest/checks). +* If branch protection requires your branch to be up-to-date, merge or rebase the base branch into your branch. See [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-status-checks-before-merging) and [AUTOTITLE](/get-started/using-git/about-git-rebase). + +If required status checks have not passed, pushing to a protected branch returns an error similar to this. + +```shell +remote: error: GH006: Protected branch update failed for refs/heads/main. +remote: error: Required status check "ci-build" is failing +``` + +> [!NOTE] +> Pull requests that are up-to-date and pass required status checks can be merged locally and pushed to the protected branch. You can do this without running status checks on the merge commit itself. + +## Required check needs to succeed against the latest commit SHA + +Check the following if a required check is still blocking a pull request. + +* Required checks must pass on the latest commit SHA. Checks from earlier commits don't satisfy the requirement. +* Successful check statuses are `success`, `skipped`, and `neutral`. See [AUTOTITLE](/pull-requests/reference/status-checks). + +## Conflicts between head commit and test merge commit + +Use the pull request status checks box to identify which commit must pass. + +| Status check source | What must pass | What you may see | +| --- | --- | --- | +| Test merge commit has a status | The test merge commit | `Showing checks for the merge commit` | +| Test merge commit has no status | The head commit | Checks for the latest head commit | + +See [AUTOTITLE](/rest/pulls/pulls#get-a-pull-request). + +## Handling skipped but required checks + +| Cause | Result | How to fix or check | +| --- | --- | --- | +| A workflow is skipped by [path filtering](/actions/reference/workflows-and-actions/workflow-syntax#onpushpull_requestpull_request_targetpathspaths-ignore), [branch filtering](/actions/reference/workflows-and-actions/workflow-syntax#onpull_requestpull_request_targetbranchesbranches-ignore), or a [commit message](/actions/how-tos/manage-workflow-runs/skip-workflow-runs) | Associated checks stay in a "Pending" state and block merging | Avoid requiring workflows that can be skipped. | +| A job is skipped by a conditional | The job reports "Success" | See [AUTOTITLE](/actions/how-tos/write-workflows/choose-when-workflows-run/control-jobs-with-conditions). | +| A job depends on a failed job | The dependent job is skipped and may not block merging | Use `always()` with `needs` for required checks that depend on other jobs. See [AUTOTITLE](/actions/how-tos/write-workflows/choose-what-workflows-do/use-jobs#defining-prerequisite-jobs). | + +{% data reusables.pull_requests.path-filtering-required-workflows %} + +### Example + +This workflow requires a successful `build` job, but runs only when a pull request changes files in `scripts`. + +```yaml +name: ci +on: + pull_request: + paths: + - 'scripts/**' +jobs: + build: + runs-on: ubuntu-latest + strategy: + matrix: + node-version: [12.x, 14.x, 16.x] + steps: + - uses: {% data reusables.actions.action-checkout %} + - name: Use Node.js {% raw %}${{ matrix.node-version }}{% endraw %} + uses: {% data reusables.actions.action-setup-node %} + with: + node-version: {% raw %}${{ matrix.node-version }}{% endraw %} + cache: 'npm' + - run: npm ci + - run: npm run build --if-present + - run: npm test +``` + +A pull request that only changes a file in the repository root will not trigger this workflow. If `build` is required, the pull request is blocked with "Waiting for status to be reported." + +### Status checks with {% data variables.product.prodname_actions %} and a Merge queue + +If a merge queue requires a {% data variables.product.prodname_actions %} check, trigger the workflow with the `merge_group` event. + +> [!NOTE] +> {% data reusables.actions.merge-group-event-with-required-checks %} + +Example trigger configuration: + +```yaml +on: + pull_request: + merge_group: +``` + +See [AUTOTITLE](/actions/reference/workflows-and-actions/events-that-trigger-workflows#merge_group). + +## Required status checks from unexpected sources + +A protected branch can also require a status check from a specific {% data variables.product.prodname_github_app %}. If you see a message similar to the following, verify that the check listed in the merge box was set by the expected app. + +```text +Required status check "build" was not set by the expected {% data variables.product.prodname_github_app %}. +``` diff --git a/content/pull-requests/how-tos/review-pull-requests/approving-a-pull-request-with-required-reviews.md b/content/pull-requests/how-tos/review-pull-requests/approving-a-pull-request-with-required-reviews.md new file mode 100644 index 000000000000..9d568a2987f3 --- /dev/null +++ b/content/pull-requests/how-tos/review-pull-requests/approving-a-pull-request-with-required-reviews.md @@ -0,0 +1,43 @@ +--- +title: Approving a pull request with required reviews +intro: Approve pull requests with required reviews, including setting approval rules, reviewing changes, and submitting feedback before merging. +redirect_from: + - /github/collaborating-with-issues-and-pull-requests/reviewing-changes-in-pull-requests/approving-a-pull-request-with-required-reviews + - /articles/approving-a-pull-request-with-required-reviews + - /github/collaborating-with-issues-and-pull-requests/approving-a-pull-request-with-required-reviews + - /github/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/approving-a-pull-request-with-required-reviews + - /pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/approving-a-pull-request-with-required-reviews +versions: + fpt: '*' + ghes: '*' + ghec: '*' +shortTitle: Approve PRs +category: + - Review pull requests +contentType: how-tos +--- + +You can comment on a pull request, approve the changes, or request improvements before approving. See [AUTOTITLE](/pull-requests/how-tos/review-pull-requests/reviewing-proposed-changes-in-a-pull-request). + +{% data reusables.search.requested_reviews_search %} + +> [!TIP] +> If a pull request you approved has changed significantly, you can dismiss your review. The pull request will need a new review before it can be merged. See [AUTOTITLE](/pull-requests/how-tos/review-pull-requests/dismissing-a-pull-request-review). + +{% data reusables.repositories.sidebar-pr %} +{% data reusables.repositories.choose-pr-review %} +{% data reusables.repositories.changed-files %} +1. Review the changes in the pull request. Optionally, comment on specific lines or files. See [AUTOTITLE](/pull-requests/how-tos/review-pull-requests/reviewing-proposed-changes-in-a-pull-request#starting-a-review). +{% data reusables.repositories.review-changes %} +{% data reusables.repositories.review-summary-comment %} +1. Select **Approve** to approve merging the proposed changes. +{% data reusables.repositories.submit-review %} + +{% data reusables.repositories.request-changes-tips %} + +## Further reading + +* [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-pull-request-reviews-before-merging) +* [AUTOTITLE](/pull-requests/how-tos/review-pull-requests/reviewing-proposed-changes-in-a-pull-request) +* [AUTOTITLE](/pull-requests/how-tos/review-pull-requests/commenting-on-a-pull-request) + diff --git a/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/checking-out-pull-requests-locally.md b/content/pull-requests/how-tos/review-pull-requests/checking-out-pull-requests-locally.md similarity index 59% rename from content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/checking-out-pull-requests-locally.md rename to content/pull-requests/how-tos/review-pull-requests/checking-out-pull-requests-locally.md index 2cd07f6fb571..5fafd0cd4993 100644 --- a/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/checking-out-pull-requests-locally.md +++ b/content/pull-requests/how-tos/review-pull-requests/checking-out-pull-requests-locally.md @@ -1,11 +1,12 @@ --- title: Checking out pull requests locally -intro: 'When someone sends you a pull request from a fork or branch of your repository, you can merge it locally to resolve a merge conflict or to test and verify the changes before merging on {% data variables.product.github %}.' +intro: Check out pull requests locally to resolve merge conflicts, test changes, or modify code. redirect_from: - /github/collaborating-with-issues-and-pull-requests/reviewing-changes-in-pull-requests/checking-out-pull-requests-locally - /articles/checking-out-pull-requests-locally - /github/collaborating-with-issues-and-pull-requests/checking-out-pull-requests-locally - /github/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/checking-out-pull-requests-locally + - /pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/checking-out-pull-requests-locally versions: fpt: '*' ghes: '*' @@ -13,22 +14,23 @@ versions: shortTitle: Check out a PR locally category: - Review pull requests +contentType: how-tos --- > [!NOTE] -> Pull request authors can give upstream repository maintainers, or those with push access to the upstream repository, permission to make commits to their pull request's compare branch in a user-owned fork. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork). +> Pull request authors can give upstream repository maintainers, or people with push access to the upstream repository, permission to make commits to their pull request's compare branch in a user-owned fork. See [AUTOTITLE](/pull-requests/how-tos/work-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork). ## Modifying an active pull request locally {% webui %} {% data reusables.repositories.sidebar-pr %} -1. In the list of pull requests, click the pull request you'd like to modify.{% ifversion fpt or ghec %} -1. To choose where you'd like to open the pull request, select the **{% octicon "code" aria-hidden="true" aria-label="code" %} Code** dropdown and click one of the tabs. +1. In the list of pull requests, click the pull request you want to modify.{% ifversion fpt or ghec %} +1. To choose where you want to open the pull request, select the **{% octicon "code" aria-hidden="true" aria-label="code" %} Code** dropdown and click one of the tabs. ![Screenshot of a pull request title. A button with an arrow indicating a dropdown menu, labeled "Code," is outlined in dark orange.](/assets/images/help/pull_requests/open-with-button.png){% else %} -1. In the merge box, click **command line instructions**. Follow the sequence of steps to bring down the proposed pull request. +1. In the merge box, click **command line instructions**. Follow the steps to download the proposed pull request. ![Screenshot of the merge box in a pull request. The link to access command line pull request instructions is outlined in dark orange.](/assets/images/help/pull_requests/pull-request-show-command-line-merge.png) @@ -52,20 +54,20 @@ gh pr checkout PULL-REQUEST ## Modifying an inactive pull request locally -If a pull request’s author is unresponsive to requests or has deleted their fork, the changes proposed in that pull request can still be merged via a new pull request. However, if you want to make changes to a pull request and the author is not responding, you'll need to perform some additional steps to update the pull request. +If a pull request’s author is unresponsive to requests or has deleted their fork, the changes proposed in that pull request can still be merged through a new pull request. However, if you want to make changes, you need to take additional steps to update the pull request. -Once a pull request is opened, {% data variables.product.github %} stores all of the changes remotely. In other words, commits in a pull request are available in a repository even before the pull request is merged. You can fetch an open pull request and recreate it as your own. +After a pull request is opened, {% data variables.product.github %} stores all of the changes remotely. Commits in a pull request are available in a repository even before the pull request is merged. You can fetch an open pull request and recreate it as your own. -Anyone can work with a previously opened pull request to continue working on it, test it out, or even open a new pull request with additional changes. However, only collaborators with push access can merge pull requests. +Anyone can work with a previously opened pull request to continue working on it, test it, or open a new pull request with additional changes. -{% data reusables.repositories.sidebar-issue-pr %} -1. In the "Pull Requests" list, click the pull request you'd like to merge. +{% data reusables.repositories.sidebar-pr %} +1. In the **Pull Requests** list, click the pull request you want to merge. 1. Find the ID number of the inactive pull request. This is the sequence of digits right after the pull request's title. ![Screenshot of the title of a pull request. The pull request's ID number is outlined in dark orange.](/assets/images/help/pull_requests/pull-request-id-number.png) -{% data reusables.command_line.open_the_multi_os_terminal %} -1. Fetch the reference to the pull request based on its ID number, creating a new branch in the process. Use the pull request ID and the name of the local branch you want to create in the command. +1. Open your terminal or Git Bash. +1. Fetch the reference to the pull request based on its ID number. This creates a new branch. Use the pull request ID and the name of the local branch you want to create in the command. ```shell git fetch origin pull/ID/head:BRANCH_NAME @@ -78,8 +80,8 @@ Anyone can work with a previously opened pull request to continue working on it, > Switched to a new branch 'BRANCH_NAME' ``` -1. At this point, you can do anything you want with this branch. You can run some local tests, or merge other branches into the branch. -1. When you're ready, you can push the new branch up: +1. Make any needed changes to this branch. You can run local tests or merge other branches into the branch. +1. When you're ready, push the new branch: ```shell [pull-inactive-pull-request] $ git push origin BRANCH_NAME @@ -92,11 +94,11 @@ Anyone can work with a previously opened pull request to continue working on it, > * [new branch] BRANCH_NAME -> BRANCH_NAME ``` -1. [Create a new pull request](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) with your new branch. +1. Create a new pull request with your new branch. ## Error: Failed to push some refs -The remote `refs/pull/` namespace is _read-only_. If you try to push any commits there, you'll see this error: +The remote `refs/pull/` namespace is _read-only_. If you try to push commits there, you'll see this error: ```shell ! [remote rejected] HEAD -> refs/pull/1/head (deny updating a hidden ref) @@ -104,4 +106,4 @@ error: failed to push some refs to 'git@github.local:USERNAME/REPOSITORY.git' ``` > [!TIP] -> When you remove or rename a remote reference, your local `refs/pull/origin/` namespace will not be affected by calls to `git-remote`. +> When you remove or rename a remote reference, calls to `git-remote` do not affect your local `refs/pull/origin/` namespace. diff --git a/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request.md b/content/pull-requests/how-tos/review-pull-requests/commenting-on-a-pull-request.md similarity index 52% rename from content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request.md rename to content/pull-requests/how-tos/review-pull-requests/commenting-on-a-pull-request.md index ed344788f46f..399cbf736b63 100644 --- a/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request.md +++ b/content/pull-requests/how-tos/review-pull-requests/commenting-on-a-pull-request.md @@ -8,7 +8,8 @@ redirect_from: - /articles/commenting-on-a-pull-request - /github/collaborating-with-issues-and-pull-requests/commenting-on-a-pull-request - /github/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request -intro: 'After you open a pull request in a repository, collaborators or team members can comment on the comparison of files between the two specified branches, or leave general comments on the project as a whole.' + - /pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request +intro: Leave comments on pull requests in {% data variables.product.github %}, including general feedback, line-specific suggestions, and file-level discussions to enhance collaboration and code reviews. versions: fpt: '*' ghes: '*' @@ -16,19 +17,20 @@ versions: shortTitle: Comment on a PR category: - Review pull requests +contentType: how-tos --- ## About pull request comments -You can comment on a pull request's **Conversation** tab to leave general comments, questions, or props. You can also suggest changes that the author of the pull request can apply directly from your comment. +You can comment on a pull request's **Conversation** tab to leave general comments, questions, or praise. You can also suggest changes that the pull request author can apply directly from your comment. -You can also comment on specific files or sections of a file in a pull request's **Files changed** tab in the form of individual line or file comments, or as part of a pull request review. Adding line or file comments is a great way to discuss questions about implementation or provide feedback to the author. For more information about pull request reviews, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews). +You can also comment on specific files or sections of a file in a pull request's **Files changed** tab as individual line or file comments, or as part of a pull request review. Adding line or file comments is a great way to discuss questions about implementation or give feedback to the author. See [AUTOTITLE](/pull-requests/reference/pull-request-reviews). -For more information on adding line or file comments to a pull request review, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request). +See [AUTOTITLE](/pull-requests/how-tos/review-pull-requests/reviewing-proposed-changes-in-a-pull-request). > [!NOTE] > If you reply to a pull request via email, your comment will be added on the **Conversation** tab and will not be part of a pull request review. -To reply to an existing line or file comment, you'll need to navigate to the comment on either the **Conversation** tab or **Files changed** tab and add an additional comment below it. +To reply to an existing line or file comment, navigate to the comment on either the **Conversation** tab or **Files changed** tab. Then, add another comment below it. > [!TIP] > * Pull request comments support the same [formatting](/get-started/writing-on-github) as regular comments on {% data variables.product.github %}, such as @mentions, emoji, and references. @@ -37,7 +39,7 @@ To reply to an existing line or file comment, you'll need to navigate to the com ## Adding comments to a pull request {% data reusables.repositories.sidebar-pr %} -1. In the list of pull requests, click the pull request where you'd like to leave line comments. +1. In the list of pull requests, click the pull request where you want to leave line comments. {% data reusables.repositories.changed-files %} {% data reusables.repositories.start-line-comment %} {% data reusables.repositories.multiple-lines-comment %} @@ -50,9 +52,11 @@ To reply to an existing line or file comment, you'll need to navigate to the com * If you want to add **multiple comments**, click **Start a review**, then continue adding comments. - When you have finished, click **Finish your review** at the top right of the page, leave a summary of your review, and click **Submit review**. + When you're finished, click **Finish your review**, leave a summary of your review, and click **Submit review**. -Anyone watching the pull request or repository will receive a notification of your comments. Batching your comments avoids multiple notifications being sent. {% ifversion copilot %}If you are commenting on a pull request created by {% data variables.product.prodname_copilot_short %}, batching your comments prevents {% data variables.product.prodname_copilot_short %} from starting to work on individual comments before you have completed your review. See [AUTOTITLE](/copilot/how-tos/use-copilot-agents/cloud-agent/start-copilot-sessions).{% endif %} +Anyone watching the pull request or repository will receive a notification of your comments. Batching your comments avoids sending multiple notifications. + +{% ifversion fpt or ghec %} If you are commenting on a pull request created by {% data variables.product.prodname_copilot_short %}, batching your comments prevents {% data variables.product.prodname_copilot_short %} from starting to work on individual comments before you have completed your review. See [AUTOTITLE](/copilot/how-tos/use-copilot-agents/cloud-agent/start-copilot-sessions).{% endif %} ### Resolving conversations @@ -60,20 +64,19 @@ You can resolve a conversation in a pull request if you opened the pull request To indicate that a conversation on the **Files changed** tab is complete, click **Resolve conversation**. -The entire conversation will be collapsed and marked as resolved, making it easier to find conversations that still need to be addressed. +The entire conversation will collapse and be marked as resolved. This makes it easier to find conversations that still need to be addressed. -If the suggestion in a comment is out of your pull request's scope, you can open a new issue that tracks the feedback and links back to the original comment. For more information, see [AUTOTITLE](/issues/tracking-your-work-with-issues/creating-an-issue#creating-an-issue-from-a-comment). +If the suggestion in a comment is out of your pull request's scope, you can open a new issue that tracks the feedback and links back to the original comment. See [AUTOTITLE](/issues/tracking-your-work-with-issues/using-issues/creating-an-issue#creating-an-issue-from-a-comment). #### Discovering and navigating conversations -You can discover and navigate to all the conversations in your pull request using the **Conversations** menu that's shown at the top of the **Files Changed** tab. +You can discover and navigate to all the conversations in your pull request with the **Conversations** menu on the **Files changed** tab. -From this view, you can see which conversations are unresolved, resolved, and outdated. This makes it easy to discover and resolve conversations. +In this view, you can see which conversations are unresolved, resolved, and outdated. This makes it easy to discover and resolve conversations. ![Screenshot of the "Conversations" menu on the "Files Changed" tab of a pull request.](/assets/images/help/pull_requests/conversations-menu.png) ## Further reading * [AUTOTITLE](/get-started/writing-on-github) -{% ifversion fpt or ghec %}- [AUTOTITLE](/communities/maintaining-your-safety-on-github/reporting-abuse-or-spam) -{% endif %} +{% ifversion fpt or ghec %}* [AUTOTITLE](/communities/maintaining-your-safety-on-github/reporting-abuse-or-spam){% endif %} diff --git a/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/dismissing-a-pull-request-review.md b/content/pull-requests/how-tos/review-pull-requests/dismissing-a-pull-request-review.md similarity index 66% rename from content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/dismissing-a-pull-request-review.md rename to content/pull-requests/how-tos/review-pull-requests/dismissing-a-pull-request-review.md index 77ebac8fb36b..8ed8df8f92c2 100644 --- a/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/dismissing-a-pull-request-review.md +++ b/content/pull-requests/how-tos/review-pull-requests/dismissing-a-pull-request-review.md @@ -1,11 +1,12 @@ --- title: Dismissing a pull request review -intro: 'If your repository requires reviews, you can dismiss pull request reviews that are no longer valid or are unable to be approved by the reviewer.' +intro: Dismiss outdated or unapproved pull request reviews and update their status with a required comment. redirect_from: - /github/collaborating-with-issues-and-pull-requests/reviewing-changes-in-pull-requests/dismissing-a-pull-request-review - /articles/dismissing-a-pull-request-review - /github/collaborating-with-issues-and-pull-requests/dismissing-a-pull-request-review - /github/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/dismissing-a-pull-request-review + - /pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/dismissing-a-pull-request-review versions: fpt: '*' ghes: '*' @@ -13,9 +14,10 @@ versions: shortTitle: Dismiss a PR review category: - Review pull requests +contentType: how-tos --- {% data reusables.pull_requests.dismiss_review %} -This changes the status of the review to a review comment. When you dismiss a review, you must add a comment explaining why you dismissed it. Your comment will be added to the pull request conversation. +Dismissing a review changes the status of the review to a review comment. When you dismiss a review, you must add a comment explaining why you dismissed it. Your comment will be added to the pull request conversation. {% data reusables.search.requested_reviews_search %} @@ -25,7 +27,7 @@ This changes the status of the review to a review comment. When you dismiss a re ![Screenshot of the merge box for a pull request. The chevron icon to see the reviews is outlined in dark orange.](/assets/images/help/pull_requests/merge_box/pull-request-open-menu.png) -1. Next. to the review you'd like to dismiss, select the {% octicon "kebab-horizontal" aria-label="Show options" %} dropdown menu, then click **Dismiss review**. +1. Next to the review you'd like to dismiss, select the {% octicon "kebab-horizontal" aria-label="Show options" %} dropdown menu, then click **Dismiss review**. ![Screenshot of the merge box of a pull request. The Show options menu (kebab icon), is expanded, and the "Dismiss review" option is outlined in orange.](/assets/images/help/pull_requests/merge_box/pull-request-dismiss-review.png) @@ -33,6 +35,6 @@ This changes the status of the review to a review comment. When you dismiss a re ## Further reading -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request) +* [AUTOTITLE](/pull-requests/reference/pull-request-reviews) +* [AUTOTITLE](/pull-requests/how-tos/review-pull-requests/reviewing-proposed-changes-in-a-pull-request) * [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-pull-request-reviews-before-merging) diff --git a/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/incorporating-feedback-in-your-pull-request.md b/content/pull-requests/how-tos/review-pull-requests/incorporating-feedback-in-your-pull-request.md similarity index 50% rename from content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/incorporating-feedback-in-your-pull-request.md rename to content/pull-requests/how-tos/review-pull-requests/incorporating-feedback-in-your-pull-request.md index 95ad17acc2d0..2ec8f7488301 100644 --- a/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/incorporating-feedback-in-your-pull-request.md +++ b/content/pull-requests/how-tos/review-pull-requests/incorporating-feedback-in-your-pull-request.md @@ -1,11 +1,12 @@ --- title: Incorporating feedback in your pull request -intro: 'When reviewers suggest changes in a pull request, you can automatically incorporate the changes into the pull request or open an issue to track out-of-scope suggestions.' +intro: Apply suggested changes directly to a pull request, batch multiple suggestions into a single commit, or open an issue to track out-of-scope feedback. redirect_from: - /github/collaborating-with-issues-and-pull-requests/reviewing-changes-in-pull-requests/incorporating-feedback-in-your-pull-request - /articles/incorporating-feedback-in-your-pull-request - /github/collaborating-with-issues-and-pull-requests/incorporating-feedback-in-your-pull-request - /github/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/incorporating-feedback-in-your-pull-request + - /pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/incorporating-feedback-in-your-pull-request versions: fpt: '*' ghes: '*' @@ -13,42 +14,45 @@ versions: shortTitle: Incorporate feedback category: - Review pull requests +contentType: how-tos --- ## Applying suggested changes -Other people can suggest specific changes to your pull request. You can apply these suggested changes directly in a pull request if you have write access to the repository. If the pull request was created from a fork and the author allowed edits from maintainers, you can also apply suggested changes if you have write access to the upstream repository. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request) and [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork). +Other people can suggest specific changes to your pull request. You can apply these suggested changes directly in a pull request if you have write access to the repository. + +If the pull request was created from a fork and the author allowed edits from maintainers, you can also apply suggested changes if you have write access to the upstream repository. See [AUTOTITLE](/pull-requests/how-tos/review-pull-requests/commenting-on-a-pull-request) and [AUTOTITLE](/pull-requests/how-tos/work-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork). To quickly incorporate more than one suggested change into a single commit, you can also apply suggested changes as a batch. Applying one suggested change or a batch of suggested changes creates a single commit on the compare branch of the pull request. -Each person who suggested a change included in the commit will be a co-author of the commit. The person who applies the suggested changes will be a co-author and the committer of the commit. For more information about the term committer in Git, see [Git Basics - Viewing the Commit History](https://git-scm.com/book/en/v2/Git-Basics-Viewing-the-Commit-History) from the _Pro Git_ book site. +Each person who suggested a change included in the commit will be a co-author of the commit. The person who applies the suggested changes will be a co-author and the committer of the commit. See [Git Basics - Viewing the Commit History](https://git-scm.com/book/en/v2/Git-Basics-Viewing-the-Commit-History) from the _Pro Git_ book site. {% data reusables.repositories.sidebar-pr %} -1. In the list of pull requests, click the pull request you'd like to apply a suggested change to. -1. Navigate to the first suggested change you'd like to apply. +1. In the list of pull requests, click the pull request where you want to apply a suggested change. +1. Navigate to the first suggested change you want to apply. * To apply the change in its own commit, click **Commit suggestion**. ![Screenshot of a review comment with a suggestion. The "Commit suggestion" option is outlined in dark orange.](/assets/images/help/pull_requests/commit-suggestion-button.png) * To add the suggestion to a batch of changes, click **Add suggestion to batch**. Continue to add the suggested changes you want to include in a single commit. When you've finished adding suggested changes, click **Commit suggestions**. - ![Screenshot of a review comment with a suggestion. The "Add suggestion to batch" option is outlined in dark orange.](/assets/images/help/pull_requests/add-suggestion-to-batch.png) + ![Screenshot of a review comment with a suggestion. The "Add suggestion to batch" option is outlined in dark orange.](/assets/images/help/pull_requests/add-suggestion-to-batch.png) 1. In the commit message field, type a short, meaningful commit message that describes the change you made to the file or files. -1. Click **Commit changes.** +1. Click **Commit changes**. ## Re-requesting a review -You can re-request a review, for example, after you've made substantial changes to your pull request. +For example, you can re-request a review after you've made substantial changes to your pull request. To request a fresh review from a reviewer, in the sidebar of the **Conversation** tab, click the {% octicon "sync" aria-label="The sync icon" %} icon. ## Opening an issue for an out-of-scope suggestion -If someone suggests changes to your pull request and the changes are out of the pull request's scope, you can open a new issue to track the feedback. For more information, see [AUTOTITLE](/issues/tracking-your-work-with-issues/creating-an-issue). +If someone suggests changes to your pull request and the changes are out of the pull request's scope, you can open a new issue to track the feedback. See [AUTOTITLE](/issues/tracking-your-work-with-issues/using-issues/creating-an-issue). ## Further reading -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/requesting-a-pull-request-review) -* [AUTOTITLE](/issues/tracking-your-work-with-issues/creating-an-issue) +* [AUTOTITLE](/pull-requests/reference/pull-request-reviews) +* [AUTOTITLE](/pull-requests/how-tos/review-pull-requests/reviewing-proposed-changes-in-a-pull-request) +* [AUTOTITLE](/pull-requests/how-tos/review-pull-requests/commenting-on-a-pull-request) +* [AUTOTITLE](/pull-requests/how-tos/create-pull-requests/requesting-a-pull-request-review) +* [AUTOTITLE](/issues/tracking-your-work-with-issues/using-issues/creating-an-issue) diff --git a/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/index.md b/content/pull-requests/how-tos/review-pull-requests/index.md similarity index 68% rename from content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/index.md rename to content/pull-requests/how-tos/review-pull-requests/index.md index c043af16f8d9..09f138cbe091 100644 --- a/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/index.md +++ b/content/pull-requests/how-tos/review-pull-requests/index.md @@ -1,27 +1,26 @@ --- -title: Reviewing changes in pull requests +title: Review pull requests redirect_from: + - /pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests - /github/collaborating-with-issues-and-pull-requests/reviewing-changes-in-pull-requests - /articles/reviewing-and-discussing-changes-in-pull-requests - /articles/reviewing-changes-in-pull-requests - /github/collaborating-with-pull-requests/reviewing-changes-in-pull-requests -intro: 'After a pull request has been opened, you can review and discuss the set of proposed changes.' +shortTitle: Review pull requests +intro: 'Review, comment on, approve, and manage pull requests effectively, including filtering files, reviewing dependency changes, and incorporating feedback.' versions: fpt: '*' ghes: '*' ghec: '*' children: - - /about-pull-request-reviews + - /checking-out-pull-requests-locally - /reviewing-proposed-changes-in-a-pull-request - - /filtering-files-in-a-pull-request - - /finding-changed-methods-and-functions-in-a-pull-request - - /commenting-on-a-pull-request - - /viewing-a-pull-request-review - /reviewing-dependency-changes-in-a-pull-request - - /incorporating-feedback-in-your-pull-request + - /commenting-on-a-pull-request - /approving-a-pull-request-with-required-reviews + - /viewing-a-pull-request-review - /dismissing-a-pull-request-review - - /checking-out-pull-requests-locally -shortTitle: Review changes + - /incorporating-feedback-in-your-pull-request +contentType: how-tos --- diff --git a/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-dependency-changes-in-a-pull-request.md b/content/pull-requests/how-tos/review-pull-requests/reviewing-dependency-changes-in-a-pull-request.md similarity index 71% rename from content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-dependency-changes-in-a-pull-request.md rename to content/pull-requests/how-tos/review-pull-requests/reviewing-dependency-changes-in-a-pull-request.md index 942ff0328622..1519dbb602a5 100644 --- a/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-dependency-changes-in-a-pull-request.md +++ b/content/pull-requests/how-tos/review-pull-requests/reviewing-dependency-changes-in-a-pull-request.md @@ -1,6 +1,6 @@ --- title: Reviewing dependency changes in a pull request -intro: If a pull request contains changes to dependencies, you can view a summary of what has changed and whether there are known vulnerabilities in any of the dependencies. +intro: Review dependency changes in pull requests to identify added, updated, or removed dependencies and detect vulnerabilities before they reach production. product: '{% data reusables.gated-features.dependency-review %}' versions: fpt: '*' @@ -10,6 +10,7 @@ redirect_from: - /github/collaborating-with-issues-and-pull-requests/reviewing-changes-in-pull-requests/reviewing-dependency-changes-in-a-pull-request - /github/collaborating-with-issues-and-pull-requests/reviewing-dependency-changes-in-a-pull-request - /github/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-dependency-changes-in-a-pull-request + - /pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-dependency-changes-in-a-pull-request shortTitle: Review dependency changes contentType: how-tos category: @@ -21,15 +22,15 @@ category: {% data reusables.dependency-review.feature-overview %} -{% ifversion ghec %}Before you can use dependency review, you must enable the dependency graph. For more information, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/exploring-the-dependencies-of-a-repository#enabling-and-disabling-the-dependency-graph).{% endif %} +{% ifversion ghec %}Before you can use dependency review, you must enable the dependency graph. See [AUTOTITLE](/code-security/how-tos/secure-your-supply-chain/secure-your-dependencies/explore-dependencies#enabling-and-disabling-the-dependency-graph).{% endif %} -{% ifversion ghes %}Before you can use dependency review, you must enable the dependency graph and connect {% data variables.location.product_location %} to {% data variables.product.prodname_dotcom_the_website %}. For more information, see [AUTOTITLE](/admin/configuration/configuring-github-connect/enabling-dependabot-for-your-enterprise).{% endif %} +{% ifversion ghes %}Before you can use dependency review, you must enable the dependency graph and connect {% data variables.location.product_location %} to {% data variables.product.prodname_dotcom_the_website %}. See [AUTOTITLE](/admin/configuring-settings/configuring-github-connect/enabling-dependabot-for-your-enterprise).{% endif %} -Dependency review allows you to "shift left". You can use the provided predictive information to catch vulnerable dependencies before they hit production. For more information, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review). +Dependency review helps you find vulnerable dependencies before they reach production. See [AUTOTITLE](/code-security/concepts/supply-chain-security/dependency-review). You can use the {% data variables.dependency-review.action_name %} to help enforce dependency reviews on pull requests in your repository. {% data reusables.dependency-review.dependency-review-action-overview %} -You can configure the {% data variables.dependency-review.action_name %} to better suit your needs by specifying the type of dependency vulnerability you wish to catch. For more information, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-the-dependency-review-action). +You can configure the {% data variables.dependency-review.action_name %} to better suit your needs by specifying the type of dependency vulnerability you want to catch. See [AUTOTITLE](/code-security/how-tos/secure-your-supply-chain/manage-your-dependency-security/configure-dependency-review-action). ## Reviewing dependencies in a pull request @@ -37,15 +38,15 @@ You can configure the {% data variables.dependency-review.action_name %} to bett {% data reusables.repositories.choose-pr-review %} {% data reusables.repositories.changed-files %} -1. If the pull request contains many files, use the **File filter** drop-down menu to collapse all files that don't record dependencies. This will make it easier to focus your review on the dependency changes. +1. If the pull request contains many files, use the **File filter** drop-down menu to collapse all files that don't record dependencies. This makes it easier to focus your review on the dependency changes. ![Screenshot of the "Changed files" tab. A dropdown labeled "File filter" is expanded, displaying a list of file types with checkboxes.](/assets/images/help/pull_requests/file-filter-menu-json.png) - The dependency review provides a clearer view of what has changed in large lock files, where the source diff is not rendered by default. + The dependency review provides a clearer view of what has changed in large lock files, where the source diff is not shown by default. > [!NOTE] > Dependency review rich diffs are not available for committed static JavaScript files like `jquery.js`. -1. On the right of the header for a manifest or lock file, display the dependency review by clicking **{% octicon "file" aria-label="Display the rich diff" %}**. +1. To display the dependency review, click **{% octicon "file" aria-label="Display the rich diff" %}** on the right of the header for a manifest or lock file. ![Screenshot of the "Files changed" tab of a pull request. The button to display the rich diff, labeled with a file icon, is outlined in dark orange.](/assets/images/help/pull_requests/dependency-review-rich-diff.png) @@ -62,8 +63,8 @@ You can configure the {% data variables.dependency-review.action_name %} to bett * The version, or version range, of the new, updated, or deleted dependency. * For a specific version of a dependency: * The age of that release of the dependency. - * The number of projects that are dependent on this software. This information is taken from the dependency graph. Checking the number of dependents can help you avoid accidentally adding the wrong dependency. - * The license used by this dependency, if this information is available. This is useful if you want to avoid code with certain licenses being used in your project. + * The number of projects that depend on this software. This information is taken from the dependency graph. Checking the number of dependents can help you avoid accidentally adding the wrong dependency. + * The license used by this dependency, if this information is available. This is useful if you want to avoid using code with certain licenses in your project. Where a dependency has a known vulnerability, the warning message includes: diff --git a/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request.md b/content/pull-requests/how-tos/review-pull-requests/reviewing-proposed-changes-in-a-pull-request.md similarity index 65% rename from content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request.md rename to content/pull-requests/how-tos/review-pull-requests/reviewing-proposed-changes-in-a-pull-request.md index c20369ed8e64..6405269f7422 100644 --- a/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request.md +++ b/content/pull-requests/how-tos/review-pull-requests/reviewing-proposed-changes-in-a-pull-request.md @@ -1,11 +1,25 @@ --- title: Reviewing proposed changes in a pull request -intro: 'In a pull request, you can review and discuss commits, changed files, and the differences (or "diff") between the files in the base and compare branches.' +intro: Review commits, file changes, and diffs in pull requests to provide feedback, approve changes, or request updates before merging. redirect_from: + - /pull-requests/how-tos/review-pull-requests/filtering-files-in-a-pull-request + - /pull-requests/how-tos/review-pull-requests/finding-changed-methods-and-functions-in-a-pull-request - /github/collaborating-with-issues-and-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request - /articles/reviewing-proposed-changes-in-a-pull-request - /github/collaborating-with-issues-and-pull-requests/reviewing-proposed-changes-in-a-pull-request - /github/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request + - /pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request + - /github/collaborating-with-issues-and-pull-requests/reviewing-changes-in-pull-requests/filtering-files-in-a-pull-request + - /articles/filtering-files-in-a-pull-request-by-file-type + - /articles/filtering-files-in-a-pull-request + - /github/collaborating-with-issues-and-pull-requests/filtering-files-in-a-pull-request + - /github/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/filtering-files-in-a-pull-request + - /pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/filtering-files-in-a-pull-request + - /github/collaborating-with-issues-and-pull-requests/reviewing-changes-in-pull-requests/finding-changed-methods-and-functions-in-a-pull-request + - /articles/finding-changed-methods-and-functions-in-a-pull-request + - /github/collaborating-with-issues-and-pull-requests/finding-changed-methods-and-functions-in-a-pull-request + - /github/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/finding-changed-methods-and-functions-in-a-pull-request + - /pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/finding-changed-methods-and-functions-in-a-pull-request versions: fpt: '*' ghes: '*' @@ -13,6 +27,7 @@ versions: shortTitle: Review proposed changes category: - Review pull requests +contentType: how-tos --- ## About reviewing pull requests @@ -24,34 +39,28 @@ It's best to review changes in a pull request one file at a time: * The **progress bar** in the pull request header shows how many files you've viewed. * When you've finished, you can **approve** the pull request or **request changes** by submitting your review with a summary comment. -{% ifversion copilot %} - -If the pull request was raised by {% data variables.product.prodname_copilot %} then, when you submit your comments, {% data variables.product.prodname_copilot_short %} will carry out more work to respond to your comments and will push a new commit to the pull request with further changes. See [AUTOTITLE](/copilot/concepts/agents/cloud-agent/about-cloud-agent). - -{% endif %} +{% ifversion fpt or ghec %} If the pull request was raised by {% data variables.product.prodname_copilot %}, then {% data variables.product.prodname_copilot_short %} will respond to your comments when you submit them. {% data variables.product.prodname_copilot_short %} will push a new commit to the pull request with further changes. See [AUTOTITLE](/copilot/concepts/agents/cloud-agent/about-cloud-agent).{% endif %} {% webui %} ## Understanding the purpose of the pull request -Gaining a clear understanding of the motivation behind a pull request helps inform your review, so you can keep it targeted and meaningful, and provide feedback that is aligned with the pull request author’s intent and the project's goals. +Understanding the motivation behind a pull request helps you keep your review targeted and meaningful. It also helps you provide feedback that aligns with the pull request author’s intent and the project's goals. -There are several options available to you to better understand the context and rationale for proposed changes. +You have several options to better understand the context and rationale for proposed changes. ### Using the pull request sidebar for context -In the pull request sidebar, you can find valuable context including: +In the pull request sidebar, you can find valuable context, including: -* Linked **issues** or **discussions**: Review these to understand the problems or goals that the pull request aims to address, or to gather information on, for example, any background, design decisions, or current debates. +* Linked **issues** or **discussions**: Review these to understand the problems or goals that the pull request aims to address. You can also gather information about background, design decisions, or current debates. * Linked **projects** or **milestones**: Review how this pull request fits within larger projects or upcoming releases. Use this information to frame your review and check if the goals of the pull request align with the original intent. -{% ifversion copilot %} - ### Using {% data variables.copilot.copilot_chat_short %} to understand the rationale -You can ask {% data variables.copilot.copilot_chat_short %} for help understanding the pull request’s intent or for clarification on any part of the change. +You can ask {% data variables.copilot.copilot_chat_short %} for help understanding the pull request’s intent or clarifying any part of the change. 1. At the top right of the pull request page, click the **{% octicon "copilot" aria-label="Copilot icon" %}** button next to the search bar. @@ -64,24 +73,22 @@ You can ask {% data variables.copilot.copilot_chat_short %} for help understandi * `Summarize the goals of this PR based on the linked issue.` * `How does this PR relate to issue ISSUE-URL?` -{% data variables.copilot.copilot_chat_short %} can help you clarify the bigger picture before diving into line-level review. - -{% endif %} +{% data variables.copilot.copilot_chat_short %} can help you clarify the bigger picture before you start line-level review. ## Starting a review {% data reusables.repositories.sidebar-pr %} {% data reusables.repositories.choose-pr-review %} {% data reusables.repositories.changed-files %} -You can change the format of the diff view in this tab by clicking {% octicon "gear" aria-label="The Settings gear" %} and choosing the unified or split view. The choice you make will apply when you view the diff for other pull requests. +To change the format of the diff view in this tab, click {% octicon "gear" aria-label="The Settings gear" %} and choose the unified or split view. The choice you make will apply when you view the diff for other pull requests. ![Screenshot of the "Files changed" tab for a pull request. The "Diff view" menu is outlined in dark orange.](/assets/images/help/pull_requests/diff-settings-menu.png) - You can also choose to hide whitespace differences. The choice you make only applies to this pull request and will be remembered the next time you visit this page. -1. Optionally, filter the files to show only the files you want to review or use the file tree to navigate to a specific file. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/filtering-files-in-a-pull-request). -{%- ifversion ghec %} -1. Optionally, if you have access to {% data variables.copilot.copilot_enterprise %}, you can ask {% data variables.product.prodname_copilot_short %} about the changes in a file in a pull request by clicking {% octicon "kebab-horizontal" aria-label="Show options" %} at the top right of the file, clicking **Ask {% data variables.product.prodname_copilot_short %} about this diff**, then typing a request such as "Explain these changes." For more information, see [AUTOTITLE](/enterprise-cloud@latest/copilot/github-copilot-chat/copilot-chat-in-github/using-github-copilot-chat-in-githubcom#asking-questions-about-a-specific-pull-request). -{%- endif %} + You can also hide whitespace differences. The choice you make only applies to this pull request and will be remembered the next time you visit this page. +1. Optionally, filter the files to show only the files you want to review or use the file tree to navigate to a specific file. +{% ifversion ghec %} +1. Optionally, if you have access to {% data variables.copilot.copilot_enterprise %}, you can ask {% data variables.product.prodname_copilot_short %} about the changes in a file in a pull request by clicking {% octicon "kebab-horizontal" aria-label="Show options" %} at the top right of the file, clicking **Ask {% data variables.product.prodname_copilot_short %} about this diff**, then typing a request such as "Explain these changes." See [AUTOTITLE](/enterprise-cloud@latest/copilot/how-tos/copilot-on-github/chat-with-copilot/chat-in-github#asking-questions-about-a-specific-pull-request). +{% endif %} {% data reusables.repositories.start-line-comment %} {% data reusables.repositories.multiple-lines-comment %} {% data reusables.repositories.type-line-comment %} @@ -89,7 +96,7 @@ You can change the format of the diff view in this tab by clicking {% octicon "g {% data reusables.repositories.start-file-comment %} 1. When you're done, click **Start a review**. If you have already started a review, you can click **Add review comment**. -Before you submit your review, your line comments are _pending_ and only visible to you. You can edit pending comments anytime before you submit your review. To cancel a pending review, including all of its pending comments, click **Review changes** above the changed code, then click **Abandon review**. +Before you submit your review, your line comments are _pending_ and only visible to you. You can edit pending comments anytime before you submit your review. To cancel a pending review, including all of its pending comments, click **Review changes**, then click **Abandon review**. ![Screenshot of the comment field for a review. The "Abandon review" button is outlined in dark orange.](/assets/images/help/pull_requests/abandon-review-button.png) {% endwebui %} @@ -102,7 +109,7 @@ Before you submit your review, your line comments are _pending_ and only visible You can use [{% data variables.product.prodname_github_codespaces %}](/codespaces/quickstart) to test, run, and review pull requests. -1. Open the pull request in a codespace, as described in [AUTOTITLE](/codespaces/developing-in-codespaces/using-github-codespaces-for-pull-requests#opening-a-pull-request-in-codespaces). +1. Open the pull request in a codespace, as described in [AUTOTITLE](/codespaces/developing-in-a-codespace/using-github-codespaces-for-pull-requests#opening-a-pull-request-in-codespaces). 1. In the Activity Bar, click the **{% data variables.product.github %} Pull Request** view. This view only appears when you open a pull request in a codespace. ![Screenshot of the {% data variables.product.prodname_vscode_shortname %} Activity Bar. The mouse pointer is hovering over an icon displaying the tooltip "{% data variables.product.prodname_dotcom %} Pull Request."](/assets/images/help/codespaces/github-pr-view.png) @@ -121,19 +128,20 @@ You can use [{% data variables.product.prodname_github_codespaces %}](/codespace ![Screenshot of the side bar showing the dropdown options "Comment and Submit," "Approve and Submit," and "Request Changes and Submit."](/assets/images/help/codespaces/submit-review.png) -For more information on reviewing pull requests in {% data variables.product.prodname_github_codespaces %}, see [AUTOTITLE](/codespaces/developing-in-codespaces/using-github-codespaces-for-pull-requests). +For more information on reviewing pull requests in {% data variables.product.prodname_github_codespaces %}, see [AUTOTITLE](/codespaces/developing-in-a-codespace/using-github-codespaces-for-pull-requests). {% endcodespaces %} {% endif %} {% webui %} -{% ifversion copilot %} + +{% ifversion fpt or ghec %} ## Understanding changes in a pull request > [!NOTE] {% data reusables.copilot.copilot-requires-subscription %} -{% data variables.product.prodname_copilot %} can help you quickly understand the changes in a pull request by providing context and explanations for specific commits. If you’re unsure about the purpose of a particular change or need more details about how it fits into the broader codebase, you can ask {% data variables.product.prodname_copilot_short %} questions about individual commits. +{% data variables.product.prodname_copilot %} can help you quickly understand changes in a pull request by providing context and explanations for specific commits. If you’re unsure about the purpose of a particular change or need more details about how it fits into the broader codebase, you can ask {% data variables.product.prodname_copilot_short %} questions about individual commits. 1. Navigate to a commit on {% data variables.product.github %}. @@ -154,7 +162,7 @@ For more information on reviewing pull requests in {% data variables.product.pro ## Reviewing dependency changes -If the pull request contains changes to dependencies you can use the dependency review for a manifest or lock file to see what has changed and check whether the changes introduce security vulnerabilities. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-dependency-changes-in-a-pull-request). +If the pull request contains changes to dependencies, you can use the dependency review for a manifest or lock file to see what has changed. You can also check whether the changes introduce security vulnerabilities. See [AUTOTITLE](/pull-requests/how-tos/review-pull-requests/reviewing-dependency-changes-in-a-pull-request). {% data reusables.repositories.changed-files %} @@ -166,7 +174,7 @@ If the pull request contains changes to dependencies you can use the dependency ## Marking a file as viewed -After you finish reviewing a file, you can mark the file as viewed, and the file will collapse. If the file changes after you view the file, it will be unmarked as viewed. +After you finish reviewing a file, you can mark the file as viewed. The file will collapse. If the file changes after you view the file, it will be unmarked as viewed. {% data reusables.repositories.changed-files %} 1. On the right of the header of the file you've finished reviewing, select **Viewed**. @@ -194,4 +202,4 @@ After you've finished reviewing all the files you want in the pull request, subm ## Further reading * [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-pull-request-reviews-before-merging) -* [AUTOTITLE](/issues/tracking-your-work-with-issues/filtering-and-searching-issues-and-pull-requests) +* [AUTOTITLE](/issues/tracking-your-work-with-issues/using-issues/filtering-and-searching-issues-and-pull-requests) diff --git a/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/viewing-a-pull-request-review.md b/content/pull-requests/how-tos/review-pull-requests/viewing-a-pull-request-review.md similarity index 53% rename from content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/viewing-a-pull-request-review.md rename to content/pull-requests/how-tos/review-pull-requests/viewing-a-pull-request-review.md index 45c51d259868..10ca5b6ae5bd 100644 --- a/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/viewing-a-pull-request-review.md +++ b/content/pull-requests/how-tos/review-pull-requests/viewing-a-pull-request-review.md @@ -1,11 +1,12 @@ --- title: Viewing a pull request review -intro: You can view all of the comments made in a single pull request review. +intro: View and navigate all comments from a single pull request review to understand changes and feedback. redirect_from: - /github/collaborating-with-issues-and-pull-requests/reviewing-changes-in-pull-requests/viewing-a-pull-request-review - /articles/viewing-a-pull-request-review - /github/collaborating-with-issues-and-pull-requests/viewing-a-pull-request-review - /github/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/viewing-a-pull-request-review + - /pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/viewing-a-pull-request-review versions: fpt: '*' ghes: '*' @@ -13,19 +14,20 @@ versions: shortTitle: View a PR review category: - Review pull requests +contentType: how-tos --- {% data reusables.search.requested_reviews_search %} -When you view a full review, you'll see the same version of the pull request as the reviewer did at the time of the review. +When you view a full review, you see the same version of the pull request as the reviewer did at the time of the review. {% data reusables.repositories.sidebar-pr %} {% data reusables.repositories.choose-pr-review %} -1. On the "Conversation" tab, scroll to the review you'd like to see, then click **View changes**. +1. On the "Conversation" tab, scroll to the review you want to see, then click **View changes**. ![Screenshot of a review. The "View changes" link is outlined in dark orange.](/assets/images/help/pull_requests/view-full-review-view-changes.png) ## Further reading -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request) -* [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/triaging-code-scanning-alerts-in-pull-requests) +* [AUTOTITLE](/pull-requests/reference/pull-request-reviews) +* [AUTOTITLE](/pull-requests/how-tos/review-pull-requests/reviewing-proposed-changes-in-a-pull-request) +* [AUTOTITLE](/code-security/how-tos/manage-security-alerts/manage-code-scanning-alerts/triage-alerts-in-pull-requests) diff --git a/content/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork.md b/content/pull-requests/how-tos/work-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork.md similarity index 53% rename from content/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork.md rename to content/pull-requests/how-tos/work-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork.md index 9cb5dfb470bf..cfa6d82939c3 100644 --- a/content/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork.md +++ b/content/pull-requests/how-tos/work-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork.md @@ -1,11 +1,12 @@ --- title: Allowing changes to a pull request branch created from a fork -intro: 'For greater collaboration, you can allow commits on branches you''ve created from forks in your personal account.' +intro: Enable collaboration by allowing repository maintainers to commit changes to pull request branches created from forks in your personal account. redirect_from: - /github/collaborating-with-issues-and-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork - /articles/allowing-changes-to-a-pull-request-branch-created-from-a-fork - /github/collaborating-with-issues-and-pull-requests/allowing-changes-to-a-pull-request-branch-created-from-a-fork - /github/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork + - /pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork permissions: People with push access to the upstream repository of a fork in a personal account can commit to the forked branches. versions: fpt: '*' @@ -14,12 +15,11 @@ versions: shortTitle: Allow changes to a branch category: - Work with forks +contentType: how-tos --- -When a user creates a pull request from their fork, the user generally has the authority to decide if other users can commit to the pull request's compare branch. If the pull request author wants greater collaboration, they can grant maintainers of the upstream repository (that is, anyone with push access to the upstream repository) permission to commit to the pull request's compare branch. To learn more about upstream repositories, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks). +When someone creates a pull request from their fork, they usually decide whether other people can commit to the pull request's compare branch. For greater collaboration, the author can give maintainers of the upstream repository—that is, anyone with push access to the upstream repository—permission to commit to the compare branch. See [AUTOTITLE](/pull-requests/reference/forks). -Pull request authors can give these permissions when they initially create a pull request from a fork in a personal account or after they create the pull request. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork). - -You can set commit permissions when you first create a pull request from a fork. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork). Additionally, you can modify an existing pull request to let repository maintainers make commits to your branch. +Pull request authors can set these permissions when they create a pull request from a fork in a personal account. They can also update an existing pull request to let repository maintainers commit to the branch. See [AUTOTITLE](/pull-requests/how-tos/create-pull-requests/creating-a-pull-request-from-a-fork). ## Enabling repository maintainer permissions on existing pull requests @@ -35,4 +35,4 @@ You can set commit permissions when you first create a pull request from a fork. ## Further reading -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/committing-changes-to-a-pull-request-branch-created-from-a-fork) +* [AUTOTITLE](/pull-requests/how-tos/commit-changes/committing-changes-to-a-pull-request-branch-created-from-a-fork) diff --git a/content/pull-requests/collaborating-with-pull-requests/working-with-forks/configuring-a-remote-repository-for-a-fork.md b/content/pull-requests/how-tos/work-with-forks/configuring-a-remote-repository-for-a-fork.md similarity index 71% rename from content/pull-requests/collaborating-with-pull-requests/working-with-forks/configuring-a-remote-repository-for-a-fork.md rename to content/pull-requests/how-tos/work-with-forks/configuring-a-remote-repository-for-a-fork.md index 37eb7b5395ba..ee81cc112c3f 100644 --- a/content/pull-requests/collaborating-with-pull-requests/working-with-forks/configuring-a-remote-repository-for-a-fork.md +++ b/content/pull-requests/how-tos/work-with-forks/configuring-a-remote-repository-for-a-fork.md @@ -1,12 +1,13 @@ --- title: Configuring a remote repository for a fork -intro: 'You must configure a remote that points to the upstream repository in Git to [sync changes you make in a fork](/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork) with the original repository. This also allows you to sync changes made in the original repository with the fork.' +intro: 'Set up a remote pointing to the upstream repository in Git to sync changes between your fork and the original repository.' redirect_from: - /github/collaborating-with-issues-and-pull-requests/working-with-forks/configuring-a-remote-for-a-fork - /articles/configuring-a-remote-for-a-fork - /github/collaborating-with-issues-and-pull-requests/configuring-a-remote-for-a-fork - /github/collaborating-with-pull-requests/working-with-forks/configuring-a-remote-for-a-fork - /github/collaborating-with-pull-requests/working-with-forks/configuring-a-remote-repository-for-a-fork + - /pull-requests/collaborating-with-pull-requests/working-with-forks/configuring-a-remote-repository-for-a-fork versions: fpt: '*' ghes: '*' @@ -14,9 +15,10 @@ versions: shortTitle: Configure a remote repository category: - Work with forks +contentType: how-tos --- -{% data reusables.command_line.open_the_multi_os_terminal %} -1. List the current configured remote repository for your fork. +1. Open your terminal or Git Bash. +1. List the remotes currently configured for your fork. ```shell $ git remote -v @@ -24,13 +26,13 @@ category: > origin https://{% data variables.product.product_url %}/YOUR-USERNAME/YOUR-FORK.git (push) ``` -1. Specify a new remote _upstream_ repository that will be synced with the fork. +1. Add a new remote named _upstream_ that points to the original repository. ```shell git remote add upstream https://{% data variables.product.product_url %}/ORIGINAL-OWNER/ORIGINAL-REPOSITORY.git ``` -1. Verify the new upstream repository you've specified for your fork. +1. Verify the new upstream repository that you specified for your fork. ```shell $ git remote -v diff --git a/content/pull-requests/collaborating-with-pull-requests/working-with-forks/detaching-a-fork.md b/content/pull-requests/how-tos/work-with-forks/detaching-a-fork.md similarity index 62% rename from content/pull-requests/collaborating-with-pull-requests/working-with-forks/detaching-a-fork.md rename to content/pull-requests/how-tos/work-with-forks/detaching-a-fork.md index 61f78a48f3c6..04037a69358f 100644 --- a/content/pull-requests/collaborating-with-pull-requests/working-with-forks/detaching-a-fork.md +++ b/content/pull-requests/how-tos/work-with-forks/detaching-a-fork.md @@ -1,22 +1,26 @@ --- title: Detaching a fork -intro: You can disconnect a repository from its fork network by leaving the network or manually deleting the fork and recreating it without any connection to the original. +intro: Disconnect a repository from its fork network by leaving the network or creating a standalone repository through manual steps. versions: fpt: '*' ghes: '*' ghec: '*' permissions: People with admin access for a forked repository can delete the forked repository. +shortTitle: Detach a fork category: - Work with forks +redirect_from: + - /pull-requests/collaborating-with-pull-requests/working-with-forks/detaching-a-fork +contentType: how-tos --- ## Converting a fork into a standalone repository -To turn your fork into a standalone repository, you can leave the fork network ensuring the new repository will no longer automatically sync with changes from the original repository. This is useful when you want to take the work you are doing in a different direction or maintain distinct versions. +To turn your fork into a standalone repository, you can leave the fork network. The new repository will no longer automatically sync with changes from the original repository. This is useful when you want to take your work in a different direction or maintain distinct versions. > [!WARNING] > * The new repository will not retain any of its issues, pull requests, wikis, stars, watchers, comments, child forks, or other metadata that may currently be associated with your current fork. -> * All git commit metadata will be preserved. Commits may become eligible to be counted as contributions if they meet certain criteria. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/why-are-my-contributions-not-showing-up-on-my-profile#your-local-git-commit-email-isnt-connected-to-your-account). +> * All git commit metadata will be preserved. Commits may become eligible to be counted as contributions if they meet certain criteria. See [AUTOTITLE](/account-and-profile/how-tos/contribution-settings/troubleshooting-missing-contributions#your-local-git-commit-email-isnt-connected-to-your-account). > * Leaving the fork network is **permanent** and the new repository **cannot** be reconnected to the fork network. {% ifversion ghes %} @@ -40,35 +44,35 @@ You can only detach forks with the leave network option when: 1. To verify that you're detaching the correct repository, in the text box, type the name of the fork. 1. Click **Leave fork network**. -While the fork is being detached, some operations will be briefly unavailable until the fork has been transitioned to a standalone repository. +While the fork is being detached, some operations will be briefly unavailable. They will become available again after the fork becomes a standalone repository. ## Manually leaving the fork network -To turn your fork into a standalone repository, you can clone the fork, use the clone to create a new repository, and then delete the fork removing the connection to the original network. +To turn your fork into a standalone repository, you can clone the fork and use the clone to create a new repository. Then, delete the fork to remove the connection to the original network. -{% data reusables.command_line.open_the_multi_os_terminal %} +1. Open your terminal or Git Bash. 1. Create a bare clone of the fork. ```shell git clone --bare https://{% data variables.product.product_url %}/EXAMPLE-USER/FORK.git ``` -1. Delete the forked repository. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/deleting-a-repository).

+1. Delete the forked repository. See [AUTOTITLE](/repositories/creating-and-managing-repositories/deleting-a-repository).

> [!WARNING] > Deleting a fork will **permanently** delete any associated pull requests and configurations. This action **cannot** be undone. -1. Create a new repository with the same name in the same location. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/creating-a-new-repository). +1. Create a new repository with the same name in the same location. See [AUTOTITLE](/repositories/creating-and-managing-repositories/creating-a-new-repository). 1. Mirror-push the repository back to the same remote URL. ```shell git --git-dir FORK.git push --mirror https://{% data variables.product.product_url %}/EXAMPLE-USER/FORK.git ``` -1. Remove temporary local clone you created earlier. +1. Remove the temporary local clone you created earlier. ```shell rm -rf FORK.git ``` -For more information, see [our support page](https://support.github.com/request/fork) on forks. +See [our support page](https://support.github.com/request/fork) on forks. diff --git a/content/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo.md b/content/pull-requests/how-tos/work-with-forks/fork-a-repo.md similarity index 56% rename from content/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo.md rename to content/pull-requests/how-tos/work-with-forks/fork-a-repo.md index 9c6d6c1f79bd..486ed10f5a0d 100644 --- a/content/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo.md +++ b/content/pull-requests/how-tos/work-with-forks/fork-a-repo.md @@ -8,53 +8,38 @@ redirect_from: - /github/getting-started-with-github/fork-a-repo - /github/getting-started-with-github/quickstart/fork-a-repo - /get-started/quickstart/fork-a-repo -intro: A fork is a new repository that shares code and visibility settings with the original upstream repository. + - /pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo +intro: Fork a repository on {% data variables.product.github %} to propose changes, collaborate on projects, and manage your own copy of the codebase. permissions: '{% data reusables.enterprise-accounts.emu-permission-fork %}' versions: fpt: '*' ghes: '*' ghec: '*' +shortTitle: Fork a repository category: - Work with forks +contentType: how-tos --- ## About forks -{% data reusables.repositories.fork-definition-long %} For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks). - -### Propose changes to someone else's project - -For example, you can use forks to propose changes related to fixing a bug. Rather than logging an issue for a bug you have found, you can: - -* Fork the repository. -* Make the fix. -* Submit a pull request to the project owner. - -### Use someone else's project as a starting point for your own idea. - -Open source software is based on the idea that by sharing code, we can make better, more reliable software. For more information, see the [About the Open Source Initiative](https://opensource.org/about) on the Open Source Initiative. - -For more information about applying open source principles to your organization's development work on {% data variables.product.prodname_dotcom %}, see {% data variables.product.prodname_dotcom %}'s white paper [An introduction to innersource](https://resources.github.com/whitepapers/introduction-to-innersource/). - -When creating your public repository from a fork of someone's project, make sure to include a license file that determines how you want your project to be shared with others. For more information, see [Choose an open source license](https://choosealicense.com/) at choosealicense.com. - -{% data reusables.open-source.open-source-guide-repositories %} {% data reusables.open-source.open-source-learning %} +Forking a repository lets you propose changes to a project without affecting the upstream repository. See [AUTOTITLE](/pull-requests/get-started/about-forks). ## Prerequisites -If you haven't yet, first set up Git and authentication with {% data variables.location.product_location %} from Git. For more information, see [AUTOTITLE](/get-started/git-basics/set-up-git). +If you haven't already, set up Git and authentication with {% data variables.location.product_location %} from Git. See [AUTOTITLE](/get-started/git-basics/set-up-git). ## Forking a repository {% webui %} -You might fork a project to propose changes to the upstream repository. In this case, it's good practice to regularly sync your fork with the upstream repository. To do this, you'll need to use Git on the command line. You can practice setting the upstream repository using the same [octocat/Spoon-Knife](https://github.com/octocat/Spoon-Knife) repository you just forked. +You might fork a project to propose changes to the upstream repository. In this case, it's good practice to sync your fork with the upstream repository regularly. To do this, you'll need to use Git on the command line. You can practice setting the upstream repository using the same [octocat/Spoon-Knife](https://github.com/octocat/Spoon-Knife) repository you just forked. 1. On {% ifversion fpt or ghec %}{% data variables.product.prodname_dotcom %}{% else %}{% data variables.location.product_location %}{% endif %}, navigate to the [octocat/Spoon-Knife](https://github.com/octocat/Spoon-Knife) repository. 1. In the top-right corner of the page, click **Fork**. ![Screenshot of the main page of repository. A button, labeled with a fork icon and "Fork 59.3k," is outlined in dark orange.](/assets/images/help/repository/fork-button.png) 1. Under "Owner," select the dropdown menu and click an owner for the forked repository. -1. By default, forks are named the same as their upstream repositories. Optionally, to further distinguish your fork, in the "Repository name" field, type a name. +1. By default, forks are named the same as their upstream repositories. Optionally, in the "Repository name" field, type a different name to distinguish your fork. 1. Optionally, in the "Description" field, type a description of your fork. 1. Optionally, select **Copy the DEFAULT branch only**. @@ -62,7 +47,7 @@ You might fork a project to propose changes to the upstream repository. In this 1. Click **Create fork**. > [!NOTE] -> If you want to copy additional branches from the upstream repository, you can do so from the **Branches** page. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository). +> If you want to copy additional branches from the upstream repository, you can do so from the **Branches** page. See [AUTOTITLE](/pull-requests/how-tos/create-pull-requests/creating-and-deleting-branches-within-your-repository). {% endwebui %} @@ -86,7 +71,7 @@ gh repo fork REPOSITORY --org "octo-org" {% desktop %} -You can fork a repository on {% data variables.product.prodname_dotcom_the_website %} or in {% data variables.product.prodname_desktop %}. For information about forking on {% data variables.product.prodname_dotcom_the_website %}, see [the web browser version of this article](/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo?tool=webui). +You can fork a repository on {% data variables.product.prodname_dotcom_the_website %} or in {% data variables.product.prodname_desktop %}. For information about forking on {% data variables.product.prodname_dotcom_the_website %}, see [the web browser version of this article](/pull-requests/how-tos/work-with-forks/fork-a-repo?tool=webui). {% data reusables.desktop.forking-a-repo %} @@ -96,19 +81,19 @@ You can fork a repository on {% data variables.product.prodname_dotcom_the_websi ## Cloning your forked repository -Right now, you have a fork of the Spoon-Knife repository, but you do not have the files in that repository locally on your computer. +You now have a fork of the Spoon-Knife repository, but you do not have the files from that repository on your computer. 1. On {% ifversion fpt or ghec %}{% data variables.product.prodname_dotcom %}{% else %}{% data variables.location.product_location %}{% endif %}, navigate to **your fork** of the Spoon-Knife repository. {% data reusables.repositories.copy-clone-url %} -{% data reusables.command_line.open_the_multi_os_terminal %} +1. Open your terminal or Git Bash. {% data reusables.command_line.change-current-directory-clone %} -1. Type `git clone`, and then paste the URL you copied earlier. It will look like this, with your {% data variables.product.github %} username instead of `YOUR-USERNAME`: +1. Type `git clone`, then paste the URL you copied earlier. It will look like this, with your {% data variables.product.github %} username instead of `YOUR-USERNAME`: ```shell git clone https://{% data variables.product.product_url %}/YOUR-USERNAME/Spoon-Knife ``` -1. Press **Enter**. Your local clone will be created. +1. Press **Enter**. Git creates your local clone. ```shell $ git clone https://{% data variables.product.product_url %}/YOUR-USERNAME/Spoon-Knife @@ -125,7 +110,7 @@ Right now, you have a fork of the Spoon-Knife repository, but you do not have th ## Cloning your forked repository -Right now, you have a fork of the Spoon-Knife repository, but you do not have the files in that repository locally on your computer. +You now have a fork of the Spoon-Knife repository, but you do not have the files from that repository on your computer. {% data reusables.cli.cli-learn-more %} @@ -139,19 +124,19 @@ gh repo fork REPOSITORY --clone=true ## Configuring Git to sync your fork with the upstream repository -When you fork a project in order to propose changes to the upstream repository, you can configure Git to pull changes from the upstream repository into the local clone of your fork. +When you fork a project to propose changes to the upstream repository, you can configure Git to pull changes from the upstream repository into the local clone of your fork. {% webui %} 1. On {% ifversion fpt or ghec %}{% data variables.product.prodname_dotcom %}{% else %}{% data variables.location.product_location %}{% endif %}, navigate to the [octocat/Spoon-Knife](https://github.com/octocat/Spoon-Knife) repository. {% data reusables.repositories.copy-clone-url %} -{% data reusables.command_line.open_the_multi_os_terminal %} -1. Change directories to the location of the fork you cloned. +1. Open your terminal or Git Bash. +1. Change to the directory for the fork you cloned. * To go to your home directory, type just `cd` with no other text. * To list the files and folders in your current directory, type `ls`. * To go into one of your listed directories, type `cd YOUR-LISTED-DIRECTORY`. * To go up one directory, type `cd ..`. -1. Type `git remote -v` and press **Enter**. You will see the current configured remote repository for your fork. +1. Type `git remote -v` and press **Enter**. You will see the remote repository currently configured for your fork. ```shell $ git remote -v @@ -159,13 +144,13 @@ When you fork a project in order to propose changes to the upstream repository, > origin https://{% data variables.product.product_url %}/YOUR-USERNAME/YOUR-FORK.git (push) ``` -1. Type `git remote add upstream`, and then paste the URL you copied in Step 3 and press **Enter**. It will look like this: +1. Type `git remote add upstream`, then paste the URL you copied in Step 3 and press **Enter**. It will look like this: ```shell git remote add upstream https://{% data variables.product.product_url %}/ORIGINAL-OWNER/Spoon-Knife.git ``` -1. To verify the new upstream repository you have specified for your fork, type `git remote -v` again. You should see the URL for your fork as `origin`, and the URL for the upstream repository as `upstream`. +1. To verify the new upstream repository you specified for your fork, type `git remote -v` again. You should see the URL for your fork as `origin` and the URL for the upstream repository as `upstream`. ```shell $ git remote -v @@ -175,7 +160,7 @@ When you fork a project in order to propose changes to the upstream repository, > upstream https://{% data variables.product.product_url %}/ORIGINAL-OWNER/ORIGINAL-REPOSITORY.git (push) ``` -Now, you can keep your fork synced with the upstream repository with a few Git commands. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork). +You can now keep your fork synced with the upstream repository with a few Git commands. See [AUTOTITLE](/pull-requests/how-tos/work-with-forks/syncing-a-fork). {% endwebui %} @@ -202,13 +187,15 @@ gh repo fork REPOSITORY --remote-name "main-remote-repo" You can make any changes to a fork, including: * **Creating branches:** [_Branches_](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository) allow you to build new features or test out ideas without putting your main project at risk. -* **Opening pull requests:** If you want to contribute back to the upstream repository, you can send a request to the original author to pull your fork into their repository by submitting a [pull request](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests). +* **Opening pull requests:** If you want to contribute back to the upstream repository, you can submit a pull request to ask the original author to pull your fork into their repository. See [AUTOTITLE](/pull-requests/how-tos/create-pull-requests/creating-a-pull-request-from-a-fork). ## Find another repository to fork -Fork a repository to start contributing to a project. {% data reusables.repositories.you-can-fork %} For more information about when you can fork a repository, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/about-permissions-and-visibility-of-forks). +Fork a repository to start contributing to a project. {% data reusables.repositories.you-can-fork %} + +For more information about when you can fork a repository, see [AUTOTITLE](/pull-requests/reference/forks). -{% ifversion fpt or ghec %}You can browse [Explore {% data variables.product.prodname_dotcom %}](https://github.com/explore) to find projects and start contributing to open source repositories. For more information, see [AUTOTITLE](/get-started/exploring-projects-on-github/finding-ways-to-contribute-to-open-source-on-github). +{% ifversion fpt or ghec %}You can browse [Explore {% data variables.product.prodname_dotcom %}](https://github.com/explore) to find projects and start contributing to open source repositories. See [AUTOTITLE](/get-started/exploring-projects-on-github/finding-ways-to-contribute-to-open-source-on-github). {% endif %} @@ -216,9 +203,9 @@ Fork a repository to start contributing to a project. {% data reusables.reposito You have now forked a repository, practiced cloning your fork, and configured an upstream repository. -* For more information about cloning the fork and syncing the changes in a forked repository from your computer, see [AUTOTITLE](/get-started/git-basics/set-up-git). +* For more information about using Git on the command line to clone and sync changes, see [AUTOTITLE](/get-started/git-basics/set-up-git). -* You can also create a new repository where you can put all your projects and share the code on {% data variables.product.prodname_dotcom %}. {% data reusables.getting-started.create-a-repository %} +* You can also create a new repository to store your projects and share the code on {% data variables.product.prodname_dotcom %}. {% data reusables.getting-started.create-a-repository %} * {% data reusables.getting-started.being-social %} diff --git a/content/pull-requests/collaborating-with-pull-requests/working-with-forks/index.md b/content/pull-requests/how-tos/work-with-forks/index.md similarity index 61% rename from content/pull-requests/collaborating-with-pull-requests/working-with-forks/index.md rename to content/pull-requests/how-tos/work-with-forks/index.md index 5cdd2b561b3b..ee6d1c6c9bdd 100644 --- a/content/pull-requests/collaborating-with-pull-requests/working-with-forks/index.md +++ b/content/pull-requests/how-tos/work-with-forks/index.md @@ -1,21 +1,22 @@ --- -title: Working with forks -intro: 'Forks are often used in open source development on {% data variables.product.github %}.' +title: Work with forks redirect_from: + - /pull-requests/collaborating-with-pull-requests/working-with-forks - /github/collaborating-with-issues-and-pull-requests/working-with-forks - /articles/working-with-forks - /github/collaborating-with-pull-requests/working-with-forks +shortTitle: Work with forks +intro: 'Fork repositories, sync changes, and manage pull request branches effectively using forks.' versions: fpt: '*' ghes: '*' ghec: '*' children: - - /about-forks - /fork-a-repo - - /about-permissions-and-visibility-of-forks - /configuring-a-remote-repository-for-a-fork - /syncing-a-fork - /allowing-changes-to-a-pull-request-branch-created-from-a-fork - - /what-happens-to-forks-when-a-repository-is-deleted-or-changes-visibility - /detaching-a-fork +contentType: how-tos --- + diff --git a/content/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork.md b/content/pull-requests/how-tos/work-with-forks/syncing-a-fork.md similarity index 77% rename from content/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork.md rename to content/pull-requests/how-tos/work-with-forks/syncing-a-fork.md index ae7bc77e8afc..75778488237a 100644 --- a/content/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork.md +++ b/content/pull-requests/how-tos/work-with-forks/syncing-a-fork.md @@ -1,6 +1,6 @@ --- title: Syncing a fork -intro: Sync a fork of a repository to keep it up-to-date with the upstream repository. +intro: Sync a forked repository with its upstream repository using the web interface, GitHub CLI, or command line. redirect_from: - /github/collaborating-with-issues-and-pull-requests/working-with-forks/syncing-a-fork - /articles/syncing-a-fork @@ -11,13 +11,16 @@ redirect_from: - /articles/merging-an-upstream-repository-into-your-fork - /github/collaborating-with-issues-and-pull-requests/merging-an-upstream-repository-into-your-fork - /github/collaborating-with-pull-requests/working-with-forks/merging-an-upstream-repository-into-your-fork + - /pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork versions: fpt: '*' ghes: '*' ghec: '*' permissions: People with write access for a forked repository can sync the fork to the upstream repository. +shortTitle: Sync a fork category: - Work with forks +contentType: how-tos --- ## Syncing a fork branch from the web UI @@ -40,13 +43,13 @@ To update the remote fork from its parent, use the `gh repo sync -b BRANCH-NAME` gh repo sync owner/cli-fork -b BRANCH-NAME ``` -If the changes from the upstream repository cause conflict then the {% data variables.product.prodname_cli %} can't sync. You can set the `--force` flag to overwrite the destination branch. +If the changes from the upstream repository cause conflicts, the {% data variables.product.prodname_cli %} can't sync. To overwrite the destination branch, use the `--force` flag. ## Syncing a fork branch from the command line -Before you can sync your fork with an upstream repository, you must configure a remote that points to the upstream repository in Git. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/configuring-a-remote-repository-for-a-fork). +Before you can sync your fork with an upstream repository, you must configure a remote that points to the upstream repository in Git. See [AUTOTITLE](/pull-requests/how-tos/work-with-forks/configuring-a-remote-repository-for-a-fork). -{% data reusables.command_line.open_the_multi_os_terminal %} +1. Open your terminal or Git Bash. 1. Change the current working directory to your local project. 1. Fetch the branches and their respective commits from the upstream repository. Commits to `BRANCH-NAME` will be stored in the local branch `upstream/BRANCH-NAME`. @@ -60,14 +63,14 @@ Before you can sync your fork with an upstream repository, you must configure a > * [new branch] main -> upstream/main ``` -1. Check out your fork's local default branch - in this case, we use `main`. +1. Check out your fork's local default branch. In this example, we use `main`. ```shell $ git checkout main > Switched to branch 'main' ``` -1. Merge the changes from the upstream default branch - in this case, `upstream/main` - into your local default branch. This brings your fork's default branch into sync with the upstream repository, without losing your local changes. +1. Merge the changes from the upstream default branch into your local default branch. In this example, the upstream default branch is `upstream/main`. This syncs your fork's default branch with the upstream repository without losing your local changes. ```shell $ git merge upstream/main @@ -80,7 +83,7 @@ Before you can sync your fork with an upstream repository, you must configure a > create mode 100644 README.md ``` - If your local branch didn't have any unique commits, Git will perform a fast-forward. For more information, see [Basic Branching and Merging](https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging) in the Git documentation. + If your local branch didn't have any unique commits, Git will perform a fast-forward. See [Basic Branching and Merging](https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging) in the Git documentation. ```shell $ git merge upstream/main @@ -90,7 +93,7 @@ Before you can sync your fork with an upstream repository, you must configure a > 1 file changed, 3 insertions(+), 2 deletions(-) ``` - If your local branch had unique commits, you may need to resolve conflicts. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts). + If your local branch had unique commits, you may need to resolve conflicts. See [AUTOTITLE](/pull-requests/how-tos/merge-and-close-pull-requests). > [!TIP] > Syncing your fork only updates your local copy of the repository. To update your fork on {% data variables.location.product_location %}, you must [push your changes](/get-started/using-git/pushing-commits-to-a-remote-repository). diff --git a/content/pull-requests/index.md b/content/pull-requests/index.md index f29a33b89b91..bbcc15fe227f 100644 --- a/content/pull-requests/index.md +++ b/content/pull-requests/index.md @@ -1,20 +1,29 @@ --- title: Pull requests documentation -intro: 'Learn how to use pull requests to suggest changes to a project, receive suggested changes to your own projects, and address issues in pull requests, such as merge conflicts.' +redirect_from: + - /pull-requests/collaborating-with-pull-requests + - /github/collaborating-with-issues-and-pull-requests + - /categories/63/articles + - /categories/collaborating + - /categories/collaborating-on-projects-using-pull-requests + - /categories/collaborating-on-projects-using-issues-and-pull-requests + - /categories/collaborating-with-issues-and-pull-requests + - /github/collaborating-with-pull-requests +intro: 'Discover how to create, review, and merge pull requests, resolve merge conflicts, and collaborate effectively on {% data variables.product.github %} projects.' introLinks: - overview: /pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests + overview: /pull-requests/get-started/about-pull-requests layout: discovery-landing carousels: recommended: - - /pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests - - /pull-requests/collaborating-with-pull-requests/getting-started/about-collaborative-development-models - - /pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request - - /pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request - - /pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request - - /pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-on-github - - /pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo - - /pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork - - /pull-requests/committing-changes-to-your-project/creating-and-editing-commits/about-commits + - /pull-requests/reference/pull-requests + - /pull-requests/reference/branches + - /pull-requests/how-tos/create-pull-requests/creating-a-pull-request + - /pull-requests/how-tos/review-pull-requests/reviewing-proposed-changes-in-a-pull-request + - /pull-requests/how-tos/merge-and-close-pull-requests/merging-a-pull-request + - /pull-requests/how-tos/merge-and-close-pull-requests/resolving-a-merge-conflict-on-github + - /pull-requests/how-tos/work-with-forks/fork-a-repo + - /pull-requests/how-tos/work-with-forks/syncing-a-fork + - /pull-requests/reference/commits includedCategories: - Create pull requests - Review pull requests @@ -27,7 +36,10 @@ versions: ghec: '*' ghes: '*' children: - - /committing-changes-to-your-project - - /collaborating-with-pull-requests + - /get-started + - /concepts + - /how-tos + - /reference +contentType: landing --- diff --git a/content/pull-requests/reference/branches.md b/content/pull-requests/reference/branches.md new file mode 100644 index 000000000000..f1a401f16542 --- /dev/null +++ b/content/pull-requests/reference/branches.md @@ -0,0 +1,97 @@ +--- +title: Branches +intro: Use branches in GitHub to isolate development work, manage default branches, and collaborate effectively using pull requests and branch protections. +redirect_from: + - /pull-requests/concepts/about-branches + - /github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches + - /articles/working-with-protected-branches + - /articles/about-branches + - /github/collaborating-with-issues-and-pull-requests/about-branches + - /github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches + - /github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-comparing-branches-in-pull-requests + - /articles/about-comparing-branches-in-pull-requests + - /github/collaborating-with-issues-and-pull-requests/about-comparing-branches-in-pull-requests + - /github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-comparing-branches-in-pull-requests + - /pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-comparing-branches-in-pull-requests + - /pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches +versions: + fpt: '*' + ghes: '*' + ghec: '*' +category: + - Create pull requests +contentType: reference +--- + +## About branches + +Branches let you develop features, fix bugs, or safely experiment with new ideas in a contained area of your repository. + +You always create a branch from an existing branch. Typically, you might create a new branch from the default branch of your repository. You can then work on this new branch in isolation from changes that other people are making to the repository. + +A branch you create to build a feature is commonly called a feature branch or topic branch. See [AUTOTITLE](/pull-requests/how-tos/create-pull-requests/creating-and-deleting-branches-within-your-repository). + +You can also use a branch to publish a {% data variables.product.prodname_pages %} site. See [AUTOTITLE](/pages/getting-started-with-github-pages/what-is-github-pages). + +You must have write access to a repository to create a branch, open a pull request, or delete and restore branches in a pull request. See [AUTOTITLE](/get-started/learning-about-github/access-permissions-on-github). + +## About the default branch + +{% data reusables.branches.new-repo-default-branch %} The default branch is the branch that {% data variables.product.prodname_dotcom %} displays when anyone visits your repository. The default branch is also the initial branch that Git checks out locally when someone clones the repository. {% data reusables.branches.default-branch-automatically-base-branch %} + +By default, {% data variables.product.github %} names the default branch `main` in any new repository. + +{% data reusables.branches.change-default-branch %} + +{% data reusables.branches.set-default-branch %} + +## Working with protected branches + +Protected branches help maintainers enforce rules on important branches. A protected branch can block force pushes or deletion, require status checks, require reviews, require code owner approval, or require signed commits before changes can merge. + +These protections help teams keep important branches stable and make expectations clear before a pull request is merged. To see whether your pull request can be merged, check the merge box at the bottom of the pull request's **Conversation** tab. See [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches). + +> [!NOTE] +> If you're a repository administrator, you can merge pull requests on branches with branch protections enabled even if the pull request does not meet the requirements, unless branch protections have been set to "Include administrators." + +## Comparing branches in pull requests + +A pull request compares the proposed changes on the head branch with the base branch. When you create your pull request, you can change the base branch that you're comparing your changes against. The **Files changed** tab shows what would change if the pull request merged. + +Diff views help reviewers understand the changes without reading every commit. You can view a unified diff, split diff, rich diff, or source diff; ignore whitespace changes; or filter files to focus on the most relevant changes. + +![Screenshot of the "Files changed" tab for a pull request. The "Diff view" menu is outlined in dark orange.](/assets/images/help/pull_requests/diff-settings-menu.png) + +Diffs may not display if a pull request exceeds repository diff limits or if a file is hidden by a rule in the repository's _.gitattributes_ file. See [AUTOTITLE](/repositories/creating-and-managing-repositories/repository-limits#diff-limits) and [AUTOTITLE](/repositories/working-with-files/managing-files/customizing-how-changed-files-appear-on-github). + +### Three-dot and two-dot Git diff comparisons + +The `git diff` command supports two comparison methods. Pull requests on {% data variables.product.prodname_dotcom %} show a three-dot diff. + +| Method | Command | What it compares | +| --- | --- | --- | +| Three-dot | `git diff A...B` | The most recent common commit of both branches (merge base) and the most recent version of the topic branch. | +| Two-dot | `git diff A..B` | The most recent state of the base branch (for example, `main`) and the most recent version of the topic branch. | + +A two-dot diff compares two Git committish references, such as SHAs or OIDs (Object IDs), directly with each other. On {% data variables.product.prodname_dotcom %}, the Git committish references in a two-dot diff comparison must be pushed to the same repository or its forks. + +See [Git diff options](https://git-scm.com/docs/git-diff#git-diff-emgitdiffemltoptionsgtltcommitgtltcommitgt--ltpathgt82308203) from the _Pro Git_ book site. + +### About three-dot comparison on {% data variables.product.prodname_dotcom %} + +Because the three-dot comparison uses the merge base, it focuses on "what a pull request introduces." + +When you use a two-dot comparison, the diff changes when the base branch is updated, even if you haven't made any changes to the topic branch. A two-dot comparison also focuses on the base branch, which can make the changes introduced by the topic branch harder to understand. + +In contrast, a three-dot comparison keeps showing the changes introduced by the topic branch since the branches diverged. + +### Merging often + +To avoid confusion, merge the base branch (for example, `main`) into your topic branch frequently. When you merge the base branch, the diffs shown by two-dot and three-dot comparisons are the same. We recommend merging a pull request as soon as possible. This encourages contributors to make pull requests smaller, which we recommend in general. + +## Further reading + +* [AUTOTITLE](/pull-requests/reference/pull-requests) +* [AUTOTITLE](/get-started/learning-about-github/github-glossary#branch) in the {% data variables.product.prodname_dotcom %} glossary +* [Branches in a Nutshell](https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell) in the Git documentation +* [AUTOTITLE](/pull-requests/reference/forks) diff --git a/content/pull-requests/reference/commits.md b/content/pull-requests/reference/commits.md new file mode 100644 index 000000000000..00bdf8cc695a --- /dev/null +++ b/content/pull-requests/reference/commits.md @@ -0,0 +1,55 @@ +--- +title: Commits +intro: Learn how commits save changes to your files, track authorship, and organize your project's history in GitHub. +redirect_from: + - /pull-requests/concepts/about-commits + - /articles/why-are-my-commits-in-the-wrong-order + - /github/committing-changes-to-your-project/why-are-my-commits-in-the-wrong-order + - /github/committing-changes-to-your-project/about-commits + - /github/committing-changes-to-your-project/creating-and-editing-commits/about-commits + - /pull-requests/committing-changes-to-your-project/viewing-and-comparing-commits/commit-branch-and-tag-labels + - /pull-requests/committing-changes-to-your-project/creating-and-editing-commits/about-commits +versions: + fpt: '*' + ghes: '*' + ghec: '*' +category: + - Commit changes +contentType: reference +--- +## About commits + +{% data reusables.commits.about-commits %} + +If the repository you are committing to requires commit signoffs, and you are committing in the web interface, you will automatically sign off on the commit. See [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-the-commit-signoff-policy-for-your-repository). + +You can add a co-author on any commits you collaborate on. See [AUTOTITLE](/pull-requests/how-tos/commit-changes/creating-a-commit-with-multiple-authors). + +You can also create a commit on behalf of an organization. See [AUTOTITLE](/pull-requests/how-tos/commit-changes/creating-a-commit-with-multiple-authors#creating-a-commit-on-behalf-of-an-organization). + +Rebasing lets you change a series of commits and can change the order of the commits in your timeline. See [AUTOTITLE](/get-started/using-git/about-git-rebase). + +## About commit branches and tag labels + +Commit pages can show labels for branches and tags that contain the commit. These labels help you understand where a commit appears in the repository history. + +![Screenshot of a commit summary. A branch icon and "main" are highlighted with an orange outline.](/assets/images/help/commits/commit-branch-indicator.png) + +If your commit is not on the default branch (`main`), the label will show the branches which contain the commit. If the commit is part of an unmerged pull request, you can click the link to go to the pull request. + +Once the commit is on the default branch, any tags that contain the commit will be shown and the default branch will be the only branch listed. See [Git Basics - Tagging](https://git-scm.com/book/en/v2/Git-Basics-Tagging) in the Git documentation. + +![Screenshot of a commit summary. The tag icon and "v2.3.4" are highlighted with an orange outline.](/assets/images/help/commits/commit-tag-label.png) + +## Using the file tree + +The file tree helps you navigate between files in a commit and focus on the diffs that matter. You can select a file to view its diff or filter by file path when a commit changes many files. + +> [!NOTE] +> The file tree will not display if your screen width is too narrow or if the commit only includes one file. + +![Screenshot of the "Files changed" tab of a pull request. In the left sidebar, the file tree is outlined in dark orange.](/assets/images/help/repository/file-tree.png) + +## Further reading + +* [AUTOTITLE](/desktop/making-changes-in-a-branch/committing-and-reviewing-changes-to-your-project-in-github-desktop#about-commits) on {% data variables.product.prodname_desktop %} diff --git a/content/pull-requests/reference/forks.md b/content/pull-requests/reference/forks.md new file mode 100644 index 000000000000..3889d221f96c --- /dev/null +++ b/content/pull-requests/reference/forks.md @@ -0,0 +1,119 @@ +--- +title: Forks +intro: Understand how forks enable independent collaboration by creating separate repositories connected to the original, with distinct settings and permissions. +redirect_from: + - /pull-requests/concepts/about-forks + - /github/collaborating-with-issues-and-pull-requests/working-with-forks/about-forks + - /articles/about-forks + - /github/collaborating-with-issues-and-pull-requests/about-forks + - /github/collaborating-with-pull-requests/working-with-forks/about-forks + - /github/collaborating-with-issues-and-pull-requests/working-with-forks/what-happens-to-forks-when-a-repository-is-deleted-or-changes-visibility + - /articles/changing-the-visibility-of-a-network + - /articles/what-happens-to-forks-when-a-repository-is-deleted-or-changes-visibility + - /github/collaborating-with-issues-and-pull-requests/what-happens-to-forks-when-a-repository-is-deleted-or-changes-visibility + - /github/collaborating-with-pull-requests/working-with-forks/what-happens-to-forks-when-a-repository-is-deleted-or-changes-visibility + - /pull-requests/collaborating-with-pull-requests/working-with-forks/what-happens-to-forks-when-a-repository-is-deleted-or-changes-visibility + - /pull-requests/collaborating-with-pull-requests/working-with-forks/about-permissions-and-visibility-of-forks + - /pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks +versions: + fpt: '*' + ghes: '*' + ghec: '*' +category: + - Work with forks +contentType: reference +--- + +Forks are repositories that start as copies of another repository, called the upstream repository. A fork has its own settings and permissions but stays connected to the upstream repository. + +When you view a forked repository on {% data variables.product.github %}, the upstream repository is indicated below the name of the fork. + +## What makes forks distinct from branches + +A branch is part of one repository. A fork is a separate repository with its own settings and collaboration space. + +Each fork can have its own: + +* Branches +* Members and discussions +* Issues and pull requests +* Actions and projects +* Tags, labels, and wikis + +## Which repositories can be forked? + +{% data reusables.repositories.you-can-fork %} + +Repository, organization, and enterprise policies can limit whether repositories can be forked and where forks can be created. For private{% ifversion ghec or ghes %} and internal{% endif %} repositories, access to forks also depends on repository visibility, organization membership, and administrator settings. + +{% ifversion fpt or ghec %} + +If you're a member of an {% data variables.enterprise.prodname_emu_enterprise %}, additional restrictions apply to the repositories you can fork. {% ifversion ghec %}{% data reusables.enterprise-accounts.emu-forks %}{% endif %} See [AUTOTITLE](/enterprise-cloud@latest/admin/concepts/identity-and-access-management/enterprise-managed-users){% ifversion fpt %} in the {% data variables.product.prodname_ghe_cloud %} documentation.{% else %}.{% endif %} + +{% endif %} + +See [AUTOTITLE](/organizations/managing-organization-settings/managing-the-forking-policy-for-your-organization){% ifversion fpt %}.{% else %} and [AUTOTITLE](/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise#enforcing-a-policy-for-forking-private-or-internal-repositories).{% endif %} + +## Visibility of forks + +A fork's visibility is tied to the upstream repository's repository network. Public repository forks are public, and private repository forks are private.{% ifversion ghec or ghes %} Forks of internal repositories are private.{% endif %} You cannot change the visibility of a fork by itself. + +All repositories in a repository network share the same visibility setting. A repository network includes the upstream repository, its forks, and forks of those forks. See [AUTOTITLE](/repositories/viewing-activity-and-data-for-your-repository/understanding-connections-between-repositories). + +Deleting a repository or changing its visibility can affect the network. If you delete a fork, code contributions from that fork can remain accessible to the repository network. + +## What happens to forks when a repository is deleted or changes visibility + +{% data reusables.repositories.deleted_forks_from_private_repositories_warning %} + +Visibility changes can separate forks into new repository networks so that existing fork owners can keep working without unexpected loss of access. + +| Action | Effect on forks | +| --- | --- | +| A private repository is deleted | Its private forks are also deleted. | +| A public repository is deleted | An active public fork becomes the new upstream repository for the network. | +| A public repository is made private | Its public forks stay public in a separate network. | +| A private repository is made public | Private forks stay private but disconnect into separate private networks. | +| {% ifversion ghec or ghes %} | +| An internal repository changes visibility | Forks owned by organizations or personal accounts remain private. | +| {% endif %} | + +Changing a public repository to private can also affect stars, watchers, dependency graph, {% data variables.product.prodname_dependabot_alerts %}, and {% data variables.product.prodname_code_scanning %} availability. Review repository visibility settings carefully before changing them. + +{% ifversion ghes %} +If a public repository has anonymous Git read access enabled and the repository is made private, all of the repository's forks lose anonymous Git read access and return to the default disabled setting. If a forked repository is made public, repository administrators can re-enable anonymous Git read access. See [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/enabling-anonymous-git-read-access-for-a-repository). +{% endif %} + +## Permissions of forks + +{% data reusables.repositories.private_forks_inherit_permissions %} + +Public forks do not inherit the permissions structure of the upstream repository. Fork owners control access to their forks, but repository networks still share Git data. Commits pushed to any repository in a network can be accessible from other repositories in that network, including the upstream repository. + +When you fork a public repository to your personal account, you can allow maintainers of the upstream repository to push to your pull request branch. This can help maintainers update your branch, run tests, or resolve small issues before merging. You cannot give push permissions to a fork owned by an organization. See [AUTOTITLE](/pull-requests/how-tos/work-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork). + +### Push rulesets for forked repositories + +{% data reusables.repositories.rulesets-push-rulesets-fork-network-information %} + +See [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets#push-rulesets). + +### Important security considerations + +Forks are powerful collaboration tools, but they can expose code and history in ways that are easy to overlook. + +* Forks have their own permissions separate from the upstream repository. +* Owners of an upstream repository can read all forks in the repository network. +* Organization owners may have administrative access to forks created in personal namespaces. +* Removing someone's access to the upstream repository does not always delete forks in other organizations. +* Commits can remain accessible in the repository network even after a fork is deleted. + +Before allowing forks for sensitive work, review the permissions and visibility model for your repository or organization. + +### Forks within an organization + +Forks within the same organization copy collaborator and team settings from the upstream repository. The organization controls permissions for these forks, and existing visible teams may keep access. + +### Forks within an enterprise + +Internal repositories support a single level of forking. You cannot fork a private fork of an internal repository. This keeps access and management simpler for repositories that are visible across an enterprise. diff --git a/content/pull-requests/reference/index.md b/content/pull-requests/reference/index.md new file mode 100644 index 000000000000..e8e3dcc7bbec --- /dev/null +++ b/content/pull-requests/reference/index.md @@ -0,0 +1,23 @@ +--- +title: Reference for pull requests +shortTitle: Reference +intro: Find detailed guidance on managing pull requests, including reviews, merges, branches, and resolving conflicts. +versions: + fpt: '*' + ghes: '*' + ghec: '*' +children: + - /pull-requests + - /branches + - /forks + - /commits + - /using-query-parameters-to-create-a-pull-request + - /pull-request-reviews + - /status-checks + - /pull-request-merges + - /merge-conflicts + - /managing-and-standardizing-pull-requests + - /working-with-pre-receive-hooks +contentType: reference +--- + diff --git a/content/pull-requests/reference/managing-and-standardizing-pull-requests.md b/content/pull-requests/reference/managing-and-standardizing-pull-requests.md new file mode 100644 index 000000000000..9e2e6a27611e --- /dev/null +++ b/content/pull-requests/reference/managing-and-standardizing-pull-requests.md @@ -0,0 +1,53 @@ +--- +title: Managing and standardizing pull requests +intro: Manage and standardize pull requests using templates, code owners, protected branches, rulesets, and automated tools for consistent and secure repository contributions. +versions: + fpt: '*' + ghes: '*' + ghec: '*' +shortTitle: Manage and standardize pull requests +category: + - Create pull requests +redirect_from: + - /pull-requests/concepts/managing-and-standardizing-pull-requests + - /pull-requests/collaborating-with-pull-requests/getting-started/managing-and-standardizing-pull-requests +contentType: reference +--- + +If you maintain a repository, you can use {% data variables.product.github %} features to make pull requests more consistent and easier to review. Standardization helps contributors know what information to provide, helps reviewers focus on the right changes, and helps protect important branches from accidental or risky merges. + +## Using pull request templates + +Pull request templates help contributors provide the context your project needs for review. A template can prompt authors to explain the purpose of the change, link related issues, include testing notes, or complete a checklist before requesting review. + +Templates are useful when many contributors open pull requests or when your project has review expectations that should be visible every time. See [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository), [AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting/about-tasklists), and [AUTOTITLE](/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue). + +## Defining code owners + +Code owners identify the people or teams responsible for specific files or directories. When a pull request changes owned code, {% data variables.product.github %} can automatically request a review from the right owners. + +Code owners help route reviews to people with the right context. They are especially useful for sensitive areas such as security files, deployment configuration, or shared libraries. See [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners). + +## Using protected branches + +Protected branches help keep important branches, such as `main`, stable. They can require conditions such as passing status checks, signed commits, or approving reviews before a pull request can merge. + +Use protected branches when a branch represents production code, a release line, or another important source of truth. See [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches). + +## Using rulesets + +Rulesets let you enforce repository policies across branches and tags. They can require status checks, workflows, pull request reviews, or other conditions before changes are accepted. + +Rulesets are useful when you want consistent rules across multiple branches or when you want to combine review requirements with automated security checks, such as dependency review or {% data variables.product.prodname_code_scanning %} merge protection. See [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets), [AUTOTITLE](/code-security/how-tos/secure-at-scale/configure-organization-security/configure-specific-tools/enforce-dependency-review), and [AUTOTITLE](/code-security/how-tos/find-and-fix-code-vulnerabilities/manage-your-configuration/set-merge-protection). + +## Using push rulesets + +{% data reusables.repositories.push-rulesets-overview %} + +Push rulesets help block risky content before it enters the repository. See [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets#push-rulesets). + +## Using automated tools to review code styling + +Automated tools, such as linters and formatters, help keep code style consistent across pull requests. They can catch small issues automatically so reviewers can focus on design, correctness, and maintainability. + +You can run these tools as part of a continuous integration workflow with {% data variables.product.prodname_actions %}. See [AUTOTITLE](/actions/get-started/continuous-integration). diff --git a/content/pull-requests/reference/merge-conflicts.md b/content/pull-requests/reference/merge-conflicts.md new file mode 100644 index 000000000000..9e96e22c3832 --- /dev/null +++ b/content/pull-requests/reference/merge-conflicts.md @@ -0,0 +1,47 @@ +--- +title: Merge conflicts +intro: Identify and resolve merge conflicts in Git to ensure smooth branch integration and successful pull request merges. +redirect_from: + - /pull-requests/concepts/about-merge-conflicts + - /github/collaborating-with-issues-and-pull-requests/addressing-merge-conflicts/about-merge-conflicts + - /articles/about-merge-conflicts + - /github/collaborating-with-issues-and-pull-requests/about-merge-conflicts + - /github/about-merge-conflicts + - /github/collaborating-with-pull-requests/addressing-merge-conflicts/about-merge-conflicts + - /pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/about-merge-conflicts +versions: + fpt: '*' + ghec: '*' + ghes: '*' +category: + - Merge and close pull requests +contentType: reference +--- + +Git can often resolve differences between branches and merge them automatically. Usually, changes are on different lines or in different files, so Git can merge them without help. Sometimes, competing changes need your help. Merge conflicts often happen when people make different changes to the same line of the same file, or when one person edits a file and another person deletes the same file. + +Merge conflicts block merging because Git cannot safely choose which version of the conflicting content to keep. You must resolve all merge conflicts before you can merge a pull request on {% data variables.product.github %}. If your pull request has a merge conflict between the compare branch and base branch, the **Merge pull request** button is deactivated until the conflicts are resolved. + +## Resolving merge conflicts + +Resolving a merge conflict means choosing the final content that should appear after the branches are merged. The right tool depends on the type of conflict. + +* Simple line conflicts can often be resolved on {% data variables.product.github %}. See [AUTOTITLE](/pull-requests/how-tos/merge-and-close-pull-requests/resolving-a-merge-conflict-on-github). +* More complex conflicts must be resolved in a local clone and pushed back to the pull request branch. See [AUTOTITLE](/pull-requests/how-tos/merge-and-close-pull-requests/resolving-a-merge-conflict-using-the-command-line). +{% ifversion fpt or ghec %}* If you have access to {% data variables.copilot.copilot_cloud_agent %} and it is enabled for the repository, {% data variables.product.prodname_copilot_short %} can help resolve conflicts from the merge box. See [AUTOTITLE](/copilot/how-tos/use-copilot-agents/cloud-agent/use-cloud-agent-on-github#resolving-merge-conflicts).{% endif %} + +On the command line, Git tells you when a merge cannot finish automatically. You cannot push the merged result until you resolve the conflict and commit the resolution. + +```shell +$ git merge BRANCH-NAME +> Auto-merging styleguide.md +> CONFLICT (content): Merge conflict in styleguide.md +> Automatic merge failed; fix conflicts and then commit the result +``` + +## Further reading + +* [AUTOTITLE](/pull-requests/reference/pull-request-merges) +* [AUTOTITLE](/pull-requests/reference/pull-requests) +* [AUTOTITLE](/pull-requests/how-tos/merge-and-close-pull-requests/resolving-a-merge-conflict-using-the-command-line) +* [AUTOTITLE](/pull-requests/how-tos/merge-and-close-pull-requests/resolving-a-merge-conflict-on-github) diff --git a/content/pull-requests/reference/pull-request-merges.md b/content/pull-requests/reference/pull-request-merges.md new file mode 100644 index 000000000000..988b0ad87b5f --- /dev/null +++ b/content/pull-requests/reference/pull-request-merges.md @@ -0,0 +1,74 @@ +--- +title: Pull request merges +intro: Learn strategies for merging pull requests, including merge commits, squash merges, and rebases, to manage repository history effectively. +redirect_from: + - /pull-requests/concepts/about-pull-request-merges + - /github/collaborating-with-issues-and-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges + - /articles/about-pull-request-merge-squashing + - /articles/about-pull-request-merges + - /github/collaborating-with-issues-and-pull-requests/about-pull-request-merges + - /github/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges + - /pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges +versions: + fpt: '*' + ghes: '*' + ghec: '*' +category: + - Merge and close pull requests +contentType: reference +--- + +Pull requests can be merged in different ways. The best strategy depends on how your team wants the repository history to look and how much detail you want to preserve from the pull request branch. + +| Strategy | Result | Choose when | +| --- | --- | --- | +| Merge commit | Preserves every commit from the pull request branch and adds an explicit merge point. | Your team values complete history, or the individual commits are meaningful on their own. | +| Squash and merge | Combines all commits in the pull request into a single commit on the base branch. | A pull request represents one logical change, especially with many small fixup commits. | +| Rebase and merge | Adds each commit onto the base branch without a merge commit, for a linear history. | Your team wants a linear history and the commits are already organized clearly. | + +## Merge your commits + +{% data reusables.pull_requests.default_merge_option %} + +A merge commit preserves the full commit history from the pull request branch. This makes it easier to see every commit that led to the final change, including review fixes and intermediate work. It also creates an explicit merge point in the base branch history. + +Choose this strategy when your team values complete history or when the individual commits in a pull request are meaningful on their own. + +## Squash and merge your commits + +{% data reusables.pull_requests.squash_and_merge_summary %} + +Squashing turns all commits in the pull request into one commit on the base branch. This keeps the default branch history concise and can make it easier to scan later. The tradeoff is that intermediate commits from the pull request are not preserved as separate commits on the base branch. + +Choose this strategy when a pull request represents one logical change, especially if the branch includes many small fixup commits. + +### Merge message for a squash merge + +When you squash and merge, {% data variables.product.prodname_dotcom %} generates a default commit message that you can edit. The default message can include the pull request title, pull request description, or commit information, depending on repository settings and the number of commits in the pull request. + +Maintainers and administrators can configure the default message for squashed commits. See [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/configuring-commit-squashing-for-pull-requests). + +### Squashing and merging a long-running branch + +Squash merging works best for short-lived branches. If you keep working on the same head branch after a squash merge, later pull requests can include commits that were already squashed into the base branch. This can make merge conflicts more likely and can force you to resolve the same conflicts more than once. + +For long-running branches, consider using a merge commit or rebasing the branch before opening the next pull request. + +## Rebase and merge your commits + +{% data reusables.pull_requests.rebase_and_merge_summary %} + +Rebasing adds each commit from the pull request branch onto the base branch without creating a merge commit. This produces a linear history while preserving the individual commits from the pull request. + +Choose this strategy when your team wants a linear history and the pull request commits are already organized clearly. If {% data variables.product.github %} cannot safely rebase the pull request automatically, you can rebase locally, resolve conflicts, and push the updated branch. See [AUTOTITLE](/pull-requests/how-tos/merge-and-close-pull-requests/resolving-a-merge-conflict-using-the-command-line) and [AUTOTITLE](/pull-requests/how-tos/merge-and-close-pull-requests/merging-a-pull-request). + +## Indirect merges + +A pull request can be marked as merged if its head branch commits become reachable from the base branch outside that pull request. This can happen when the same commits are merged through another pull request or pushed directly to the default branch. + +Indirect merges are uncommon, but they can affect automation and branch protection expectations. Pull requests merged indirectly are marked as `merged` even if branch protection rules on that pull request were not satisfied. + +## Further reading + +* [AUTOTITLE](/pull-requests/reference/pull-requests) +* [AUTOTITLE](/pull-requests/how-tos/merge-and-close-pull-requests) diff --git a/content/pull-requests/reference/pull-request-reviews.md b/content/pull-requests/reference/pull-request-reviews.md new file mode 100644 index 000000000000..0d58905bf044 --- /dev/null +++ b/content/pull-requests/reference/pull-request-reviews.md @@ -0,0 +1,54 @@ +--- +title: Pull request reviews +intro: Review pull requests to provide feedback, suggest changes, and ensure code quality before merging. +redirect_from: + - /pull-requests/concepts/about-pull-request-reviews + - /github/collaborating-with-issues-and-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews + - /articles/about-pull-request-reviews + - /github/collaborating-with-issues-and-pull-requests/about-pull-request-reviews + - /github/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews + - /pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews +versions: + fpt: '*' + ghes: '*' + ghec: '*' +shortTitle: PR reviews +category: + - Review pull requests +contentType: reference +--- + +Pull request reviews let people comment on changes, suggest improvements, and approve or request changes before code is merged. Anyone with read access can review and comment on proposed changes, helping teams maintain code quality and share knowledge. + +{% raw %}View pull requests awaiting your review{% endraw %} + +## Review decision types + +When a reviewer submits a review, they choose one of the following decisions: + +| Decision | Meaning | +| --- | --- | +| Comment | Leaves general feedback without explicitly approving or requesting changes. | +| Approve | Signals that the changes are ready to merge. | +| Request changes | Flags feedback that the author should address before merging. | + +Reviewers can also comment on specific lines, suggest exact changes, and discuss implementation details. Review conversations appear in the pull request timeline so the team can track feedback and decisions. + +## Requesting and requiring reviews + +Reviews can be requested from specific people or teams when they need feedback from the right experts. + +To request a review, you need write access to the repository. You can request a review from a person or team with read access to the repository, and they receive a notification. +* Pull request authors can request reviews only if they are repository owners or collaborators with write access. +* Organization members with write access or triage permissions can also assign a reviewer for a pull request. +* If you request a review from a team and code review assignment is enabled, specific members will be requested and the team will be removed as a reviewer. + +If you define code owners in a CODEOWNERS file, {% data variables.product.github %} can automatically request review from owners when a pull request changes their code. See [AUTOTITLE](/pull-requests/how-tos/create-pull-requests/requesting-a-pull-request-review). + +Repository administrators can require approvals before pull requests are merged. Required reviews help protect important branches and reduce accidental merges. See [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-pull-request-reviews-before-merging). + +## Further reading + +* [AUTOTITLE](/pull-requests/how-tos/review-pull-requests/reviewing-proposed-changes-in-a-pull-request) +* [AUTOTITLE](/pull-requests/how-tos/create-pull-requests/requesting-a-pull-request-review) +* Learn more in the [Review pull requests](https://github.com/skills/review-pull-requests?ref_product=github&ref_type=engagement&ref_style=text) {% data variables.product.prodname_learning %} course diff --git a/content/pull-requests/reference/pull-requests.md b/content/pull-requests/reference/pull-requests.md new file mode 100644 index 000000000000..117d5127669f --- /dev/null +++ b/content/pull-requests/reference/pull-requests.md @@ -0,0 +1,87 @@ +--- +title: Pull requests +shortTitle: Pull requests +intro: Propose, review, and merge code changes using pull requests to collaborate effectively and maintain code quality. +redirect_from: + - /pull-requests/concepts/about-pull-requests + - /github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests + - /articles/using-pull-requests + - /articles/about-pull-requests + - /github/collaborating-with-issues-and-pull-requests/about-pull-requests + - /github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests + - /github/collaborating-with-issues-and-pull-requests/getting-started/about-collaborative-development-models + - /articles/types-of-collaborative-development-models + - /articles/about-collaborative-development-models + - /github/collaborating-with-issues-and-pull-requests/about-collaborative-development-models + - /github/collaborating-with-pull-requests/getting-started/about-collaborative-development-models + - /pull-requests/collaborating-with-pull-requests/getting-started/about-collaborative-development-models + - /pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests +versions: + fpt: '*' + ghes: '*' + ghec: '*' +category: + - Create pull requests +contentType: reference +--- + +Pull requests are proposals to merge code changes into a project. A pull request is {% data variables.product.github %}'s key **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 {% octicon "link-external" height:16 aria-label="link-external" %} + +## Working with pull requests + +A pull request brings together the context reviewers need to understand a change. This context is organized into tabs: + +* The **Conversation** tab shows the description, timeline, comments, and reviews. +* The **Commits** tab shows how the pull request branch changed over time. +* The **Checks** tab shows automated tests, builds, and other validations. +* The **Files changed** tab shows the diff that reviewers use to understand the proposed changes. +* The **Findings** tab shows automated code review results, such as code scanning alerts, for the proposed changes. + +Separately from the tabs, the **merge status** highlights blockers, missing approvals, and other requirements before merging. It appears in the pull request header and in the merge box. + +Together, these views help authors and reviewers discuss the change, track feedback, and decide when the pull request is ready to merge. + +## 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. Drafts are useful when you want to share work-in-progress without formally requesting reviews. + +{% data reusables.pull_requests.mark-ready-review %} You can convert a pull request to a draft at any time. See [AUTOTITLE](/pull-requests/how-tos/create-pull-requests/changing-the-stage-of-a-pull-request). + +## Pull request refs and merge branches + +When you open a pull request, {% data variables.product.github %} creates temporary Git references that point to the pull request's head branch and, when possible, to a simulated merge result. These refs help {% data variables.product.github %} and integrations evaluate the pull request without changing the base branch. + +For most contributors, these refs stay in the background. They are most relevant when you are building automation, debugging CI behavior, or fetching pull request state locally. For information about how {% data variables.product.prodname_actions %} uses the merge branch, see [AUTOTITLE](/actions/reference/workflows-and-actions/events-that-trigger-workflows#how-the-merge-branch-affects-your-workflow). + +## Differences between commits on compare and pull request pages + +Compare pages and pull request pages can calculate changed files from different merge bases. As a result, the same branches can sometimes show different diffs in each place. + +This usually matters when the base branch has changed since the pull request was created. Pull request pages focus on what the pull request introduced, while compare pages reflect the current comparison between two refs. + +## Collaborative development models + +The way you use pull requests depends on the type of development model you use in your project. You can use the fork and pull model or the shared repository model. + +### Fork and pull model + +In the fork and pull model, anyone can fork an existing ("upstream") repository if they have read access and the owner of the upstream repository allows it. Be aware that a fork and its upstream share the same Git data. This means that all content uploaded to a fork is accessible from the upstream and all other forks of that upstream. + +You do not need permission from the upstream repository to push to a fork you created. You can optionally allow anyone with push access to the upstream repository to make changes to your pull request branch. This model is popular with open-source projects because it reduces friction for new contributors and lets people work independently without upfront coordination. + +> [!TIP] +> {% data reusables.open-source.open-source-guide-general %} {% data reusables.open-source.open-source-learning %} + +### Shared repository model + +In the shared repository model, collaborators have push access to a single shared repository and create topic branches when they need to make changes. Pull requests are useful in this model because they start code review and general discussion about a set of changes before the changes are merged into the main development branch. This model is more common with small teams and organizations collaborating on private projects. + +## Further reading + +* [AUTOTITLE](/pull-requests/how-tos/create-pull-requests/creating-a-pull-request) +* [AUTOTITLE](/pull-requests/reference/branches) +* [AUTOTITLE](/pull-requests/how-tos/review-pull-requests/commenting-on-a-pull-request) +* [AUTOTITLE](/pull-requests/how-tos/create-pull-requests/creating-a-pull-request-from-a-fork) +* [AUTOTITLE](/pull-requests/how-tos/work-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork) diff --git a/content/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks.md b/content/pull-requests/reference/status-checks.md similarity index 59% rename from content/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks.md rename to content/pull-requests/reference/status-checks.md index 6f313dcd5c63..8ca54b88a372 100644 --- a/content/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks.md +++ b/content/pull-requests/reference/status-checks.md @@ -1,28 +1,32 @@ --- -title: About status checks -intro: Status checks let you know if your commits meet the conditions set for the repository you're contributing to. +title: Status checks +intro: Understand how status checks ensure commits meet repository conditions, assist pull request reviews, and manage validations like builds, tests, and deployments. redirect_from: + - /pull-requests/concepts/about-status-checks - /github/collaborating-with-issues-and-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks - /articles/about-statuses - /articles/about-status-checks - /github/collaborating-with-issues-and-pull-requests/about-status-checks - /github/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks + - /pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks versions: fpt: '*' ghes: '*' ghec: '*' category: - Merge and close pull requests +contentType: reference --- -Status checks are based on external processes, such as continuous integration builds, which run for each push you make to a repository. You can see the _pending_, _passing_, or _failing_ state of status checks next to individual commits in your pull request. + +Status checks show whether commits meet the conditions set for a repository. They are usually created by external systems, such as continuous integration builds, tests, code scanning, or deployment checks. + +Status checks help reviewers and maintainers understand whether a pull request is ready to merge. A check can show that work is still running, that changes passed validation, or that something needs attention. ![Screenshot of a list of commits and statuses.](/assets/images/help/pull_requests/commit-list-statuses.png) Anyone with write permissions to a repository can set the state for any status check in the repository. -You can see the overall state of the last commit to a branch on your repository's branches page or in your repository's list of pull requests. - -If status checks are required for a repository, they must pass before you can merge your branch into the protected branch. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-status-checks-before-merging). +If status checks are required for a protected branch, they must pass before the pull request can be merged. See [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-status-checks-before-merging). {% data reusables.actions.workflows.skipped-job-status-checks-passing %} @@ -30,34 +34,32 @@ If status checks are required for a repository, they must pass before you can me There are two types of status checks on {% data variables.product.github %}: -* Checks -* Commit statuses - -_Checks_ are different from _commit statuses_ in that they provide line annotations, more detailed messaging, and are only available for use with {% data variables.product.prodname_github_apps %}. +| Type | Detail level | Created by | +| --- | --- | --- | +| Checks | Detailed output, annotations, and messages. | {% data variables.product.prodname_github_apps %}, including {% data variables.product.prodname_actions %}. | +| Commit statuses | A simpler status for a commit. | External services and integrations. | > [!NOTE] > {% data variables.product.prodname_actions %} generates checks, not commit statuses, when workflows are run. -Organization owners and users with push access to a repository can create checks and commit statuses with {% data variables.product.github %}'s API. For more information, see [AUTOTITLE](/rest/checks) and [AUTOTITLE](/rest/commits/statuses). +Organization owners and users with push access to a repository can create checks and commit statuses with {% data variables.product.github %}'s API. See [AUTOTITLE](/rest/checks) and [AUTOTITLE](/rest/commits/statuses). ## Checks -Pull requests have a **Checks** tab where you can view detailed build output from checks and rerun failed checks. +Checks can include build logs, test results, annotations, and links to more detail. In a pull request, the **Checks** tab helps you understand which validations ran and why a check passed or failed. -> [!NOTE] -> The **Checks** tab only gets populated for pull requests if you set up _checks_, not _commit statuses_, for the repository. +![Screenshot of the "Checks" tab of a pull request. The "Checks" tab and the dropdown menu to select a commit are both outlined in dark orange.](/assets/images/help/pull_requests/checks-summary-for-various-commits.png) -When a specific line in a commit causes a check to fail, you will see details about the failure, warning, or notice next to the relevant code in the **Files** tab of the pull request. +> [!NOTE] +> The **Checks** tab is populated for pull requests only if you set up _checks_, not _commit statuses_, for the repository. -You can navigate between the checks summaries for various commits in a pull request, using the commit drop-down menu under the **Checks** tab. - -![Screenshot of the "Checks" tab of a pull request. The "Checks" tab and the dropdown menu to select a commit are both outlined in dark orange.](/assets/images/help/pull_requests/checks-summary-for-various-commits.png) +When a check points to a specific line, details can also appear in the **Files** tab of the pull request. This helps reviewers connect automated feedback to the code being changed. ## Skipping and requesting checks for individual commits -When a repository is set to automatically request checks for pushes, you can choose to skip checks for an individual commit you push. When a repository is _not_ set to automatically request checks for pushes, you can request checks for an individual commit you push. For more information on these settings, see [AUTOTITLE](/rest/checks/suites#update-repository-preferences-for-check-suites). +Some repositories allow checks to be skipped or requested for individual commits. This can be useful when a check is not relevant to a specific change, or when checks are not requested automatically. -You can also skip workflow runs triggered by the `push` and `pull_request` events by including a command in your commit message. For more information, see [AUTOTITLE](/actions/managing-workflow-runs/skipping-workflow-runs) +For {% data variables.product.prodname_actions %} workflows, you can skip workflow runs triggered by the `push` and `pull_request` events by including a skip instruction in your commit message. See [AUTOTITLE](/actions/how-tos/manage-workflow-runs/skip-workflow-runs). Alternatively, to skip or request _all_ checks for your commit, add one of the following trailer lines to the end of your commit message: @@ -83,7 +85,7 @@ Alternatively, to skip or request _all_ checks for your commit, add one of the f ## Check statuses and conclusions -Checks can have many different statuses. Statuses describe the state of a check from when it is created to when it is completed. Some statuses cannot be set manually and are reserved for {% data variables.product.prodname_actions %}. When a check has a status of `completed`, it has a conclusion. The conclusion describes the result of the check. All possible check statuses and conclusions are listed below. +Checks move through statuses as they run, then receive a conclusion when they finish. Some statuses cannot be set manually and are reserved for {% data variables.product.prodname_actions %}. | Status | Description | {% data variables.product.prodname_actions %} only? | | --- | --- | --- | @@ -97,6 +99,8 @@ Checks can have many different statuses. Statuses describe the state of a check | `startup_failure` | The check suite failed during startup. This status is not applicable to check runs. | Yes | | `waiting` | The check run is waiting for a [deployment protection rule](/actions/managing-workflow-runs-and-deployments/managing-deployments/managing-environments-for-deployment#deployment-protection-rules) to be satisfied. | Yes | +When a check has a status of `completed`, it has a conclusion. A successful conclusion usually means the check does not block merging. A failure, timeout, or action-required conclusion usually means someone must review the details before the pull request can merge. + | Conclusion | Description | | --- | --- | | `action_required` | The check run provided required actions upon its completion. For more information, see [AUTOTITLE](/rest/guides/using-the-rest-api-to-interact-with-checks#check-runs-and-requested-actions). | diff --git a/content/pull-requests/reference/using-query-parameters-to-create-a-pull-request.md b/content/pull-requests/reference/using-query-parameters-to-create-a-pull-request.md new file mode 100644 index 000000000000..0b253116731c --- /dev/null +++ b/content/pull-requests/reference/using-query-parameters-to-create-a-pull-request.md @@ -0,0 +1,31 @@ +--- +title: Using query parameters to create a pull request +intro: 'Use query parameters to create custom URLs that open pull requests with pre-filled titles, descriptions, labels, and more.' +redirect_from: + - /github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/using-query-parameters-to-create-a-pull-request + - /pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/using-query-parameters-to-create-a-pull-request +versions: + fpt: '*' + ghes: '*' + ghec: '*' +category: + - Create pull requests +contentType: reference +--- + +You can add query parameters to a compare URL to open a pull request with pre-populated fields. For pull request templates, see [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository). + +| Parameter | Purpose | Example | +| --- | --- | --- | +| `quick_pull` | Opens the "Open a pull request" page for the compared branches. | `https://github.com/octo-org/octo-repo/compare/main...my-branch?quick_pull=1` | +| `title` | Adds a pull request title. Use `+` for spaces. | `https://github.com/octo-org/octo-repo/compare/main...my-branch?quick_pull=1&labels=bug&title=Bug+fix` | +| `body` | Adds text to the pull request body. Use `+` for spaces. | `https://github.com/octo-org/octo-repo/compare/main...my-branch?quick_pull=1&title=Bug+fix&body=Describe+the+fix.` | +| `labels` | Adds one or more labels. Separate multiple labels with commas. | `https://github.com/octo-org/octo-repo/compare/main...my-branch?quick_pull=1&labels=help+wanted,bug` | +| `milestone` | Adds a milestone. Use `+` for spaces. | `https://github.com/octo-org/octo-repo/compare/main...my-branch?quick_pull=1&milestone=testing+milestones` | +| `assignees` | Assigns the pull request to one or more users. Separate multiple users with commas. | `https://github.com/octo-org/octo-repo/compare/main...my-branch?quick_pull=1&assignees=octocat` | +| `projects` | Adds the pull request to a project. | `https://github.com/octo-org/octo-repo/compare/main...my-branch?quick_pull=1&title=Bug+fix&projects=octo-org/1` | +| `template` | Adds a pull request template from a `PULL_REQUEST_TEMPLATE` subdirectory in the root, `docs/`, or `.github/` directory. | `https://github.com/octo-org/octo-repo/compare/main...my-branch?quick_pull=1&template=issue_template.md` | + +You must have permission to complete the equivalent action to use its query parameter. For example, you must have permission to add labels to use `labels`. See [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization). + +Invalid query parameters or insufficient permissions return a `404 Not Found` error. URLs that exceed the server limit return a `414 URI Too Long` error. diff --git a/content/pull-requests/reference/working-with-pre-receive-hooks.md b/content/pull-requests/reference/working-with-pre-receive-hooks.md new file mode 100644 index 000000000000..b9e90d06dceb --- /dev/null +++ b/content/pull-requests/reference/working-with-pre-receive-hooks.md @@ -0,0 +1,41 @@ +--- +title: Working with pre-receive hooks +intro: Enforce repository policies and prevent issues like secrets or invalid commits using pre-receive hooks on GitHub Enterprise Server. +redirect_from: + - /github/collaborating-with-issues-and-pull-requests/collaborating-on-repositories-with-code-quality-features/working-with-pre-receive-hooks + - /articles/working-with-pre-receive-hooks + - /github/collaborating-with-issues-and-pull-requests/working-with-pre-receive-hooks + - /github/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/working-with-pre-receive-hooks + - /pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/working-with-pre-receive-hooks + - /pull-requests/concepts/working-with-pre-receive-hooks +versions: + ghes: '*' +shortTitle: Pre-receive hooks +category: + - Merge and close pull requests +contentType: reference +--- + +Pre-receive hooks are scripts that run on {% data variables.product.prodname_ghe_server %} before Git accepts pushed commits. They enforce repository, organization, or enterprise policy at the point where code enters a repository. + +A pre-receive hook can check whether a push follows required rules. For example, a hook might block pushes that include secrets, use nonstandard commit messages, or change protected files. If the push passes the checks, Git accepts it. If the push fails, Git rejects it and shows an error message. + +If your push isn't accepted, you'll see an error message for the failed pre-receive hook. + +```shell +$ git push +Counting objects: 3, done. +Delta compression using up to 4 threads. +Compressing objects: 100% (2/2), done. +Writing objects: 100% (3/3), 916 bytes | 0 bytes/s, done. +Total 3 (delta 0), reused 0 (delta 0) +remote: always_reject.sh: failed with exit status 1 +remote: error: rejecting all pushes +To https://54.204.174.51/hodor/nope.git + ! [remote rejected] main -> main (pre-receive hook declined) +error: failed to push some refs to 'https://54.204.174.51/hodor/nope.git' +``` + +Pre-receive hooks matter because they apply rules consistently before changes reach the repository. This can reduce manual review burden and prevent policy violations from being stored in Git history. + +Your {% data variables.product.prodname_ghe_server %} site administrator creates and removes pre-receive hooks. They may also allow organization or repository administrators to enable or disable hooks for specific scopes. See [AUTOTITLE](/admin/enforcing-policies/enforcing-policy-with-pre-receive-hooks). diff --git a/content/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/setting-repository-visibility.md b/content/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/setting-repository-visibility.md index 6283c244e942..2acaea55749f 100644 --- a/content/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/setting-repository-visibility.md +++ b/content/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/setting-repository-visibility.md @@ -44,7 +44,7 @@ We recommend reviewing the following caveats before you change the visibility of * {% data variables.product.github %} will detach public forks of the public repository and put them into a new network. Public forks are not made private. {%- ifversion ghes or ghec %} -* If you change a repository's visibility from internal to private, {% data variables.product.github %} will remove forks that belong to any user without access to the newly private repository. The visibility of any forks will also change to private. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/what-happens-to-forks-when-a-repository-is-deleted-or-changes-visibility) +* If you change a repository's visibility from internal to private, {% data variables.product.github %} will remove forks that belong to any user without access to the newly private repository. The visibility of any forks will also change to private. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/about-permissions-and-visibility-of-forks#what-happens-to-forks-when-a-repository-is-deleted-or-changes-visibility) {%- endif %} {%- ifversion fpt %} * If you're using {% data variables.product.prodname_free_user %} for personal accounts or organizations, some features won't be available in the repository after you change the visibility to private. Any published {% data variables.product.prodname_pages %} site will be automatically unpublished. If you added a custom domain to the {% data variables.product.prodname_pages %} site, you should remove or update your DNS records before making the repository private, to avoid the risk of a domain takeover. For more information, see [AUTOTITLE](/get-started/learning-about-github/githubs-plans) and [AUTOTITLE](/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site). @@ -61,13 +61,13 @@ We recommend reviewing the following caveats before you change the visibility of ### Making a repository internal -* Any forks of the repository will remain in the repository network, and {% data variables.product.github %} maintains the relationship between the root repository and the fork. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/what-happens-to-forks-when-a-repository-is-deleted-or-changes-visibility) +* Any forks of the repository will remain in the repository network, and {% data variables.product.github %} maintains the relationship between the root repository and the fork. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/about-permissions-and-visibility-of-forks#what-happens-to-forks-when-a-repository-is-deleted-or-changes-visibility) {% endif %} ### Making a repository public -* {% data variables.product.github %} will detach private forks and turn them into a standalone private repository. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/what-happens-to-forks-when-a-repository-is-deleted-or-changes-visibility#changing-a-private-repository-to-a-public-repository){% ifversion fpt or ghec %} +* {% data variables.product.github %} will detach private forks and turn them into a standalone private repository. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/about-permissions-and-visibility-of-forks#changing-a-private-repository-to-a-public-repository){% ifversion fpt or ghec %} * If you're converting your private repository to a public repository as part of a move toward creating an open source project, see the [Open Source Guides](http://opensource.guide) for helpful tips and guidelines. You can also take a free course on managing an open source project with [{% data variables.product.prodname_learning %}]({% data variables.product.prodname_learning_link %}). Once your repository is public, you can also view your repository's community profile to see whether your project meets best practices for supporting contributors. For more information, see [AUTOTITLE](/communities/setting-up-your-project-for-healthy-contributions/about-community-profiles-for-public-repositories). * The repository will automatically gain access to {% data variables.product.prodname_GHAS %} features. * Actions history and logs will be visible to everyone. If your repository had reusable or required workflows that were shared from a different repository in your organization, the workflow file path including the repository name will be visible in the logs. For more information on how to remove workflow runs and artifacts see [AUTOTITLE](/actions/how-tos/manage-workflow-runs#deleting-logs) and [AUTOTITLE](/rest/actions/workflow-runs). diff --git a/data/reusables/code-quality/dismiss-irrelevant-findings.md b/data/reusables/code-quality/dismiss-irrelevant-findings.md deleted file mode 100644 index 32ee53002c5f..000000000000 --- a/data/reusables/code-quality/dismiss-irrelevant-findings.md +++ /dev/null @@ -1,7 +0,0 @@ -You can dismiss a finding if it isn’t relevant or actionable in the context of your codebase. Common reasons to dismiss a finding include: - -* The finding is in legacy code that’s no longer maintained. -* It’s a known exception to your team’s coding standards. -* It’s a false positive that doesn’t pose a real quality risk. - -Dismissing irrelevant alerts keeps your quality checks focused on meaningful issues. diff --git a/data/reusables/code-quality/fix-findings-with-copilot-autofix.md b/data/reusables/code-quality/fix-findings-with-copilot-autofix.md deleted file mode 100644 index 5eb0c961cd2d..000000000000 --- a/data/reusables/code-quality/fix-findings-with-copilot-autofix.md +++ /dev/null @@ -1,3 +0,0 @@ -Comments on the pull request include a suggested **autofix** that you can commit directly to your pull request. Carefully review the suggested autofix for logic, security, and style, then click **Commit suggestion**. - -You don't need a {% data variables.product.prodname_copilot_short %} license to apply these suggestions. diff --git a/data/reusables/code-quality/shared-workflow-preview.md b/data/reusables/code-quality/shared-workflow-preview.md deleted file mode 100644 index 16cb54d22753..000000000000 --- a/data/reusables/code-quality/shared-workflow-preview.md +++ /dev/null @@ -1 +0,0 @@ -During the {% data variables.release-phases.public_preview %}, {% data variables.product.prodname_code_quality_short %} uses the `{% data variables.code-quality.workflow_name_billing %}` workflow that is also used by {% data variables.product.prodname_code_scanning %}. diff --git a/data/reusables/copilot/create-managed-settings.md b/data/reusables/copilot/create-managed-settings.md deleted file mode 100644 index 16580384896a..000000000000 --- a/data/reusables/copilot/create-managed-settings.md +++ /dev/null @@ -1,3 +0,0 @@ -1. Create or update your enterprise managed settings file using your preferred deployment method. For a comparison of deployment methods, see [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/configure-enterprise-managed-settings#choosing-a-deployment-method). - - For server-managed deployment in a `.github-private` repository, create the file at `copilot/{% data variables.copilot.managed_setting_file %}`. The legacy path (`.github/copilot/settings.json`) is also supported. diff --git a/data/reusables/enterprise-onboarding/about-audit-logs.md b/data/reusables/enterprise-onboarding/about-audit-logs.md deleted file mode 100644 index 6b50fee9f55e..000000000000 --- a/data/reusables/enterprise-onboarding/about-audit-logs.md +++ /dev/null @@ -1,33 +0,0 @@ -## What are audit logs? - -> [!NOTE] -> {% data reusables.webhooks.webhooks-as-audit-log-alternative %} - -{% data reusables.audit_log.retention-periods %} - -{% data reusables.audit_log.audit-log-search-list-info-about-action %} - -{% ifversion ghes %}Site administrators can review the audit log for an instance, which contains a wider range of events including system administrative events. To access the instance-level audit log: - -{% data reusables.enterprise_site_admin_settings.access-settings %} -1. In the left menu, click **Audit log**.{% endif %} - -In addition to viewing your audit log, you can monitor activity in your enterprise in other ways, such as {% ifversion ghes %}viewing push logs and {% endif %}managing global webhooks. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/exploring-user-activity-in-your-enterprise). You can also use the audit log, and other tools, to monitor the actions taken in response to security alerts. For more information, see [AUTOTITLE](/code-security/concepts/security-at-scale/audit-security-alerts). - -## How to use audit logs - -As an enterprise owner{% ifversion ghes %} or site administrator{% endif %}, you can interact with the audit log data for your enterprise in several ways: -* You can view the audit log for your enterprise. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/accessing-the-audit-log-for-your-enterprise). -* You can search the audit log for specific events{% ifversion ghec %} and export audit log data{% endif %}. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/searching-the-audit-log-for-your-enterprise){% ifversion ghec %} and [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/exporting-audit-log-activity-for-your-enterprise){% endif %}. -* You can identify all events that were performed by a specific access token. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/identifying-audit-log-events-performed-by-an-access-token).{% ifversion ghes %} -* You can configure settings, such as the retention period for audit log events and whether Git events are included. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/configuring-the-audit-log-for-your-enterprise).{% endif %} -{%- ifversion enterprise-audit-log-ip-addresses %} -* You can display the IP address associated with events in the audit log. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/displaying-ip-addresses-in-the-audit-log-for-your-enterprise). -{%- endif %} -* You can stream audit and Git events data from {% data variables.product.prodname_dotcom %} to an external data management system. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/streaming-the-audit-log-for-your-enterprise). -{%- ifversion ghes %} -* You can forward audit and system logs, from your enterprise to an third-party hosted monitoring system. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/exploring-user-activity-in-your-enterprise/log-forwarding). -{%- endif %} -* You can use the Audit log API to view actions performed in your enterprise. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/using-the-audit-log-api-for-your-enterprise). - -For a full list of audit log actions that may appear in your enterprise audit log, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/audit-log-events-for-your-enterprise). diff --git a/data/reusables/enterprise-onboarding/about-policies.md b/data/reusables/enterprise-onboarding/about-policies.md deleted file mode 100644 index 2a3b779e7bed..000000000000 --- a/data/reusables/enterprise-onboarding/about-policies.md +++ /dev/null @@ -1,5 +0,0 @@ -To help you enforce business rules and regulatory compliance, policies provide a single point of management for all the organizations owned by an enterprise account. - -{% data reusables.enterprise.about-policies %} - -For example, with the "Base permissions" policy, you can allow organization owners to configure the "Base permissions" policy for their organization, or you can enforce a specific base permissions level, such as "Read", for all organizations within the enterprise. diff --git a/data/reusables/enterprise-onboarding/about-roles.md b/data/reusables/enterprise-onboarding/about-roles.md deleted file mode 100644 index 5a0764635164..000000000000 --- a/data/reusables/enterprise-onboarding/about-roles.md +++ /dev/null @@ -1,25 +0,0 @@ -## What are roles? - -Roles allow you to delegate administrative duties and manage access securely at every level of your enterprise. - -A role is a **set of permissions** that you can assign to individuals or teams. A permission is the ability to perform a specific action, such as changing billing settings. - -A user in an enterprise has roles for both the enterprise account and organizations where they have access. - -* The enterprise-level roles define the user's access to enterprise settings. -* Organization-level roles define the user's access to organization settings and repositories in an organization. - -## Predefined and custom roles - -Organization and enterprise roles can be **predefined** or **custom**. Enterprise custom roles are in {% data variables.release-phases.public_preview %}. - -* Predefined roles, such as enterprise owner, organization owner, or billing manager, are available for all accounts. They grant a predefined set of permissions to users or teams and may contain more permissions than someone needs to do their job. -* Custom roles include your choice of fine-grained permissions. They can include access to account settings and (for organization custom roles) repository access, allowing you to provide teams with just the access they need to do their jobs. For example, you could allow a team to view your enterprise's audit logs without allowing them to change any settings. - -To follow the principle of least privilege access, we recommend using custom roles if they allow for the permissions you require. However, not all capabilities of predefined roles can currently be replicated in custom roles. - -## Who manages roles? - -Enterprise owners can create custom enterprise roles and assign enterprise roles to users and teams. They can also create custom organization roles to be used across organizations, but these roles can only be assigned by organization owners. - -Organization owners can grant organization roles and create custom organization roles, but cannot edit roles or change role assignments that are defined at the enterprise level. diff --git a/data/reusables/enterprise-onboarding/about-teams.md b/data/reusables/enterprise-onboarding/about-teams.md deleted file mode 100644 index 1902cd7a839b..000000000000 --- a/data/reusables/enterprise-onboarding/about-teams.md +++ /dev/null @@ -1,68 +0,0 @@ -## What are teams? - -Teams are **groups of users** in an enterprise or organization. By creating teams, you can manage users at scale and simplify access, licensing, and communication. For example, you could create an auditor team for users who need access to audit logs{% ifversion copilot %}, or a {% data variables.product.prodname_copilot_short %} team for users who receive {% data variables.product.prodname_copilot_short %} licenses{% endif %}. - -**Enterprise teams** are managed at the enterprise level and can include users from across the enterprise and its organizations. With enterprise teams, you can centralize administration and manage organization access, roles, and licensing at scale. - -**Organization teams** are managed at the organization level and can only include members of a single organization. There are certain features of organization teams that are not currently supported for enterprise teams, such as CODEOWNER status. - -## Can I manage teams from an identity provider? - -{% ifversion ghes %}If you have enabled SCIM user provisioning on {% data variables.product.prodname_ghe_server %}{% else %}If you have integrated {% data variables.product.github %} with an identity provider (IdP){% endif %}, you can link teams on {% data variables.product.github %} with groups in your IdP. When membership of the IdP group changes, the change is reflected in the {% data variables.product.github %} team, allowing you to centralize access management. - -{% ifversion not ghes %} -The capabilities of this feature depend on whether you use {% data variables.product.prodname_emus %} or personal accounts. - -### {% data variables.product.prodname_emus %} - -{% endif %} - -You can make changes to IdP groups to manage repository access, add or remove users from organizations, or grant or remove {% data variables.product.prodname_copilot %} licenses. For example, if a new user is added to an IdP group that is linked to a team with access to an organization, the user receives access to that organization. For more information, see [AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/managing-team-memberships-with-identity-provider-groups). - -This feature is available with both enterprise and organization teams. - -{% ifversion not ghes %} - -### Personal accounts - -Team synchronization allows you to centrally manage any privileges linked to an organization team, such as repository access and CODEOWNER status. However, team sync cannot be used to add users to organizations where they don't already have access. For more information, see [AUTOTITLE](/admin/managing-iam/using-saml-for-enterprise-iam/managing-team-synchronization-for-organizations-in-your-enterprise). - -Team sync with personal accounts is only available with organization teams, and you must use Entra ID or Okta as an IdP. - -{% endif %} - -## What kind of team should I use? - -To simplify administration at scale, {% data variables.product.company_short %} recommends using enterprise teams for any use cases that apply to the enterprise account or to multiple organizations. Organization teams are useful when the need for the team is scoped to a single organization and the team can be managed by an organization administrator. - -You may need to create organization teams if the functionality you need is not covered by enterprise teams. The limitations listed below reflect the current capabilities of enterprise teams and may change over time. - -{% data reusables.enterprise.enterprise-teams-can %} - -{%- ifversion enterprise-teams-ga %} - -To @-mention an enterprise team, or request a review from the team, use the team's slug in the format `@/ent:TEAM-SLUG`. {% data variables.product.github %} generates the slug from the team's name and adds the `ent:` prefix, so an enterprise team named `Platform SRE` has the slug `ent:platform-sre`. - -To mention the team from an organization it is assigned to, such as `octo-org`, use `@octo-org/ent:platform-sre`. You can mention an enterprise team from any organization the team is assigned to. - -{%- endif %} - -However, unlike organization teams, enterprise teams currently do **not** support: - -{%- ifversion enterprise-teams-ga %} -{%- else %} -* `@-mentions` of the team name in organizations -* Review requests of the team in pull requests -{%- endif %} -* Adding the team to a project board -{%- ifversion not ghes %} -* Team sync if you use {% data variables.product.prodname_ghe_cloud %} with personal accounts -{%- endif %} -* CODEOWNER status -* Secret teams -* Nested teams -* Team maintainers - -{% data reusables.enterprise.enterprise-teams-limits %} - -For more information about the capabilities of organization teams, see [AUTOTITLE](/organizations/organizing-members-into-teams/about-teams). diff --git a/data/reusables/enterprise-onboarding/assign-roles.md b/data/reusables/enterprise-onboarding/assign-roles.md deleted file mode 100644 index cb8cdc8080b2..000000000000 --- a/data/reusables/enterprise-onboarding/assign-roles.md +++ /dev/null @@ -1,41 +0,0 @@ -Enterprise owners can assign custom and predefined **enterprise roles** to users and teams. Some roles can be assigned to enterprise teams, whereas other roles are only available for individual users. Find the section below for the role you want to assign. - -For more information about using roles effectively, see [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-roles-in-your-enterprise/identify-role-requirements). - -## Assigning app managers, security managers, and custom roles - ->[!NOTE] These roles are in public preview and subject to change. - -These roles can be assigned to existing users and teams in your enterprise settings, including {% ifversion ghes %}users whose accounts were provisioned with SCIM{% else %}{% data variables.enterprise.prodname_managed_users %}{% endif %}. - -Before you assign a role, you may need to create a team. Teams are the best way to manage role assignments at scale. The enterprise security manager role can **only** be assigned to a team, not to individual users. See [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/create-enterprise-teams). - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.people-tab %} -1. In the left sidebar, click **{% octicon "globe" aria-hidden="true" aria-label="globe" %} Enterprise roles**, then click **Role assignments**. -1. Click **Assign role**. -1. Choose the user or team and the role they should receive, then click **Assign role**. - -## Assigning enterprise owners{% ifversion not ghes %}, billing managers, and guest collaborators{% endif %} - -{% ifversion ghes %}This role{% else %}These roles{% endif %}: - -* Can be chosen when you invite a user to your enterprise or provision a user from your identity provider (IdP) -* Cannot currently be assigned to enterprise teams -* Can be changed for existing users - -### Assigning to new users - -* If you {% ifversion ghes %}have enabled SCIM provisioning{% else %}use **{% data variables.product.prodname_emus %}**{% endif %}, roles are assigned from your IdP via the SCIM `roles` attribute. -* Otherwise, you can invite someone as {% ifversion ghes %}an enterprise owner. See {% else %}a user or administrator. See [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/invite-users-directly) or {% endif %}[AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/inviting-people-to-manage-your-enterprise). - -### Assigning to existing administrators - -You can change an administrator's role or convert them to a regular member once they have joined your enterprise. - -* If you {% ifversion ghes %}provisioned the user via SCIM{% else %}use **{% data variables.product.prodname_emus %}**{% endif %}, you must do this from your IdP via the SCIM `roles` attribute. -* {% ifversion ghes %}For all other accounts{% else %}If you use an **enterprise with personal accounts**{% endif %}, you can change the role on your enterprise's "Administrators" page, using the **{% octicon "kebab-horizontal" aria-label="Administrator" %}** menu next to the user's name. See [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/viewing-people-in-your-enterprise#viewing-enterprise-administrators). - -## Assigning roles in an organization - -Enterprise owners cannot assign organization-level roles from the enterprise settings. An organization administrator must do this. See [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/using-organization-roles#assigning-an-organization-role). diff --git a/data/reusables/enterprise-onboarding/automations.md b/data/reusables/enterprise-onboarding/automations.md deleted file mode 100644 index e7d8b700fdc4..000000000000 --- a/data/reusables/enterprise-onboarding/automations.md +++ /dev/null @@ -1,119 +0,0 @@ -Automation on {% data variables.product.github %} typically involves multiple components working together. The most important {% data variables.product.github %} native components are: - -* **{% data variables.product.prodname_actions %} workflows**, which provide a runtime for executing automation logic. Out of the box, they work within a single repository, but they can be extended to automate across or even outside of repositories. -* **{% data variables.product.prodname_github_apps %}**, which do not have a runtime. Instead, they provide identity, permissions, and event delivery so your automations, whether external services or workflows, can authenticate and act securely. - -Most enterprise automation use {% data variables.product.prodname_github_apps %} and {% data variables.product.prodname_actions %} together. For example, a workflow running in {% data variables.product.prodname_actions %} may use a {% data variables.product.prodname_github_app %} to obtain a short-lived token that allows it to perform tasks across repositories or organizations. - -This guide explains how {% data variables.product.prodname_github_apps %}, external automations, and {% data variables.product.prodname_actions %} complement each other, and when to use each in your enterprise. - -## {% data variables.product.prodname_github_apps %} - -A {% data variables.product.prodname_github_app %} provides the **identity, permissions, and webhook events** required for automation on or across repositories, organizations, or your enterprise. {% data variables.product.prodname_github_apps %} themselves do **not** execute logic, they enable other systems to do so. - -{% data variables.product.prodname_github_apps %} support enterprise automation by offering: - -* **Granular permissions** to follow least-privilege principles -* **Scoped installations** at the enterprise, organization, or repository level -* **Short-lived tokens** for secure access -* **Distinct identities** with full auditability -* **Delegated administration** through the {% data variables.product.prodname_github_app %} manager role -* **Consistency at scale** when owned by the enterprise account - -### What do {% data variables.product.prodname_github_apps %} enable? - -{% data variables.product.prodname_github_apps %} allow **automations you write elsewhere**—such as external services or workflow steps—to act on {% data variables.product.github %} APIs within the permissions you grant. For example: - -* Receiving webhook events and triggering external services -* Enabling a workflow to act outside its default repository scope -* Integrating {% data variables.product.github %} with third-party systems -* Coordinating changes across many repositories -* Running long-lived bots or services that monitor enterprise-level activity - -{% ifversion enterprise-installed-apps %} - -> [!NOTE] -> Enterprise-installed {% data variables.product.prodname_github_apps %} cannot call every API endpoint. See [AUTOTITLE](/apps/using-github-apps/installing-a-github-app-on-your-enterprise#what-enterprise-installed-apps-can-do). - -{% endif %} - -## {% data variables.product.prodname_actions %} - -{% data variables.product.prodname_actions %} provide {% data variables.product.github %}’s built-in **runtime** for executing automation logic inside repositories. Workflows run on hosted or self-hosted runners and are ideal for tasks tied to code changes or repository events. - -Use {% data variables.product.prodname_actions %} for: - -* CI/CD (build, test, deploy) -* Pull request checks and validations -* Repository-level maintenance tasks -* Event-driven workflows responding to pushes, tags, or issue updates -* Scheduled jobs with cron - -### How {% data variables.product.prodname_actions %} uses {% data variables.product.prodname_github_apps %} - -{% data variables.product.prodname_actions %} and {% data variables.product.prodname_github_apps %} are deeply connected: - -* Workflow permissions map directly to {% data variables.product.prodname_github_app %} permissions. -* Workflows can authenticate as a specific {% data variables.product.prodname_github_app %} using `actions/create-github-app-token`. -* {% data variables.product.prodname_github_apps %} can trigger workflows through events such as `repository_dispatch`. - -## External automations and services - -External automations run outside {% data variables.product.github %} on your own infrastructure. These services typically: - -* Receive webhook events from a {% data variables.product.prodname_github_app %} -* Use the {% data variables.product.prodname_github_app %} to request short-lived installation tokens -* Execute long-running or cross-enterprise logic -* Integrate with external business systems - -Examples include: - -* Organization-wide configuration management -* Policy enforcement services -* Multi-repository code or metadata synchronization -* Compliance report generation -* Cross-organization issue or pull request management - -All of these rely on {% data variables.product.prodname_github_apps %} for authentication, identity, and events—**not** for execution. - -## How these components work together - -Most enterprise automation uses a combination of {% data variables.product.prodname_github_apps %}, external services, and {% data variables.product.prodname_actions %} to achieve robust, scalable workflows. - -For example: - -1. An enterprise {% data variables.product.prodname_github_app %} receives a webhook when a new repository is created, and sends the webhook payload to a server where an external service is running. -1. The external service standardizes required settings and provisions resources. -1. The service triggers a {% data variables.product.prodname_actions %} workflow in the repository. -1. The workflow performs CI, deploys templates, or configures scanning. - -Each component handles a different layer of automation. - -## When to use each type of automation - -Use **a {% data variables.product.prodname_github_app %}** when you need: - -* Authentication or permission to act across many repositories -* Integration with external systems -* Webhook-driven automations -* Long-lived or enterprise-wide workflows -* Auditability and identity separation - -Use **external automations** when you need: - -* Logic that runs continuously or outside {% data variables.product.github %} -* Integration with internal systems - -Use **{% data variables.product.prodname_actions %}** when you need: - -* CI/CD pipelines -* Repository-scoped automation -* Automated checks tied to repository events -* Execution of logic using {% data variables.product.github %}’s runner infrastructure - -Use **{% data variables.product.prodname_github_apps %} and {% data variables.product.prodname_actions %} together** when: - -* A workflow must act beyond the repository’s default permissions -* A {% data variables.product.prodname_github_app %} needs to trigger a workflow -* External logic orchestrates in-repo execution -* Enterprise-wide policies or workflows require both identity and runtime diff --git a/data/reusables/enterprise-onboarding/best-practices.md b/data/reusables/enterprise-onboarding/best-practices.md deleted file mode 100644 index 045f4243e618..000000000000 --- a/data/reusables/enterprise-onboarding/best-practices.md +++ /dev/null @@ -1,35 +0,0 @@ -## Use organizations for work or governance - -There are two main models of using organizations: - -* **Group related work projects**: Group repositories for a specific application and related services. Teams that work on that application will then be able to communicate effectively and contribute across the different repositories. -* **Group similar governance requirements**: Group repositories that require similar policies, security settings, or access restrictions. You will be able to apply the necessary settings to the organization at scale. For example, if you have highly confidential work projects or a specific data classification, group these in an organization where only a limited number of people have access. - -## Create organizations intentionally - -Creating organizations is a balance. While {% data variables.product.company_short %} continues to make organization management more scalable, you should be intentional about why you create an organization. It's always easier to add organizations than to remove them. - -Don't try to fit unnatural pieces of your company together into a single large organization. The administrative features of an enterprise account allow you to automate processes, manage access, and apply policies across multiple organizations at once. However, there are tradeoffs of segregating work into many different organizations: - -* It's easier for people to communicate within one organization, as @-mentions only work between members of the same organization. -* It's easier for people to find resources in one organization, as there's only one place to search. - -You may want to start with a small number of organizations as you develop your strategy. After you build confidence in what works well for your business, you can create additional organizations as the need arises. - -You should regularly evaluate your strategies for access, governance, and organization of work. Cleaning up legacy organizations is a part of that process. - -{% ifversion enterprise-teams %} - -## Use teams to organize people - -Enterprise teams are the best way to control access and permissions at scale. Create teams and manage their membership as your primary means of performing actions like adding users to organizations, granting licenses, and delegating access to enterprise settings. - -When you use teams in this way, controlling membership of teams is a sensitive action. Limit the permission to control teams and their membership to a small number of people. If you use an external identity provider (IdP), sync teams to IdP groups so that team membership can be controlled by a central administrator. - -Use roles to delegate administrative duties to teams. This allows you to limit the number of enterprise owners in your company and give people just the permissions they need to do their jobs effectively. For example, a team of auditors can receive access to the enterprise audit log without being able to access any other settings. - -{% endif %} - -## Collaborate in organization-owned repositories - -We recommend collaborating in organization-owned repositories whenever possible and minimizing collaboration in user-owned repositories. Organization-owned repositories have more sophisticated security and administrative features, and they remain accessible even as enterprise membership changes. diff --git a/data/reusables/enterprise-onboarding/create-custom-roles.md b/data/reusables/enterprise-onboarding/create-custom-roles.md deleted file mode 100644 index 50442b812e2e..000000000000 --- a/data/reusables/enterprise-onboarding/create-custom-roles.md +++ /dev/null @@ -1,30 +0,0 @@ -To tailor access management to your company's needs, you can create custom roles for your{% ifversion enterprise-custom-roles %} enterprise account and{% endif %} organizations. - -Custom roles are sets of permissions for settings and resources that you can assign to users and teams.{% ifversion enterprise-custom-roles %} To learn best practices for using roles on {% data variables.product.github %}, see [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-roles-in-your-enterprise/identify-role-requirements).{% endif %} - -{% ifversion enterprise-custom-roles %} - -## Creating enterprise custom roles - ->[!NOTE] This feature is in {% data variables.release-phases.public_preview %} and subject to change. - -Enterprise custom roles grant access to a subset of enterprise settings, such as viewing audit logs and creating organizations. {% data variables.product.github %} plans to expand the list of available permissions over time. - -{% data reusables.enterprise-accounts.start-creating-custom-role %} -1. Enter the details, then click **Create role**. - -{% endif %} - -## Creating organization custom roles - -Organization custom roles grant access to organization settings and repositories. Custom organization roles created at the enterprise level use the same permissions and base roles as roles created at the organization level. For more information, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/permissions-of-custom-organization-roles). - -Enterprise owners can create and edit custom organization roles, but cannot assign them. Organization owners can assign custom roles in an organization. - ->[!NOTE] An enterprise can create up to 20 custom organization roles. This limit applies to the enterprise: each organization can also create up to 20 custom organization roles. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.people-tab %} -1. In the left sidebar, select **Organization roles**. -1. Click **Create custom role**. -1. Enter the details, then click **Create role**. diff --git a/data/reusables/enterprise-onboarding/create-enterprise-apps.md b/data/reusables/enterprise-onboarding/create-enterprise-apps.md deleted file mode 100644 index d84e825c0ff3..000000000000 --- a/data/reusables/enterprise-onboarding/create-enterprise-apps.md +++ /dev/null @@ -1,38 +0,0 @@ -You can create a {% data variables.product.prodname_github_app %} under your enterprise account. The app can only be installed on{% ifversion enterprise-installed-apps %} your enterprise or{% endif %} organizations within your enterprise, and can only be authorized by members of your enterprise. The app can't be installed on user accounts. - -## Step 1: Registering a {% data variables.product.prodname_github_app %} - -To create a {% data variables.product.prodname_github_app %}, you must first register the app. See [AUTOTITLE](/apps/creating-github-apps/registering-a-github-app/registering-a-github-app). - -Apps can also be transferred to an enterprise from a member or organization. To transfer an app, see [AUTOTITLE](/apps/maintaining-github-apps/transferring-ownership-of-a-github-app). -{%- ifversion enterprise-app-manager %} - -### Step 1a: Adding an enterprise app manager - -Enterprise owners can add enterprise members to an app as an app manager. App managers can manage the app's settings and credentials, but cannot install the app. For more information, see [AUTOTITLE](/apps/maintaining-github-apps/about-github-app-managers).{% endif %} - -## Step 2: Building a {% data variables.product.prodname_github_app %} - -After registering a {% data variables.product.prodname_github_app %}, you will want to write code to make your {% data variables.product.prodname_github_app %} do something. For examples of how to write code, see: - -* [AUTOTITLE](/apps/creating-github-apps/writing-code-for-a-github-app/quickstart) -* [AUTOTITLE](/apps/creating-github-apps/writing-code-for-a-github-app/building-a-github-app-that-responds-to-webhook-events) -* [AUTOTITLE](/apps/creating-github-apps/writing-code-for-a-github-app/building-a-login-with-github-button-with-a-github-app) -* [AUTOTITLE](/apps/creating-github-apps/writing-code-for-a-github-app/building-a-cli-with-a-github-app) -* [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow) - -You should aim to follow best practices. See [AUTOTITLE](/apps/creating-github-apps/about-creating-github-apps/best-practices-for-creating-a-github-app). - -## Step 3: Authorizing or installing your {% data variables.product.prodname_github_app %} - -Once your {% data variables.product.prodname_github_app %} is registered, you'll need to make it available for use, either through **authorization** or **installation**, depending on the app’s purpose. - -Enterprise owners {% ifversion enterprise-app-manager %}and app managers {% endif %}can modify the permissions for apps owned by their enterprise at any time. Permissions changes will be automatically accepted by organizations in the enterprise{% ifversion enterprise-app-manager %} if the change was made by the enterprise owner. Otherwise, the changes will be accepted only where the app manager is also an organization owner, and an organization owner must accept the update request for all other organizations{% endif %}. - -### Step 3a: Authorizing your {% data variables.product.prodname_github_app %} - -Some {% data variables.product.prodname_github_apps %}, like {% data variables.product.prodname_copilot_short %} extensions, require **authorization** but do not need to be installed on an organization. Users in your enterprise can authorize the app to access resources within organizations. However, the app will only have access to {% data variables.product.github %} resources where it is installed. See [AUTOTITLE](/apps/using-github-apps/authorizing-github-apps). - -### Step 3b: Sharing your {% data variables.product.prodname_github_app %} via an installation link - -For apps that require installation to function, you can provide organization owners with an installation link. Once the app is installed, it will have access to the organization's resources. See [AUTOTITLE](/apps/sharing-github-apps/sharing-your-github-app#sharing-your-github-app-via-an-install-link). diff --git a/data/reusables/enterprise-onboarding/create-enterprise-teams.md b/data/reusables/enterprise-onboarding/create-enterprise-teams.md deleted file mode 100644 index 4dc2ff204495..000000000000 --- a/data/reusables/enterprise-onboarding/create-enterprise-teams.md +++ /dev/null @@ -1,57 +0,0 @@ -## 1. Navigate to the enterprise teams page - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.people-tab %} -1. In the left sidebar, click **{% octicon "people" aria-hidden="true" aria-label="people" %} Enterprise teams**. - -## 2. Create a team - -1. On the enterprise teams page, click **Create Enterprise team**. -1. Choose the team's name, description, and organization access. - - When you give a team access to organizations, members of the team are added directly to those organizations, without an invitation, and receive the same access as other organization members. - - * Outside collaborators{% ifversion not ghes %} and unaffiliated users{% endif %} in the team become standard enterprise members, meaning they have access to your enterprise's internal repositories{% ifversion not ghes %} and consume a {% data variables.product.prodname_enterprise %} license{% endif %}. - * Team members receive the base level of repository permissions for the organization. - * Organization administrators can give the team additional repository access and assign them organization-level roles, but **cannot** remove any permissions granted by enterprise administrators. - -1. Click **Create Enterprise team**. - -## 3. Add users - -There are multiple ways to add users to an enterprise team. - -* [Adding users manually](#adding-users-manually) -* [Syncing with an IdP group](#syncing-with-an-idp-group) ({% data variables.product.prodname_emus %} only) -* Using the [AUTOTITLE](/rest/enterprise-teams/enterprise-team-members) - -{% ifversion ghec %} -Enterprise teams can contain organization members, unaffiliated users, and outside collaborators. -{% endif %} - -### Adding users manually - -1. On the enterprise teams page, click the team you want to add users to. -1. Click **Add members**, then search for and select the users you want to add. -1. Click **Add**. - -### Syncing with an IdP group - -If you {% ifversion ghes %}have enabled SCIM on {% data variables.product.prodname_ghe_server %}{% else %}use {% data variables.product.prodname_emus %}{% endif %}, you can sync membership of an enterprise team to a group in your identity provider. That way, any changes made to the group in the IdP (such as adding or removing a user) will be synced to the enterprise team via SCIM. For details and requirements, see [AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/managing-team-memberships-with-identity-provider-groups). - -1. On the enterprise teams page, click the team you want to sync. -1. Ensure the team contains no manually assigned users. You can remove users by using the **{% octicon "kebab-horizontal" aria-hidden="true" aria-label="More member actions" %}** menu next to the user's name in the member list. -1. Next to the team's name, click **{% octicon "pencil" aria-hidden="true" aria-label="pencil" %} Edit**. -1. Under "Manage members", click **Identity provider group**. -1. Click **Select group**, then choose the external IdP group to sync to the team. Members from the IdP group will display in the team's member list. -1. Click **Update team**. - -#### Limits on IdP group sizes - -If an IdP group goes over the team size limit of 5,000 users, the team will stop being synced. - -For example: - -* An enterprise team is initially synced with an IdP group of 5 users. -* 5,000 more users are added to the IdP group. Because the IdP group now has 5,005 users, the group isn't synced and the enterprise team remains at 5 members. -* 5 users are removed from the IdP group to bring it to 5,000 users. Syncing resumes and the enterprise team now contains the same 5,000 users as the IdP group. diff --git a/data/reusables/enterprise-onboarding/creating-custom-properties.md b/data/reusables/enterprise-onboarding/creating-custom-properties.md deleted file mode 100644 index d090a71424ff..000000000000 --- a/data/reusables/enterprise-onboarding/creating-custom-properties.md +++ /dev/null @@ -1,32 +0,0 @@ -Custom properties allow you to decorate your repositories with information such as compliance frameworks, data sensitivity, or project details. Custom properties are private and can only be viewed by people with read permissions to the repository. An enterprise can have up to 100 property definitions. An allowed value list can have up to 200 items. - -Defining custom properties at the enterprise level allows you to create consistent values that users can apply to repositories. With custom properties in place, you can apply consistent governance across repositories in your enterprise by creating a ruleset or repository policy targeting repositories with certain properties. - -## Allowed characters - -{% data reusables.repositories.custom-property-allowed-characters %} - -## Who can set and view values for custom properties I define? - -After you define a custom property, users can set a value for that property in repositories in the enterprise. See [AUTOTITLE](/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization#setting-values-for-repositories-in-your-organization). - -* As an enterprise owner, you can set a default value for required properties. -* Organization owners can set values in their organization, either across repositories or at the repository level. -* If enabled, people with repository access, or the `custom properties` fine-grained permission, can set and update the property value for their repository. - -People with read permissions to a repository can view the custom property values for that repository. - -Additionally, organization owners can search for repositories in their organization by custom property values. See [AUTOTITLE](/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization#searching-and-filtering-repositories-by-custom-property-values). - -## Adding custom properties - -You can add custom properties to your enterprise to make those properties available in all of your organizations. - -{% data reusables.enterprise-accounts.access-enterprise %} -1. In the left sidebar, under "Policies", click **Custom properties**. -1. To add a new custom property, in the upper-right corner, click **New property**. -1. Enter a name, description, and type for the custom property. The name must be unique across all of your organizations, can't contain spaces, and cannot exceed 75 characters in length. -1. Optionally, select **Allow repository actors to set this property**. When enabled, repository users and apps with the repository-level `custom properties` fine-grained permission will be able to set and update the property value for their repository. Additionally, any actor creating a repository can set the property on the repository. -1. Optionally, select **Require this property for all repositories** and add a default value. This means that you require that all repositories in your enterprise have a value for this property. Repositories that don’t have an explicit value for this property will inherit the default value. -{% data reusables.organizations.custom-properties-required-values %} -1. Click **Save property**. diff --git a/data/reusables/enterprise-onboarding/identify-role-requirements.md b/data/reusables/enterprise-onboarding/identify-role-requirements.md deleted file mode 100644 index 1cfd2ff15415..000000000000 --- a/data/reusables/enterprise-onboarding/identify-role-requirements.md +++ /dev/null @@ -1,73 +0,0 @@ -Roles control people's access to settings and resources in your enterprise and organizations. For an introduction to roles, see [AUTOTITLE](/admin/concepts/enterprise-fundamentals/roles-in-an-enterprise). - -By using roles effectively, you can: - -* Delegate administrative duties and manage access securely at every level of your enterprise. -* Harden security by reducing the number of people with blanket administrative access in your enterprise. -* Ensure everyone has the permissions they need to be independent and productive. - -## 1. Review available roles and permissions - -This guide helps you understand best practices for roles, so you can plan which roles are required in your enterprise and organizations. You will then be able to create a team structure that uses roles effectively. - -As you think about tasks that would benefit from a specific role, refer to the available predefined roles and custom permissions to see if a granular role for this task is currently possible. If not, you will need to rely on a role with more blanket access, such as enterprise owner. - ->[!NOTE] Enterprise custom roles currently only cover a limited subset of enterprise settings, but {% data variables.product.company_short %} plans to expand the list of permissions over time. - -| Role type | More information | -| --------- | ---------------- | -| Predefined enterprise roles | [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-roles-in-your-enterprise/abilities-of-roles) | -| Predefined organization roles | [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization) | -| Custom enterprise roles | Review the list of available permissions at `{% data variables.product.product_url %}/enterprises/ENTERPRISE/enterprise_roles/new`, where ENTERPRISE is the name of your enterprise account. | -| Custom organization roles | [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/permissions-of-custom-organization-roles) | - -## 2. Identify two owners per account - -Decide who will serve as enterprise owners and organization owners. The "owner" role has full administrative access to an enterprise or organization account. - -We recommend having at least two owners per account. Although it is good practice to limit the number of people with this level of access, if an account only has one owner, the account's resources can become inaccessible if the owner is unreachable. - -## 3. Identify roles for administrative duties - -Identify predefined or custom roles that will help you delegate time-consuming administrative duties to other teams. This will help enterprise owners to focus on urgent or strategic work. - -It is unlikely that you can granularly assign every administrative duty in your enterprise to a specific team, so we recommend focusing on the most frequent and time-consuming tasks. Some examples of how you might use roles to delegate common tasks are: - -* **Auditing**: Use a custom role to give a team access to your audit logs without allowing them to access any other settings. -* **Authentication**: Use a custom role to give your identity provider administrators permission to manage SSO settings on {% data variables.product.github %}, so they can configure authentication independently. -{%- ifversion ent-security-manager %} -* **Security**: Use the enterprise security manager role to give security teams access to alerts and security data across the enterprise and organizations. -{%- endif %} - -Some administrative tasks are more sensitive than others. For example, if your enterprise uses enterprise teams to manage licensing, access, and roles, then being able to change membership of a team is a powerful action that you may want to restrict to a small group of people. - -## 4. Identify base permissions for non-administrators - -Consider if there are permissions that every member of your enterprise would benefit from. These can be added to a custom role that you assign to everyone. - -For example, regular users have limited visibility of your enterprise account by default. If you want more transparency, you may want to allow all employees to: - -* View other enterprise members and administrators so they know where to go for help -* View audit logs to see what people are doing in the enterprise - -## 5. Delegate work to apps - -Not all tasks are best-suited to humans. Identify frequent, time-consuming, and easily automated tasks, and plan to delegate these tasks to {% data variables.product.prodname_github_apps %}. - -{% data variables.product.prodname_github_apps %} provide scoped tokens for use in scripts and workflows. Although they use a different permissions system from the roles you assign to users, you can think about apps like humans with a role on {% data variables.product.github %}: - -* They have fine-grained permissions for specific tasks. -* They have scoped access to specific repositories and accounts. -* They have their own identity, which you can trace in audit logs. - -For more information about what apps can do, see [AUTOTITLE](/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps#understanding-what-type-of-github-app-to-build). - -{% ifversion copilot %} - -## 6. Assign tasks to agents - -Another way to delegate frequent, time-consuming tasks is to assign work to {% data variables.copilot.copilot_cloud_agent %}. You can define custom agents for specific roles in your enterprise. Custom agents are created using Markdown files called "agent profiles," which define the instructions and tools the agent needs to perform a task. For example, you could create a {% data variables.copilot.copilot_custom_agent_short %} for writing README files or generating unit tests. - -For more information, see [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/prepare-for-custom-agents). - -{% endif %} diff --git a/data/reusables/enterprise-onboarding/install-enterprise-apps.md b/data/reusables/enterprise-onboarding/install-enterprise-apps.md deleted file mode 100644 index 0519d4a611ee..000000000000 --- a/data/reusables/enterprise-onboarding/install-enterprise-apps.md +++ /dev/null @@ -1,59 +0,0 @@ -> [!NOTE] -> Enterprise-installed {% data variables.product.prodname_github_apps %} are in {% data variables.release-phases.public_preview %} and subject to change. - -## About installing {% data variables.product.prodname_github_apps %} on your enterprise - -Enterprise-installed {% data variables.product.prodname_github_apps %} are apps that request enterprise-level permissions and can perform operations on your enterprise account. Unlike organization or user installations, they do not have access to any organization or repository permissions—they only manage the enterprise itself. - -When an enterprise owner installs a {% data variables.product.prodname_github_app %} on your enterprise, the app will be granted the enterprise permissions it requested. These permissions allow the app to perform operations such as creating organizations in the enterprise, installing applications across organizations, and managing SCIM provisioning. - -## Requirements to install a {% data variables.product.prodname_github_app %} on your enterprise - -The {% data variables.product.prodname_github_app %} must request enterprise-level permissions. It can request other permissions as well, but only the enterprise permissions will be granted during installation. - -The app must be owned by your enterprise or an organization within your enterprise. You cannot install apps owned by an account outside your enterprise. - -## Installing a {% data variables.product.prodname_github_app %} on your enterprise - -To install an app on your enterprise, navigate to the {% data variables.product.prodname_github_app %} installation page. This may be provided by the app developer as an installation link, or you can find it in the app's registration. The URL will look something like `{% data variables.product.oauth_host_code %}/apps/APP-NAME/installations/new`, where `APP-NAME` is the name of the {% data variables.product.prodname_github_app %}. - -If the app can be installed, the list of available installation locations will include your enterprise. You can select your enterprise to install the app. - -After installation, the app will be able to create an installation token for your enterprise or sign in enterprise members in order to act on their behalf at the enterprise level. Acting on a user's behalf requires the user to be able to perform the desired operations within the enterprise. For example, if the app needs to invite a user to an enterprise, the user must have permission to invite members to the enterprise as well. - -## What enterprise-installed apps can do - -Enterprise-installed {% data variables.product.prodname_github_apps %} cannot call every enterprise API, but several APIs have already been updated to support GitHub Apps. These APIs and GraphQL mutations include: - -* [List and create organizations in your enterprise](/graphql/reference/enterprise-admin#mutation-createenterpriseorganization) -* [Manage users in your enterprise](/graphql/reference#enterprise) -* Create and manage {% data variables.product.prodname_github_app %} installations in your organizations -* Manage enterprise custom repository properties -* Call the enterprise SCIM APIs - -Check the [changelog](https://github.blog/changelog/) for updates on new APIs and permissions for {% data variables.product.prodname_github_apps %}. - -For more information about available permissions and API endpoints, see [AUTOTITLE](/rest/authentication/permissions-required-for-github-apps). - -{% ifversion not ghes %} - -## Rate limits for enterprise-installed {% data variables.product.prodname_github_apps %} - -The installation token for an enterprise-installed {% data variables.product.prodname_github_apps %} has the same rate limit as a {% data variables.product.prodname_ghe_cloud %} organization. Rate limits are per installation. For example, if an app is installed on an enterprise and two organizations, it will require 3 installation tokens to access them and have a full, independent rate limit budget for each installation. For more information, see [AUTOTITLE](/rest/using-the-rest-api/rate-limits-for-the-rest-api) and [AUTOTITLE](/graphql/overview/rate-limits-and-query-limits-for-the-graphql-api). -{% endif %} - -## Current limitations - -Enterprise-installed {% data variables.product.prodname_github_apps %} are currently in {% data variables.release-phases.public_preview %} with the following limitations. - -### API support - -Not all APIs support enterprise-installed {% data variables.product.prodname_github_apps %} yet. As more permissions are built and APIs updated, support will become broader. For more information about the APIs and permissions that support enterprise-installed {% data variables.product.prodname_github_apps %}, see [AUTOTITLE](/rest/authentication/permissions-required-for-github-apps). - -### Webhook support - -Enterprise installations do not currently support webhooks. Apps installed at the enterprise level cannot receive webhook events for enterprise-level activities. Install them on organizations or repositories to receive webhook events for those resources. - -### Organization access - -Enterprise installations are not granted access to organizations or repositories within your enterprise, with the exception of the organization installations API. To access organization or repository resources, you must install the app separately on each organization where access is needed. diff --git a/data/reusables/enterprise-onboarding/use-innersource.md b/data/reusables/enterprise-onboarding/use-innersource.md deleted file mode 100644 index 51ef77ecbcc5..000000000000 --- a/data/reusables/enterprise-onboarding/use-innersource.md +++ /dev/null @@ -1,52 +0,0 @@ -You can use innersource practices to drive collaboration and productivity in your enterprise. Innersource makes it easy for all employees to discover and reuse work. This allows development teams to learn from each other's work, share their expertise, and avoid duplicating effort to recreate common services. - -## Make repositories discoverable - -Unless they contain sensitive information, you should aim to make repositories visible to all employees. - -To do this, encourage employees to use **internal** visibility whenever possible. Internal visibility allows any member of any organization in the enterprise to view the repository, regardless of whether the user is a member of the organization that owns the repository. - -You should also set permissive **base permissions** for organizations. An organization's base permission policy determines the default level of access that members of that organization have to all the organization's repositories. Generally, organizations should have at least a "Read" base permission so that all organization members can see any repository. Organization owners can then use teams to grant people greater levels of access in specific repositories. - -If you have more sensitive repositories that should not be widely visible, you can set up a dedicated organization with a more restrictive base permission and add specific teams to this organization. - -For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/about-repositories#about-internal-repositories) and [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/setting-base-permissions-for-an-organization). - -## Document projects - -Organize and document your repositories so that people can search for work across the enterprise. - -Repository **READMEs** are effective because they're defined in files in the repository, so users can search for them like code. You can also create READMEs at the level of an organization or enterprise account to provide a higher-level overview of where to find different projects. For more formal internal documentation, consider setting up a **{% data variables.product.prodname_pages %} site** or **wikis**. - -You can use **repository topics** to group repositories that contain a certain programming language, are owned by a certain team, and so on. This is another way of making repositories easier to find. - -For more information, see: - -* [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes), [AUTOTITLE](/organizations/collaborating-with-groups-in-organizations/customizing-your-organizations-profile#adding-a-member-only-organization-profile-readme), and [AUTOTITLE](/admin/managing-your-enterprise-account/creating-a-readme-for-an-enterprise) -* [AUTOTITLE](/pages/getting-started-with-github-pages/creating-a-github-pages-site) -* [AUTOTITLE](/communities/documenting-your-project-with-wikis/adding-or-editing-wiki-pages) -* [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics) - -## Set up a culture for sharing work - -Encourage teams to publicize their work and share resources with other teams. {% data variables.product.github %} has a number of features that make this easier. For example, teams can: - -* Use **discussions** to make their work more visible to other teams. See [AUTOTITLE](/discussions/collaborating-with-your-community-using-discussions/participating-in-a-discussion#creating-a-discussion). -* Create a dedicated internal repository for sharing **actions and reusable {% data variables.product.prodname_actions %} workflows**, which anyone can reference when they write a workflow within the enterprise. See [AUTOTITLE](/actions/how-tos/reuse-automations/share-with-your-enterprise). -* Share reusable pieces of code in internal packages with **{% data variables.product.prodname_registry %}** registries. For enhanced security, you can give {% data variables.product.github %}'s security features access to these registries. See [AUTOTITLE](/packages/learn-github-packages/introduction-to-github-packages). -* Set up common templates and frameworks as **template repositories** that other people can copy to get started with a project. See [AUTOTITLE](/repositories/creating-and-managing-repositories/creating-a-template-repository). - -Like with an open source project, you should ensure shared projects have a support model and a clearly defined team of maintainers, especially for services that many parts of your enterprise rely on. Ideally the maintainers team will contain representatives from the different teams that use the service. - -## Hide content from external collaborators - -If you have external contractors or collaborators who need access to your enterprise's projects, you can grant them a different level of access from regular employees. - -Specifically, you may want to hide internal repositories from an external collaborator. To do this: - -* If you use {% data variables.product.prodname_emus %}, provision an account for the user with the **guest collaborator** role. Guest collaborators don't have access to internal repositories by default, but they receive base permissions in organizations where they're added as members. They can also be added as repository collaborators in repositories. -* If you do not use {% data variables.product.prodname_emus %}, add the user as an **outside collaborator** in the required repositories, but ensure they are not added as a member of any organization. - -Outside collaborators (called **repository collaborators** if you use {% data variables.product.prodname_emus %}) only have access to a specific repository. These users are not full organization members, so they do not receive the base level of access for the organization, and they cannot automatically see internal repositories in the enterprise unless they are a member of another organization. - -For more information, see {% ifversion ghec %}[AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/enabling-guest-collaborators) and{% endif %} [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-outside-collaborators/adding-outside-collaborators-to-repositories-in-your-organization). diff --git a/data/reusables/gated-features/more-info.md b/data/reusables/gated-features/more-info.md index 16baddaae07e..cb4853d45610 100644 --- a/data/reusables/gated-features/more-info.md +++ b/data/reusables/gated-features/more-info.md @@ -1 +1 @@ -{% ifversion fpt or ghec %}For more information, see [AUTOTITLE](/get-started/learning-about-github/githubs-plans).{% endif %} +See [AUTOTITLE](/get-started/learning-about-github/githubs-plans). diff --git a/data/reusables/pull_requests/automatically-delete-branches.md b/data/reusables/pull_requests/automatically-delete-branches.md index 1bcc053ddf7a..bc556de91251 100644 --- a/data/reusables/pull_requests/automatically-delete-branches.md +++ b/data/reusables/pull_requests/automatically-delete-branches.md @@ -1 +1 @@ -You can have head branches automatically deleted after pull requests are merged in your repository. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-the-automatic-deletion-of-branches). +You can have head branches automatically deleted after pull requests are merged in your repository. See [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-the-automatic-deletion-of-branches). diff --git a/data/reusables/repositories/asking-for-review.md b/data/reusables/repositories/asking-for-review.md index 5a5857da4ff1..afa094ce6b01 100644 --- a/data/reusables/repositories/asking-for-review.md +++ b/data/reusables/repositories/asking-for-review.md @@ -1,2 +1,2 @@ > [!TIP] -> After you create a pull request, you can ask a specific person to [review your proposed changes](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request). For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/requesting-a-pull-request-review). +> After you create a pull request, you can ask a specific person to review your proposed changes. See [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/requesting-a-pull-request-review). diff --git a/data/reusables/repositories/sidebar-pr.md b/data/reusables/repositories/sidebar-pr.md index 49b4d724f06f..63781746cea9 100644 --- a/data/reusables/repositories/sidebar-pr.md +++ b/data/reusables/repositories/sidebar-pr.md @@ -1,3 +1 @@ 1. Under your repository name, click **{% octicon "git-pull-request" aria-hidden="true" aria-label="git-pull-request" %} Pull requests**. - - ![Screenshot of the main page of a repository. In the horizontal navigation bar, a tab, labeled "Pull requests," is outlined in dark orange.](/assets/images/help/repository/repo-tabs-pull-requests-global-nav-update.png) diff --git a/src/content-pipelines/state/copilot-cli.sha b/src/content-pipelines/state/copilot-cli.sha index 878da12aecef..c87931bd7c46 100644 --- a/src/content-pipelines/state/copilot-cli.sha +++ b/src/content-pipelines/state/copilot-cli.sha @@ -1 +1 @@ -0a6e6489329eccb43213166dd5eb8621e877b1a5 +99bdacdd87aebaa6496754421e70b45485235cc8 diff --git a/src/frame/tests/page.ts b/src/frame/tests/page.ts index 5bde34f72e1d..389a088a9238 100644 --- a/src/frame/tests/page.ts +++ b/src/frame/tests/page.ts @@ -27,8 +27,7 @@ const enterpriseServerVersions = Object.keys(allVersions).filter((v) => const nonEnterpriseDefaultPlan = nonEnterpriseDefaultVersion.split('@')[0] const opts = { - relativePath: - 'pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches.md', + relativePath: 'pull-requests/reference/branches.md', basePath: path.join(__dirname, '../../../content'), languageCode: 'en', } @@ -202,8 +201,7 @@ describe('Page class', () => { test('sets versioned values', async () => { const page = await Page.init(opts) - const expectedPath = - 'pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches' + const expectedPath = 'pull-requests/reference/branches' expect( page!.permalinks.find((permalink) => permalink.pageVersion === nonEnterpriseDefaultVersion)! .href, diff --git a/src/redirects/tests/redirects.ts b/src/redirects/tests/redirects.ts index 4e2222b17503..93d5ebc52eae 100644 --- a/src/redirects/tests/redirects.ts +++ b/src/redirects/tests/redirects.ts @@ -17,8 +17,7 @@ describe('redirects', () => { test('page.buildRedirects() returns an array', async () => { const page = await Page.init({ - relativePath: - 'pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches.md', + relativePath: 'pull-requests/reference/branches.md', basePath: path.join(__dirname, '../../../content'), languageCode: 'en', }) @@ -312,7 +311,7 @@ describe('redirects', () => { }) describe('enterprise user article', () => { - const userArticle = `/en/enterprise-server@${enterpriseServerReleases.latest}/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo` + const userArticle = `/en/enterprise-server@${enterpriseServerReleases.latest}/pull-requests/how-tos/work-with-forks/fork-a-repo` test('no product redirects to GitHub.com product on the latest version', async () => { const res = await get( @@ -344,7 +343,7 @@ describe('redirects', () => { }) describe('enterprise user article with frontmatter redirect', () => { - const userArticle = `/en/enterprise-server@${enterpriseServerReleases.latest}/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo` + const userArticle = `/en/enterprise-server@${enterpriseServerReleases.latest}/pull-requests/how-tos/work-with-forks/fork-a-repo` const redirectFromPath = '/articles/fork-a-repo' test('redirects to expected article', async () => {