Merge pull request #43535 from github/repo-sync

Repo sync

Author: docs-bot

content/admin/configuring-settings/configuring-user-applications-for-your-enterprise/best-practices-for-configuring-api-rate-limits.md

@@ -0,0 +1,96 @@
+---
+title: Best practices for configuring API rate limits
+shortTitle: API rate limits best practices
+intro: 'A data-driven approach to API rate limits protects your {% data variables.product.prodname_ghe_server %} instance from excessive usage without disrupting critical integrations.'
+permissions: Site administrators can configure rate limits for a {% data variables.product.prodname_ghe_server %} instance.
+versions:
+  ghes: '*'
+contentType: how-tos
+category:
+  - Enable GitHub features for your enterprise
+---
+
+## About a data-driven approach to rate limits
+
+Without rate limits, a single CI integration making tens of thousands of requests per hour can slow down your entire instance for every user. But setting limits too aggressively can break the integrations your teams rely on. A data-driven approach helps you find the right balance—start by observing real usage patterns, then gradually enforce limits based on the data you collect.
+
+The approach follows these phases:
+
+1. **Observe**: Enable log forwarding and analyze API traffic patterns.
+1. **Baseline**: Enable rate limits with a high initial value to start collecting rate limit data.
+1. **Refine**: Adjust limits based on observed usage and communicate with affected teams.
+1. **Maintain**: Continuously monitor and adjust limits over time.
+
+For information about enabling rate limits through the {% data variables.enterprise.management_console %}, see [AUTOTITLE](/admin/configuring-settings/configuring-user-applications-for-your-enterprise/configuring-rate-limits).
+
+## Prerequisites
+
+Before you begin, make sure you have:
+
+* Admin access to the {% data variables.enterprise.management_console %}
+* Access to log forwarding configuration
+* The ability to analyze centralized logs
+* An understanding of your organization's API usage patterns and critical integrations
+
+## Step 1: Enable log forwarding
+
+Use log forwarding to centralize API request logs for monitoring and analysis. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/exploring-user-activity-in-your-enterprise/log-forwarding).
+
+When analyzing forwarded logs, focus on these key fields:
+
+| Field | Description |
+|-------|-------------|
+| `Timestamp` | Tracks when requests are made |
+| `user` / `gh.actor.login` | Identifies the user or integration making requests |
+| `path_info` / `gh.request.api.route` | The API route being accessed |
+| `status` | HTTP response code (for example, `200` for success or `429` when rate limited) |
+| `user_agent` | Identifies the client or integration sending the request |
+
+## Step 2: Analyze API trends before enabling limits
+
+Before enabling rate limits, analyze your overall usage trends to establish a baseline:
+
+* **Identify top consumers.** Find users or integrations making the highest number of requests.
+* **Review high-demand endpoints.** Highlight API routes (`path_info`) that receive the most traffic and may benefit from optimization.
+* **Detect inefficient patterns.** Look for signs of heavy or inefficient usage, such as frequent polling without caching or redundant requests.
+
+This baseline data will help you set rate limits that are informed by actual usage rather than guesswork.
+
+## Step 3: Enable rate limits with a high initial value
+
+When you're ready to enable rate limits, start with a high threshold so you can gather additional data without disrupting existing workflows.
+
+1. In the {% data variables.enterprise.management_console %}, set the primary API rate limit to a high value, such as 25,000 requests per hour. For more information, see [AUTOTITLE](/admin/configuring-settings/configuring-user-applications-for-your-enterprise/configuring-rate-limits#enabling-rate-limits-for-the-github-enterprise-server-apis).
+1. After enabling rate limits, monitor the `gh.rate_limit` fields that appear in your forwarded logs:
+
+   | Field | Description |
+   |-------|-------------|
+   | `gh.rate_limit.primary.max` | Maximum allowed requests |
+   | `gh.rate_limit.primary.remaining` | Remaining requests in the current period |
+   | `gh.rate_limit.primary.used` | Requests already made in the period |
+   | `gh.rate_limit.primary.reset` | Unix timestamp when the rate limit period resets |
+
+## Step 4: Refine limits and address heavy usage
+
+Use the data from the `gh.rate_limit` fields to make informed decisions:
+
+* **Identify users nearing the limit.** Find users or integrations that are frequently approaching or exceeding the threshold.
+* **Determine appropriate limits.** Set rate limits based on observed usage trends rather than arbitrary values.
+* **Communicate with affected teams.** Work with teams to optimize their API usage through techniques like request batching, response caching, and conditional requests.
+
+## Step 5: Reduce limits and maintain over time
+
+Once you have a clear picture of your API usage, gradually reduce the rate limit to align with your instance's capacity and actual usage patterns. Monitor for unintended disruptions after each adjustment.
+
+As you refine limits, work with teams whose integrations are affected. Techniques like request batching, response caching, and conditional requests can help teams reduce their API usage. You can also exempt specific users from rate limits using the `ghe-config` utility. For more information, see [AUTOTITLE](/admin/administering-your-instance/administering-your-instance-from-the-command-line/command-line-utilities#ghe-config).
+
+Review your rate limit data periodically, since usage patterns change as new integrations are added and workflows evolve.
+
+## Additional considerations
+
+* **GraphQL API limits.** The GraphQL API has a separate rate limit (default: 5,000 points per hour) that cannot be bypassed through the exemption list. For more information, see [AUTOTITLE](/graphql/overview/rate-limits-and-node-limits-for-the-graphql-api).
+* **Secondary rate limits.** You can also enable secondary rate limits to protect the overall level of service. For more information, see [AUTOTITLE](/admin/configuring-settings/configuring-user-applications-for-your-enterprise/configuring-rate-limits#enabling-secondary-rate-limits).
+
+## Further reading
+
+* [AUTOTITLE](/rest/overview/rate-limits-for-the-rest-api)

content/admin/configuring-settings/configuring-user-applications-for-your-enterprise/configuring-rate-limits.md

@@ -17,43 +17,43 @@ category:
 
 ## About rate limits for {% data variables.product.prodname_ghe_server %}
 
-To prevent excessive use of resources on {% data variables.location.product_location %} that could affect the instance's availability or performance for all users, you can configure rate limits. Rate limits are configurable for the {% data variables.product.prodname_enterprise_api %} and {% data variables.product.prodname_actions %}.
+Rate limits help prevent excessive resource use on {% data variables.location.product_location %} that could affect availability or performance for all users. You can configure rate limits for the {% data variables.product.prodname_enterprise_api %} and {% data variables.product.prodname_actions %}.
 
-Implement rate limits carefully and communicate frequently with your users as you tune the limits. To avoid interrupting your users' work, {% data variables.product.company_short %} recommends that you start with permissive rate limits, and gradually tune the limits to suit your environment.
+Implement rate limits carefully and communicate with your users as you tune them. Start with permissive rate limits and gradually adjust them to suit your environment.
 
 You can also configure rate limits for authentication attempts to the {% data variables.enterprise.management_console %}. For more information, see [AUTOTITLE](/admin/configuration/administering-your-instance-from-the-management-console/managing-access-to-the-management-console#configuring-rate-limits-for-authentication-to-the-management-console).
 
 ## Enabling rate limits for the {% data variables.product.prodname_enterprise_api %}
 
-Excessive numbers of requests to the {% data variables.product.prodname_enterprise_api %} can affect the availability and performance of your instance. For more information about how rate limits for the API affect your users, see [AUTOTITLE](/rest/overview/rate-limits-for-the-rest-api).
+Too many requests to the {% data variables.product.prodname_enterprise_api %} can slow down your instance or make it unavailable. For more information about how API rate limits affect your users, see [AUTOTITLE](/rest/overview/rate-limits-for-the-rest-api).
 
-You can exempt a list of users from API rate limits using the `ghe-config` utility in the administrative shell. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/command-line-utilities#ghe-config).
+You can exempt specific users from API rate limits using the `ghe-config` utility in the administrative shell. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/command-line-utilities#ghe-config).
 
 > [!NOTE]
 > The {% data variables.enterprise.management_console %} lists the time period (per minute or per hour) for each rate limit.
 
 {% data reusables.enterprise_site_admin_settings.access-settings %}
 {% data reusables.enterprise_site_admin_settings.management-console %}
 1. Under "Rate Limiting", select **Enable HTTP API Rate Limiting**.
-1. Type limits for authenticated and unauthenticated requests for each API, or accept the pre-filled default limits.
+1. Enter limits for authenticated and unauthenticated requests for each API, or accept the prefilled default limits.
 {% data reusables.enterprise_management_console.save-settings %}
 
 ## Enabling secondary rate limits
 
-Setting secondary rate limits protects the overall level of service on {% data variables.location.product_location %}.
+Secondary rate limits help keep {% data variables.location.product_location %} stable for all users.
 
 {% data reusables.enterprise_site_admin_settings.access-settings %}
 {% data reusables.enterprise_site_admin_settings.management-console %}
 1. Under "Rate Limiting", select **Enable Secondary Rate Limiting**.
-1. Type limits for Total Requests, CPU Limit, and CPU Limit for Searching, or accept the pre-filled default limits.
+1. Enter limits for Total Requests, CPU Limit, and CPU Limit for Searching, or accept the prefilled default limits.
 {% data reusables.enterprise_management_console.save-settings %}
 
 ## Enabling rate limits for Git
 
-If a member of {% data variables.product.company_short %}'s staff has recommended it, you can apply Git rate limits per repository network or per user ID. Git rate limits are expressed in concurrent operations per minute, and are adaptive based on the current CPU load.
+If a member of {% data variables.product.company_short %}'s staff has recommended it, you can apply Git rate limits per repository network or per user ID. Git rate limits are measured in concurrent operations per minute and adapt to the current CPU load.
 
 > [!WARNING]
-> We encourage you to leave this setting disabled unless directly recommended by a member of {% data variables.product.company_short %}'s staff. Git operations are rarely the leading driver of CPU and RAM usage. Enabling this feature can make Git operations more likely to fail under high load conditions but does not address the underlying cause of those conditions.
+> Leave this setting disabled unless directly recommended by {% data variables.product.company_short %}'s staff. Git operations are rarely the leading driver of CPU and RAM usage. Enabling this feature can make Git operations more likely to fail under high load but doesn't address the underlying cause.
 
 {% data reusables.enterprise_site_admin_settings.access-settings %}
 {% data reusables.enterprise_site_admin_settings.management-console %}
@@ -68,15 +68,15 @@ You can apply a rate limit to {% data variables.product.prodname_actions %} work
 
 ### About rate limits for {% data variables.product.prodname_actions %}
 
-Your {% data variables.product.prodname_ghe_server %} instance assigns each {% data variables.product.prodname_actions %} workflow job to a runner. If your instance cannot immediately assign a job to an available runner, the job will wait in a queue until a runner is available. If {% data variables.product.prodname_actions %} experiences sustained high load, the queue can back up, and the performance of {% data variables.location.product_location %} may degrade.
+Your {% data variables.product.prodname_ghe_server %} instance assigns each {% data variables.product.prodname_actions %} workflow job to a runner. If your instance can't immediately assign a job to an available runner, the job waits in a queue. If {% data variables.product.prodname_actions %} experiences sustained high load, the queue can back up and the performance of {% data variables.location.product_location %} may degrade.
 
-To avoid this performance degradation, you can configure a rate limit for {% data variables.product.prodname_actions %}. This rate limit is expressed in job runs per minute. {% data variables.product.prodname_ghe_server %} calculates and applies the rate limit for the sum total of all job runs on the instance. If runs exceed the rate limit, additional runs will fail instead of entering the queue. The following error will appear in the run's annotations.
+To avoid this, you can configure a rate limit for {% data variables.product.prodname_actions %}. This rate limit is measured in job runs per minute. {% data variables.product.prodname_ghe_server %} applies the rate limit across all job runs on the instance. If runs exceed the rate limit, additional runs fail instead of entering the queue. The following error appears in the run's annotations.
 
 > You've exceeded the rate limit for workflow run requests. Please wait before retrying the run.
 
-An appropriate rate limit protects {% data variables.location.product_location %} from abnormal usage of {% data variables.product.prodname_actions %} without interfering with day-to-day operations. The exact threshold depends on your instance's available resources and overall load profile. For more information about the hardware requirements for {% data variables.product.prodname_actions %}, see [AUTOTITLE](/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/getting-started-with-github-actions-for-github-enterprise-server#review-hardware-requirements).
+A good rate limit protects {% data variables.location.product_location %} from unusual spikes in {% data variables.product.prodname_actions %} usage without interfering with day-to-day operations. The right threshold depends on your instance's available resources and typical workload. For more information about hardware requirements for {% data variables.product.prodname_actions %}, see [AUTOTITLE](/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/getting-started-with-github-actions-for-github-enterprise-server#review-hardware-requirements).
 
-By default, the rate limit for {% data variables.product.prodname_actions %} is disabled. Because {% data variables.product.prodname_ghe_server %} can handle temporary spikes in usage without performance degradation, this rate limit is intended to protect against sustained high load. We recommend leaving the rate limit disabled unless you are experiencing performance problems. In some cases, {% data variables.contact.github_support %} may recommend that you enable a rate limit for {% data variables.product.prodname_actions %}.
+By default, the rate limit for {% data variables.product.prodname_actions %} is disabled. {% data variables.product.prodname_ghe_server %} can handle temporary usage spikes without problems, so this rate limit protects against sustained high load. Leave it disabled unless you experience performance problems. In some cases, {% data variables.contact.github_support %} may recommend enabling a rate limit for {% data variables.product.prodname_actions %}.
 
 ### Enabling or disabling rate limits for {% data variables.product.prodname_actions %}
 
@@ -88,7 +88,7 @@ By default, the rate limit for {% data variables.product.prodname_actions %} is
    ghe-config actions-rate-limiting.queue-runs-per-minute RUNS-PER-MINUTE
    ```
 
-1. To disable the rate limit after it's been enabled, run the following command.
+1. To disable the rate limit, run the following command.
 
    ```shell
    ghe-config actions-rate-limiting.enabled false
@@ -104,10 +104,10 @@ By default, the rate limit for {% data variables.product.prodname_actions %} is
 
 ## Controlling the rate for the live update service
 
-If the number of AJAX requests to your {% data variables.product.prodname_ghe_server %} instance causes problems, then you may need to edit the rate limit for the WebSockets controller used by these live updates. For details of how to view Alive requests, see [AUTOTITLE](/admin/monitoring-and-managing-your-instance/monitoring-your-instance/about-the-monitor-dashboards).
+If the number of AJAX requests to your {% data variables.product.prodname_ghe_server %} instance causes problems, you may need to adjust the rate limit for the WebSockets controller used by these live updates. For details on how to view Alive requests, see [AUTOTITLE](/admin/monitoring-and-managing-your-instance/monitoring-your-instance/about-the-monitor-dashboards).
 
-When primary rate limits are enabled, by default a maximum of 100 requests is allowed per minute for each IP address. Administrators with access to the administrative shell can use the [ghe-config](/admin/administering-your-instance/administering-your-instance-from-the-command-line/command-line-utilities#ghe-config) utility to set `app.github.web-sockets-rate-limit` with the number of requests allowed per minute for each IP address or disable this rate limit. Setting the limit to any value that is not a positive integer (for example, `0`, `-1`, `disabled`) disables rate limiting on the WebSockets controller for live updates.
+With primary rate limits enabled, the default limit is 100 requests per minute per IP address. Use the [ghe-config](/admin/administering-your-instance/administering-your-instance-from-the-command-line/command-line-utilities#ghe-config) utility in the administrative shell to set `app.github.web-sockets-rate-limit` to the number of requests allowed per minute per IP address, or to disable this rate limit. Setting the limit to any non-positive-integer value (for example, `0`, `-1`, `disabled`) disables rate limiting on the WebSockets controller.
 
 {% data reusables.github-connect.rate-limit-live-dotcom-requests %}
 
-After you make any changes to the values of these settings, run [ghe-config-apply](/admin/administering-your-instance/administering-your-instance-from-the-command-line/command-line-utilities#ghe-config-apply) to apply the settings.
+After you change these settings, run [ghe-config-apply](/admin/administering-your-instance/administering-your-instance-from-the-command-line/command-line-utilities#ghe-config-apply) to apply them.

content/admin/configuring-settings/configuring-user-applications-for-your-enterprise/index.md

@@ -10,6 +10,7 @@ children:
   - /configuring-email-for-notifications
   - /configuring-github-pages-for-your-enterprise
   - /configuring-rate-limits
+  - /best-practices-for-configuring-api-rate-limits
   - /configuring-web-commit-signing
   - /configuring-interactive-maps
   - /managing-github-mobile-for-your-enterprise