diff --git a/assets/images/help/writing/alerts-rendered.png b/assets/images/help/writing/alerts-rendered.png index 9f2d50f797b2..012a081f562f 100644 Binary files a/assets/images/help/writing/alerts-rendered.png and b/assets/images/help/writing/alerts-rendered.png differ diff --git a/content/admin/backing-up-and-restoring-your-instance/configuring-backups-on-your-instance.md b/content/admin/backing-up-and-restoring-your-instance/configuring-backups-on-your-instance.md index 471d03cc3dc9..024277ea058d 100644 --- a/content/admin/backing-up-and-restoring-your-instance/configuring-backups-on-your-instance.md +++ b/content/admin/backing-up-and-restoring-your-instance/configuring-backups-on-your-instance.md @@ -174,6 +174,7 @@ Network settings are excluded from the backup snapshot. After restoration, you m 1. Ensure maintenance mode is enabled on the primary instance and all active processes have completed. For more information, see "[AUTOTITLE](/admin/configuration/configuring-your-enterprise/enabling-and-scheduling-maintenance-mode)." 1. Stop replication on all replica nodes in a high-availability configuration. For more information, see "[AUTOTITLE](/admin/enterprise-management/configuring-high-availability/about-high-availability-configuration#ghe-repl-stop)." +1. Provision a new {% data variables.product.product_name %} instance to use as a target for the restoration of your backup. For more information, see "[AUTOTITLE](/admin/installation/setting-up-a-github-enterprise-server-instance)." 1. If {% data variables.location.product_location %} has {% data variables.product.prodname_actions %} enabled, you must configure the external storage provider for {% data variables.product.prodname_actions %} on the replacement instance. For more information, see "[AUTOTITLE](/admin/github-actions/advanced-configuration-and-troubleshooting/backing-up-and-restoring-github-enterprise-server-with-github-actions-enabled)." ### Starting the restore operation diff --git a/content/admin/configuration/configuring-private-networking-for-hosted-compute-products/configuring-private-networking-for-github-hosted-runners.md b/content/admin/configuration/configuring-private-networking-for-hosted-compute-products/configuring-private-networking-for-github-hosted-runners.md index d81d1c53734f..e7d6f2e0b690 100644 --- a/content/admin/configuration/configuring-private-networking-for-hosted-compute-products/configuring-private-networking-for-github-hosted-runners.md +++ b/content/admin/configuration/configuring-private-networking-for-hosted-compute-products/configuring-private-networking-for-github-hosted-runners.md @@ -222,7 +222,7 @@ To use the script, fill in the placeholder environment variable values with the # - Resource group # - Network Security Group rules # - Virtual network (vnet) and subnet -# - Network Settings with specified subnet and GitHub Enterprise databse ID +# - Network Settings with specified subnet and GitHub Enterprise database ID # # It also registers the `GitHub.Network` resource provider with the subscription, # delegates the created subnet to the Actions service via the `GitHub.Network/NetworkSettings` diff --git a/content/admin/identity-and-access-management/using-ldap-for-enterprise-iam/using-ldap.md b/content/admin/identity-and-access-management/using-ldap-for-enterprise-iam/using-ldap.md index a21d582bf8f1..ad469dc4a440 100644 --- a/content/admin/identity-and-access-management/using-ldap-for-enterprise-iam/using-ldap.md +++ b/content/admin/identity-and-access-management/using-ldap-for-enterprise-iam/using-ldap.md @@ -114,6 +114,8 @@ When this option is selected, the certificate is validated to make sure: You can establish role-based access control for users from your LDAP server by synchronizing {% data variables.product.prodname_ghe_server %} users and team membership against your established LDAP groups. For more information, see "[AUTOTITLE](/organizations/organizing-members-into-teams/creating-a-team#creating-teams-with-ldap-sync-enabled)." +LDAP sync does not create user accounts on {% data variables.location.product_location %}. For more information, see "[Viewing and creating LDAP users](#viewing-and-creating-ldap-users)." + {% note %} **Note:** Using LDAP Synchronization with groups that exceed 1499 members may lead to team membership synchronization failures. @@ -124,7 +126,7 @@ If you need help determining if modifying the `MaxValRange` is the right approac {% endnote %} -To enable LDAP Sync, in your LDAP settings, select **Synchronize Emails**, **Synchronize SSH Keys**, or **Synchronize GPG Keys** . +To enable LDAP Sync, in your LDAP settings, select **Synchronize Emails**, **Synchronize SSH Keys**, or **Synchronize GPG Keys**. After you enable LDAP sync, a synchronization job will run at the specified time interval to perform the following operations on each user account: @@ -188,6 +190,8 @@ If disclosing such information is not desired, your company or organization shou ## Viewing and creating LDAP users +When you use LDAP, your instance creates a user account the first time someone successfully signs in using LDAP credentials. Alternatively, you can manually provision a user account. + You can view the full list of LDAP users who have access to your instance and provision new users. {% data reusables.enterprise_site_admin_settings.sign-in %} diff --git a/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/managing-dormant-users.md b/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/managing-dormant-users.md index af4e9c7601e8..274da19541b7 100644 --- a/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/managing-dormant-users.md +++ b/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/managing-dormant-users.md @@ -8,6 +8,7 @@ redirect_from: - /admin/user-management/managing-dormant-users - /admin/user-management/managing-users-in-your-enterprise/managing-dormant-users intro: '{% data reusables.enterprise-accounts.dormant-user-activity-threshold %}' +permissions: "{% ifversion ghec or ghae %}Enterprise owners can manage dormant users for an enterprise.{% elsif ghes %}Site administrators can manage dormant users on a {% data variables.product.product_name %} instance.{% endif %}" versions: ghec: '*' ghes: '*' @@ -37,12 +38,14 @@ You can customize the dormancy threshold for {% data variables.location.product_ Dormancy applies to both enterprise members and outside collaborators. +{% ifversion ghes %} + ## Viewing dormant users {% data reusables.enterprise-accounts.viewing-dormant-users %} {% data reusables.enterprise_site_admin_settings.access-settings %} -1. In the left sidebar, click **Dormant users**.{% ifversion ghes %} +1. In the left sidebar, click **Dormant users**. 1. To suspend all the dormant users in this list, at the top of the page, click **Suspend all**. ## Determining whether a user account is dormant @@ -62,6 +65,7 @@ Dormancy applies to both enterprise members and outside collaborators. {% data reusables.enterprise-accounts.policies-tab %} {% data reusables.enterprise-accounts.options-tab %} 1. Under "Dormancy threshold", select the dropdown menu, and click the desired dormancy threshold. + {% endif %} {% ifversion ghec %} diff --git a/content/apps/github-marketplace/using-the-github-marketplace-api-in-your-app/rest-endpoints-for-the-github-marketplace-api.md b/content/apps/github-marketplace/using-the-github-marketplace-api-in-your-app/rest-endpoints-for-the-github-marketplace-api.md index ae54e9437d74..a474c2f2b691 100644 --- a/content/apps/github-marketplace/using-the-github-marketplace-api-in-your-app/rest-endpoints-for-the-github-marketplace-api.md +++ b/content/apps/github-marketplace/using-the-github-marketplace-api-in-your-app/rest-endpoints-for-the-github-marketplace-api.md @@ -32,6 +32,6 @@ See these pages for details on how to authenticate when using the {% data variab {% note %} -**Note:** [Rate limits for the REST API](/rest/overview/rate-limits-for-the-rest-api) apply to all {% data variables.product.prodname_marketplace %} API endpoints. +**Note:** [Rate limits for the REST API](/rest/using-the-rest-api/rate-limits-for-the-rest-api) apply to all {% data variables.product.prodname_marketplace %} API endpoints. {% endnote %} diff --git a/content/billing/managing-the-plan-for-your-github-account/about-per-user-pricing.md b/content/billing/managing-the-plan-for-your-github-account/about-per-user-pricing.md index ff1c3ac64406..78cbe8c36b3b 100644 --- a/content/billing/managing-the-plan-for-your-github-account/about-per-user-pricing.md +++ b/content/billing/managing-the-plan-for-your-github-account/about-per-user-pricing.md @@ -108,11 +108,11 @@ If your enterprise does not use {% data variables.product.prodname_emus %}, you ### Accounts that consume a license on {% data variables.product.prodname_ghe_server %} -Each user account on {% data variables.product.prodname_ghe_server %} consumes a seat. +After a user successfully authenticates to a {% data variables.product.prodname_ghe_server %} instance for the first time, the user consumes a seat. Suspended users are not counted when calculating the number of licensed users consuming seats. For more information, see "[Suspending and unsuspending users]({% ifversion not ghes %}/enterprise-server@latest{% endif %}/admin/user-management/managing-users-in-your-enterprise/suspending-and-unsuspending-users){% ifversion not ghes %}" in the {% data variables.product.prodname_ghe_server %} documentation.{% else %}."{% endif %} -Dormant users do occupy a seat license. As such, you can choose to suspend dormant users to release user licenses. For more information, see "[Managing dormant users]({% ifversion not ghes %}/enterprise-server@latest{% endif %}/admin/user-management/managing-users-in-your-enterprise/managing-dormant-users){% ifversion not ghes %}" in the {% data variables.product.prodname_ghe_server %} documentation.{% else %}."{% endif %} +Dormant users do occupy a seat license. Administrators can suspend dormant users to free licenses. For more information, see "[Managing dormant users]({% ifversion not ghes %}/enterprise-server@latest{% endif %}/admin/user-management/managing-users-in-your-enterprise/managing-dormant-users){% ifversion not ghes %}" in the {% data variables.product.prodname_ghe_server %} documentation.{% else %}."{% endif %} {% endif %} diff --git a/content/contributing/style-guide-and-content-model/style-guide.md b/content/contributing/style-guide-and-content-model/style-guide.md index 9a7cf82df386..c0c60f06055e 100644 --- a/content/contributing/style-guide-and-content-model/style-guide.md +++ b/content/contributing/style-guide-and-content-model/style-guide.md @@ -217,6 +217,14 @@ Use italics to emphasize words or parts of a sentence. Use emphasis sparingly fo - **Use:** _For types of packages other than containers_, to the right of the package version click **Delete**. - **Avoid:** Next to _**Title**_, add a descriptive label for your new key. +## Error messages + +When you include the text of an error message from a {% data variables.product.company_short %} product or interface in an article, format the text according to the interface where the message appears. + +- If the message appears in {% data variables.product.prodname_dotcom %}'s web interface, or in a graphical client app like {% data variables.product.prodname_desktop %} or {% data variables.product.prodname_mobile %}, treat the message like other text in the UI. For more information, see "[User interface text](#user-interface-text)." + +- If the message appears in a command-line interface, log output, or a response from an API, reproduce the text exactly and use backticks to format the message using a monospaced font. + ## Footnotes Avoid using footnotes where possible. Consider instead whether you could use a [callout](#callouts) or present the information in another way. See some [examples of alternatives to footnotes from NICE.org.uk](https://www.nice.org.uk/corporate/ecd6/chapter/footnotes). @@ -841,6 +849,7 @@ A release note for a bug fix answers the following questions. - Language like "fixed a bug..." or "fixed an issue..." is implied and unnecessary. - To reduce repetition and unnecessary words, "now" is usually implied. - To clarify actors and impact, avoid passive language when possible. +- If the release note includes an error message, format the message according to the guidance in "[Error messages](#error-messages)." #### Examples of release notes for bug fixes @@ -896,6 +905,7 @@ A release note for a known issue answers the following questions. - To clarify actors and impact, avoid passive language when possible. - To reduce repetition and unnecessary words, "now" is usually implied. +- If the release note includes an error message, format the message according to the guidance in "[Error messages](#error-messages)." - If useful, include relevant links to GitHub Docs. - Known issues are also a type of content on GitHub Docs. For more information, see "[AUTOTITLE](/contributing/style-guide-and-content-model/troubleshooting-content-type#known-issues)." If useful, write or link to more in-depth and contextually relevant content in the docs. diff --git a/content/copilot/github-copilot-enterprise/copilot-chat-in-github/using-github-copilot-chat-in-githubcom.md b/content/copilot/github-copilot-enterprise/copilot-chat-in-github/using-github-copilot-chat-in-githubcom.md index de8dcb324ab0..774538dce470 100644 --- a/content/copilot/github-copilot-enterprise/copilot-chat-in-github/using-github-copilot-chat-in-githubcom.md +++ b/content/copilot/github-copilot-enterprise/copilot-chat-in-github/using-github-copilot-chat-in-githubcom.md @@ -26,7 +26,7 @@ On {% data variables.product.prodname_dotcom_the_website %}, you can use {% data The following limitations apply to this beta release of {% data variables.product.prodname_copilot_chat_dotcom %}: - {% data reusables.copilot.chat-limited-docset-availability %} -- Chat responses may be suboptimal if you ask questions about a specific repository that you've selected as a context, and the repository has not been indexed for semantic code search. Owners of organizations {% ifversion ghec %}or enterprises {% endif %} can index up to {% data variables.copilot.max-chat-indexed-repos %} repositories for each organization. +- Chat responses may be suboptimal if you ask questions about a specific repository that you've selected as a context, and the repository has not been indexed for semantic code search. Anyone who gets access to {% data variables.product.prodname_copilot_short %} from the organization that owns a repository can index that repository. Up to {% data variables.copilot.max-chat-indexed-repos %} repositories can be indexed for each organization. - The quality of the results from {% data variables.product.prodname_copilot_chat_short %} may, in some situations, be degraded if very large files, or a large number of files, are used as a context for a question. ## Prerequisites @@ -92,7 +92,7 @@ You can choose a specific context, such as a particular repository or a document {% data variables.product.prodname_copilot_short %}'s ability to answer natural language questions like these in a repository context is improved when the repository has been indexed for semantic code search. The indexing status of the repository is displayed when you start a conversation that has a repository context. - If you are an organization owner{% ifversion ghec %}, or an enterprise owner,{% endif %} and the repository has not been indexed, an **Index this repository** button is displayed. Click this button to start the indexing process. You can index up to {% data variables.copilot.max-chat-indexed-repos %} repositories in an organization. + If you get access to {% data variables.product.prodname_copilot_short %} from the organization that owns the repository, and the repository has not been indexed, an **Index this repository** button is displayed. Click this button to start the indexing process. Up to {% data variables.copilot.max-chat-indexed-repos %} repositories can be indexed for each organization. ![Screenshot showing the 'Index this repository' button highlighted with a dark orange outline.](/assets/images/help/copilot/index-this-repo.png) diff --git a/content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax.md b/content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax.md index e1f75f63567d..929017d32dd7 100644 --- a/content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax.md +++ b/content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax.md @@ -344,39 +344,32 @@ Footnotes are not supported in wikis. ## Alerts -Alerts are an extension of the blockquote syntax that you can use to emphasize critical information. On {% data variables.product.product_name %}, they are displayed with distinctive colors and icons to indicate the importance of the content. Alert syntax is supported in: -- Issues -- Pull requests -- Markdown files -- Discussions -- Gists -- Wikis -- Releases +Alerts are a Markdown extension based on the blockquote syntax that you can use to emphasize critical information. On {% data variables.product.product_name %}, they are displayed with distinctive colors and icons to indicate the significance of the content. -We recommend restricting the use of alerts to one or two per article to avoid overloading the reader. Consecutive alerts should be avoided. +Use alerts only when they are crucial for user success and limit them to one or two per article to prevent overloading the reader. Additionally, you should avoid placing alerts consecutively. Alerts cannot be nested within other elements. -Multiple types of alerts are available. You can add an alert with a special blockquote line that specifies the alert type, and then add the alert information in a standard blockquote immediately after. +To add an alert, use a special blockquote line specifying the alert type, followed by the alert information in a standard blockquote. Five types of alerts are available: ```markdown > [!NOTE] -> Highlights information that users should take into account, even when skimming. +> Useful information that users should know, even when skimming content. > [!TIP] -> Optional information to help a user be more successful. +> Helpful advice for doing things better or more easily. > [!IMPORTANT] -> Crucial information necessary for users to succeed. +> Key information users need to know to achieve their goal. > [!WARNING] -> Critical content demanding immediate user attention due to potential risks. +> Urgent info that needs immediate user attention to avoid problems. > [!CAUTION] -> Negative potential consequences of an action. +> Advises about risks or negative outcomes of certain actions. ``` -Here are the rendered alerts. +Here are the rendered alerts: -![Screenshot of rendered Markdown alerts showing how Note, Tips, Important, Warning, and Caution render with different colored text and icons.](/assets/images/help/writing/alerts-rendered.png) +![Screenshot of rendered Markdown alerts showing how Note, Tip, Important, Warning, and Caution render with different colored text and icons.](/assets/images/help/writing/alerts-rendered.png) {% endif %} diff --git a/content/issues/planning-and-tracking-with-projects/managing-your-project/adding-your-project-to-a-repository.md b/content/issues/planning-and-tracking-with-projects/managing-your-project/adding-your-project-to-a-repository.md index bb00a9a802ca..38a469c24901 100644 --- a/content/issues/planning-and-tracking-with-projects/managing-your-project/adding-your-project-to-a-repository.md +++ b/content/issues/planning-and-tracking-with-projects/managing-your-project/adding-your-project-to-a-repository.md @@ -17,6 +17,6 @@ In order for repository members to see a project listed in a repository, they mu 1. On {% data variables.product.prodname_dotcom %}, navigate to the main page of your repository. 1. Click {% octicon "table" aria-hidden="true" %} **Projects**. ![Screenshot showing a repository's tabs. The "Projects" tab is highlighted with an orange outline.](/assets/images/help/projects-v2/repo-tab.png) -1. Click **Link project**. +1. Click **Link a project**. 1. In the search bar that appears, search for projects that are owned by the same user or organization that owns the repository. 1. Click on a project to list it in your repository. diff --git a/content/organizations/managing-user-access-to-your-organizations-repositories/managing-outside-collaborators/adding-outside-collaborators-to-repositories-in-your-organization.md b/content/organizations/managing-user-access-to-your-organizations-repositories/managing-outside-collaborators/adding-outside-collaborators-to-repositories-in-your-organization.md index ece68a3301d0..edf00023dcbc 100644 --- a/content/organizations/managing-user-access-to-your-organizations-repositories/managing-outside-collaborators/adding-outside-collaborators-to-repositories-in-your-organization.md +++ b/content/organizations/managing-user-access-to-your-organizations-repositories/managing-outside-collaborators/adding-outside-collaborators-to-repositories-in-your-organization.md @@ -44,6 +44,8 @@ If your organization requires two-factor authentication, all outside collaborato Outside collaborators cannot be added to an {% data variables.enterprise.prodname_emu_enterprise %}. However, you can grant limited access to users outside your enterprise using the guest collaborator role. For more information, see "[AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/roles-in-an-enterprise#guest-collaborators)." {% endif %} +Outside collaborators cannot be added to a team, team membership is restricted to members of the organization. + ## Adding outside collaborators to a repository You can give outside collaborators access to a repository in your repository settings. For more information, see "[AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-teams-and-people-with-access-to-your-repository#inviting-a-team-or-person)." diff --git a/content/rest/overview/about-the-openapi-description-for-the-rest-api.md b/content/rest/about-the-rest-api/about-the-openapi-description-for-the-rest-api.md similarity index 97% rename from content/rest/overview/about-the-openapi-description-for-the-rest-api.md rename to content/rest/about-the-rest-api/about-the-openapi-description-for-the-rest-api.md index 7afa6d06f3ec..a3d04d7015b3 100644 --- a/content/rest/overview/about-the-openapi-description-for-the-rest-api.md +++ b/content/rest/about-the-rest-api/about-the-openapi-description-for-the-rest-api.md @@ -10,6 +10,7 @@ topics: - API redirect_from: - /rest/overview/openapi-description + - /rest/overview/about-the-openapi-description-for-the-rest-api --- ## About OpenAPI diff --git a/content/rest/overview/api-versions.md b/content/rest/about-the-rest-api/api-versions.md similarity index 98% rename from content/rest/overview/api-versions.md rename to content/rest/about-the-rest-api/api-versions.md index 9cb4ea02f20c..e767e7fd7262 100644 --- a/content/rest/overview/api-versions.md +++ b/content/rest/about-the-rest-api/api-versions.md @@ -4,6 +4,8 @@ shortTitle: API Versions intro: Learn how to specify which REST API version to use whenever you make a request to the REST API. versions: feature: api-date-versioning +redirect_from: + - /rest/overview/api-versions --- ## About API versioning diff --git a/content/rest/overview/breaking-changes.md b/content/rest/about-the-rest-api/breaking-changes.md similarity index 96% rename from content/rest/overview/breaking-changes.md rename to content/rest/about-the-rest-api/breaking-changes.md index 684729e4642e..619c3b9a2249 100644 --- a/content/rest/overview/breaking-changes.md +++ b/content/rest/about-the-rest-api/breaking-changes.md @@ -4,6 +4,8 @@ shortTitle: Breaking changes intro: Learn about breaking changes that were introduced in each REST API version. versions: feature: api-date-versioning +redirect_from: + - /rest/overview/breaking-changes --- ## About breaking changes in the REST API diff --git a/content/rest/overview/comparing-githubs-rest-api-and-graphql-api.md b/content/rest/about-the-rest-api/comparing-githubs-rest-api-and-graphql-api.md similarity index 98% rename from content/rest/overview/comparing-githubs-rest-api-and-graphql-api.md rename to content/rest/about-the-rest-api/comparing-githubs-rest-api-and-graphql-api.md index 4b66784181a1..5a676627702a 100644 --- a/content/rest/overview/comparing-githubs-rest-api-and-graphql-api.md +++ b/content/rest/about-the-rest-api/comparing-githubs-rest-api-and-graphql-api.md @@ -8,6 +8,7 @@ redirect_from: - /github/extending-github/getting-started-with-the-api - /developers/overview/about-githubs-apis - /rest/overview/about-githubs-apis + - /rest/overview/comparing-githubs-rest-api-and-graphql-api versions: fpt: '*' ghes: '*' diff --git a/content/rest/about-the-rest-api/index.md b/content/rest/about-the-rest-api/index.md new file mode 100644 index 000000000000..4ecfeadf3479 --- /dev/null +++ b/content/rest/about-the-rest-api/index.md @@ -0,0 +1,19 @@ +--- +title: About the REST API +intro: 'Learn more about the {% data variables.product.prodname_dotcom %} REST API and what you can do with it.' +versions: + fpt: '*' + ghes: '*' + ghae: '*' + ghec: '*' +topics: + - API +children: + - /comparing-githubs-rest-api-and-graphql-api + - /api-versions + - /breaking-changes + - /about-the-openapi-description-for-the-rest-api +autogenerated: rest +--- + + diff --git a/content/rest/overview/authenticating-to-the-rest-api.md b/content/rest/authentication/authenticating-to-the-rest-api.md similarity index 99% rename from content/rest/overview/authenticating-to-the-rest-api.md rename to content/rest/authentication/authenticating-to-the-rest-api.md index 4636a96d4855..1d34f2af4475 100644 --- a/content/rest/overview/authenticating-to-the-rest-api.md +++ b/content/rest/authentication/authenticating-to-the-rest-api.md @@ -4,6 +4,7 @@ intro: You can authenticate to the REST API to access more endpoints and have a redirect_from: - /v3/auth - /rest/overview/other-authentication-methods + - /rest/overview/authenticating-to-the-rest-api versions: fpt: '*' ghes: '*' diff --git a/content/rest/overview/endpoints-available-for-fine-grained-personal-access-tokens.md b/content/rest/authentication/endpoints-available-for-fine-grained-personal-access-tokens.md similarity index 68% rename from content/rest/overview/endpoints-available-for-fine-grained-personal-access-tokens.md rename to content/rest/authentication/endpoints-available-for-fine-grained-personal-access-tokens.md index daa5c382a8af..c3cdc9b21e3f 100644 --- a/content/rest/overview/endpoints-available-for-fine-grained-personal-access-tokens.md +++ b/content/rest/authentication/endpoints-available-for-fine-grained-personal-access-tokens.md @@ -3,8 +3,10 @@ title: Endpoints available for fine-grained personal access tokens intro: 'Your {% data variables.product.pat_v2 %} can make requests to the following REST endpoints.' versions: feature: pat-v2 -shortTitle: 'Endpoints for fine-grained PATs' +shortTitle: Endpoints for fine-grained PATs autogenerated: github-apps +redirect_from: + - /rest/overview/endpoints-available-for-fine-grained-personal-access-tokens --- diff --git a/content/rest/overview/endpoints-available-for-github-app-installation-access-tokens.md b/content/rest/authentication/endpoints-available-for-github-app-installation-access-tokens.md similarity index 91% rename from content/rest/overview/endpoints-available-for-github-app-installation-access-tokens.md rename to content/rest/authentication/endpoints-available-for-github-app-installation-access-tokens.md index a9409a9b2291..9397d5b3958d 100644 --- a/content/rest/overview/endpoints-available-for-github-app-installation-access-tokens.md +++ b/content/rest/authentication/endpoints-available-for-github-app-installation-access-tokens.md @@ -7,6 +7,7 @@ redirect_from: - /v3/apps/available-endpoints - /rest/reference/endpoints-available-for-github-apps - /rest/overview/endpoints-available-for-github-apps + - /rest/overview/endpoints-available-for-github-app-installation-access-tokens versions: fpt: '*' ghes: '*' diff --git a/content/rest/overview/endpoints-available-for-github-app-user-access-tokens.md b/content/rest/authentication/endpoints-available-for-github-app-user-access-tokens.md similarity index 76% rename from content/rest/overview/endpoints-available-for-github-app-user-access-tokens.md rename to content/rest/authentication/endpoints-available-for-github-app-user-access-tokens.md index b6672fda18ee..b2970dd1f632 100644 --- a/content/rest/overview/endpoints-available-for-github-app-user-access-tokens.md +++ b/content/rest/authentication/endpoints-available-for-github-app-user-access-tokens.md @@ -1,7 +1,7 @@ --- title: Endpoints available for GitHub App user access tokens shortTitle: Endpoints for GitHub App user tokens -intro: 'Your GitHub App can make requests to the following REST endpoints with a user access token.' +intro: Your GitHub App can make requests to the following REST endpoints with a user access token. permissions: 'You can use a user access token to access these endpoints using your {% data variables.product.prodname_github_app %}. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-a-github-app-on-behalf-of-a-user)."' versions: fpt: '*' @@ -12,6 +12,8 @@ topics: - API - GitHub Apps autogenerated: github-apps +redirect_from: + - /rest/overview/endpoints-available-for-github-app-user-access-tokens --- diff --git a/content/rest/overview/index.md b/content/rest/authentication/index.md similarity index 50% rename from content/rest/overview/index.md rename to content/rest/authentication/index.md index 1fa5e8699b09..ef89d85e04ce 100644 --- a/content/rest/overview/index.md +++ b/content/rest/authentication/index.md @@ -1,7 +1,7 @@ --- -title: REST API overview -shortTitle: Overview -intro: 'Learn about resources, libraries, previews and troubleshooting for {% data variables.product.prodname_dotcom %}''s REST API.' +title: Authenticating to the REST API +shortTitle: Authentication +intro: 'Learn how to authenticate your REST API requests.' versions: fpt: '*' ghes: '*' @@ -10,25 +10,11 @@ versions: topics: - API children: - - /comparing-githubs-rest-api-and-graphql-api - - /resources-in-the-rest-api - - /rate-limits-for-the-rest-api - - /api-versions - - /media-types - /authenticating-to-the-rest-api - /keeping-your-api-credentials-secure - - /troubleshooting-the-rest-api - - /libraries-for-the-rest-api - - /about-the-openapi-description-for-the-rest-api - - /issue-event-types - - /github-event-types - /endpoints-available-for-github-app-installation-access-tokens - /endpoints-available-for-github-app-user-access-tokens - /endpoints-available-for-fine-grained-personal-access-tokens - /permissions-required-for-github-apps - /permissions-required-for-fine-grained-personal-access-tokens - - /breaking-changes -redirect_from: - - /developers/overview --- - diff --git a/content/rest/overview/keeping-your-api-credentials-secure.md b/content/rest/authentication/keeping-your-api-credentials-secure.md similarity index 97% rename from content/rest/overview/keeping-your-api-credentials-secure.md rename to content/rest/authentication/keeping-your-api-credentials-secure.md index 95f6b39c6dc3..d0d3b0188c43 100644 --- a/content/rest/overview/keeping-your-api-credentials-secure.md +++ b/content/rest/authentication/keeping-your-api-credentials-secure.md @@ -1,7 +1,7 @@ --- title: Keeping your API credentials secure shortTitle: Keeping API credentials secure -intro: 'Follow these best practices to keep your API credentials and tokens secure.' +intro: Follow these best practices to keep your API credentials and tokens secure. versions: fpt: '*' ghes: '*' @@ -9,6 +9,8 @@ versions: ghec: '*' topics: - API +redirect_from: + - /rest/overview/keeping-your-api-credentials-secure --- ## Choose an appropriate authentication method diff --git a/content/rest/overview/permissions-required-for-fine-grained-personal-access-tokens.md b/content/rest/authentication/permissions-required-for-fine-grained-personal-access-tokens.md similarity index 89% rename from content/rest/overview/permissions-required-for-fine-grained-personal-access-tokens.md rename to content/rest/authentication/permissions-required-for-fine-grained-personal-access-tokens.md index 4d65c545beb2..1a701245ce03 100644 --- a/content/rest/overview/permissions-required-for-fine-grained-personal-access-tokens.md +++ b/content/rest/authentication/permissions-required-for-fine-grained-personal-access-tokens.md @@ -3,8 +3,10 @@ title: Permissions required for fine-grained personal access tokens intro: 'These are the permissions required for a {% data variables.product.pat_v2 %} to use each REST API endpoint that works with {% data variables.product.pat_v2 %}s.' versions: feature: pat-v2 -shortTitle: 'Permissions for fine-grained PATs' +shortTitle: Permissions for fine-grained PATs autogenerated: github-apps +redirect_from: + - /rest/overview/permissions-required-for-fine-grained-personal-access-tokens --- ## About permissions required for {% data variables.product.pat_v2 %} diff --git a/content/rest/overview/permissions-required-for-github-apps.md b/content/rest/authentication/permissions-required-for-github-apps.md similarity index 96% rename from content/rest/overview/permissions-required-for-github-apps.md rename to content/rest/authentication/permissions-required-for-github-apps.md index 3f1ad9cbc437..4e9d7aa54a9d 100644 --- a/content/rest/overview/permissions-required-for-github-apps.md +++ b/content/rest/authentication/permissions-required-for-github-apps.md @@ -4,6 +4,7 @@ intro: 'These are the permissions required for a {% data variables.product.prodn redirect_from: - /v3/apps/permissions - /rest/reference/permissions-required-for-github-apps + - /rest/overview/permissions-required-for-github-apps versions: fpt: '*' ghes: '*' diff --git a/content/rest/guides/index.md b/content/rest/guides/index.md index c2ec86152c7e..d77919954ed8 100644 --- a/content/rest/guides/index.md +++ b/content/rest/guides/index.md @@ -12,16 +12,13 @@ versions: topics: - API children: - - /getting-started-with-the-rest-api - /scripting-with-the-rest-api-and-javascript - /scripting-with-the-rest-api-and-ruby - /discovering-resources-for-a-user - /delivering-deployments - /rendering-data-as-graphs - /working-with-comments - - /using-pagination-in-the-rest-api - /building-a-ci-server - - /best-practices-for-using-the-rest-api - /using-the-rest-api-to-interact-with-your-git-database - /using-the-rest-api-to-interact-with-checks - /encrypting-secrets-for-the-rest-api diff --git a/content/rest/index.md b/content/rest/index.md index 59946f3169c2..12a94b71f6ec 100644 --- a/content/rest/index.md +++ b/content/rest/index.md @@ -1,35 +1,35 @@ --- title: GitHub REST API documentation shortTitle: REST API -intro: >- - To create integrations, retrieve data, and automate your workflows, build with - the {% data variables.product.prodname_dotcom %} REST API. +intro: 'Create integrations, retrieve data, and automate your workflows with the {% data variables.product.prodname_dotcom %} REST API.' introLinks: quickstart: /rest/quickstart - overview: /rest/guides/getting-started-with-the-rest-api + overview: /rest/using-the-rest-api/getting-started-with-the-rest-api featuredLinks: startHere: - - /rest/guides/getting-started-with-the-rest-api - - /rest/overview/authenticating-to-the-rest-api - - /rest/guides/best-practices-for-using-the-rest-api - - /rest/guides/using-pagination-in-the-rest-api + - /rest/using-the-rest-api/getting-started-with-the-rest-api + - /rest/authentication/authenticating-to-the-rest-api + - /rest/using-the-rest-api/best-practices-for-using-the-rest-api + - /rest/using-the-rest-api/using-pagination-in-the-rest-api popular: - - /rest/overview/rate-limits-for-the-rest-api - - /rest/overview/api-versions - - /rest/overview/authenticating-to-the-rest-api - - /rest/overview/troubleshooting-the-rest-api + - /rest/using-the-rest-api/rate-limits-for-the-rest-api + - /rest/about-the-rest-api/api-versions + - /rest/authentication/authenticating-to-the-rest-api + - /rest/using-the-rest-api/troubleshooting-the-rest-api - /rest/guides/scripting-with-the-rest-api-and-javascript - - /rest/overview/keeping-your-api-credentials-secure + - /rest/authentication/keeping-your-api-credentials-secure guideCards: - /rest/guides/delivering-deployments - /rest/guides/using-the-rest-api-to-interact-with-checks - - /rest/guides/using-pagination-in-the-rest-api + - /rest/using-the-rest-api/using-pagination-in-the-rest-api changelog: label: 'api, apis' layout: product-landing redirect_from: - /v3 - /rest/reference + - /rest/overview + - /developers/overview versions: fpt: '*' ghes: '*' @@ -37,7 +37,9 @@ versions: ghec: '*' children: - /quickstart - - /overview + - /about-the-rest-api + - /using-the-rest-api + - /authentication - /guides - /actions - /activity diff --git a/content/rest/guides/best-practices-for-using-the-rest-api.md b/content/rest/using-the-rest-api/best-practices-for-using-the-rest-api.md similarity index 99% rename from content/rest/guides/best-practices-for-using-the-rest-api.md rename to content/rest/using-the-rest-api/best-practices-for-using-the-rest-api.md index 0cec5eaf8734..e22bd616376c 100644 --- a/content/rest/guides/best-practices-for-using-the-rest-api.md +++ b/content/rest/using-the-rest-api/best-practices-for-using-the-rest-api.md @@ -5,6 +5,7 @@ redirect_from: - /guides/best-practices-for-integrators - /v3/guides/best-practices-for-integrators - /rest/guides/best-practices-for-integrators + - /rest/guides/best-practices-for-using-the-rest-api versions: fpt: '*' ghes: '*' diff --git a/content/rest/guides/getting-started-with-the-rest-api.md b/content/rest/using-the-rest-api/getting-started-with-the-rest-api.md similarity index 99% rename from content/rest/guides/getting-started-with-the-rest-api.md rename to content/rest/using-the-rest-api/getting-started-with-the-rest-api.md index 16c54db78565..cb4726229ee7 100644 --- a/content/rest/guides/getting-started-with-the-rest-api.md +++ b/content/rest/using-the-rest-api/getting-started-with-the-rest-api.md @@ -1,6 +1,6 @@ --- title: Getting started with the REST API -shortTitle: Using the API +shortTitle: Getting started intro: 'Learn how to use the {% data variables.product.prodname_dotcom %} REST API.' versions: fpt: '*' @@ -9,6 +9,8 @@ versions: ghec: '*' topics: - API +redirect_from: + - /rest/guides/getting-started-with-the-rest-api --- ## Introduction diff --git a/content/rest/overview/github-event-types.md b/content/rest/using-the-rest-api/github-event-types.md similarity index 99% rename from content/rest/overview/github-event-types.md rename to content/rest/using-the-rest-api/github-event-types.md index 958462a5cae6..ec241435b105 100644 --- a/content/rest/overview/github-event-types.md +++ b/content/rest/using-the-rest-api/github-event-types.md @@ -7,6 +7,7 @@ redirect_from: - /developers/webhooks-and-events/events/github-event-types - /webhooks-and-events/events/github-event-types - /developers/webhooks-and-events/events + - /rest/overview/github-event-types versions: fpt: '*' ghes: '*' diff --git a/content/rest/using-the-rest-api/index.md b/content/rest/using-the-rest-api/index.md new file mode 100644 index 000000000000..3a4755645bec --- /dev/null +++ b/content/rest/using-the-rest-api/index.md @@ -0,0 +1,22 @@ +--- +title: Using the REST API +intro: 'Learn how to use the {% data variables.product.prodname_dotcom %} REST API, follow best practices, and troubleshoot problems.' +versions: + fpt: '*' + ghes: '*' + ghae: '*' + ghec: '*' +topics: + - API +children: + - /getting-started-with-the-rest-api + - /rate-limits-for-the-rest-api + - /resources-in-the-rest-api + - /using-pagination-in-the-rest-api + - /libraries-for-the-rest-api + - /media-types + - /best-practices-for-using-the-rest-api + - /troubleshooting-the-rest-api + - /issue-event-types + - /github-event-types +--- diff --git a/content/rest/overview/issue-event-types.md b/content/rest/using-the-rest-api/issue-event-types.md similarity index 99% rename from content/rest/overview/issue-event-types.md rename to content/rest/using-the-rest-api/issue-event-types.md index 121c4fed8f1b..b36926590cd2 100644 --- a/content/rest/overview/issue-event-types.md +++ b/content/rest/using-the-rest-api/issue-event-types.md @@ -6,6 +6,7 @@ redirect_from: - /developers/webhooks-and-events/issue-event-types - /developers/webhooks-and-events/events/issue-event-types - /webhooks-and-events/events/issue-event-types + - /rest/overview/issue-event-types versions: fpt: '*' ghes: '*' diff --git a/content/rest/overview/libraries-for-the-rest-api.md b/content/rest/using-the-rest-api/libraries-for-the-rest-api.md similarity index 99% rename from content/rest/overview/libraries-for-the-rest-api.md rename to content/rest/using-the-rest-api/libraries-for-the-rest-api.md index 7fea288445d3..78f7705c9b76 100644 --- a/content/rest/overview/libraries-for-the-rest-api.md +++ b/content/rest/using-the-rest-api/libraries-for-the-rest-api.md @@ -6,6 +6,7 @@ redirect_from: - /libraries - /v3/libraries - /rest/overview/libraries + - /rest/overview/libraries-for-the-rest-api versions: fpt: '*' ghes: '*' diff --git a/content/rest/overview/media-types.md b/content/rest/using-the-rest-api/media-types.md similarity index 99% rename from content/rest/overview/media-types.md rename to content/rest/using-the-rest-api/media-types.md index a577a59d72a2..1e978757e3bd 100644 --- a/content/rest/overview/media-types.md +++ b/content/rest/using-the-rest-api/media-types.md @@ -3,6 +3,7 @@ title: Media types intro: Learn about media types for specifying the format of the data you want to consume. redirect_from: - /v3/media + - /rest/overview/media-types versions: fpt: '*' ghes: '*' diff --git a/content/rest/overview/rate-limits-for-the-rest-api.md b/content/rest/using-the-rest-api/rate-limits-for-the-rest-api.md similarity index 99% rename from content/rest/overview/rate-limits-for-the-rest-api.md rename to content/rest/using-the-rest-api/rate-limits-for-the-rest-api.md index 42b314e33fd1..6fcaab4c98f7 100644 --- a/content/rest/overview/rate-limits-for-the-rest-api.md +++ b/content/rest/using-the-rest-api/rate-limits-for-the-rest-api.md @@ -9,6 +9,8 @@ versions: ghec: '*' topics: - API +redirect_from: + - /rest/overview/rate-limits-for-the-rest-api --- {% ifversion ghes %} diff --git a/content/rest/overview/resources-in-the-rest-api.md b/content/rest/using-the-rest-api/resources-in-the-rest-api.md similarity index 99% rename from content/rest/overview/resources-in-the-rest-api.md rename to content/rest/using-the-rest-api/resources-in-the-rest-api.md index e6b887f102fa..8904961ba10a 100644 --- a/content/rest/overview/resources-in-the-rest-api.md +++ b/content/rest/using-the-rest-api/resources-in-the-rest-api.md @@ -3,6 +3,7 @@ title: Resources in the REST API intro: 'Learn how to navigate the resources provided by the {% ifversion fpt or ghec %}{% data variables.product.prodname_dotcom %}{% else %}{% data variables.product.product_name %}{% endif %} API.' redirect_from: - /rest/initialize-the-repo + - /rest/overview/resources-in-the-rest-api versions: fpt: '*' ghes: '*' diff --git a/content/rest/overview/troubleshooting-the-rest-api.md b/content/rest/using-the-rest-api/troubleshooting-the-rest-api.md similarity index 99% rename from content/rest/overview/troubleshooting-the-rest-api.md rename to content/rest/using-the-rest-api/troubleshooting-the-rest-api.md index 3a855334c804..75345d452a5f 100644 --- a/content/rest/overview/troubleshooting-the-rest-api.md +++ b/content/rest/using-the-rest-api/troubleshooting-the-rest-api.md @@ -5,6 +5,7 @@ intro: Learn how to diagnose and resolve common problems for the REST API. redirect_from: - /v3/troubleshooting - /rest/overview/troubleshooting + - /rest/overview/troubleshooting-the-rest-api versions: fpt: '*' ghes: '*' diff --git a/content/rest/guides/using-pagination-in-the-rest-api.md b/content/rest/using-the-rest-api/using-pagination-in-the-rest-api.md similarity index 99% rename from content/rest/guides/using-pagination-in-the-rest-api.md rename to content/rest/using-the-rest-api/using-pagination-in-the-rest-api.md index 832d07bf1582..c1487dd2692e 100644 --- a/content/rest/guides/using-pagination-in-the-rest-api.md +++ b/content/rest/using-the-rest-api/using-pagination-in-the-rest-api.md @@ -5,6 +5,7 @@ redirect_from: - /guides/traversing-with-pagination - /v3/guides/traversing-with-pagination - /rest/guides/traversing-with-pagination + - /rest/guides/using-pagination-in-the-rest-api versions: fpt: '*' ghes: '*' diff --git a/content/sponsors/receiving-sponsorships-through-github-sponsors/tax-information-for-github-sponsors.md b/content/sponsors/receiving-sponsorships-through-github-sponsors/tax-information-for-github-sponsors.md index 737c5620187c..1703e9455890 100644 --- a/content/sponsors/receiving-sponsorships-through-github-sponsors/tax-information-for-github-sponsors.md +++ b/content/sponsors/receiving-sponsorships-through-github-sponsors/tax-information-for-github-sponsors.md @@ -16,11 +16,11 @@ shortTitle: Tax information ## W-9/W-8 tax forms -By law, {% data variables.product.prodname_dotcom %} is required by the U.S. Internal Revenue Service (IRS) to collect tax information from all U.S. and non-U.S. maintainers. These forms are held by {% data variables.product.prodname_dotcom %} and are not required to be submitted to the IRS. +By law, {% data variables.product.prodname_dotcom %} is required by the U.S. Internal Revenue Service (IRS) to collect tax information from all U.S. and non-U.S. maintainers. These forms are held by Stripe and are not required to be submitted to the IRS. ### W-9 (U.S.) -The information from W-9 tax forms helps {% data variables.product.prodname_dotcom %} use the correct Taxpayer Identification Number (TIN) to report income paid to you to the IRS in a 1099 form. +The information from W-9 tax forms helps Stripe use the correct Taxpayer Identification Number (TIN) to report income paid to you to the IRS in a 1099 form. If you are a taxpayer in the United States, you must submit a [W-9](https://www.irs.gov/forms-pubs/about-form-w-9) before you can publish your {% data variables.product.prodname_sponsors %} profile. @@ -28,9 +28,9 @@ If you are a taxpayer in the United States, you must submit a [W-9](https://www. W-8 BEN and W-8 BEN-E tax forms help {% data variables.product.prodname_dotcom %} determine the beneficial owner of an amount subject to withholding. -If you are a taxpayer in any other region besides the United States, you must submit a [W-8 BEN](https://www.irs.gov/pub/irs-pdf/fw8ben.pdf) (individual) or [W-8 BEN-E](https://www.irs.gov/forms-pubs/about-form-w-8-ben-e) (company) form before you can publish your {% data variables.product.prodname_sponsors %} profile. For more information, see "[AUTOTITLE](/sponsors/receiving-sponsorships-through-github-sponsors/setting-up-github-sponsors-for-your-personal-account#submitting-your-tax-information)" and "[AUTOTITLE](/sponsors/receiving-sponsorships-through-github-sponsors/setting-up-github-sponsors-for-your-organization#submitting-your-tax-information)." {% data variables.product.prodname_dotcom %} will send you the appropriate forms, notify you when they are due, and give you a reasonable amount of time to complete and send in the forms. +If you are a taxpayer in any other region besides the United States, you must submit a [W-8 BEN](https://www.irs.gov/pub/irs-pdf/fw8ben.pdf) (individual) or [W-8 BEN-E](https://www.irs.gov/forms-pubs/about-form-w-8-ben-e) (company) form before you can publish your {% data variables.product.prodname_sponsors %} profile. For more information, see "[AUTOTITLE](/sponsors/receiving-sponsorships-through-github-sponsors/setting-up-github-sponsors-for-your-personal-account#submitting-your-tax-information)" and "[AUTOTITLE](/sponsors/receiving-sponsorships-through-github-sponsors/setting-up-github-sponsors-for-your-organization#submitting-your-tax-information)." Stripe will send you the appropriate forms, notify you when they are due, and give you a reasonable amount of time to complete and send in the forms. -If you have been assigned an incorrect tax form, contact us through the {% data variables.contact.contact_support_portal %} to get reassigned the correct one for your situation. +If you have been assigned an incorrect tax form, you can contact Stripe to get reassigned the correct one for your situation. For more information, see [Contact Us](https://support.stripe.com/contact/email?topic=connect) on the Stripe Support site. ### Tax identification numbers @@ -61,7 +61,7 @@ If you are a taxpayer in the United States and earn more than 600 US dollars in ## Sales tax -GitHub is providing information to assist you in calculating your sales tax obligations. This information is not personalized to your country or tax situation and we recommend you talk to a professional to understand your specific obligations. However, we'd like to provide some high-level information to help you understand the general principles of digital sales tax. +{% data variables.product.prodname_dotcom %} is providing information to assist you in calculating your sales tax obligations. This information is not personalized to your country or tax situation and we recommend you talk to a professional to understand your specific obligations. However, we'd like to provide some high-level information to help you understand the general principles of digital sales tax. In most countries around the world, sales tax for digital transactions is based on the location of the recipient, not on the seller. For example, if you are a maintainer in the United States and you provide a taxable benefit to a Sponsor in Germany, German sales tax would apply. @@ -73,4 +73,4 @@ In the EU and most other countries and regions, B2C sales are subject to sales t ## Further reading -- [Viewing your sponsors and sponsorships](/sponsors/receiving-sponsorships-through-github-sponsors/viewing-your-sponsors-and-sponsorships) +- "[AUTOTITLE](/sponsors/receiving-sponsorships-through-github-sponsors/viewing-your-sponsors-and-sponsorships)" diff --git a/src/code-scanning/README.md b/src/code-scanning/README.md new file mode 100644 index 000000000000..2dbadbf1306d --- /dev/null +++ b/src/code-scanning/README.md @@ -0,0 +1,64 @@ +# Code scanning query tables + +This nascent pipeline creates autogenerated documentation docs.github.com from the query suites included with the [CodeQL bundle](https://github.com/github/codeql-action/releases). + +The pipeline is used to generate Markdown tables that are stored in reusable files and used in article pages on the docs.github.com site. + +## How does it work + +```mermaid +--- +title: "Process for generating Code scanning query tables" +--- +flowchart TB + +accDescr: A flow chart describing how the automation generates documentation for code scanning queries. + + start([Start]) --> checkout[Checkout the codeql repository] + start --- download[Download the CodeQL CLI] + checkout --- query-suites[fa:fa-file Query suites *.qls] + query-suites ---> generate[Generate tables:src/code-scanning/scripts/generate-code-scanning-query-lists.ts] + download --- codeql-cli[CodeQL CLI: codeql.exe] + codeql-cli --> generate + generate --- markdown[fa:fa-file Reusable files *.md] + markdown --> pr[Generate a PR overwriting:data/reusables/code-scanning/codeql-query-tables/*.md] + pr --> finish([End]) + +%% Define styles + classDef start fill:#1AAC9D, color:white + classDef action fill:#6557F6, color:white + classDef finish fill:#F8C324, color:white + classDef file fill:#ddd + +%% Assign styles + class start start; + class finish finish; + class checkout,download,generate,pr action; + class markdown,query-suites,codeql-cli file; +``` + +A [workflow](.github/workflows/generate-code-scanning-query-lists.yml) is used to trigger the automation of the code scanning query tables documentation. The workflow is manually triggered by a member of the GitHub Docs team approximately every two weeks to align to releases of the CodeQL CLI. The workflow takes an input parameter that specifies the branch to pull the source files from in the semmle-code repo. If the branch input is omitted, the workflow will default to the `main` branch. + +The workflow runs the `npm run generate-code-scanning-query-list` script, which generates Markdown files under `data/reusables/code-scanning/codeql-query-tables`. + +The workflow automatically creates a new pull request with the changes and the label `codeql-query-tables`. + +## Local development + +To run the pipeline locally, see the comments in the [script](scripts/generate-code-scanning-query-list.ts). + +## Content team + +The content writers can use the reusables in any content article. They have no need to make any changes to the script unless additional built-in query suites are added. + +## How to get help + +### For workflow and script problems + +Slack: `#docs-engineering` +Repo: `github/docs-engineering` + +### For CodeQL repository and CLI problems + +Slack: `#code-scanning-internal-dx` +Repo: `github/code-scanning-internal-dx-team` diff --git a/src/fixtures/fixtures/content/rest/overview/about-githubs-apis.md b/src/fixtures/fixtures/content/rest/about-the-rest-api/comparing-githubs-rest-api-and-graphql-api.md similarity index 100% rename from src/fixtures/fixtures/content/rest/overview/about-githubs-apis.md rename to src/fixtures/fixtures/content/rest/about-the-rest-api/comparing-githubs-rest-api-and-graphql-api.md diff --git a/src/fixtures/fixtures/content/rest/overview/index.md b/src/fixtures/fixtures/content/rest/about-the-rest-api/index.md similarity index 84% rename from src/fixtures/fixtures/content/rest/overview/index.md rename to src/fixtures/fixtures/content/rest/about-the-rest-api/index.md index 3562c0e09636..36340c4bbdcf 100644 --- a/src/fixtures/fixtures/content/rest/overview/index.md +++ b/src/fixtures/fixtures/content/rest/about-the-rest-api/index.md @@ -8,5 +8,5 @@ versions: ghae: '*' ghec: '*' children: - - /about-githubs-apis + - /comparing-githubs-rest-api-and-graphql-api --- diff --git a/src/fixtures/fixtures/content/rest/index.md b/src/fixtures/fixtures/content/rest/index.md index 678acad855d3..e591e8931b27 100644 --- a/src/fixtures/fixtures/content/rest/index.md +++ b/src/fixtures/fixtures/content/rest/index.md @@ -5,10 +5,10 @@ intro: >- To create integrations, retrieve data, and automate your workflows, build with the {% data variables.product.prodname_dotcom %} REST API. introLinks: - quickstart: /rest/overview + quickstart: /rest featuredLinks: popular: - - /rest/overview/about-githubs-apis + - /rest/about-the-rest-api/comparing-githubs-rest-api-and-graphql-api changelog: label: 'api, apis' layout: product-landing @@ -18,7 +18,7 @@ versions: ghae: '*' ghec: '*' children: - - /overview + - /about-the-rest-api - /actions --- diff --git a/src/fixtures/fixtures/rest-redirects.json b/src/fixtures/fixtures/rest-redirects.json index 9178ef1db688..94540bc4a297 100644 --- a/src/fixtures/fixtures/rest-redirects.json +++ b/src/fixtures/fixtures/rest-redirects.json @@ -393,7 +393,7 @@ "/v3/actions/workflow-jobs": "/en/rest/actions/workflow-jobs", "/v3/actions/workflow-runs": "/en/rest/actions/workflow-runs", "/v3/actions/workflows": "/en/rest/actions/workflows", - "/v3/activity/event_types": "/en/rest/overview/github-event-types", + "/v3/activity/event_types": "/en/rest/using-the-rest-api/github-event-types", "/v3/activity/events/types": "/en/webhooks/webhook-events-and-payloads", "/v3/activity/events": "/en/rest/activity/events", "/v3/activity/feeds": "/en/rest/activity/feeds", @@ -401,12 +401,12 @@ "/v3/activity/notifications": "/en/rest/activity/notifications", "/v3/activity/starring": "/en/rest/activity/starring", "/v3/activity/watching": "/en/rest/activity/watching", - "/v3/apps/available-endpoints": "/en/rest/overview/endpoints-available-for-github-app-installation-access-tokens", + "/v3/apps/available-endpoints": "/en/rest/authentication/endpoints-available-for-github-app-installation-access-tokens", "/v3/apps": "/en/rest/apps", "/v3/apps/installations": "/en/rest/apps/installations", "/v3/apps/marketplace": "/en/rest/apps/marketplace", "/v3/apps/oauth_applications": "/en/rest/apps/oauth-applications", - "/v3/apps/permissions": "/en/rest/overview/permissions-required-for-github-apps", + "/v3/apps/permissions": "/en/rest/authentication/permissions-required-for-github-apps", "/v3/checks": "/en/rest/checks", "/v3/checks/runs": "/en/rest/checks/runs", "/v3/checks/suites": "/en/rest/checks/suites", @@ -440,7 +440,7 @@ "/v3/issues/comments": "/en/rest/issues/comments", "/v3/issues/events": "/en/rest/issues/events", "/v3/issues": "/en/rest/issues", - "/v3/issues/issue-event-types": "/en/rest/overview/issue-event-types", + "/v3/issues/issue-event-types": "/en/rest/using-the-rest-api/issue-event-types", "/v3/issues/labels": "/en/rest/issues/labels", "/v3/issues/milestones": "/en/rest/issues/milestones", "/v3/issues/timeline": "/en/rest/issues/timeline", diff --git a/src/fixtures/tests/playwright-a11y.spec.ts b/src/fixtures/tests/playwright-a11y.spec.ts index 6813db989d0c..44957ed7e560 100644 --- a/src/fixtures/tests/playwright-a11y.spec.ts +++ b/src/fixtures/tests/playwright-a11y.spec.ts @@ -13,7 +13,7 @@ const pages: { [key: string]: string } = { productLanding: '/code-security', restCategory: '/rest/actions/artifacts', restLanding: '/rest', - restOverview: '/rest/overview/about-githubs-apis', + restOverview: '/rest/about-the-rest-api/comparing-githubs-rest-api-and-graphql-api', search: '/search?q=playwright', switchers: '/get-started/liquid/tool-platform-switcher', tableWithHeaders: '/get-started/liquid/table-row-headers', diff --git a/src/github-apps/lib/config.json b/src/github-apps/lib/config.json index 81ea3eedec7e..4ef0ef64dc6e 100644 --- a/src/github-apps/lib/config.json +++ b/src/github-apps/lib/config.json @@ -1,5 +1,5 @@ { - "targetDirectory": "content/rest/overview", + "targetDirectory": "content/rest/authentication", "pages": { "server-to-server-rest": { "frontmatterDefaults": { @@ -11,7 +11,7 @@ }, "autogenerated": "github-apps" }, - "targetFilename": "content/rest/overview/endpoints-available-for-github-app-installation-access-tokens.md" + "targetFilename": "content/rest/authentication/endpoints-available-for-github-app-installation-access-tokens.md" }, "user-to-server-rest": { "frontmatterDefaults": { @@ -23,7 +23,7 @@ }, "autogenerated": "github-apps" }, - "targetFilename": "content/rest/overview/endpoints-available-for-github-app-user-access-tokens.md" + "targetFilename": "content/rest/authentication/endpoints-available-for-github-app-user-access-tokens.md" }, "server-to-server-permissions": { "frontmatterDefaults": { @@ -35,21 +35,21 @@ }, "autogenerated": "github-apps" }, - "targetFilename": "content/rest/overview/permissions-required-for-github-apps.md" + "targetFilename": "content/rest/authentication/permissions-required-for-github-apps.md" }, "fine-grained-pat": { "frontmatterDefaults": { "versions": "data/features/pat-v2.yml", "autogenerated": "github-apps" }, - "targetFilename": "content/rest/overview/endpoints-available-for-fine-grained-personal-access-tokens.md" + "targetFilename": "content/rest/authentication/endpoints-available-for-fine-grained-personal-access-tokens.md" }, "fine-grained-pat-permissions": { "frontmatterDefaults": { "versions": "data/features/pat-v2.yml", "autogenerated": "github-apps" }, - "targetFilename": "content/rest/overview/permissions-required-for-fine-grained-personal-access-tokens.md" + "targetFilename": "content/rest/authentication/permissions-required-for-fine-grained-personal-access-tokens.md" } }, "api-versions": { diff --git a/src/pages/[versionId]/rest/overview/[...restPage].tsx b/src/pages/[versionId]/rest/about-the-rest-api/[...restPage].tsx similarity index 100% rename from src/pages/[versionId]/rest/overview/[...restPage].tsx rename to src/pages/[versionId]/rest/about-the-rest-api/[...restPage].tsx diff --git a/src/pages/[versionId]/rest/overview/index.tsx b/src/pages/[versionId]/rest/about-the-rest-api/index.tsx similarity index 100% rename from src/pages/[versionId]/rest/overview/index.tsx rename to src/pages/[versionId]/rest/about-the-rest-api/index.tsx diff --git a/src/pages/[versionId]/rest/authentication/[...restPage].tsx b/src/pages/[versionId]/rest/authentication/[...restPage].tsx new file mode 100644 index 000000000000..3544355f3fb1 --- /dev/null +++ b/src/pages/[versionId]/rest/authentication/[...restPage].tsx @@ -0,0 +1 @@ +export { default, getServerSideProps } from '../../[productId]/index' diff --git a/src/pages/[versionId]/rest/overview/endpoints-available-for-fine-grained-personal-access-tokens.tsx b/src/pages/[versionId]/rest/authentication/endpoints-available-for-fine-grained-personal-access-tokens.tsx similarity index 100% rename from src/pages/[versionId]/rest/overview/endpoints-available-for-fine-grained-personal-access-tokens.tsx rename to src/pages/[versionId]/rest/authentication/endpoints-available-for-fine-grained-personal-access-tokens.tsx diff --git a/src/pages/[versionId]/rest/overview/endpoints-available-for-github-app-installation-access-tokens.tsx b/src/pages/[versionId]/rest/authentication/endpoints-available-for-github-app-installation-access-tokens.tsx similarity index 100% rename from src/pages/[versionId]/rest/overview/endpoints-available-for-github-app-installation-access-tokens.tsx rename to src/pages/[versionId]/rest/authentication/endpoints-available-for-github-app-installation-access-tokens.tsx diff --git a/src/pages/[versionId]/rest/overview/endpoints-available-for-github-app-user-access-tokens.tsx b/src/pages/[versionId]/rest/authentication/endpoints-available-for-github-app-user-access-tokens.tsx similarity index 100% rename from src/pages/[versionId]/rest/overview/endpoints-available-for-github-app-user-access-tokens.tsx rename to src/pages/[versionId]/rest/authentication/endpoints-available-for-github-app-user-access-tokens.tsx diff --git a/src/pages/[versionId]/rest/authentication/index.tsx b/src/pages/[versionId]/rest/authentication/index.tsx new file mode 100644 index 000000000000..3544355f3fb1 --- /dev/null +++ b/src/pages/[versionId]/rest/authentication/index.tsx @@ -0,0 +1 @@ +export { default, getServerSideProps } from '../../[productId]/index' diff --git a/src/pages/[versionId]/rest/overview/permissions-required-for-fine-grained-personal-access-tokens.tsx b/src/pages/[versionId]/rest/authentication/permissions-required-for-fine-grained-personal-access-tokens.tsx similarity index 100% rename from src/pages/[versionId]/rest/overview/permissions-required-for-fine-grained-personal-access-tokens.tsx rename to src/pages/[versionId]/rest/authentication/permissions-required-for-fine-grained-personal-access-tokens.tsx diff --git a/src/pages/[versionId]/rest/overview/permissions-required-for-github-apps.tsx b/src/pages/[versionId]/rest/authentication/permissions-required-for-github-apps.tsx similarity index 100% rename from src/pages/[versionId]/rest/overview/permissions-required-for-github-apps.tsx rename to src/pages/[versionId]/rest/authentication/permissions-required-for-github-apps.tsx diff --git a/src/pages/[versionId]/rest/using-the-rest-api/[...restPage].tsx b/src/pages/[versionId]/rest/using-the-rest-api/[...restPage].tsx new file mode 100644 index 000000000000..3544355f3fb1 --- /dev/null +++ b/src/pages/[versionId]/rest/using-the-rest-api/[...restPage].tsx @@ -0,0 +1 @@ +export { default, getServerSideProps } from '../../[productId]/index' diff --git a/src/pages/[versionId]/rest/using-the-rest-api/index.tsx b/src/pages/[versionId]/rest/using-the-rest-api/index.tsx new file mode 100644 index 000000000000..3544355f3fb1 --- /dev/null +++ b/src/pages/[versionId]/rest/using-the-rest-api/index.tsx @@ -0,0 +1 @@ +export { default, getServerSideProps } from '../../[productId]/index' diff --git a/src/redirects/lib/static/redirect-exceptions.txt b/src/redirects/lib/static/redirect-exceptions.txt index 9b4c05dd1078..030054efae39 100644 --- a/src/redirects/lib/static/redirect-exceptions.txt +++ b/src/redirects/lib/static/redirect-exceptions.txt @@ -11,7 +11,7 @@ - /admin/enterprise-support/overview/about-github-premium-support-for-github-enterprise # FPT versioning was removed as part of github/docs-content#5166 -/rest/overview/resources-in-the-rest-api +/rest/using-the-rest-api/resources-in-the-rest-api - /rest/overview/api-previews /enterprise-server@latest/search-github/getting-started-with-searching-on-github/enabling-githubcom-repository-search-from-your-private-enterprise-environment diff --git a/src/rest/lib/config.js b/src/rest/lib/config.js index aab2e4510502..f72f164bc964 100644 --- a/src/rest/lib/config.js +++ b/src/rest/lib/config.js @@ -5,9 +5,15 @@ // in the JSON file. // These paths must match the paths in src/pages/[versionId]/rest -export const nonAutomatedRestPaths = ['/rest/guides', '/rest/quickstart', '/rest/overview'] +export const nonAutomatedRestPaths = [ + '/rest/quickstart', + '/rest/about-the-rest-api', + '/rest/using-the-rest-api', + '/rest/authentication', + '/rest/guides', +] // This path is used to set the page in the // src/rest/components/ApiVersionPicker.tsx component. That component // has a link to the page that describes what api versioning is. -export const apiVersionPath = '/rest/overview/api-versions' +export const apiVersionPath = '/rest/about-the-rest-api/api-versions' diff --git a/src/rest/lib/config.json b/src/rest/lib/config.json index 7bd8e350ffff..c156cc2e61b5 100644 --- a/src/rest/lib/config.json +++ b/src/rest/lib/config.json @@ -34,10 +34,12 @@ "content/rest/index.md": { "startsWith": [ "quickstart", - "overview", + "about-the-rest-api", + "using-the-rest-api", + "authentication", "guides" ] } }, "sha": "1fd29675070876e3278e71b47f4f2606601bc698" -} \ No newline at end of file +} diff --git a/tests/fixtures/content/rest/about-the-rest-api/comparing-githubs-rest-api-and-graphql-api.md b/tests/fixtures/content/rest/about-the-rest-api/comparing-githubs-rest-api-and-graphql-api.md new file mode 100644 index 000000000000..c7af7b15be7b --- /dev/null +++ b/tests/fixtures/content/rest/about-the-rest-api/comparing-githubs-rest-api-and-graphql-api.md @@ -0,0 +1,13 @@ +--- +title: About GitHub's APIs +intro: 'Gentle and fun intro about APIs' +versions: + fpt: '*' + ghes: '*' + ghae: '*' + ghec: '*' +--- + +## About {% data variables.product.company_short %}'s APIs + +First paragraph right here. diff --git a/tests/fixtures/content/rest/about-the-rest-api/index.md b/tests/fixtures/content/rest/about-the-rest-api/index.md new file mode 100644 index 000000000000..36340c4bbdcf --- /dev/null +++ b/tests/fixtures/content/rest/about-the-rest-api/index.md @@ -0,0 +1,12 @@ +--- +title: REST API overview +shortTitle: Overview +intro: 'Learn about resources, libraries, previews and troubleshooting for {% data variables.product.prodname_dotcom %}''s REST API.' +versions: + fpt: '*' + ghes: '*' + ghae: '*' + ghec: '*' +children: + - /comparing-githubs-rest-api-and-graphql-api +---