diff --git a/content/actions/concepts/index.md b/content/actions/concepts/index.md index 2fe67a494c3a..f604ef884611 100644 --- a/content/actions/concepts/index.md +++ b/content/actions/concepts/index.md @@ -1,18 +1,18 @@ --- title: Concepts for GitHub Actions shortTitle: Concepts -intro: "Learn the core concepts that you'll need to understand GitHub Actions." +intro: Learn the core concepts that you'll need to understand GitHub Actions. versions: fpt: '*' ghes: '*' ghec: '*' children: - - /overview - /workflows-and-actions - /runners - /security - - /about-github-actions-metrics + - /metrics - /billing-and-usage redirect_from: - /actions/concepts/use-cases --- + diff --git a/content/actions/concepts/about-github-actions-metrics.md b/content/actions/concepts/metrics.md similarity index 91% rename from content/actions/concepts/about-github-actions-metrics.md rename to content/actions/concepts/metrics.md index 935339335687..1f1484c076cf 100644 --- a/content/actions/concepts/about-github-actions-metrics.md +++ b/content/actions/concepts/metrics.md @@ -2,9 +2,11 @@ title: About GitHub Actions metrics shortTitle: Metrics intro: 'Learn about the {% data variables.product.prodname_actions %} metrics available for your organizations and repositories.' -permissions: Organization owners and users with the "View organization Actions metrics" permission can view organization-level metrics.

Users with the base repository role can view repository-level metrics. +permissions: Organization owners and users with the "View organization Actions metrics" permission can view organization-level metrics.

Users with the base repository role can view repository-level metrics. versions: feature: actions-metrics +redirect_from: + - /actions/concepts/about-github-actions-metrics --- {% data reusables.actions.about-actions-metrics %} diff --git a/content/actions/concepts/overview/index.md b/content/actions/concepts/overview/index.md deleted file mode 100644 index 665ab660aa57..000000000000 --- a/content/actions/concepts/overview/index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Overview of GitHub Actions -shortTitle: Overview -intro: "Learn the overarching concepts that apply to GitHub Actions as a whole." -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /continuous-integration - - /continuous-deployment - - /github-actions-vs-github-apps ---- diff --git a/content/actions/concepts/runners/index.md b/content/actions/concepts/runners/index.md index 9eac054e5f31..c5b41fd86a27 100644 --- a/content/actions/concepts/runners/index.md +++ b/content/actions/concepts/runners/index.md @@ -1,7 +1,7 @@ --- title: GitHub Actions Runners shortTitle: Runners -intro: "Learn about the concept of runners in GitHub Actions." +intro: Learn about the concept of runners in GitHub Actions. versions: fpt: '*' ghes: '*' @@ -10,9 +10,10 @@ children: - /github-hosted-runners - /larger-runners - /self-hosted-runners - - /private-networking-with-github-hosted-runners + - /private-networking - /runner-groups - /runner-scale-sets - /actions-runner-controller - - /support-for-actions-runner-controller + - /support-for-arc --- + diff --git a/content/actions/concepts/runners/private-networking-with-github-hosted-runners.md b/content/actions/concepts/runners/private-networking.md similarity index 96% rename from content/actions/concepts/runners/private-networking-with-github-hosted-runners.md rename to content/actions/concepts/runners/private-networking.md index 1ee4e6cd3cb8..e7d7aee1eb14 100644 --- a/content/actions/concepts/runners/private-networking-with-github-hosted-runners.md +++ b/content/actions/concepts/runners/private-networking.md @@ -1,6 +1,6 @@ --- title: Private networking with GitHub-hosted runners -shortTitle: About private networking +shortTitle: Private networking intro: '{% data reusables.actions.private-networking-intro %}' versions: fpt: '*' @@ -17,6 +17,7 @@ topics: redirect_from: - /actions/using-github-hosted-runners/connecting-to-a-private-network/about-private-networking-with-github-hosted-runners - /actions/concepts/runners/about-private-networking-with-github-hosted-runners + - /actions/concepts/runners/private-networking-with-github-hosted-runners --- {% data reusables.actions.enterprise-github-hosted-runners %} diff --git a/content/actions/concepts/runners/support-for-actions-runner-controller.md b/content/actions/concepts/runners/support-for-arc.md similarity index 98% rename from content/actions/concepts/runners/support-for-actions-runner-controller.md rename to content/actions/concepts/runners/support-for-arc.md index eeabbfccb3e7..55106b55ec8c 100644 --- a/content/actions/concepts/runners/support-for-actions-runner-controller.md +++ b/content/actions/concepts/runners/support-for-arc.md @@ -12,6 +12,7 @@ topics: redirect_from: - /actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/about-support-for-actions-runner-controller - /actions/concepts/runners/about-support-for-actions-runner-controller + - /actions/concepts/runners/support-for-actions-runner-controller --- ## Overview diff --git a/content/actions/concepts/security/artifact-attestations.md b/content/actions/concepts/security/artifact-attestations.md index cefa2d1d1378..0a04f07cd60c 100644 --- a/content/actions/concepts/security/artifact-attestations.md +++ b/content/actions/concepts/security/artifact-attestations.md @@ -1,7 +1,6 @@ --- title: Artifact attestations intro: 'Understand the usage and security benefits of artifact attestations.' -shortTitle: Artifact attestations topics: - Actions - Security diff --git a/content/actions/concepts/security/compromised-runners.md b/content/actions/concepts/security/compromised-runners.md index 00c1fed7d2e8..52b1c4af9a22 100644 --- a/content/actions/concepts/security/compromised-runners.md +++ b/content/actions/concepts/security/compromised-runners.md @@ -1,7 +1,6 @@ --- title: Compromised runners intro: 'Understand the security risks associated with compromised {% data variables.product.prodname_actions %} runners.' -shortTitle: Compromised runners versions: fpt: '*' ghes: '*' diff --git a/content/actions/concepts/security/github_token.md b/content/actions/concepts/security/github_token.md index 498955a6563e..a445f4330637 100644 --- a/content/actions/concepts/security/github_token.md +++ b/content/actions/concepts/security/github_token.md @@ -1,7 +1,6 @@ --- title: GITHUB_TOKEN intro: Learn what `GITHUB_TOKEN` is, how it works, and why it matters for secure automation in {% data variables.product.prodname_actions %} workflows. -shortTitle: GITHUB_TOKEN versions: fpt: '*' ghes: '*' diff --git a/content/actions/concepts/security/openid-connect.md b/content/actions/concepts/security/openid-connect.md index 3a36a847445f..6fb26e5edaac 100644 --- a/content/actions/concepts/security/openid-connect.md +++ b/content/actions/concepts/security/openid-connect.md @@ -1,6 +1,5 @@ --- title: OpenID Connect -shortTitle: OpenID Connect intro: OpenID Connect allows your workflows to exchange short-lived tokens directly from your cloud provider. versions: fpt: '*' diff --git a/content/actions/concepts/security/script-injections.md b/content/actions/concepts/security/script-injections.md index e384e3464315..a93a9d2ecb81 100644 --- a/content/actions/concepts/security/script-injections.md +++ b/content/actions/concepts/security/script-injections.md @@ -1,7 +1,6 @@ --- title: Script injections intro: Understand the security risks associated with script injections and {% data variables.product.prodname_actions %} workflows. -shortTitle: Script injections versions: fpt: '*' ghes: '*' diff --git a/content/actions/concepts/workflows-and-actions/avoiding-duplication.md b/content/actions/concepts/workflows-and-actions/avoiding-duplication.md deleted file mode 100644 index 6dd0addba4b9..000000000000 --- a/content/actions/concepts/workflows-and-actions/avoiding-duplication.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: Avoiding duplication -shortTitle: Avoid duplication -intro: You can use reusable workflows or composite actions to avoid duplicating the content of workflows. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: how_to -topics: - - Workflows -redirect_from: - - /actions/using-workflows/avoiding-duplication - - /actions/sharing-automations/avoiding-duplication ---- - -## About reusable workflows and composite actions - -Reusable workflows and composite actions are two ways to avoid duplicating the content of workflows. - -**Reusable workflows** allow you to reuse an entire workflow, including all of its jobs and steps. This is particularly useful when you have a complete CI/CD process that you want to use across multiple repositories. Reusable workflows can be centrally maintained, in one location, but used in many repositories across your organization. - -**Composite actions** allow you to combine multiple steps into a single action. You can then run this bundle of steps as a single step within a workflow. This is useful if you have a sequence of steps that will be used in more than one workflow. Composite actions allow you refactor long YAML workflow files into much smaller files and avoid copying and pasting between workflow files. - -Reusable workflows and composite actions solve similar problems, but have a few important differences. Most of the time you can use either solution. But some of the time, you’ll need to use one or the other, as described later in this article. - -For details of how to create and use reusable workflows and composite actions, see [AUTOTITLE](/actions/using-workflows/reusing-workflows) and [AUTOTITLE](/actions/creating-actions/creating-a-composite-action). - -## Comparison of reusable workflows and composite actions - -* **Workflow jobs** - Composite actions contain a series of steps, that are run as a single step within the caller workflow. Unlike reusable workflows, they cannot contain jobs. -* **Logging** - When a composite action runs, the log will show just the step in the caller workflow that ran the composite action, not the individual steps within the composite action. With reusable workflows, every job and step is logged separately. -* **Specifying runners** - Reusable workflows contain one or more jobs. As with all workflow jobs, the jobs in a reusable workflow specify the type of machine on which the job will run. Therefore, if the steps must be run on a type of machine that might be different from the machine chosen for the calling workflow job, then you should use a reusable workflow, not a composite action. -* **Passing output to steps** - A composite action is run as a step within a workflow job, and you can have multiple steps before or after the step that runs the composite action. Reusable workflows are called directly within a job, and not from within a job step. You can't add steps to a job after calling a reusable workflow, so you can't use `GITHUB_ENV` to pass values to subsequent job steps in the caller workflow. - -### Key differences between reusable workflows and composite actions - -| Reusable workflows | Composite actions | -| ------------------ | ----------------- | -| A YAML file, very similar to any standard workflow file | An action containing a bundle of workflow steps | -| Each reusable workflow is a single file in the `.github/workflows` directory of a repository | Each composite action is a separate repository, or a directory, containing an `action.yml` file and, optionally, other files | -| Called by referencing a specific YAML file | Called by referencing a repository or directory in which the action is defined | -| Called directly within a job, not from a step | Run as a step within a job | -| Can contain multiple jobs | Does not contain jobs | -| Each step is logged in real-time | Logged as one step even if it contains multiple steps | -| Can connect a maximum of four levels of workflows | Can be nested to have up to 10 composite actions in one workflow | -| Can use secrets | Cannot use secrets | diff --git a/content/actions/concepts/workflows-and-actions/contexts.md b/content/actions/concepts/workflows-and-actions/contexts.md index 8732c87b63b2..e1e65d2b60c3 100644 --- a/content/actions/concepts/workflows-and-actions/contexts.md +++ b/content/actions/concepts/workflows-and-actions/contexts.md @@ -1,6 +1,5 @@ --- title: Contexts -shortTitle: Contexts intro: 'Learn about contexts in {% data variables.product.prodname_actions %}.' versions: fpt: '*' diff --git a/content/actions/concepts/workflows-and-actions/about-custom-actions.md b/content/actions/concepts/workflows-and-actions/custom-actions.md similarity index 98% rename from content/actions/concepts/workflows-and-actions/about-custom-actions.md rename to content/actions/concepts/workflows-and-actions/custom-actions.md index 2b7614666caf..2ca759a3d989 100644 --- a/content/actions/concepts/workflows-and-actions/about-custom-actions.md +++ b/content/actions/concepts/workflows-and-actions/custom-actions.md @@ -10,6 +10,7 @@ redirect_from: - /actions/creating-actions/about-actions - /actions/creating-actions/about-custom-actions - /actions/sharing-automations/creating-actions/about-custom-actions + - /actions/concepts/workflows-and-actions/about-custom-actions versions: fpt: '*' ghes: '*' diff --git a/content/actions/concepts/workflows-and-actions/dependency-caching.md b/content/actions/concepts/workflows-and-actions/dependency-caching.md index f22cdb397802..9525265bf4da 100644 --- a/content/actions/concepts/workflows-and-actions/dependency-caching.md +++ b/content/actions/concepts/workflows-and-actions/dependency-caching.md @@ -1,6 +1,5 @@ --- title: Dependency caching -shortTitle: Dependency caching intro: 'Learn about dependency caching for workflow speed and efficiency.' versions: fpt: '*' diff --git a/content/actions/concepts/workflows-and-actions/index.md b/content/actions/concepts/workflows-and-actions/index.md index b36e92dc3168..d5fbdb4f5510 100644 --- a/content/actions/concepts/workflows-and-actions/index.md +++ b/content/actions/concepts/workflows-and-actions/index.md @@ -1,6 +1,6 @@ --- title: Workflows and actions -intro: "Learn about the concepts of workflows and actions in GitHub Actions." +intro: Learn about the concepts of workflows and actions in GitHub Actions. versions: fpt: '*' ghes: '*' @@ -8,11 +8,10 @@ versions: children: - /workflows - /variables - - /avoiding-duplication - - /reusable-workflows - - /about-custom-actions - /contexts - /expressions + - /reusable-workflows + - /custom-actions - /deployment-environments - /concurrency - /workflow-artifacts diff --git a/content/actions/concepts/workflows-and-actions/notifications-for-workflow-runs.md b/content/actions/concepts/workflows-and-actions/notifications-for-workflow-runs.md index 0db9ec25704a..24900f7d89c6 100644 --- a/content/actions/concepts/workflows-and-actions/notifications-for-workflow-runs.md +++ b/content/actions/concepts/workflows-and-actions/notifications-for-workflow-runs.md @@ -1,6 +1,5 @@ --- title: Notifications for workflow runs -shortTitle: Notifications for workflow runs intro: You can subscribe to notifications about workflow runs that you trigger. versions: fpt: '*' @@ -10,7 +9,7 @@ redirect_from: - /actions/monitoring-and-troubleshooting-workflows/notifications-for-workflow-runs - /actions/monitoring-and-troubleshooting-workflows/monitoring-workflows/notifications-for-workflow-runs --- - + {% data reusables.actions.enterprise-github-hosted-runners %} {% data reusables.repositories.workflow-notifications %} diff --git a/content/actions/concepts/workflows-and-actions/reusable-workflows.md b/content/actions/concepts/workflows-and-actions/reusable-workflows.md index cdec35708b61..4006f888f03f 100644 --- a/content/actions/concepts/workflows-and-actions/reusable-workflows.md +++ b/content/actions/concepts/workflows-and-actions/reusable-workflows.md @@ -1,11 +1,14 @@ --- title: Reusable workflows -shortTitle: Reusable workflows intro: Learn how to avoid duplication when creating a workflow by reusing existing workflows. versions: fpt: '*' ghec: '*' ghes: '*' +redirect_from: + - /actions/using-workflows/avoiding-duplication + - /actions/sharing-automations/avoiding-duplication + - /actions/concepts/workflows-and-actions/avoiding-duplication --- ## About reusable workflows @@ -32,7 +35,27 @@ You can view the reused workflows referenced in your {% data variables.product.p ## Reusable workflows versus composite actions -Reusable workflows and composite actions both help you to avoid duplication. Whereas reusable workflows allow you to reuse an entire workflow, with multiple jobs and steps, composite actions combine multiple steps that you can then run within a job step, just like any other action. For more information, see [AUTOTITLE](/actions/using-workflows/avoiding-duplication). +Reusable workflows and composite actions both help you avoid duplicating workflow content. Whereas reusable workflows allow you to reuse an entire workflow, with multiple jobs and steps, composite actions combine multiple steps that you can then run within a job step, just like any other action. + +Let's compare some aspects of each solution: + +* **Workflow jobs** - Composite actions contain a series of steps that are run as a single step within the caller workflow. Unlike reusable workflows, they cannot contain jobs. +* **Logging** - When a composite action runs, the log will show just the step in the caller workflow that ran the composite action, not the individual steps within the composite action. With reusable workflows, every job and step is logged separately. +* **Specifying runners** - Reusable workflows contain one or more jobs. As with all workflow jobs, the jobs in a reusable workflow specify the type of machine on which the job will run. Therefore, if the steps must be run on a type of machine that might be different from the machine chosen for the calling workflow job, then you should use a reusable workflow, not a composite action. +* **Passing output to steps** - A composite action is run as a step within a workflow job, and you can have multiple steps before or after the step that runs the composite action. Reusable workflows are called directly within a job, and not from within a job step. You can't add steps to a job after calling a reusable workflow, so you can't use `GITHUB_ENV` to pass values to subsequent job steps in the caller workflow. + +### Key differences between reusable workflows and composite actions + +| Reusable workflows | Composite actions | +| ------------------ | ----------------- | +| A YAML file, very similar to any standard workflow file | An action containing a bundle of workflow steps | +| Each reusable workflow is a single file in the `.github/workflows` directory of a repository | Each composite action is a separate repository, or a directory, containing an `action.yml` file and, optionally, other files | +| Called by referencing a specific YAML file | Called by referencing a repository or directory in which the action is defined | +| Called directly within a job, not from a step | Run as a step within a job | +| Can contain multiple jobs | Does not contain jobs | +| Each step is logged in real-time | Logged as one step even if it contains multiple steps | +| Can connect a maximum of four levels of workflows | Can be nested to have up to 10 composite actions in one workflow | +| Can use secrets | Cannot use secrets | ## Reusable workflows and workflow templates diff --git a/content/actions/concepts/workflows-and-actions/workflows.md b/content/actions/concepts/workflows-and-actions/workflows.md index 1b3c94540d54..f6acfbe14755 100644 --- a/content/actions/concepts/workflows-and-actions/workflows.md +++ b/content/actions/concepts/workflows-and-actions/workflows.md @@ -1,6 +1,5 @@ --- title: Workflows -shortTitle: Workflows intro: 'Get a high-level overview of {% data variables.product.prodname_actions %} workflows, including triggers, syntax, and advanced features.' versions: fpt: '*' diff --git a/content/actions/concepts/overview/github-actions-vs-github-apps.md b/content/actions/get-started/actions-vs-apps.md similarity index 92% rename from content/actions/concepts/overview/github-actions-vs-github-apps.md rename to content/actions/get-started/actions-vs-apps.md index 2f486d35a0f6..0efbb59f5a96 100644 --- a/content/actions/concepts/overview/github-actions-vs-github-apps.md +++ b/content/actions/get-started/actions-vs-apps.md @@ -9,6 +9,9 @@ versions: type: overview topics: - CD +redirect_from: + - /actions/concepts/overview/github-actions-vs-github-apps + - /actions/get-started/github-actions-vs-github-apps --- {% data variables.product.prodname_marketplace %} offers both {% data variables.product.prodname_actions %} and {% data variables.product.prodname_github_apps %}, each of which can be valuable automation and workflow tools. Understanding the differences and the benefits of each option will allow you to select the best fit for your job. diff --git a/content/actions/concepts/overview/continuous-deployment.md b/content/actions/get-started/continuous-deployment.md similarity index 98% rename from content/actions/concepts/overview/continuous-deployment.md rename to content/actions/get-started/continuous-deployment.md index 30d09201993d..6226a100cd2c 100644 --- a/content/actions/concepts/overview/continuous-deployment.md +++ b/content/actions/get-started/continuous-deployment.md @@ -13,6 +13,7 @@ redirect_from: - /actions/about-github-actions/about-continuous-deployment - /actions/about-github-actions/about-continuous-deployment-with-github-actions - /actions/concepts/overview/about-continuous-deployment-with-github-actions + - /actions/concepts/overview/continuous-deployment topics: - CD --- diff --git a/content/actions/concepts/overview/continuous-integration.md b/content/actions/get-started/continuous-integration.md similarity index 98% rename from content/actions/concepts/overview/continuous-integration.md rename to content/actions/get-started/continuous-integration.md index a145eaa50e78..0763126f9aa7 100644 --- a/content/actions/concepts/overview/continuous-integration.md +++ b/content/actions/get-started/continuous-integration.md @@ -11,6 +11,7 @@ redirect_from: - /actions/about-github-actions/about-continuous-integration - /actions/about-github-actions/about-continuous-integration-with-github-actions - /actions/concepts/overview/about-continuous-integration-with-github-actions + - /actions/concepts/overview/continuous-integration versions: fpt: '*' ghes: '*' @@ -18,7 +19,6 @@ versions: type: overview topics: - CI -shortTitle: Continuous integration --- {% data reusables.actions.enterprise-github-hosted-runners %} diff --git a/content/actions/get-started/index.md b/content/actions/get-started/index.md index e1a1f3581f38..0355f5fd8549 100644 --- a/content/actions/get-started/index.md +++ b/content/actions/get-started/index.md @@ -1,14 +1,18 @@ --- title: Get started with GitHub Actions shortTitle: Get started -intro: "Learn the basics of GitHub Actions." +intro: Learn the basics of GitHub Actions. versions: fpt: '*' ghes: '*' ghec: '*' children: - /quickstart - - /understanding-github-actions + - /understand-github-actions + - /continuous-integration + - /continuous-deployment + - /actions-vs-apps redirect_from: - /actions/about-github-actions + - /actions/concepts/overview --- diff --git a/content/actions/get-started/understanding-github-actions.md b/content/actions/get-started/understand-github-actions.md similarity index 99% rename from content/actions/get-started/understanding-github-actions.md rename to content/actions/get-started/understand-github-actions.md index 63cdd36d3f2f..2d922151051d 100644 --- a/content/actions/get-started/understanding-github-actions.md +++ b/content/actions/get-started/understand-github-actions.md @@ -11,6 +11,7 @@ redirect_from: - /actions/learn-github-actions/essential-features-of-github-actions - /articles/getting-started-with-github-actions - /actions/about-github-actions/understanding-github-actions + - /actions/get-started/understanding-github-actions versions: fpt: '*' ghes: '*' diff --git a/content/actions/how-tos/monitor-workflows/using-workflow-run-logs.md b/content/actions/how-tos/monitor-workflows/using-workflow-run-logs.md index ea9e8f40a65d..2a62607fef67 100644 --- a/content/actions/how-tos/monitor-workflows/using-workflow-run-logs.md +++ b/content/actions/how-tos/monitor-workflows/using-workflow-run-logs.md @@ -6,6 +6,7 @@ redirect_from: - /actions/managing-workflow-runs/using-workflow-run-logs - /actions/monitoring-and-troubleshooting-workflows/using-workflow-run-logs - /actions/monitoring-and-troubleshooting-workflows/monitoring-workflows/using-workflow-run-logs + - /actions/how-tos/monitoring-and-troubleshooting-workflows/monitoring-workflows/using-workflow-run-logs versions: fpt: '*' ghes: '*' diff --git a/content/actions/index.md b/content/actions/index.md index dc0f3a3b207c..1b90cb2846d4 100644 --- a/content/actions/index.md +++ b/content/actions/index.md @@ -3,13 +3,13 @@ title: '{% data variables.product.prodname_actions %} documentation' shortTitle: '{% data variables.product.prodname_actions %}' intro: 'Automate, customize, and execute your software development workflows right in your repository with {% data variables.product.prodname_actions %}. You can discover, create, and share actions to perform any job you''d like, including CI/CD, and combine actions in a completely customized workflow.' introLinks: - overview: /actions/get-started/understanding-github-actions + overview: /actions/get-started/understand-github-actions quickstart: /actions/get-started/quickstart featuredLinks: startHere: - /actions/how-tos/writing-workflows - /actions/tutorials - - /actions/concepts/overview/continuous-integration + - /actions/get-started/continuous-integration - /packages/managing-github-packages-using-github-actions-workflows/publishing-and-installing-a-package-with-github-actions guideCards: - /actions/how-tos/writing-workflows/using-workflow-templates diff --git a/content/copilot/concepts/about-mcp.md b/content/copilot/concepts/about-mcp.md new file mode 100644 index 000000000000..a62b619ba22b --- /dev/null +++ b/content/copilot/concepts/about-mcp.md @@ -0,0 +1,60 @@ +--- +title: About Model Context Protocol (MCP) +allowTitleToDifferFromFilename: true +shortTitle: About MCP +intro: 'Model Context Protocol (MCP) is a protocol that allows you to extend the capabilities of {% data variables.product.prodname_copilot %} by integrating it with other systems.' +versions: + feature: copilot +topics: + - Copilot +type: overview +--- + +>[!NOTE] +> * MCP support is generally available (GA) in {% data variables.copilot.copilot_chat_short %} for {% data variables.product.prodname_vscode %}. +> * MCP support for {% data variables.product.prodname_copilot_short %} in {% data variables.product.prodname_vs %}, JetBrains, Eclipse, and Xcode is in {% data variables.release-phases.public_preview %} and is subject to change. +> * The [AUTOTITLE](/free-pro-team@latest/site-policy/github-terms/github-pre-release-license-terms) apply only to {% data variables.product.prodname_copilot_short %} in IDEs where MCP support is still in preview. GA terms apply when using MCP for {% data variables.product.prodname_copilot_short %} in {% data variables.product.prodname_vscode %}. + +## Overview of Model Context Protocol (MCP) + +The Model Context Protocol (MCP) is an open standard that defines how applications share context with large language models (LLMs). MCP provides a standardized way to connect AI models to different data sources and tools, enabling them to work together more effectively. + +You can use MCP to extend the capabilities of {% data variables.copilot.copilot_chat_short %} by integrating it with a wide range of existing tools and services. For example, the {% data variables.product.github %} MCP server allows you to use {% data variables.copilot.copilot_chat_short %} in your IDE to perform tasks on {% data variables.product.github %}. You can also use MCP to create new tools and services that work with {% data variables.copilot.copilot_chat_short %}, allowing you to customize and enhance your experience. + +For more information on MCP, see [the official MCP documentation](https://modelcontextprotocol.io/introduction). For information on currently available MCP servers, see [the MCP servers repository](https://github.com/modelcontextprotocol/servers/tree/main). + +To learn how to configure and use MCP servers with {% data variables.copilot.copilot_chat_short %}, see [AUTOTITLE](/copilot/how-tos/context/model-context-protocol/extending-copilot-chat-with-mcp). + +Enterprises and organizations can choose to enable or disable use of MCP for members of their organization or enterprise. See [AUTOTITLE](/copilot/how-tos/administer/enterprises/managing-policies-and-features-for-copilot-in-your-enterprise#mcp-servers-on-githubcom). The MCP policy only applies to members with {% data variables.copilot.copilot_business_short %}, {% data variables.copilot.copilot_enterprise_short %}, or {% data variables.product.prodname_copilot_short %} licenses assigned by the organization or enterprise that configures the policy. {% data variables.copilot.copilot_free_short %}, {% data variables.copilot.copilot_pro_short %}, or {% data variables.copilot.copilot_pro_plus_short %} do not have their MCP access governed by this policy. + +## About the {% data variables.product.github %} MCP server + +The {% data variables.product.github %} MCP server is a Model Context Protocol (MCP) server provided and maintained by {% data variables.product.github %}. + +{% data variables.product.github %} MCP server can be used to: + +* Automate and streamline code-related tasks. +* Connect third-party tools (like Cursor, Windsurf, or future integrations) to leverage {% data variables.product.github %}’s context and AI capabilities. +* Enable cloud-based workflows that work from any device, without local setup. + +You can access the {% data variables.product.github %} MCP server remotely through {% data variables.product.prodname_vscode %}, or other editors that support remote MCP; or you can run it locally in any MCP-compatible editor, allowing you to choose between the convenience of a hosted solution or the customizability of a self-hosted setup. + +If you want to utilize the remote {% data variables.product.github %} MCP server, you can do so in a few steps, without any local setup. This is particularly useful for users who want to quickly leverage {% data variables.product.github %}’s AI capabilities without the overhead of managing a local MCP server. + +Running the {% data variables.product.github %} MCP server locally requires a bit more setup, but it allows for greater customization and control over your AI interactions. + +To learn how to set up and use the {% data variables.product.github %} MCP server, see [AUTOTITLE](/copilot/how-tos/context/model-context-protocol/using-the-github-mcp-server). + +## Availability + +There is currently broad support for local MCP servers in clients such as {% data variables.product.prodname_vscode %}, JetBrains IDEs, XCode, and others. + +Support for remote MCP servers is growing, with editors like {% data variables.product.prodname_vscode %} (with OAuth or PAT), {% data variables.product.prodname_vs %} (PAT only), JetBrains IDEs (PAT only), Xcode (PAT only), Eclipse (PAT only), Windsurf (PAT only), and Cursor (PAT only) already providing this functionality. + +To find out if your preferred editor supports remote MCP servers, check the documentation for your specific editor. + +## Next steps + +* [AUTOTITLE](/copilot/how-tos/context/model-context-protocol/extending-copilot-chat-with-mcp) +* [AUTOTITLE](/copilot/how-tos/context/model-context-protocol/using-the-github-mcp-server) +* [AUTOTITLE](/copilot/tutorials/enhancing-copilot-agent-mode-with-mcp) diff --git a/content/copilot/concepts/index.md b/content/copilot/concepts/index.md index aafafeaf8900..a2360f1eb128 100644 --- a/content/copilot/concepts/index.md +++ b/content/copilot/concepts/index.md @@ -12,6 +12,7 @@ children: - /about-github-copilot-chat - /coding-agent - /code-review + - /about-mcp - /about-organizing-and-sharing-context-with-copilot-spaces - /copilot-billing - /prompt-engineering-for-copilot-chat diff --git a/content/copilot/get-started/github-copilot-features.md b/content/copilot/get-started/github-copilot-features.md index 1453d37b983b..3e4c4e9f8371 100644 --- a/content/copilot/get-started/github-copilot-features.md +++ b/content/copilot/get-started/github-copilot-features.md @@ -5,7 +5,7 @@ versions: feature: copilot topics: - Copilot -shortTitle: Copilot features +shortTitle: Features redirect_from: - /copilot/copilot-business/github-copilot-business-feature-set - /copilot/copilot-individual/github-copilot-individual-feature-set diff --git a/content/copilot/get-started/plans-for-github-copilot.md b/content/copilot/get-started/plans-for-github-copilot.md index 2a514d145392..13c85d8bef68 100644 --- a/content/copilot/get-started/plans-for-github-copilot.md +++ b/content/copilot/get-started/plans-for-github-copilot.md @@ -5,7 +5,7 @@ versions: feature: copilot topics: - Copilot -shortTitle: Plans for Copilot +shortTitle: Plans redirect_from: - /copilot/about-github-copilot/subscription-plans-for-github-copilot - /copilot/about-github-copilot/plans-for-github-copilot diff --git a/content/copilot/how-tos/context/model-context-protocol/extending-copilot-chat-with-mcp.md b/content/copilot/how-tos/context/model-context-protocol/extending-copilot-chat-with-mcp.md index e69269d927c6..62a5c5ff272a 100644 --- a/content/copilot/how-tos/context/model-context-protocol/extending-copilot-chat-with-mcp.md +++ b/content/copilot/how-tos/context/model-context-protocol/extending-copilot-chat-with-mcp.md @@ -18,24 +18,21 @@ redirect_from: > * MCP support for {% data variables.product.prodname_copilot_short %} in {% data variables.product.prodname_vs %}, JetBrains, Eclipse, and Xcode is in {% data variables.release-phases.public_preview %} and is subject to change. > * The [AUTOTITLE](/free-pro-team@latest/site-policy/github-terms/github-pre-release-license-terms) apply only to {% data variables.product.prodname_copilot_short %} in IDEs where MCP support is still in preview. GA terms apply when using MCP for {% data variables.product.prodname_copilot_short %} in {% data variables.product.prodname_vscode %}. -{% vscode %} +## Introduction -## Overview +The Model Context Protocol (MCP) is an open standard that defines how applications share context with large language models (LLMs). For an overview of MCP, see [AUTOTITLE](/copilot/concepts/about-mcp). -The Model Context Protocol (MCP) is an open standard that defines how applications share context with large language models (LLMs). MCP provides a standardized way to connect AI models to different data sources and tools, enabling them to work together more effectively. +For information on currently available MCP servers, see [the MCP servers repository](https://github.com/modelcontextprotocol/servers/tree/main). -You can use MCP to extend the capabilities of {% data variables.copilot.copilot_chat_short %} by integrating it with a wide range of existing tools and services. For example, the {% data variables.product.github %} MCP server allows you to use {% data variables.copilot.copilot_chat_short %} in {% data variables.product.prodname_vscode %} to perform tasks on {% data variables.product.github %}. You can also use MCP to create new tools and services that work with {% data variables.copilot.copilot_chat_short %}, allowing you to customize and enhance your experience. +{% vscode %} Enterprises and organizations can choose to enable or disable use of MCP for members of their organization or enterprise. See [AUTOTITLE](/copilot/how-tos/administer/enterprises/managing-policies-and-features-for-copilot-in-your-enterprise#mcp-servers-on-githubcom). The MCP policy only applies to members with {% data variables.copilot.copilot_business_short %}, {% data variables.copilot.copilot_enterprise_short %}, or {% data variables.product.prodname_copilot_short %} licenses assigned by the organization or enterprise that configures the policy. {% data variables.copilot.copilot_free_short %}, {% data variables.copilot.copilot_pro_short %}, or {% data variables.copilot.copilot_pro_plus_short %} do not have their MCP access governed by this policy. -For more information on MCP, see [the official MCP documentation](https://modelcontextprotocol.io/introduction). - -For information on some of the other currently available MCP servers, see [the MCP servers repository](https://github.com/modelcontextprotocol/servers/tree/main). - ## Prerequisites * **Access to {% data variables.product.prodname_copilot_short %}**. {% data reusables.copilot.subscription-prerequisite %} * **{% data variables.product.prodname_vscode %} version 1.99 or later**. For information on installing {% data variables.product.prodname_vscode %}, see the [{% data variables.product.prodname_vscode %} download page](https://code.visualstudio.com/Download). +* If you are a member of an organization or enterprise with a {% data variables.copilot.copilot_business_short %} or {% data variables.copilot.copilot_enterprise_short %} plan, the "MCP servers in Copilot" policy must be enabled in order to use MCP. ## Configuring MCP servers in {% data variables.product.prodname_vscode %} @@ -125,12 +122,6 @@ If you already have an MCP configuration in Claude Desktop, you can use that con {% jetbrains %} -## Overview - -{% data reusables.copilot.mcp-overview-other-ides %} - -For information on other currently available MCP servers, see [the MCP servers repository](https://github.com/modelcontextprotocol/servers/tree/main). - ## Prerequisites * **Access to {% data variables.product.prodname_copilot_short %}**. {% data reusables.copilot.subscription-prerequisite %} @@ -154,12 +145,6 @@ Alternatively, to access the MCP settings, once you're in "Agent Mode," click th {% xcode %} -## Overview - -{% data reusables.copilot.mcp-overview-other-ides %} - -For information on other currently available MCP servers, see [the MCP servers repository](https://github.com/modelcontextprotocol/servers/tree/main). - ## Prerequisites * **Access to {% data variables.product.prodname_copilot_short %}**. {% data reusables.copilot.subscription-prerequisite %} @@ -178,12 +163,6 @@ For information on other currently available MCP servers, see [the MCP servers r {% eclipse %} -## Overview - -{% data reusables.copilot.mcp-overview-other-ides %} - -For information on other currently available MCP servers, see [the MCP servers repository](https://github.com/modelcontextprotocol/servers/tree/main). - ## Prerequisites {% data reusables.copilot.eclipse-prerequisites %} @@ -211,3 +190,4 @@ For more information on creating and configuring your own MCP servers, see [the * [AUTOTITLE](/copilot/using-github-copilot/coding-agent/extending-copilot-coding-agent-with-mcp) * [AUTOTITLE](/copilot/customizing-copilot/using-model-context-protocol/using-the-github-mcp-server) +* [AUTOTITLE](/copilot/tutorials/enhancing-copilot-agent-mode-with-mcp) diff --git a/content/migrations/using-github-enterprise-importer/migrating-between-github-products/migrating-repositories-from-github-enterprise-server-to-github-enterprise-cloud.md b/content/migrations/using-github-enterprise-importer/migrating-between-github-products/migrating-repositories-from-github-enterprise-server-to-github-enterprise-cloud.md index 0f9cad1c8a98..60529b6af56a 100644 --- a/content/migrations/using-github-enterprise-importer/migrating-between-github-products/migrating-repositories-from-github-enterprise-server-to-github-enterprise-cloud.md +++ b/content/migrations/using-github-enterprise-importer/migrating-between-github-products/migrating-repositories-from-github-enterprise-server-to-github-enterprise-cloud.md @@ -69,27 +69,25 @@ To migrate your repositories from {% data variables.product.prodname_ghe_server ## Step 3: Set up blob storage -Because many {% data variables.product.prodname_ghe_server %} instances sit behind firewalls, for {% data variables.product.prodname_ghe_server %} versions 3.8 or higher, we use blob storage as an intermediate location to store your data that {% data variables.product.prodname_dotcom %} can access. - -You must first set up blob storage with a supported cloud provider, then configure your settings in the {% data variables.enterprise.management_console %} of {% data variables.location.product_location_enterprise %}. +{% data reusables.enterprise-migration-tool.blob-storage-intro %} > [!NOTE] > You only need to configure blob storage if you use {% data variables.product.prodname_ghe_server %} versions 3.8 or higher. If you use {% data variables.product.prodname_ghe_server %} versions 3.7 or lower, skip to [Step 4: Set up a migration source in {% data variables.product.prodname_ghe_cloud %}](#step-4-set-up-a-migration-source-in-github-enterprise-cloud). > > Blob storage is required to migrate repositories with large Git source or metadata. If you use {% data variables.product.prodname_ghe_server %} versions 3.7 or lower, you will not be able to perform migrations where your Git source or metadata exports exceed 2GB. To perform these migrations, update to {% data variables.product.prodname_ghe_server %} versions 3.8 or higher. -### Setting up blob storage with a supported cloud provider - -{% data reusables.enterprise-migration-tool.supported-blob-storage-providers %} - -#### Setting up an AWS S3 storage bucket +### Setting up an AWS S3 storage bucket {% data reusables.enterprise-migration-tool.set-up-aws-bucket %} -#### Setting up an Azure Blob Storage account +### Setting up an Azure Blob Storage account {% data reusables.enterprise-migration-tool.set-up-azure-storage-account %} +### Using local storage (GHES 3.16+) + +{% data reusables.enterprise-migration-tool.local-storage-steps %} + ### Configuring blob storage in the {% data variables.enterprise.management_console %} of {% data variables.location.product_location_enterprise %} {% data reusables.enterprise-migration-tool.blob-storage-management-console %} @@ -330,25 +328,23 @@ For {% data variables.product.pat_generic %} requirements, see [AUTOTITLE](/migr ## Step 4: Set up blob storage -Because many {% data variables.product.prodname_ghe_server %} instances sit behind firewalls, we use blob storage as an intermediate location to store your data that {% data variables.product.prodname_dotcom %} can access. +{% data reusables.enterprise-migration-tool.blob-storage-intro %} -First, you must set up blob storage with a supported cloud provider. Then, you must configure your credentials for the storage provider in the {% data variables.enterprise.management_console %} or {% data variables.product.prodname_cli %}. - -### Setting up blob storage with a supported cloud provider - -{% data reusables.enterprise-migration-tool.supported-blob-storage-providers %} - -#### Setting up an AWS S3 storage bucket +### Setting up an AWS S3 storage bucket {% data reusables.enterprise-migration-tool.set-up-aws-bucket %} -#### Setting up an Azure Blob Storage storage account +### Setting up an Azure Blob Storage storage account {% data reusables.enterprise-migration-tool.set-up-azure-storage-account %} +### Using local storage (GHES 3.16+) + +{% data reusables.enterprise-migration-tool.local-storage-steps %} + ### Configuring your blob storage credentials -After you set up blob storage with a supported cloud provider, you must configure your credentials for the storage provider in {% data variables.product.prodname_dotcom %}: +If you set up blob storage with a **cloud provider** (as opposed to local storage), you must configure your credentials for the storage provider in {% data variables.product.prodname_dotcom %}: * If you use {% data variables.product.prodname_ghe_server %} 3.8 or higher, configure your credentials in the {% data variables.enterprise.management_console %}. * If you use {% data variables.product.prodname_ghe_server %} 3.7 or lower, configure the credentials in the {% data variables.product.prodname_cli %}. diff --git a/data/learning-tracks/admin.yml b/data/learning-tracks/admin.yml index 0e1673700d55..4034461901fd 100644 --- a/data/learning-tracks/admin.yml +++ b/data/learning-tracks/admin.yml @@ -44,7 +44,7 @@ adopting_github_actions_for_your_enterprise_ghec: guides: - >- /admin/managing-github-actions-for-your-enterprise/getting-started-with-github-actions-for-your-enterprise/about-github-actions-for-enterprises - - /actions/get-started/understanding-github-actions + - /actions/get-started/understand-github-actions - >- /admin/managing-github-actions-for-your-enterprise/getting-started-with-github-actions-for-your-enterprise/introducing-github-actions-to-your-enterprise - >- @@ -65,7 +65,7 @@ adopting_github_actions_for_your_enterprise_ghes: guides: - >- /admin/managing-github-actions-for-your-enterprise/getting-started-with-github-actions-for-your-enterprise/about-github-actions-for-enterprises - - /actions/get-started/understanding-github-actions + - /actions/get-started/understand-github-actions - >- /admin/managing-github-actions-for-your-enterprise/getting-started-with-github-actions-for-your-enterprise/introducing-github-actions-to-your-enterprise - >- diff --git a/data/reusables/copilot/mcp/about-github-mcp-server.md b/data/reusables/copilot/mcp/about-github-mcp-server.md index 02f2aef8f777..7c4e2d8939cb 100644 --- a/data/reusables/copilot/mcp/about-github-mcp-server.md +++ b/data/reusables/copilot/mcp/about-github-mcp-server.md @@ -2,24 +2,4 @@ The {% data variables.product.github %} MCP server is a Model Context Protocol (MCP) server provided and maintained by {% data variables.product.github %}. MCP allows you to integrate AI capabilities with other tools and services, enhancing your development experience by providing context-aware AI assistance. -For more information on MCP, see [the official MCP documentation](https://modelcontextprotocol.io/introduction). - -You can access the {% data variables.product.github %} MCP server remotely through {% data variables.product.prodname_vscode %}, or other editors that support remote MCP; or you can run it locally in any MCP-compatible editor, allowing you to choose between the convenience of a hosted solution or the customizability of a self-hosted setup. - -If you want to utilize the remote {% data variables.product.github %} MCP server, you can do so in a few steps, without any local setup. This is particularly useful for users who want to quickly leverage {% data variables.product.github %}’s AI capabilities without the overhead of managing a local MCP server. - -Running the {% data variables.product.github %} MCP server locally requires a bit more setup, but it allows for greater customization and control over your AI interactions. - -{% data variables.product.github %} MCP server can be used to: - -* Automate and streamline code-related tasks. -* Connect third-party tools (like Cursor, Windsurf, or future integrations) to leverage {% data variables.product.github %}’s context and AI capabilities. -* Enable cloud-based workflows that work from any device, without local setup. - -## Availability - -There is currently broad support for local MCP servers in clients such as {% data variables.product.prodname_vscode %}, JetBrains IDEs, XCode, and others. - -Support for remote MCP servers is growing, with editors like {% data variables.product.prodname_vscode %} (with OAuth or PAT), {% data variables.product.prodname_vs %} (PAT only), JetBrains IDEs (PAT only), Xcode (PAT only), Eclipse (PAT only), Windsurf (PAT only), and Cursor (PAT only) already providing this functionality. - -To find out if your preferred editor supports remote MCP servers, check the documentation for your specific editor. +For a full introduction to the {% data variables.product.github %} MCP server and an overview of MCP, see [AUTOTITLE](/copilot/concepts/about-mcp). diff --git a/data/reusables/enterprise-migration-tool/blob-storage-intro.md b/data/reusables/enterprise-migration-tool/blob-storage-intro.md new file mode 100644 index 000000000000..c59e6eb65b82 --- /dev/null +++ b/data/reusables/enterprise-migration-tool/blob-storage-intro.md @@ -0,0 +1,6 @@ +You must store your repository data in a place that {% data variables.product.prodname_dotcom %} can access. If your {% data variables.product.prodname_ghe_server %} instance is behind a firewall, you may need to set up blob storage with an external cloud service. + +First, you must set up blob storage with a supported provider. Then, if you're using a cloud provider, you must configure your credentials for the storage provider in the {% data variables.enterprise.management_console %} or {% data variables.product.prodname_cli %}. + +{% data reusables.enterprise-migration-tool.supported-blob-storage-providers %} +* Local storage on the GHES instance (GHES **3.16** and later) diff --git a/data/reusables/enterprise-migration-tool/local-storage-steps.md b/data/reusables/enterprise-migration-tool/local-storage-steps.md new file mode 100644 index 000000000000..6a1288212e45 --- /dev/null +++ b/data/reusables/enterprise-migration-tool/local-storage-steps.md @@ -0,0 +1,11 @@ +When you run a migration with local storage, archive data is written to the disk on {% data variables.location.product_location_enterprise %}, without the need for a cloud storage provider. {% data variables.product.prodname_importer_proper_name %} will automatically retrieve the stored archive from {% data variables.product.prodname_ghe_server %}, unless you have blocked egress traffic from {% data variables.product.prodname_ghe_server %}. + +1. From an administrative account on {% data variables.product.prodname_ghe_server %}, in the upper-right corner of any page, click {% octicon "rocket" aria-label="Site admin" %}. +{% data reusables.enterprise_site_admin_settings.management-console %} +1. Sign in to the {% data variables.enterprise.management_console %}. +1. In the left sidebar, click **Migrations**. +1. Click **Enable {% data variables.product.company_short %} Migrations**. +1. Under "Migrations Storage", click **Local Storage**. +1. Click **Save settings**. + +When you perform the migration, monitor your disk space on {% data variables.product.prodname_ghe_server %}. Migration archives are automatically deleted after 7 days. To free up space, you can delete an archive using the [AUTOTITLE](/rest/migrations/orgs#delete-an-organization-migration-archive). diff --git a/src/content-render/tests/table-accessibility-labels.js b/src/content-render/tests/table-accessibility-labels.js new file mode 100644 index 000000000000..552e8c4341af --- /dev/null +++ b/src/content-render/tests/table-accessibility-labels.js @@ -0,0 +1,212 @@ +import cheerio from 'cheerio' +import { describe, expect, test } from 'vitest' + +import { renderContent } from '#src/content-render/index' +import { EOL } from 'os' + +// Use platform-specific line endings for realistic tests when templates have +// been loaded from disk +const nl = (str) => str.replace(/\n/g, EOL) + +describe('table accessibility labels', () => { + test('adds aria-labelledby to tables following headings', async () => { + const template = nl(` +## Supported Platforms + +| Platform | Status | +|----------|--------| +| Linux | ✅ | +| Windows | ✅ | +`) + + const html = await renderContent(template) + const $ = cheerio.load(html) + + const table = $('table') + expect(table.length).toBe(1) + expect(table.attr('aria-labelledby')).toBe('supported-platforms') + + const heading = $('#supported-platforms') + expect(heading.length).toBe(1) + expect(heading.text()).toBe('Supported Platforms') + }) + + test('works with different heading levels', async () => { + const template = nl(` +### Configuration Options + +| Option | Default | +|--------|---------| +| debug | false | +| port | 3000 | +`) + + const html = await renderContent(template) + const $ = cheerio.load(html) + + const table = $('table') + expect(table.attr('aria-labelledby')).toBe('configuration-options') + }) + + test('skips tables that already have accessibility attributes', async () => { + const template = nl(` +## Test Heading + + + + +
HeaderHeader
DataData
+`) + + const html = await renderContent(template) + const $ = cheerio.load(html) + + const table = $('table') + expect(table.attr('aria-label')).toBe('Pre-labeled table') + expect(table.attr('aria-labelledby')).toBeUndefined() + }) + + test('skips tables that already have captions', async () => { + const template = nl(` +## Test Heading + + + + + +
Existing caption
HeaderHeader
DataData
+`) + + const html = await renderContent(template) + const $ = cheerio.load(html) + + const table = $('table') + expect(table.find('caption').text()).toBe('Existing caption') + expect(table.attr('aria-labelledby')).toBeUndefined() + }) + + test('handles multiple tables with different headings', async () => { + const template = nl(` +## First Table + +| A | B | +|---|---| +| 1 | 2 | + +## Second Table + +| X | Y | +|---|---| +| 3 | 4 | +`) + + const html = await renderContent(template) + const $ = cheerio.load(html) + + const tables = $('table') + expect(tables.length).toBe(2) + expect($(tables[0]).attr('aria-labelledby')).toBe('first-table') + expect($(tables[1]).attr('aria-labelledby')).toBe('second-table') + }) + + test('skips tables without preceding headings', async () => { + const template = nl(` +| Header | Header | +|--------|--------| +| Data | Data | + +Some text here. + +| Another | Table | +|---------|-------| +| More | Data | +`) + + const html = await renderContent(template) + const $ = cheerio.load(html) + + const tables = $('table') + expect(tables.length).toBe(2) + expect($(tables[0]).attr('aria-labelledby')).toBeUndefined() + expect($(tables[1]).attr('aria-labelledby')).toBeUndefined() + }) + + test('finds nearest preceding heading even with content in between', async () => { + const template = nl(` +## Data Table + +This table shows important information: + +Some additional context here. + +| Column | Value | +|--------|-------| +| Item | 123 | +`) + + const html = await renderContent(template) + const $ = cheerio.load(html) + + const table = $('table') + expect(table.attr('aria-labelledby')).toBe('data-table') + }) + + test('stops searching at another table', async () => { + const template = nl(` +## First Heading + +| Table | One | +|-------|-----| +| A | B | + +| Table | Two | +|-------|-----| +| C | D | +`) + + const html = await renderContent(template) + const $ = cheerio.load(html) + + const tables = $('table') + expect(tables.length).toBe(2) + expect($(tables[0]).attr('aria-labelledby')).toBe('first-heading') + // Second table should not get the same heading since the first table is in between + expect($(tables[1]).attr('aria-labelledby')).toBeUndefined() + }) + + test('handles headings with complex content', async () => { + const template = nl(` +## Supported GitHub Actions Features + +| Feature | Status | +|---------|--------| +| Build | ✅ | +| Deploy | ✅ | +`) + + const html = await renderContent(template) + const $ = cheerio.load(html) + + const table = $('table') + expect(table.attr('aria-labelledby')).toBe('supported-github-actions-features') + }) + + test('preserves existing table structure and attributes', async () => { + const template = nl(` +## Test Table + +| Header 1 | Header 2 | +|----------|----------| +| Cell 1 | Cell 2 | +`) + + const html = await renderContent(template) + const $ = cheerio.load(html) + + const table = $('table') + expect(table.find('thead th').length).toBe(2) + expect(table.find('tbody td').length).toBe(2) + expect(table.find('th').first().attr('scope')).toBe('col') + expect(table.attr('aria-labelledby')).toBe('test-table') + }) +}) diff --git a/src/content-render/unified/processor.ts b/src/content-render/unified/processor.ts index 5cce9c65bb1e..a717a4b709f0 100644 --- a/src/content-render/unified/processor.ts +++ b/src/content-render/unified/processor.ts @@ -23,6 +23,7 @@ import headingLinks from './heading-links' import rewriteTheadThScope from './rewrite-thead-th-scope' import rewriteEmptyTableRows from './rewrite-empty-table-rows' import rewriteForRowheaders from './rewrite-for-rowheaders' +import rewriteTableCaptions from './rewrite-table-captions' import wrapProceduralImages from './wrap-procedural-images' import parseInfoString from './parse-info-string' import annotate from './annotate' @@ -72,6 +73,7 @@ export function createProcessor(context: Context): UnifiedProcessor { .use(rewriteEmptyTableRows) .use(rewriteTheadThScope) .use(rewriteForRowheaders) + .use(rewriteTableCaptions) .use(rewriteImgSources) .use(rewriteAssetImgTags) // alerts plugin requires context with alertTitles property diff --git a/src/content-render/unified/rewrite-table-captions.js b/src/content-render/unified/rewrite-table-captions.js new file mode 100644 index 000000000000..af534430e9c4 --- /dev/null +++ b/src/content-render/unified/rewrite-table-captions.js @@ -0,0 +1,129 @@ +import { visit } from 'unist-util-visit' + +/** + * A rehype plugin that automatically adds aria-labelledby attributes to tables + * based on their preceding headings for accessibility. + * + * This plugin improves table accessibility by ensuring screen readers can + * announce table names when users navigate with the 'T' shortcut key. + * + * Transforms this structure: + * + *

Supported platforms

+ * + * ... + * ... + *
+ * + * Into this: + * + *

Supported platforms

+ * + * ... + * ... + *
+ * + * The plugin works by: + * 1. Finding table elements in the HTML AST + * 2. Looking backwards for the nearest preceding heading with an id + * 3. Adding aria-labelledby attribute pointing to that heading's id + * 4. Skipping tables that already have accessibility attributes + */ + +function isTableElement(node) { + return node.type === 'element' && node.tagName === 'table' +} + +function isHeadingElement(node) { + return node.type === 'element' && ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'].includes(node.tagName) +} + +function hasExistingAccessibilityAttributes(tableNode) { + return ( + tableNode.properties && + (tableNode.properties.ariaLabel || + tableNode.properties.ariaLabelledBy || + tableNode.properties['aria-label'] || + tableNode.properties['aria-labelledby']) + ) +} + +function hasExistingCaption(tableNode) { + return tableNode.children?.some( + (child) => child.type === 'element' && child.tagName === 'caption', + ) +} + +function findPrecedingHeading(parent, tableIndex) { + if (!parent.children || tableIndex === 0) return null + + // Look backwards from the table position for the nearest heading + for (let i = tableIndex - 1; i >= 0; i--) { + const node = parent.children[i] + + if (isHeadingElement(node)) { + // Check if the heading has an id attribute + const headingId = node.properties?.id + if (headingId) { + return { + id: headingId, + text: extractTextFromNode(node), + } + } + } + + // Stop searching if we hit another table or significant content block + if ( + isTableElement(node) || + (node.type === 'element' && ['section', 'article', 'div'].includes(node.tagName)) + ) { + break + } + } + + return null +} + +function extractTextFromNode(node) { + if (node.type === 'text') { + return node.value + } + + if (node.type === 'element' && node.children) { + return node.children + .map((child) => extractTextFromNode(child)) + .filter(Boolean) + .join('') + .trim() + } + + return '' +} + +export default function addTableAccessibilityLabels() { + return (tree) => { + visit(tree, (node, index, parent) => { + if (!isTableElement(node) || !parent || typeof index !== 'number') { + return + } + + // Skip tables that already have accessibility attributes or captions + if (hasExistingAccessibilityAttributes(node) || hasExistingCaption(node)) { + return + } + + // Find the preceding heading + const precedingHeading = findPrecedingHeading(parent, index) + if (!precedingHeading) { + return + } + + // Add aria-labelledby attribute to the table + if (!node.properties) { + node.properties = {} + } + + node.properties.ariaLabelledBy = precedingHeading.id + }) + } +} pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy