Repo sync

.github/instructions/content.instructions.md

@@ -95,17 +95,23 @@ Examples:
 
 ## Versioning
 
-Avoid `{% ifversion fpt %}`, `{% ifversion ghec %}`, and `{% ifversion fpt or ghec %}` in content files whenever possible. Instead of suggesting or adding version-gating within an article:
+Follow one of these sets of instructions, depending on how articles are versioned in the frontmatter. Articles may be versioned for FPT and GHEC, for GHES only, or for all three. Articles may also be versioned using feature-based versioning defined in `data/features`. Feature-based versioning allows centralized control of when content appears for specific GHES releases.
 
-* Write content that applies to all versions the article is versioned for
-* If content is truly version-specific, consider whether it is low-harm to show it to all readers (e.g., an enterprise-only row in a reference table)
-* Only use `{% ifversion %}` as a last resort when content would be actively misleading for readers on a different version
+### FPT/GHEC-only articles
 
-**FPT and GHEC content**: When dotcom content applies to both products, version the page for `fpt` and `ghec` in the frontmatter. Do NOT use in-article Liquid versioning. Do NOT suggest adding `{% ifversion fpt or ghec %}` blocks as a fix for content that mentions a dotcom-only feature. Instead, suggest rewriting the content using the alternatives to inline versioning options listed below.
+All articles that are ONLY for FPT and GHEC should be versioned for these versions in the frontmatter.
 
-**GHES content**: If versioning is necessary for GitHub Enterprise Server content, use feature-based versioning (FBV). GHES content should rely on feature flags defined in `data/features/` rather than inline `{% ifversion ghes %}` blocks. Feature flags allow centralized control of when content appears for specific GHES releases.
+For such content, DO NOT use in-article Liquid versioning such as `{% ifversion fpt %}`, `{% ifversion ghec %}`, and `{% ifversion fpt or ghec %}`.
 
-### Alternatives to inline versioning
+### GHES-only articles
+
+All articles that are ONLY for GitHub Enterprise Server (GHES) should be versioned in the frontmatter using feature-based versioning defined in `data/features/`. 
+
+### FPT, GHEC, GHES articles
+
+All articles that are versioned for all of FPT, GHEC, and GHES in the frontmatter MAY require certain blocks of content to be versioned using in-article Liquid versioning. Before recommending this, check if this is really the case.
+
+#### Check in-article versioning is required
 
 Before resorting to in-article versioning, first consider whether the content is actually different across versions. Often procedures can be simplified to work at both levels.
 
@@ -127,26 +133,6 @@ Use these strategies instead of `{% ifversion %}`, depending on the level of con
 * End list items with "({% data variables.product.prodname_ghe_cloud %} only)", "({% data variables.product.prodname_dotcom_the_website %} only)", etc.
 * Specify if the feature is not available for GHES with "NAME-OF-FEATURE is not available for {% data variables.product.prodname_ghe_server %}", "... (not available in {% data variables.product.prodname_ghe_server %})", etc.
 
-### Example
-
-When documenting a feature that only applies to dotcom (not GHES):
-
-❌ Don't wrap content in version blocks:
-
-```markdown
-{% ifversion fpt or ghec %}
-
-## Immutable subject claims
-
-Repositories created after July 15, 2026 now use an immutable default subject format.
-
-{% endif %}
-```
-
-✅ Do use prose to indicate availability:
-
-```markdown
-## Immutable subject claims
+#### If in-article versioning is required
 
-Repositories created after July 15, 2026 now use an immutable default subject format. This rollout does not include {% data variables.product.prodname_ghe_server %}.
-```
+In-article versioning is required if a block of content in an article is definitely ONLY relevant for GHES, but the article itself is otherwise versioned in the frontmatter for all of FPT, GHEC, and GHES. In this situation, use feature-based versioning (FBV) wherever possible, using `{% ifversion FBV %}` blocks, where FBV is defined in `data/features/`. If it's not possible to use FBV, use {% ifversion ghes %} blocks, which will version the content block for all versions of GHES.

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

@@ -231,8 +231,7 @@ jobs:
         env:
           FASTLY_TOKEN: ${{ secrets.FASTLY_TOKEN }}
           FASTLY_SERVICE_ID: ${{ secrets.FASTLY_SERVICE_ID }}
-          FASTLY_SURROGATE_KEY: api-search:${{ matrix.language }}
-        run: npm run purge-fastly-edge-cache
+        run: npm run purge-fastly -- --surrogate-key api-search:${{ matrix.language }}
 
       - name: Upload failures artifact
         if: ${{ steps.check-failures.outputs.has_failures == 'true' }}

.github/workflows/purge-fastly.yml

@@ -1,29 +1,50 @@
 name: Purge Fastly
 
-# **What it does**: Sends a soft-purge to Fastly.
-# **Why we have it**: So that, right after a production deploy, we start afresh
-# **Who does it impact**: Writers and engineers.
+# **What it does**: Purges Fastly after a deploy and on demand. Soft purge by
+#   default; can hard purge specific languages, or hard purge the ENTIRE cache.
+# **Why we have it**: So that, right after a production deploy, we start afresh,
+#   and so docs engineering can clear a bad cache state without the Fastly UI.
+# **Who does it impact**: Writers and engineers. A full purge impacts all readers,
+#   origin sees a traffic spike while the cache refills, so it's gated below.
 
 on:
   deployment_status:
   workflow_dispatch:
     inputs:
       languages:
-        description: "Comma separated languages. E.g. 'en,es,ja,pt,zh,ru,fr,ko,de' (defaults to en)"
+        description: "Languages: Comma separated languages, e.g. 'en,es,ja,pt,zh,ru,fr,ko,de'. Blank = all languages."
         required: false
-        default: 'en' # Temporary, only purge English on deploy. Set to empty string for all
+        default: 'en'
+      hard:
+        description: 'Hard purge: Evict immediately instead of the default soft purge. Use when a soft purge fails to clear stale content.'
+        type: boolean
+        required: false
+        default: false
+      everything:
+        description: 'Everything: Hard-purge the entire Fastly cache... every key, all readers. Ignores the languages/hard inputs. To confirm, type exactly: "purge everything". Otherwise leave blank.'
+        required: false
+        default: ''
 
 permissions:
   contents: read
 
+# Serialize full-cache purges so two can't overlap and leave the cache in an
+# unknown state. Every other run (per-deploy, per-language) gets a unique group
+# so those never block each other.
+concurrency:
+  group: ${{ (inputs.everything == 'purge everything' && 'purge-fastly-all') || format('purge-fastly-{0}', github.run_id) }}
+  cancel-in-progress: false
+
 env:
   FASTLY_TOKEN: ${{ secrets.FASTLY_TOKEN }}
   FASTLY_SERVICE_ID: ${{ secrets.FASTLY_SERVICE_ID }}
 
 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.
-    # NOTE: This workflow triggers on all deployment_status events (including staging), but only runs for production.
+    # Run when workflow_dispatch is the event
+    # or when deployment_status is the event 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: >-
       ${{
@@ -38,52 +59,50 @@ jobs:
 
       - uses: ./.github/actions/node-npm-setup
 
-      - name: Wait for production to match build commit SHA
-        if: github.event_name != 'workflow_dispatch'
-        # A single /_build match only proves *one* Moda instance is serving the
-        # new build; others can still be mid-rollout. If we purge then, Fastly's
-        # soft purge serves stale-while-revalidate and may revalidate against a
-        # lagging instance, re-caching old content as fresh for a full TTL. So we
-        # require several consecutive matches to confirm the rollout has settled
-        # across instances before purging.
+      - name: Validate confirmation input
+        # A full-cache purge only triggers on the exact string "purge everything".
+        # Any other non-empty value (e.g. a typo) would otherwise be silently
+        # ignored and fall through to a normal soft purge that finishes green, so
+        # an operator could think they evicted the whole cache when they didn't.
+        # Fail loudly instead.
+        env:
+          EVERYTHING_INPUT: ${{ inputs.everything }}
         run: |
-          needs=$(git rev-parse HEAD)
-          start_time=$(date +%s)
-          timeout_seconds=1200
-          required_matches=5
-          interval_seconds=10
-          consecutive=0
-          while [[ $consecutive -lt $required_matches ]]
-          do
-            if [[ $(($(date +%s) - $start_time)) -gt $timeout_seconds ]]
-            then
-              echo "Production did not reach $required_matches consecutive build matches within $timeout_seconds seconds"
-              exit 1
-            fi
-            if [[ $needs == $(curl -s --fail --retry-connrefused --retry 5 https://docs.github.com/_build) ]]
-            then
-              consecutive=$((consecutive + 1))
-              echo "Production matches the build commit ($consecutive/$required_matches)"
-            else
-              if [[ $consecutive -gt 0 ]]
-              then
-                echo "Production stopped matching the build commit; resetting consecutive count"
-              else
-                echo "Production is not up to date with the build commit"
-              fi
-              consecutive=0
-            fi
-            if [[ $consecutive -lt $required_matches ]]
-            then
-              sleep $interval_seconds
-            fi
-          done
-          echo "Production is up to date with the build commit ($required_matches consecutive matches)"
+          if [ -n "$EVERYTHING_INPUT" ] && [ "$EVERYTHING_INPUT" != "purge everything" ]; then
+            echo "::error::To purge the entire cache, the 'everything' input must be exactly 'purge everything'. Got: '$EVERYTHING_INPUT'. Leave it blank for a normal purge."
+            exit 1
+          fi
 
-      - name: Purge Fastly edge cache per language
+      - name: Purge Fastly
+        # Auto post-deploy runs wait for the build, purge English only (temporary),
+        # and stay soft. A manual run uses the inputs: blank languages = all, the
+        # `hard` toggle, or a confirmed full-cache purge.
+        #
+        # Raw inputs are passed through the environment and quoted, never spliced
+        # into the command string, so a value like `en' --everything` can't break
+        # out of its argument and inject another flag.
         env:
-          LANGUAGES: ${{ inputs.languages || 'en' }} # Temporary, only purge English on deploy. Set to empty string for all
-        run: npm run purge-fastly-edge-cache-per-language
+          EVENT_NAME: ${{ github.event_name }}
+          LANGUAGES_INPUT: ${{ inputs.languages }}
+          HARD_INPUT: ${{ inputs.hard }}
+          EVERYTHING_INPUT: ${{ inputs.everything }}
+        run: |
+          args=()
+          if [ "$EVENT_NAME" != "workflow_dispatch" ]; then
+            args+=(--wait-for-build)
+          fi
+          if [ "$EVENT_NAME" = "deployment_status" ]; then
+            args+=(--languages en)
+          elif [ -n "$LANGUAGES_INPUT" ]; then
+            args+=(--languages "$LANGUAGES_INPUT")
+          fi
+          if [ "$HARD_INPUT" = "true" ]; then
+            args+=(--hard)
+          fi
+          if [ "$EVERYTHING_INPUT" = "purge everything" ]; then
+            args+=(--everything)
+          fi
+          npm run purge-fastly -- "${args[@]}"
 
       - uses: ./.github/actions/slack-alert
         if: ${{ failure() && github.event_name != 'workflow_dispatch' }}

content/admin/administering-your-instance/administering-your-instance-from-the-command-line/command-line-utilities.md

@@ -1384,12 +1384,15 @@ In this example, `ghe-repl-status -vv` sends verbose status information from a r
 
 ### ghe-check-background-upgrade-jobs
 
-During an upgrade to a feature release, this utility displays the status of background jobs on {% data variables.location.product_location %}. If you're running back-to-back upgrades, you should use this utility to check that all background jobs are complete before proceeding with the next upgrade.
+During an upgrade to a feature release, this utility displays the status of background upgrade jobs, such as Elasticsearch index migrations, on {% data variables.location.product_location %}. If you're running back-to-back upgrades, you should use this utility to check that all background jobs are complete before proceeding with the next feature upgrade.
 
 ```shell
 ghe-check-background-upgrade-jobs
 ```
 
+> [!NOTE]
+> This utility only gates a **subsequent feature upgrade**. It is not a prerequisite for upgrading replica or other additional nodes to the same release.
+
 ### ghe-migrations
 
 During an upgrade to a feature release, this utility displays the status of active database migrations on {% data variables.location.product_location %}. The output includes a version identifier for the migration, the migration's name, the migration's status, and the current duration of the migration.

content/admin/upgrading-your-instance/performing-an-upgrade/upgrading-with-an-upgrade-package.md

@@ -53,6 +53,9 @@ While you can use a hotpatch to upgrade to the latest patch release within a fea
 
     See [AUTOTITLE](/admin/configuration/configuring-your-enterprise/command-line-utilities#ghe-check-background-upgrade-jobs).
 
+   > [!NOTE]
+   > Background upgrade jobs only need to complete before you begin a subsequent feature upgrade. You don't need to wait for `ghe-check-background-upgrade-jobs` before upgrading replica or other additional nodes to the same release.
+
    To monitor progress of the configuration run, read the output in `/data/user/common/ghe-config.log`. For example, you can tail the log by running the following command:
 
    ```shell

content/copilot/concepts/agents/copilot-cli/context-management.md

@@ -34,12 +34,15 @@ This means that in a very long session, {% data variables.product.prodname_copil
 
 ## Checking your context usage
 
-You can check how much of the context window is currently in use by entering the `/context` slash command. This displays a visual breakdown of your token usage, showing:
-
-* **System/Tools**: The fixed overhead of system instructions and tool definitions.
-* **Messages**: The space used by your conversation history.
-* **Free Space**: How much room is left for new messages.
-* **Buffer**: A reserved portion that triggers automatic context management.
+You can use the `/context` slash command to visualize your current context window usage. The first line of the output shows the active model and the number of tokens currently in use out of the model's total context window capacity. The remainder of the output shows token usage, and context window percentage, for:
+
+* **System Prompt**: the base system prompt.
+* **Custom Instructions**: your loaded custom instructions (shown only when present).
+* **System Tools**: built-in tool definitions.
+* **MCP Tools**: tool definitions contributed by MCP servers.
+* **Messages**: your conversation history.
+* **Free Space**: unused context still available.
+* **Buffer**: capacity reserved for the model's response and headroom.
 
 ![Screenshot of the output of the '/context' CLI command.](/assets/images/help/copilot/copilot-cli-context-usage.png)