Merge branch 'main' into docs/add-repository-name-limits

Author: webdevpraveen

.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-all.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' }}

.github/workflows/purge-fastly.yml

@@ -44,6 +44,7 @@ To create a custom image, you must first set up an image-generation runner. When
    * **Platform**: Select a supported platform that matches the platform of the image you plan to create (Linux x64, Linux ARM64, or Windows x64).
    * **Image**: Select an image to build on, then enable the checkbox **Enable this runner to generate custom images**.
      * You can start from a {% data variables.product.github %}-owned image or choose a base image to start from a clean OS.
+     * You can start from an existing custom image as the base, enabling layered image workflows.
      * For ARM64 platforms, you can also select an ARM-maintained image with preinstalled tooling.
    * **Runner group**: Select the group for your runner to be a member of. Once the custom image is created, only runners in this runner group can generate new versions of that image.
 
@@ -139,6 +140,12 @@ If you specify an older major version in the YAML (for example, version: 1.* whe
 > [!NOTE]
 > {% data variables.actions.github_hosted_larger_runner %} creation does not support wildcards in image version selection.
 
+## Expiration for images built from custom images
+
+When a custom image is built from another custom image, the derived image inherits the expiration timeline of its base image. The maximum version age is calculated from when the base custom image was built, not when the derived image was created.
+
+For example, if Custom Image A is built on Day 2 and Custom Image B is built from A on Day 4 with a 7-day maximum version age policy, both A and B expire on Day 9.
+
 ## Billing and storage for custom images
 
 Jobs that use custom images are billed at the same per-minute rate as the {% data variables.actions.hosted_runner %} that uses the image. Storage for custom images is billed separately through {% data variables.product.prodname_actions %} storage.

assets/images/help/copilot/copilot-cli-context-usage.png

@@ -8,6 +8,7 @@ versions:
   ghec: '*'
 children:
   - /secure-use
+  - /securely-using-pull_request_target
   - /secrets
   - /oidc
 contentType: reference

content/actions/how-tos/manage-runners/larger-runners/use-custom-images.md

@@ -106,8 +106,6 @@ For more information, see [AUTOTITLE](/code-security/code-scanning/introduction-
 
 To help mitigate the risk of an exposed token, consider restricting the assigned permissions. For more information, see [AUTOTITLE](/actions/security-guides/automatic-token-authentication#modifying-the-permissions-for-the-github_token).
 
-{% ifversion custom-org-roles %}
-
 ## Mitigating the risks of untrusted code checkout
 
 Similar to script injection attacks, untrusted pull request content that automatically triggers actions processing can also pose a security risk. The `pull_request_target` and `workflow_run` workflow triggers, when used with the checkout of an untrusted pull request, expose the repository to security compromises. These workflows are privileged, which means they share the same cache of the main branch with other privileged workflow triggers, and may have repository write access and access to referenced secrets. These vulnerabilities can be exploited to take over a repository.
@@ -116,6 +114,8 @@ For more information on these triggers, how to use them, and the associated risk
 
 For additional examples and guidance on the risks of untrusted code checkout, see [Preventing pwn requests](https://securitylab.github.com/research/github-actions-preventing-pwn-requests/) from {% data variables.product.prodname_security %} and the [Dangerous-Workflow](https://github.com/ossf/scorecard/blob/main/docs/checks.md#dangerous-workflow) documentation from OpenSSF Scorecard.
 
+For detailed guidance on deciding whether to use `pull_request_target`, hardening these workflows, and opting out of the `actions/checkout` protection, see [AUTOTITLE](/actions/reference/security/securely-using-pull_request_target).
+
 ### Good practices
 
 * Avoid using the `pull_request_target` workflow trigger if it's not necessary. For privilege separation between workflows, `workflow_run` is a better trigger. Only use these workflow triggers when the workflow actually needs the privileged context.
@@ -126,8 +126,6 @@ For additional examples and guidance on the risks of untrusted code checkout, se
 
 * OpenSSF Scorecards can help you identify potentially vulnerable workflows, along with other security risks when using {% data variables.product.prodname_actions %}. See [Using OpenSSF Scorecards to secure workflow dependencies](#using-openssf-scorecards-to-secure-workflow-dependencies) later in this article.
 
-{% endif %}
-
 ## Using third-party actions
 
 The individual jobs in a workflow can interact with (and compromise) other jobs. For example, a job querying the environment variables used by a later job, writing files to a shared directory that a later job processes, or even more directly by interacting with the Docker socket and inspecting other running containers and executing commands in them.