diff --git a/content/apps/creating-github-apps/about-creating-github-apps/best-practices-for-creating-a-github-app.md b/content/apps/creating-github-apps/about-creating-github-apps/best-practices-for-creating-a-github-app.md index e38c0d8fdf5a..d7f311e4efac 100644 --- a/content/apps/creating-github-apps/about-creating-github-apps/best-practices-for-creating-a-github-app.md +++ b/content/apps/creating-github-apps/about-creating-github-apps/best-practices-for-creating-a-github-app.md @@ -73,6 +73,8 @@ User access tokens will attribute activity to a user and to your app. These are An installation access token is restricted based on the {% data variables.product.prodname_github_app %}'s permissions and access. A user access token is restricted based on both the {% data variables.product.prodname_github_app %}'s permission and access and the user's permission and access. Therefore, if your {% data variables.product.prodname_github_app %} takes an action on behalf of a user, it should always use a user access token instead of an installation access token. Otherwise, your app might allow a user to see or do things that they shouldn't be able to see or do. +Your app should never use a {% data variables.product.pat_generic %} or {% data variables.product.company_short %} password to authenticate. + ## Validate organization access for every new authentication When you use a user access token, you should track which organizations the token is authorized for. If an organization uses SAML SSO and a user has not performed SAML SSO, the user access token should not have access to that organization. You can use the `GET /user/installations` REST API endpoint to verify which organizations a user access token has access to. If the user is not authorized to access an organization, you should reject their access until they perform SAML SSO. For more information, see "[AUTOTITLE](/rest/apps/installations#list-app-installations-accessible-to-the-user-access-token)." @@ -83,13 +85,17 @@ When you use a user access token, you should track which organizations the token Installation access tokens expire after one hour, expiring user access tokens expire after eight hours, and refresh tokens expire after six months. However, you can also revoke tokens as soon as you no longer need them. For more information, see "[AUTOTITLE](/rest/apps/installations#revoke-an-installation-access-token)" to revoke an installation access token and "[AUTOTITLE](/rest/apps/oauth-applications#delete-an-app-token)" to revoke a user access token. -## Make a plan for rotating credentials +## Make a plan for handling security breaches You should have a plan in place so that you can handle any security breaches in a timely manner. In the event that your app's private key or secret is compromised, you will need to generate a new key or secret, update your app to use the new key or secret, and delete your old key or secret. -In the event that installation access tokens, user access tokens, or refresh tokens are compromised, you should immediately revoke these tokens. For more information, see "[AUTOTITLE](/rest/apps/installations#revoke-an-installation-access-token)." +In the event that installation access tokens, user access tokens, or refresh tokens are compromised, you should immediately revoke these tokens. For more information, see "[AUTOTITLE](/rest/apps/installations#revoke-an-installation-access-token)" to revoke an installation access token and "[AUTOTITLE](/rest/apps/oauth-applications#delete-an-app-token)" to revoke a user access token. + +## Conduct regular vulnerability scans + +{% data reusables.apps.app-scans %} ## Choose an appropriate environment @@ -111,6 +117,18 @@ When you add repository or organization permissions to your {% data variables.pr When you update permissions, you should consider making your app backwards compatible to give your users time to accept the new permissions. You can use the [installation webhook with the `new_permissions_accepted` action property](/webhooks-and-events/webhooks/webhook-events-and-payloads?actionType=new_permissions_accepted#installation) to learn when users accept new permissions for your app. +## Use services in a secure manner + +{% data reusables.apps.app-services %} + +## Add logging and monitoring + +{% data reusables.apps.apps-logging %} + +## Enable data deletion + +If your {% data variables.product.prodname_github_app %} is available to other users or organizations, you should give users and organization owners a way to delete their data. Users should not need to email or call a support person in order to delete their data. + {% ifversion fpt or ghec %} ## Further reading diff --git a/content/apps/creating-github-apps/about-creating-github-apps/deciding-when-to-build-a-github-app.md b/content/apps/creating-github-apps/about-creating-github-apps/deciding-when-to-build-a-github-app.md index bb8fff6415ce..1688c8efe131 100644 --- a/content/apps/creating-github-apps/about-creating-github-apps/deciding-when-to-build-a-github-app.md +++ b/content/apps/creating-github-apps/about-creating-github-apps/deciding-when-to-build-a-github-app.md @@ -54,7 +54,7 @@ The rate limit for {% data variables.product.prodname_github_app %}s using an in In general, {% data variables.product.prodname_github_app %}s and {% data variables.product.prodname_oauth_app %}s can make the same API requests. However, there are some differences: - The REST API to manage check runs and check suites is only available to {% data variables.product.prodname_github_app %}s. -- Enterprise resources are only available to {% data variables.product.prodname_oauth_app %}s. +- Enterprise-level resources such as the enterprise object itself are not available to {% data variables.product.prodname_github_app %}s. This means that {% data variables.product.prodname_github_app %}s cannot call endpoints like `GET /enterprise/settings/license`. However, enterprise-owned organization and repository resources are available. - Some requests may return incomplete data depending on the permissions and repository access that was granted to an {% data variables.product.prodname_github_app %}. For example, if your app makes a request to get all repositories that a user can access, the response will only include the repositories that the app was also granted access to. For more information about the REST API endpoints that are available to {% data variables.product.prodname_github_app %}s, see "[AUTOTITLE](/rest/overview/endpoints-available-for-github-apps)." diff --git a/content/apps/oauth-apps/building-oauth-apps/best-practices-for-creating-an-oauth-app.md b/content/apps/oauth-apps/building-oauth-apps/best-practices-for-creating-an-oauth-app.md new file mode 100644 index 000000000000..3bfb2f0be25f --- /dev/null +++ b/content/apps/oauth-apps/building-oauth-apps/best-practices-for-creating-an-oauth-app.md @@ -0,0 +1,85 @@ +--- +title: Best practices for creating an OAuth App +shortTitle: Best practices +intro: 'Follow these best practices to improve the security and performance of your OAuth App.' +versions: + fpt: '*' + ghes: '*' + ghae: '*' + ghec: '*' +topics: + - OAuth Apps +--- + +## Use a {% data variables.product.prodname_github_app %} instead + +If possible, consider using a {% data variables.product.prodname_github_app %} instead of an OAuth App. In general, {% data variables.product.prodname_github_app %}s are preferred over {% data variables.product.prodname_oauth_app %}s. {% data variables.product.prodname_github_app %}s use fine-grained permissions, give the user more control over which repositories the app can access, and use short-lived tokens. These properties can harden the security of your app by limiting the damage that could be done if your app's credentials are leaked. + +Similar to {% data variables.product.prodname_oauth_app %}s, {% data variables.product.prodname_github_app %}s can still use OAuth 2.0 and generate a type of OAuth token (called a user access token) and take actions on behalf of a user. However, {% data variables.product.prodname_github_app %}s can also act independently of a user. + +For more information about {% data variables.product.prodname_github_app %}s, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-creating-github-apps)." + +For more information about migrating an existing {% data variables.product.prodname_oauth_app %} to a {% data variables.product.prodname_github_app %}, see "[AUTOTITLE](/apps/creating-github-apps/guides/migrating-oauth-apps-to-github-apps)." + +## Use minimal scopes + +Your OAuth App should only request the scopes that the app needs to perform its intended functionality. If any tokens for your app become compromised, this will limit the amount of damage that can occur. For more information, see "[AUTOTITLE](/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps)." + +## Secure your app's credentials + +With a client secret, your app can authorize a user and generate user access tokens. These tokens can be used to make API requests on behalf of a user. + +You must store your app's client secret and any generated tokens securely. The storage mechanism depends on your integrations architecture and the platform that it runs on. In general, you should use a storage mechanism that is intended to store sensitive data on the platform that you are using. + +### Client secrets + +If your app is a website or web app, consider storing your client secret in a key vault, such as [Azure Key Vault](https://azure.microsoft.com/products/key-vault), or as an encrypted environment variable or secret on your server. + +If your app is a native client, client-side app, or runs on a user device (as opposed to running on your servers), you cannot secure your client secret. You should use caution if you plan to gate access to your own services based on tokens generated by your app, because anyone can access the client secret to generate a token. + +### User access tokens + +If your app is a website or web app, you should encrypt the tokens on your back end and ensure there is security around the systems that can access the tokens. Consider storing refresh tokens in a separate place from active access tokens. + +If your app is a native client, client-side app, or runs on a user device (as opposed to running on your servers), you may not be able to secure tokens as well as an app that runs on your servers. You should store tokens via the mechanism recommended for your app's platform, and keep in mind that the storage mechanism may not be fully secure. + +## Use the appropriate token type + +OAuth Apps can generate user access tokens in order to make authenticated API requests. Your app should never use a {% data variables.product.pat_generic %} or {% data variables.product.company_short %} password to authenticate. + +## Make a plan for handling security breaches + +You should have a plan in place so that you can handle any security breaches in a timely manner. + +In the event that your app's client secret is compromised, you will need to generate a new secret, update your app to use the new secret, and delete your old secret. + +In the event that user access tokens are compromised, you should immediately revoke these tokens. For more information, see "[AUTOTITLE](/rest/apps/oauth-applications#delete-an-app-token)." + +## Conduct regular vulnerability scans + +{% data reusables.apps.app-scans %} + +## Choose an appropriate environment + +If your app runs on a server, verify that your server environment is secure and that it can handle the volume of traffic that you expect for your app. + +## Use services in a secure manner + +{% data reusables.apps.app-services %} + +## Add logging and monitoring + +{% data reusables.apps.apps-logging %} + +## Enable data deletion + +If your app is available to other users, you should give users a way to delete their data. Users should not need to email or call a support person in order to delete their data. + +{% ifversion fpt or ghec %} + +## Further reading + +- "[AUTOTITLE](/apps/publishing-apps-to-github-marketplace/creating-apps-for-github-marketplace/security-best-practices-for-apps)" +- "[AUTOTITLE](/apps/publishing-apps-to-github-marketplace/creating-apps-for-github-marketplace/customer-experience-best-practices-for-apps)" + +{% endif %} diff --git a/content/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps.md b/content/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps.md index 79206d218f32..dcf21d69c5f3 100644 --- a/content/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps.md +++ b/content/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps.md @@ -24,13 +24,13 @@ shortTitle: GitHub Apps & OAuth Apps In general, {% data variables.product.prodname_github_app %}s are preferred over {% data variables.product.prodname_oauth_app %}s. {% data variables.product.prodname_github_app %}s use fine grained permissions, give the user more control over which repositories the app can access, and use short-lived tokens. These properties can harden the security of your app by limiting the damage that could be done if your app's credentials were leaked. -Similar to {% data variables.product.prodname_oauth_app %}s, {% data variables.product.prodname_github_app %}s can still generate a type of OAuth token (called a user access token) and take actions on behalf of a user. However, {% data variables.product.prodname_github_app %}s can also act independently of a user. This is beneficial for automations that do not require user input. The app will continue to work even if the person who installed the app on an organization leaves the organization. +Similar to {% data variables.product.prodname_oauth_app %}s, {% data variables.product.prodname_github_app %}s can still use OAuth 2.0 and generate a type of OAuth token (called a user access token) and take actions on behalf of a user. However, {% data variables.product.prodname_github_app %}s can also act independently of a user. This is beneficial for automations that do not require user input. The app will continue to work even if the person who installed the app on an organization leaves the organization. {% data variables.product.prodname_github_app %}s have built-in, centralized webhooks. {% data variables.product.prodname_github_app %}s can receive webhook events for all repositories and organizations the app can access. Conversely, {% data variables.product.prodname_oauth_app %}s must configure webhooks individually for each repository and organization. The rate limit for {% data variables.product.prodname_github_app %}s using an installation access token scales with the number of repositories and number of organization users. Conversely, {% data variables.product.prodname_oauth_app %}s have lower rate limits and do not scale. -There is one case where an {% data variables.product.prodname_oauth_app %} is preferred over a {% data variables.product.prodname_github_app %}. If your app needs to access enterprise resources, you should use an {% data variables.product.prodname_oauth_app %} because a {% data variables.product.prodname_github_app %} cannot yet be given permissions against an enterprise. +There is one case where an {% data variables.product.prodname_oauth_app %} is preferred over a {% data variables.product.prodname_github_app %}. If your app needs to access enterprise-level resources such as the enterprise object itself, you should use an {% data variables.product.prodname_oauth_app %} because a {% data variables.product.prodname_github_app %} cannot yet be given permissions against an enterprise. {% data variables.product.prodname_github_app %}s can still access enterprise-owned organization and repository resources. For more information about {% data variables.product.prodname_github_app %}s, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-creating-github-apps)." diff --git a/content/apps/oauth-apps/building-oauth-apps/index.md b/content/apps/oauth-apps/building-oauth-apps/index.md index 8b6d46062e3f..03c203c64c9c 100644 --- a/content/apps/oauth-apps/building-oauth-apps/index.md +++ b/content/apps/oauth-apps/building-oauth-apps/index.md @@ -20,5 +20,6 @@ children: - /authorizing-oauth-apps - /scopes-for-oauth-apps - /creating-a-custom-badge-for-your-oauth-app + - /best-practices-for-creating-an-oauth-app --- diff --git a/content/apps/publishing-apps-to-github-marketplace/creating-apps-for-github-marketplace/customer-experience-best-practices-for-apps.md b/content/apps/publishing-apps-to-github-marketplace/creating-apps-for-github-marketplace/customer-experience-best-practices-for-apps.md index 27453d48f59d..cb895d632966 100644 --- a/content/apps/publishing-apps-to-github-marketplace/creating-apps-for-github-marketplace/customer-experience-best-practices-for-apps.md +++ b/content/apps/publishing-apps-to-github-marketplace/creating-apps-for-github-marketplace/customer-experience-best-practices-for-apps.md @@ -22,6 +22,7 @@ If you follow these best practices it will help you to provide a good customer e - Apps should include links to user-facing documentation that describe how to set up and use the app. - Customers should be able to see what type of plan they have in the billing, profile, or account settings section of the app. - Customers should be able to install and use your app on both a personal account and an organization account. They should be able to view and manage the app on those accounts separately. +- Apps should provide customers with a way to delete their account, without having to email or call a support person. Apps should delete all {% data variables.product.company_short %} user data within 30 days of receiving a request from the user, or within 30 days of the end of the user's legal relationship with {% data variables.product.company_short %}. ## Plan management @@ -30,4 +31,5 @@ If you follow these best practices it will help you to provide a good customer e ## Further reading - "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/best-practices-for-creating-a-github-app)" +- "[AUTOTITLE](/apps/oauth-apps/building-oauth-apps/best-practices-for-creating-an-oauth-app)" - "[AUTOTITLE](/apps/publishing-apps-to-github-marketplace/creating-apps-for-github-marketplace/security-best-practices-for-apps)" diff --git a/content/apps/publishing-apps-to-github-marketplace/creating-apps-for-github-marketplace/security-best-practices-for-apps-on-github-marketplace.md b/content/apps/publishing-apps-to-github-marketplace/creating-apps-for-github-marketplace/security-best-practices-for-apps-on-github-marketplace.md index f879b7401c58..466fdac74342 100644 --- a/content/apps/publishing-apps-to-github-marketplace/creating-apps-for-github-marketplace/security-best-practices-for-apps-on-github-marketplace.md +++ b/content/apps/publishing-apps-to-github-marketplace/creating-apps-for-github-marketplace/security-best-practices-for-apps-on-github-marketplace.md @@ -18,56 +18,11 @@ topics: {% data reusables.marketplace.marketplace-apps-not-actions %} -If you follow these best practices it will help you to provide a secure user experience. +Before listing an app on {% data variables.product.prodname_marketplace %}, you should follow the best practices for the type of app that you are listing: -## Authorization, authentication, and access control - -We recommend creating a GitHub App rather than an OAuth App. {% data reusables.marketplace.github_apps_preferred %}. See "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/differences-between-github-apps-and-oauth-apps)" for more details. -- Apps should use the principle of least privilege and should only request the OAuth scopes and GitHub App permissions that the app needs to perform its intended functionality. For more information, see [Principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege) in Wikipedia. -- Apps should provide customers with a way to delete their account, without having to email or call a support person. -- Apps should not share tokens between different implementations of the app. For example, a desktop app should have a separate token from a web-based app. Individual tokens allow each app to request the access needed for GitHub resources separately. -- Design your app with different user roles, depending on the functionality needed by each type of user. For example, a standard user should not have access to admin functionality, and billing managers might not need push access to repository code. -- Apps should not share service accounts such as email or database services to manage your SaaS service. -- All services used in your app should have unique login and password credentials. -- Admin privilege access to the production hosting infrastructure should only be given to engineers and employees with administrative duties. -- Apps should not use {% data variables.product.pat_generic %}s to authenticate and should authenticate as an [OAuth App](/apps/oauth-apps/building-oauth-apps) or a [GitHub App](/apps/creating-github-apps/setting-up-a-github-app/about-creating-github-apps#about-github-apps): - - OAuth Apps should authenticate using an [OAuth token](/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps). - - GitHub Apps should authenticate using either a [JSON Web Token (JWT)](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-json-web-token-jwt-for-a-github-app), [OAuth token](/apps/creating-github-apps/authenticating-with-a-github-app/identifying-and-authorizing-users-for-github-apps), or [installation access token](/apps/creating-github-apps/authenticating-with-a-github-app/generating-an-installation-access-token-for-a-github-app). - -## Data protection - -- Apps should encrypt data transferred over the public internet using HTTPS, with a valid TLS certificate, or SSH for Git. -- Apps should store client ID and client secret keys securely. We recommend storing them as [environmental variables](https://en.wikipedia.org/wiki/Environment_variable#Getting_and_setting_environment_variables). -- Apps should delete all GitHub user data within 30 days of receiving a request from the user, or within 30 days of the end of the user's legal relationship with GitHub. -- Apps should not require the user to provide their GitHub password. -- Apps should encrypt tokens, client IDs, and client secrets. - -## Logging and monitoring - -Apps should have logging and monitoring capabilities. App logs should be retained for at least 30 days and archived for at least one year. -A security log should include: - -- Authentication and authorization events -- Service configuration changes -- Object reads and writes -- All user and group permission changes -- Elevation of role to admin -- Consistent timestamping for each event -- Source users, IP addresses, and/or hostnames for all logged actions - -## Incident response workflow - -To provide a secure experience for users, you should have a clear incident response plan in place before listing your app. We recommend having a security and operations incident response team in your company rather than using a third-party vendor. You should have the capability to notify {% data variables.product.product_name %} within 24 hours of a confirmed incident. - -For an example of an incident response workflow, see the "Data Breach Response Policy" on the [SANS Institute website](https://www.sans.org/information-security-policy/). A short document with clear steps to take in the event of an incident is more valuable than a lengthy policy template. - -## Vulnerability management and patching workflow - -You should conduct regular vulnerability scans of production infrastructure. You should triage the results of vulnerability scans and define a period of time in which you agree to remediate the vulnerability. - -If you are not ready to set up a full vulnerability management program, it's useful to start by creating a patching process. For guidance in creating a patch management policy, see this TechRepublic article "[Establish a patch management policy](https://www.techrepublic.com/article/establish-a-patch-management-policy-87756/)." +- "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/best-practices-for-creating-a-github-app)" +- "[AUTOTITLE](/apps/oauth-apps/building-oauth-apps/best-practices-for-creating-an-oauth-app)" -## Further reading +Additionally, you should have the capability to notify {% data variables.product.product_name %} within 24 hours of a confirmed security incident. -- "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/best-practices-for-creating-a-github-app)" -- "[AUTOTITLE](/apps/publishing-apps-to-github-marketplace/creating-apps-for-github-marketplace/customer-experience-best-practices-for-apps)" +In addition to following security best practices, you should also follow customer experience best practices. For more information, see "[AUTOTITLE](/apps/publishing-apps-to-github-marketplace/creating-apps-for-github-marketplace/customer-experience-best-practices-for-apps)." diff --git a/content/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches.md b/content/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches.md index a391980e9f7e..bbfcc22605ac 100644 --- a/content/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches.md +++ b/content/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches.md @@ -42,11 +42,11 @@ By default, the restrictions of a branch protection rule don't apply to people w {% data reusables.pull_requests.you-can-auto-merge %} {% ifversion repo-rules %} -{% tip %} +{% note %} -**Tip:** Only a single branch protection rule can apply at a time, which means it can be difficult to know which rule will apply when multiple versions of a rule target the same branch. {% ifversion repo-rules-enterprise %}Additionally, you may want to create a single set of rules that applies to multiple repositories in an organization. {% endif %}For information about an alternative to branch protection rules, see "[AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets)." +**Note:** Only a single branch protection rule can apply at a time, which means it can be difficult to know which rule will apply when multiple versions of a rule target the same branch. {% ifversion repo-rules-enterprise %}Additionally, you may want to create a single set of rules that applies to multiple repositories in an organization. {% endif %}For information about an alternative to branch protection rules, see "[AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets)." -{% endtip %} +{% endnote %} {% endif %} ## About branch protection settings @@ -102,6 +102,10 @@ Optionally, you can require that the most recent reviewable push must be approve For complex pull requests that require many reviews, requiring an approval from someone other than the last person to push can be a compromise that avoids the need to dismiss all stale reviews: with this option, "stale" reviews are not dismissed, and the pull request remains approved as long as someone other than the person who made the most recent changes approves it. Users who have already reviewed a pull request can reapprove after the most recent push to meet this requirement. If you are concerned about pull requests being "hijacked" (where unapproved content is added to approved pull requests), it is safer to dismiss stale reviews. {% endif %} +{% ifversion pull-request-mergeability-security-changes %} +{% data reusables.pull_requests.security-changes-mergeability %} +{% endif %} + ### Require status checks before merging Required status checks ensure that all required CI tests are passing before collaborators can make changes to a protected branch. Required status checks can be checks or statuses. For more information, see "[AUTOTITLE](/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks)." diff --git a/content/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/managing-a-branch-protection-rule.md b/content/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/managing-a-branch-protection-rule.md index deb3d0f84d13..6db46a20c0d1 100644 --- a/content/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/managing-a-branch-protection-rule.md +++ b/content/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/managing-a-branch-protection-rule.md @@ -44,11 +44,11 @@ To create an exception to an existing branch rule, you can create a new branch p For more information about each of the available branch protection settings, see "[AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches)." {% ifversion repo-rules %} -{% tip %} +{% note %} -**Tip:** Only a single branch protection rule can apply at a time, which means it can be difficult to know how which rule will apply when multiple versions of a rule target the same branch. {% ifversion repo-rules-enterprise %}Additionally, you may want to create a single set of rules that applies to multiple repositories in an organization. {% endif %}For information about an alternative to branch protection rules, see "[AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets)." +**Note:** Only a single branch protection rule can apply at a time, which means it can be difficult to know how which rule will apply when multiple versions of a rule target the same branch. {% ifversion repo-rules-enterprise %}Additionally, you may want to create a single set of rules that applies to multiple repositories in an organization. {% endif %}For information about an alternative to branch protection rules, see "[AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets)." -{% endtip %} +{% endnote %} {% endif %} ## Creating a branch protection rule @@ -60,6 +60,9 @@ When you create a branch rule, the branch you specify doesn't have to exist yet {% data reusables.repositories.repository-branches %} {% data reusables.repositories.add-branch-protection-rules %} 1. Optionally, enable required pull requests. +{% ifversion pull-request-mergeability-security-changes %} +{% indented_data_reference reusables.pull_requests.security-changes-mergeability spaces=3 %} +{% endif %} - Under "Protect matching branches", select **Require a pull request before merging**. - Optionally, to require approvals before a pull request can be merged, select **Require approvals**. diff --git a/content/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets.md b/content/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets.md index f843075a3bf9..b190105132f5 100644 --- a/content/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets.md +++ b/content/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets.md @@ -12,7 +12,7 @@ shortTitle: Available rules {% data reusables.repositories.rulesets-public-beta %} -You can create rulesets to control how users can interact with selected branches and tags in a repository. When you create a ruleset, you can choose to enable or disable the rules described in the following sections. +You can create rulesets to control how users can interact with selected branches and tags in a repository. When you create a ruleset, you can choose to enable or disable the rules described in the following sections. When you create a ruleset, you can allow certain users to bypass the rules in the ruleset. This can be users with certain permissions, specific teams, or {% data variables.product.prodname_github_apps %}. For more information, see "[AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets)." @@ -76,6 +76,10 @@ You can require that all changes to the target branch be associated with a pull ### Additional settings +{% ifversion pull-request-mergeability-security-changes %} +{% data reusables.pull_requests.security-changes-mergeability %} +{% endif %} + {% data reusables.pull_requests.required-reviews-for-prs-summary %} If you enable required reviews, collaborators can only push changes to a branch via a pull request that is approved by the required number of reviewers with write permissions. diff --git a/data/features/pull-request-mergeability-security-changes.yml b/data/features/pull-request-mergeability-security-changes.yml new file mode 100644 index 000000000000..f3fd4e14cbd5 --- /dev/null +++ b/data/features/pull-request-mergeability-security-changes.yml @@ -0,0 +1,5 @@ +# Issue 10179 - Security Changes for Pull Request Mergeability +versions: + fpt: '*' + ghec: '*' + ghes: '>=3.10' diff --git a/data/graphql/ghae/schema.docs-ghae.graphql b/data/graphql/ghae/schema.docs-ghae.graphql index 457e013741d1..eab2b52bfe16 100644 --- a/data/graphql/ghae/schema.docs-ghae.graphql +++ b/data/graphql/ghae/schema.docs-ghae.graphql @@ -14923,7 +14923,7 @@ union IpAllowListOwner = App | Enterprise | Organization """ An Issue is a place to discuss ideas, enhancements, tasks, and bugs for a project. """ -type Issue implements Assignable & Closable & Comment & Labelable & Lockable & Node & Reactable & RepositoryNode & Subscribable & UniformResourceLocatable & Updatable & UpdatableComment { +type Issue implements Assignable & Closable & Comment & Deletable & Labelable & Lockable & Node & Reactable & RepositoryNode & Subscribable & UniformResourceLocatable & Updatable & UpdatableComment { """ Reason that the conversation was locked. """ @@ -15396,6 +15396,11 @@ type Issue implements Assignable & Closable & Comment & Labelable & Lockable & N """ viewerCanClose: Boolean! + """ + Check if the current viewer can delete this object. + """ + viewerCanDelete: Boolean! + """ Can user react to this subject """ diff --git a/data/graphql/ghec/schema.docs.graphql b/data/graphql/ghec/schema.docs.graphql index 2542d9fc275d..dcf6c67e2e99 100644 --- a/data/graphql/ghec/schema.docs.graphql +++ b/data/graphql/ghec/schema.docs.graphql @@ -16723,7 +16723,7 @@ union IpAllowListOwner = App | Enterprise | Organization """ An Issue is a place to discuss ideas, enhancements, tasks, and bugs for a project. """ -type Issue implements Assignable & Closable & Comment & Labelable & Lockable & Node & ProjectV2Owner & Reactable & RepositoryNode & Subscribable & UniformResourceLocatable & Updatable & UpdatableComment { +type Issue implements Assignable & Closable & Comment & Deletable & Labelable & Lockable & Node & ProjectV2Owner & Reactable & RepositoryNode & Subscribable & UniformResourceLocatable & Updatable & UpdatableComment { """ Reason that the conversation was locked. """ @@ -17331,6 +17331,11 @@ type Issue implements Assignable & Closable & Comment & Labelable & Lockable & N """ viewerCanClose: Boolean! + """ + Check if the current viewer can delete this object. + """ + viewerCanDelete: Boolean! + """ Can user react to this subject """ diff --git a/data/graphql/schema.docs.graphql b/data/graphql/schema.docs.graphql index 2542d9fc275d..dcf6c67e2e99 100644 --- a/data/graphql/schema.docs.graphql +++ b/data/graphql/schema.docs.graphql @@ -16723,7 +16723,7 @@ union IpAllowListOwner = App | Enterprise | Organization """ An Issue is a place to discuss ideas, enhancements, tasks, and bugs for a project. """ -type Issue implements Assignable & Closable & Comment & Labelable & Lockable & Node & ProjectV2Owner & Reactable & RepositoryNode & Subscribable & UniformResourceLocatable & Updatable & UpdatableComment { +type Issue implements Assignable & Closable & Comment & Deletable & Labelable & Lockable & Node & ProjectV2Owner & Reactable & RepositoryNode & Subscribable & UniformResourceLocatable & Updatable & UpdatableComment { """ Reason that the conversation was locked. """ @@ -17331,6 +17331,11 @@ type Issue implements Assignable & Closable & Comment & Labelable & Lockable & N """ viewerCanClose: Boolean! + """ + Check if the current viewer can delete this object. + """ + viewerCanDelete: Boolean! + """ Can user react to this subject """ diff --git a/data/reusables/apps/app-scans.md b/data/reusables/apps/app-scans.md new file mode 100644 index 000000000000..84085943e709 --- /dev/null +++ b/data/reusables/apps/app-scans.md @@ -0,0 +1 @@ +You should conduct regular vulnerability scans for your app. For example, you might set up code scanning and secret scanning for the repository that hosts your app's code. For more information, see "[AUTOTITLE](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning)" and "[AUTOTITLE](/code-security/secret-scanning/about-secret-scanning)." diff --git a/data/reusables/apps/app-services.md b/data/reusables/apps/app-services.md new file mode 100644 index 000000000000..0fa0db299a83 --- /dev/null +++ b/data/reusables/apps/app-services.md @@ -0,0 +1,5 @@ +If your app uses third-party services, they should be used in a secure manner: + +- Any services used by your app should have a unique login and password. +- Apps should not share service accounts such as email or database services to manage your SaaS service. +- Only employees with administrative duties should have admin access to the infrastructure that hosts your app. diff --git a/data/reusables/apps/apps-logging.md b/data/reusables/apps/apps-logging.md new file mode 100644 index 000000000000..71e05867475e --- /dev/null +++ b/data/reusables/apps/apps-logging.md @@ -0,0 +1,9 @@ +Consider adding logging and monitoring capabilities for your app. A security log could include: + +- Authentication and authorization events +- Service configuration changes +- Object reads and writes +- User and group permission changes +- Elevation of role to admin + +Your logs should use consistent timestamping for each event and should record the users, IP addresses, or hostnames for all logged events. \ No newline at end of file diff --git a/data/reusables/pull_requests/security-changes-mergeability.md b/data/reusables/pull_requests/security-changes-mergeability.md new file mode 100644 index 000000000000..518b0a04397f --- /dev/null +++ b/data/reusables/pull_requests/security-changes-mergeability.md @@ -0,0 +1,7 @@ +{% note %} + +**Note:** If you select **Dismiss stale pull request approvals when new commits are pushed** and/or **Require approval of the most recent reviewable push**, manually creating the merge commit for a pull request and pushing it directly to a protected branch will fail, unless the contents of the merge exactly match the merge generated by {% data variables.product.prodname_dotcom %} for the pull request. + +In addition, with these settings, approving reviews will be dismissed as stale if the merge base introduces new changes after the review was submitted. The merge base is the commit that is the last common ancestor between the topic branch and the base branch. If the merge base changes, the pull request cannot be merged until someone approves the work again. + +{% endnote %} diff --git a/src/graphql/data/fpt/changelog.json b/src/graphql/data/fpt/changelog.json index a4377ea3392b..3884f2811f2b 100644 --- a/src/graphql/data/fpt/changelog.json +++ b/src/graphql/data/fpt/changelog.json @@ -1,4 +1,18 @@ [ + { + "schemaChanges": [ + { + "title": "The GraphQL schema includes these changes:", + "changes": [ + "

Issue object implements Deletable interface

", + "

Field viewerCanDelete was added to object type Issue

" + ] + } + ], + "previewChanges": [], + "upcomingChanges": [], + "date": "2023-06-06" + }, { "schemaChanges": [ { diff --git a/src/graphql/data/fpt/schema.json b/src/graphql/data/fpt/schema.json index ca1e1ada24a5..98aad6a15d19 100644 --- a/src/graphql/data/fpt/schema.json +++ b/src/graphql/data/fpt/schema.json @@ -26382,6 +26382,11 @@ "id": "comment", "href": "/graphql/reference/interfaces#comment" }, + { + "name": "Deletable", + "id": "deletable", + "href": "/graphql/reference/interfaces#deletable" + }, { "name": "Labelable", "id": "labelable", @@ -27582,6 +27587,14 @@ "kind": "scalars", "href": "/graphql/reference/scalars#boolean" }, + { + "name": "viewerCanDelete", + "description": "

Check if the current viewer can delete this object.

", + "type": "Boolean!", + "id": "boolean", + "kind": "scalars", + "href": "/graphql/reference/scalars#boolean" + }, { "name": "viewerCanReact", "description": "

Can user react to this subject.

", diff --git a/src/graphql/data/ghae/schema.json b/src/graphql/data/ghae/schema.json index b6dd74471a71..db66a5b1f9f1 100644 --- a/src/graphql/data/ghae/schema.json +++ b/src/graphql/data/ghae/schema.json @@ -23331,6 +23331,11 @@ "id": "comment", "href": "/graphql/reference/interfaces#comment" }, + { + "name": "Deletable", + "id": "deletable", + "href": "/graphql/reference/interfaces#deletable" + }, { "name": "Labelable", "id": "labelable", @@ -24255,6 +24260,14 @@ "kind": "scalars", "href": "/graphql/reference/scalars#boolean" }, + { + "name": "viewerCanDelete", + "description": "

Check if the current viewer can delete this object.

", + "type": "Boolean!", + "id": "boolean", + "kind": "scalars", + "href": "/graphql/reference/scalars#boolean" + }, { "name": "viewerCanReact", "description": "

Can user react to this subject.

", diff --git a/src/graphql/data/ghec/schema.json b/src/graphql/data/ghec/schema.json index ca1e1ada24a5..98aad6a15d19 100644 --- a/src/graphql/data/ghec/schema.json +++ b/src/graphql/data/ghec/schema.json @@ -26382,6 +26382,11 @@ "id": "comment", "href": "/graphql/reference/interfaces#comment" }, + { + "name": "Deletable", + "id": "deletable", + "href": "/graphql/reference/interfaces#deletable" + }, { "name": "Labelable", "id": "labelable", @@ -27582,6 +27587,14 @@ "kind": "scalars", "href": "/graphql/reference/scalars#boolean" }, + { + "name": "viewerCanDelete", + "description": "

Check if the current viewer can delete this object.

", + "type": "Boolean!", + "id": "boolean", + "kind": "scalars", + "href": "/graphql/reference/scalars#boolean" + }, { "name": "viewerCanReact", "description": "

Can user react to this subject.

",