Merge pull request #42512 from github/repo-sync

Repo sync

Author: docs-bot

.github/agents/copilot-readability-editor-2.md

@@ -0,0 +1,128 @@
+---
+name: "Copilot-Readability-Editor-2"
+description: "Improves the readability and scannability of an article provided by the user, applying plain language principles and the GitHub Docs team's style guide and writing standards."
+tools: ['read', 'edit/editFiles', 'search', 'web', 'github/*', 'execute']
+
+---
+
+# Copilot-Readability-Editor Agent
+
+You are an expert editor for the GitHub Docs content team. Your job is to maximize the readability of articles using plain language principles and the Docs team's writing standards.
+
+## Readability Score Target
+
+Your primary goal is to improve the Flesch Reading Ease score. Target 35+ (ideally 40+).
+
+The Flesch formula rewards:
+* **Shorter sentences** (biggest impact)
+* **Fewer syllables per word**
+
+When in doubt, make two short sentences instead of one medium sentence.
+
+## Editing Process
+
+Follow this two-pass approach:
+
+1. **First pass—Split sentences**: Find all sentences over 20 words and break them into 2+ shorter sentences. This is the single biggest driver of improved readability scores.
+2. **Second pass—Simplify words**: Replace complex words with simpler alternatives where meaning is preserved.
+
+## Sentence Structure Targets
+
+* **Target 12-15 words per sentence on average** (not just "under 20")
+* Aim for 1.5-2x more sentences than the original while keeping similar word count
+* When you see a sentence with commas, em dashes, or "and/or" conjunctions, consider splitting it
+* Make sure no more than 25% of sentences contain more than 20 words
+* Avoid consecutive sentences starting the same way
+
+## Word Choice for Readability
+
+Replace multi-syllable words when a shorter synonym exists:
+
+| Instead of | Use |
+|------------|-----|
+| instantiates | starts, creates |
+| utilize | use |
+| functionality | features |
+| configuration | setup, settings |
+| implementation | setup, code |
+| appropriate | right, correct |
+| indicates | shows |
+| requirements | needs |
+| assistance | help |
+
+Keep unavoidable technical terms (MCP, Copilot, repository) but simplify surrounding words to compensate.
+
+## Plain Language Principles
+
+* Use concise, everyday language. Explain or remove jargon when it doesn't support user understanding.
+* Use full terms, not shortened versions (repository, not repo).
+* Use active voice and personal pronouns ("you," "your"); favor present tense.
+* Write one idea per sentence; avoid redundancy, vague modifiers, and ambiguous phrasing.
+* Limit paragraphs to 150 words or fewer.
+* State the topic at the start of each paragraph; clarify connections between paragraphs.
+
+## Scannability (Conservative Approach)
+
+* Do NOT add new headings unless clearly beneficial
+* Do NOT add excessive bold formatting
+* Do NOT create headers that would only have one sentence of content
+* Convert long inline lists to bulleted lists, but preserve existing structure otherwise
+* Focus on sentence clarity over structural changes
+* Structure logically with clear, descriptive headings and short sections
+
+## Audience Guidance
+
+When editing, consider the audience type:
+* [Builders](https://github.com/github/docs-team/discussions/5060)
+* [Drivers](https://github.com/github/docs-team/discussions/5061)
+* [Learners](https://github.com/github/docs-team/blob/main/personas/learners/best-practices-for-learners-content.md)
+
+## Formatting Rules
+
+* When creating lists, use asterisks (*) instead of hyphens (-)
+* Do not end list items with periods if the items are not complete sentences
+* Use "For more information, see [link]" or "See [link]" before links that provide additional details; do not use a colon or other formats
+* Consider splitting a paragraph or list item when it includes two topics or steps, or is notably longer than others
+
+## What to Preserve
+
+* Retain all essential technical details: defaults, warnings, and admin options
+* Do not remove sentences about defaults, feature scope, or access unless clearly repeated
+* Retain essential usage details, admin options, and warnings unless obviously redundant
+* Do not alter the intent of verbs and actions (e.g., "navigate" does not necessarily mean "select")
+
+## Avoid These Patterns
+
+Based on past tests, do NOT:
+* ❌ Add excessive bold text on every key term
+* ❌ Create subheadings with bold text instead of actual ## headings
+* ❌ Add headers that only have one sentence of content
+* ❌ Use "See: [link]" with a colon (use "See [link]" instead)
+* ❌ Convert simple prose to overly nested lists
+* ❌ Reorganize sections unless clearly beneficial
+
+## Review Process
+
+1. Read through the article once, noting barriers to readability
+2. Identify sentences over 20 words that can be split
+3. Identify complex words that can be simplified
+4. Make changes according to the guidelines above
+5. Only analyze and edit the specific `.md` files provided
+6. Do not move or delete files
+7. Make edits only when they provide meaningful improvements
+8. Submit edits as a pull request
+
+## References
+
+* [Example: good readability and scannability PR](https://github.com/github/docs-internal/pull/57154)
+* [Readability improvement outcomes & examples](https://github.com/github/docs-team/discussions/5971)
+
+## Quality Checklist
+
+- [ ] Flesch Reading Ease score improved (target 35+)
+- [ ] Sentences average 12-15 words; no more than 25% exceed 20 words
+- [ ] Language is clear, direct, and free from unnecessary complexity
+- [ ] Article is easy to scan (headings, lists, short paragraphs)
+- [ ] Article follows the Docs team's style, tone, and formatting standards
+- [ ] Technical details, defaults, and warnings are preserved
+- [ ] Summary and at least 2 before/after examples included in output

.github/workflows/index-general-search.yml

@@ -26,9 +26,11 @@ on:
 permissions:
   contents: read
 
-# This allows a subsequently queued workflow run to cancel previous runs
+# This allows a subsequently queued workflow run to cancel previous runs.
+# Include the triggering workflow's conclusion in the group so that runs triggered
+# by skipped Purge Fastly workflows don't cancel runs triggered by successful ones.
 concurrency:
-  group: '${{ github.workflow }} @ ${{ github.head_ref }} ${{ github.event_name }}'
+  group: '${{ github.workflow }} @ ${{ github.head_ref }} ${{ github.event_name }} ${{ github.event.workflow_run.conclusion }}'
   cancel-in-progress: true
 
 env:
@@ -40,7 +42,9 @@ env:
 
 jobs:
   figureOutMatrix:
-    if: ${{ github.repository == 'github/docs-internal' }}
+    # Skip immediately if triggered by a non-successful Purge Fastly run.
+    # This prevents skipped runs from canceling valid indexing runs via concurrency.
+    if: ${{ github.repository == 'github/docs-internal' && (github.event_name != 'workflow_run' || github.event.workflow_run.conclusion == 'success') }}
     runs-on: ubuntu-latest
     outputs:
       matrix: ${{ steps.set-matrix.outputs.result }}
@@ -55,11 +59,13 @@ jobs:
             const allPossible = ["en", ...allNonEnglish]
 
             if (context.eventName === "workflow_run") {
+              // Job-level `if` already ensures we only get here for successful runs,
+              // but keep this as a safety check.
               if (context.payload.workflow_run.conclusion === "success") {
                 return ["en"]
               }
-              console.warn(`NOTE! It was a workflow_run but not success ('${context.payload.workflow_run.conclusion}')`)
-              console.warn("This means we're not going to index anything in the next dependent step.")
+              // This shouldn't happen due to job-level filter, but handle gracefully.
+              console.warn(`Unexpected: workflow_run with conclusion '${context.payload.workflow_run.conclusion}'`)
               return []
             }
 

.github/workflows/purge-fastly.yml

@@ -22,7 +22,9 @@ env:
 
 jobs:
   send-purges:
-    # Run when workflow_dispatch is the event (manual) or when deployment_status is the event (automatic) and it's a successful production deploy
+    # Run when workflow_dispatch is the event (manual) or when deployment_status is the event (automatic) and it's a successful production deploy.
+    # NOTE: This workflow triggers on all deployment_status events (including staging), but only runs for production.
+    # Non-production deploys will show as "skipped" - this is expected behavior.
     if: >-
       ${{
         github.repository == 'github/docs-internal' &&

content/code-security/concepts/security-at-scale/choosing-a-security-configuration-for-your-repositories.md

@@ -36,8 +36,6 @@ The {% data variables.product.prodname_github_security_configuration %} offers a
 
 The {% data variables.product.prodname_github_security_configuration %} includes {% data variables.product.prodname_GH_code_security %} and {% data variables.product.prodname_GH_secret_protection %} features. Applying the configuration to private and internal repositories in your organization will incur usage costs or require licenses.
 
-To start securing repositories in your organization with the {% data variables.product.prodname_github_security_configuration %}, see [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/applying-the-github-recommended-security-configuration-in-your-organization).
-
 ## Choosing a {% data variables.product.prodname_custom_security_configuration %}
 
 If you are familiar with {% data variables.product.company_short %}'s security products, and you have specific security needs that the {% data variables.product.prodname_github_security_configuration %} can't meet, you can create and apply {% data variables.product.prodname_custom_security_configurations %}. With {% data variables.product.prodname_custom_security_configurations %}, you can:

content/code-security/how-tos/secure-at-scale/configure-organization-security/configure-specific-tools/configuring-private-vulnerability-reporting-for-an-organization.md

@@ -32,7 +32,7 @@ For more information about configuring notification preferences, see [AUTOTITLE]
 
 ## Enabling or disabling private vulnerability reporting for public repositories added to the organization
 
-You can enable or disable private vulnerability reporting for new public repositories added to the organization using the {% data variables.product.prodname_github_security_configuration %}, or you can create a {% data variables.product.prodname_custom_security_configuration %}. For more information, see [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/applying-the-github-recommended-security-configuration-in-your-organization) and [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/creating-a-custom-security-configuration).
+You can enable or disable private vulnerability reporting for new public repositories added to the organization by creating a {% data variables.product.prodname_custom_security_configuration %}. For more information, see [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/creating-a-custom-security-configuration).
 
 ## What having private vulnerability reporting enabled for a repository looks like for a security researcher
 

content/code-security/how-tos/secure-at-scale/configure-organization-security/configure-specific-tools/protect-your-secrets.md

@@ -31,4 +31,4 @@ Before you configure {% data variables.product.prodname_GH_secret_protection %},
    * **For public repositories for free**: Click to enable for _only_ public repositories in your organization.
    * **For all repositories**: Click to see an estimated cost for {% data variables.product.prodname_GH_secret_protection %} for all repositories in your organization.
      * If you are satisfied with the pricing estimate, to enable {% data variables.product.prodname_secret_scanning %} alerts and push protection across your organization, click **Enable {% data variables.product.prodname_secret_protection %}**.
-     * Alternatively, click **Configure in settings** to customize which repositories you want to enable {% data variables.product.prodname_secret_protection %} for. See {% ifversion fpt or ghec %}[AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/applying-the-github-recommended-security-configuration-in-your-organization) and {% endif %}[AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/creating-a-custom-security-configuration).
+     * Alternatively, click **Configure in settings** to customize which repositories you want to enable {% data variables.product.prodname_secret_protection %} for. See [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/creating-a-custom-security-configuration).

content/code-security/how-tos/secure-at-scale/configure-organization-security/establish-complete-coverage/index.md

@@ -7,7 +7,6 @@ versions:
   ghec: '*'
 contentType: how-tos
 children:
-  - /applying-the-github-recommended-security-configuration-in-your-organization
   - /creating-a-custom-security-configuration
   - /applying-a-custom-security-configuration
   - /configuring-global-security-settings-for-your-organization

content/copilot/concepts/agents/coding-agent/about-custom-agents.md

@@ -11,24 +11,28 @@ topics:
 
 ## About {% data variables.copilot.custom_agents_short %}
 
-{% data variables.copilot.custom_agents_caps_short %} are specialized versions of {% data variables.copilot.copilot_coding_agent %} that you can tailor to your unique workflows, coding conventions, and use cases. Instead of repeatedly providing the same instructions and context, {% data variables.copilot.custom_agents_short %} allow you to define specialized agents that act like tailored teammates—following standards, using the right tools, and implementing team-specific practices.
+{% data variables.copilot.custom_agents_caps_short %} are specialized versions of {% data variables.copilot.copilot_coding_agent %}. You can tailor them to your workflows, coding conventions, and use cases.
 
-{% data variables.copilot.custom_agents_caps_short %} are defined using Markdown files, called {% data variables.copilot.agent_profiles %}, that specify prompts, tools, and MCP servers. This allows individuals and teams to encode their conventions, frameworks, and desired outcomes directly into {% data variables.product.prodname_copilot_short %}. The {% data variables.copilot.agent_profile %} serves as the artifact that defines the {% data variables.copilot.copilot_custom_agent_short %}'s behavior, and assigning the agent to a task or issue instantiates the {% data variables.copilot.copilot_custom_agent_short %}.
+With {% data variables.copilot.custom_agents_short %}, you define agents that act like tailored teammates. They follow your standards, use the right tools, and apply your team's practices. You don't need to repeat the same instructions each time.
+
+You define {% data variables.copilot.custom_agents_short %} using Markdown files called {% data variables.copilot.agent_profiles %}. These files specify prompts, tools, and MCP servers. This lets you build your conventions and desired outcomes directly into {% data variables.product.prodname_copilot_short %}.
+
+The {% data variables.copilot.agent_profile %} defines the {% data variables.copilot.copilot_custom_agent_short %}'s behavior. When you assign the agent to a task or issue, it starts working.
 
 ## {% data variables.copilot.agent_profile_caps %} format
 
-{% data variables.copilot.agent_profiles_caps %} are Markdown files with YAML frontmatter. In their simplest form, they include:
+{% data variables.copilot.agent_profiles_caps %} are Markdown files with YAML frontmatter. A basic profile includes:
 
 * **Name**: A unique identifier for the {% data variables.copilot.copilot_custom_agent_short %}
-* **Description**: Explains the agent's purpose and capabilities
-* **Prompt**: Custom instructions that define the agent's behavior and expertise
-* **Tools**: Specific tools the agent can access. This is optional, and the default is access to all available tools, including built-in tools and MCP server tools.
+* **Description**: The agent's purpose and what it can do
+* **Prompt**: Instructions that define the agent's behavior and expertise
+* **Tools** (optional): Specific tools the agent can access—by default, agents can use all available tools
 
-Organization and enterprise-level {% data variables.copilot.agent_profiles %} can also include MCP server configurations within the {% data variables.copilot.agent_profile %}, using the `mcp-server` property.
+At the organization and enterprise level, {% data variables.copilot.agent_profiles %} can also include MCP server settings. Use the `mcp-server` property to add these.
 
 ### Example {% data variables.copilot.agent_profile %}
 
-This is a basic {% data variables.copilot.agent_profile %} with name, description, and prompt configured.
+The following example shows a basic {% data variables.copilot.agent_profile %} with a name, description, and prompt.
 
 ```text
 ---
@@ -49,17 +53,26 @@ Focus on the following instructions:
 
 ## Where you can configure {% data variables.copilot.custom_agents_short %}
 
-You can define {% data variables.copilot.agent_profiles %} at the repository level (`.github/agents/CUSTOM-AGENT-NAME.md` in your repository) for project-specific agents, or at the organization or enterprise level (`/agents/CUSTOM-AGENT-NAME.md` in a `.github-private` repository) for broader availability. See [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-organization/prepare-for-custom-agents) and [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/prepare-for-custom-agents).
+You can define {% data variables.copilot.agent_profiles %} at different levels:
+
+* **Repository level**: Create `.github/agents/CUSTOM-AGENT-NAME.md` in your repository for project-specific agents
+* **Organization or enterprise level**: Create `/agents/CUSTOM-AGENT-NAME.md` in a `.github-private` repository for broader access
+
+For more information, see [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-organization/prepare-for-custom-agents) and [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/prepare-for-custom-agents).
 
 ## Where you can use {% data variables.copilot.custom_agents_short %}
 
 {% data reusables.copilot.custom-agents-ide-preview %}
 
-Once created, your {% data variables.copilot.custom_agents_short %} are available wherever you can use {% data variables.copilot.copilot_coding_agent %}, including {% data variables.product.prodname_dotcom_the_website %} (the agents tab and panel, issue assignment, pull requests), the {% data variables.copilot.copilot_cli %}, and in {% data variables.product.prodname_vscode %}, JetBrains IDEs, Eclipse, and Xcode.
+After you create {% data variables.copilot.custom_agents_short %}, you can use them wherever {% data variables.copilot.copilot_coding_agent %} is available:
+
+* **{% data variables.product.prodname_dotcom_the_website %}**: The agents tab and panel, issue assignment, and pull requests
+* **Command line**: The {% data variables.copilot.copilot_cli %}
+* **IDEs**: {% data variables.product.prodname_vscode %}, JetBrains IDEs, Eclipse, and Xcode
 
-{% data variables.copilot.agent_profiles_caps %} can be used directly in {% data variables.product.prodname_vscode %}, JetBrains IDEs, Eclipse, and Xcode, though some properties may function differently, or be ignored, between environments. 
+You can use {% data variables.copilot.agent_profiles %} directly in these IDEs. Some properties may work differently or be ignored depending on the environment. 
 
-For more information on using {% data variables.copilot.custom_agents_short %} in {% data variables.product.prodname_vscode %} specifically, see [{% data variables.copilot.custom_agents_caps_short %} in {% data variables.product.prodname_vscode_shortname %}](https://code.visualstudio.com/docs/copilot/customization/custom-agents) in the {% data variables.product.prodname_vscode_shortname %} documentation.
+For more information about using {% data variables.copilot.custom_agents_short %} in {% data variables.product.prodname_vscode %}, see [{% data variables.copilot.custom_agents_caps_short %} in {% data variables.product.prodname_vscode_shortname %}](https://code.visualstudio.com/docs/copilot/customization/custom-agents) in the {% data variables.product.prodname_vscode_shortname %} documentation.
 
 ## Next steps