Merge pull request #44461 from github/repo-sync

Repo sync

Author: docs-bot

content/actions/tutorials/build-and-test-code/python.md

@@ -297,6 +297,13 @@ steps:
     pytest tests.py --doctest-modules --junitxml=junit/test-results.xml --cov=com --cov-report=xml --cov-report=html
 ```
 
+{% ifversion code-quality %}
+
+> [!TIP]
+> This example already produces a Cobertura XML coverage report (`--cov-report=xml`). To display coverage results directly on pull requests, upload the report using the `actions/upload-code-coverage` action. See [AUTOTITLE](/code-security/how-tos/maintain-quality-code/set-up-code-coverage).
+
+{% endif %}
+
 ### Using Ruff to lint and/or format code
 
 The following example installs or upgrades `ruff` and uses it to lint all files. For more information, see [Ruff](https://docs.astral.sh/ruff).

content/actions/tutorials/store-and-share-data.md

@@ -83,6 +83,13 @@ jobs:
           path: output/test/code-coverage.html
 ```
 
+{% ifversion code-quality %}
+
+> [!TIP]
+> To display code coverage results directly on pull requests instead of downloading artifacts, you can upload a Cobertura XML coverage report to {% data variables.product.prodname_code_quality_short %}. See [AUTOTITLE](/code-security/how-tos/maintain-quality-code/set-up-code-coverage).
+
+{% endif %}
+
 ## Configuring a custom artifact retention period
 
 You can define a custom retention period for individual artifacts created by a workflow. When using a workflow to create a new artifact, you can use `retention-days` with the `upload-artifact` action. This example demonstrates how to set a custom retention period of 5 days for the artifact named `my-artifact`:

content/code-security/concepts/about-code-quality.md

@@ -30,6 +30,7 @@ With {% data variables.product.prodname_code_quality_short %}, you can:
 * Use **repository dashboards** to track reliability and maintainability scores, identify areas needing attention, and prioritize remediation.
 * Monitor **organization dashboards** to understand the code health of your repositories at a glance and determine which repositories to investigate further.
 * Set up **rulesets** for pull requests to enforce code quality standards and block changes that do not meet your criteria.
+* Upload **code coverage** reports to see test coverage metrics directly on pull requests, helping reviewers identify untested code.
 * Easily assign remediation work to **{% data variables.copilot.copilot_cloud_agent %}**, if you have a {% data variables.product.prodname_copilot_short %} license.
 
 ## Availability and usage costs
@@ -63,6 +64,8 @@ In addition, you'll see an AI-powered analysis of all recent pushes to the defau
 
 When {% data variables.product.prodname_codeql %} finds rule-based problems on pull requests, you'll see comments from the `{% data variables.code-quality.pr_commenter %}`. Where possible, each comment will include a {% data variables.copilot.copilot_autofix_short %} suggestion on how to fix the problem. See [AUTOTITLE](/code-security/code-quality/tutorials/fix-findings-in-prs).
 
+If you have set up code coverage, the `{% data variables.code-quality.pr_commenter %}` also posts a coverage summary showing the aggregate coverage percentage for the PR branch compared to the default branch. See [AUTOTITLE](/code-security/how-tos/maintain-quality-code/interpret-results#viewing-code-coverage-on-pull-requests).
+
 ### Default branch results
 
 {% data variables.product.prodname_code_quality_short %} findings on the default branch are reported on "{% data variables.code-quality.code_quality_ui %}" pages on the **{% data variables.product.prodname_security_and_quality_tab %}** tab for the repository:

content/code-security/how-tos/maintain-quality-code/enable-code-quality.md

@@ -42,4 +42,5 @@ category:
 ## Next steps
 
 * **For your repository:** Explore your code quality findings and merge your first fix. See [AUTOTITLE](/code-security/tutorials/improve-code-quality/quickstart).
+* **Add code coverage:** Upload test coverage reports to see coverage results directly on pull requests. See [AUTOTITLE](/code-security/how-tos/maintain-quality-code/set-up-code-coverage).
 * **For your organization:** Understand the code health of your repositories at a glance. See [AUTOTITLE](/code-security/how-tos/view-and-interpret-data/analyze-organization-data/explore-code-quality).

content/code-security/how-tos/maintain-quality-code/index.md

@@ -8,6 +8,7 @@ versions:
 contentType: how-tos
 children:
   - /enable-code-quality
+  - /set-up-code-coverage
   - /interpret-results
   - /set-pr-thresholds
   - /unblock-your-pr

content/code-security/how-tos/maintain-quality-code/interpret-results.md

@@ -54,6 +54,18 @@ Code quality results should always be interpreted in the context of your reposit
 
 To learn more about the metrics and how the ratings are calculated, see [AUTOTITLE](/code-security/code-quality/reference/metrics-and-ratings).
 
+## Viewing code coverage on pull requests
+
+After code coverage is configured for your repository, the `{% data variables.code-quality.pr_commenter %}` posts a coverage summary comment on each pull request. The comment includes:
+
+* **Branch-vs-default-branch comparison:** The aggregate coverage percentage for the pull request branch and the default branch (for example, "65% on pull request branch, 44% on default branch").
+* **Most impacted files:** The 10 files with the largest coverage changes between the default branch and the pull request branch. This list may include files not directly modified in the pull request. New or modified files are ranked above deleted files. Within each group, files are sorted by the absolute change in line coverage weighted by the number of lines in the file, with coverage magnitude and then filename as tiebreakers.
+* **Per-file breakdown:** An expandable section listing each file with its coverage percentage and delta value. A positive delta means the file gained coverage on this branch. A negative delta indicates coverage decreased, which may signal untested code paths introduced by the change.
+
+Use the coverage summary to identify files with low or declining coverage and prioritize review attention on untested changes.
+
+For more information about how the coverage percentage is calculated, see [AUTOTITLE](/code-security/reference/code-quality/metrics-and-ratings#code-coverage).
+
 ## Next steps
 
 * Remediate quality findings in your default branch and improve the maintainability and reliability rating for your repository. See [AUTOTITLE](/code-security/code-quality/tutorials/improve-your-codebase).

content/code-security/how-tos/maintain-quality-code/set-up-code-coverage.md

@@ -0,0 +1,129 @@
+---
+title: Setting up code coverage for your repository
+shortTitle: Set up code coverage
+intro: 'Upload test coverage reports to see coverage results directly on pull requests, helping reviewers identify untested code before merging.'
+versions:
+  feature: code-quality
+product: '{% data reusables.gated-features.code-quality-availability %}'
+permissions: '{% data reusables.permissions.code-quality-repo-enable %}'
+contentType: how-tos
+layout: inline
+category:
+  - Improve code quality
+---
+
+{% data reusables.code-quality.code-quality-preview-note %}
+
+In the following procedures, you will generate a Cobertura XML coverage report from your test suite, upload it to {% data variables.product.github %}, and view the coverage results on your pull requests.
+
+## Prerequisites
+
+* {% data variables.product.prodname_code_quality_short %} is enabled for your repository.
+* Your repository has a test suite that runs in {% data variables.product.prodname_actions %}.
+* Your test framework can produce a coverage report in **Cobertura XML** format.
+
+## Step 1: Generate a Cobertura XML coverage report
+
+Configure your test framework to output a coverage report in the Cobertura XML format. Code coverage works with any programming language that can produce this format.
+
+1. Identify the coverage tool for your language from the table below.
+1. Add the appropriate command or configuration to your CI workflow so that a Cobertura XML file is generated each time your tests run.
+
+| Language | Framework / Tool | How to generate Cobertura XML |
+|----------|-----------------|-------------------------------|
+| Python | `pytest` + `pytest-cov` | `pytest --cov=. --cov-report=xml` |
+| Java | JaCoCo | Use the `cover2cover.py` script or the JaCoCo-to-Cobertura Gradle/Maven plugin |
+| JavaScript/TypeScript | Istanbul / `nyc` | `nyc report --reporter=cobertura` |
+| Ruby | SimpleCov | Add `SimpleCov::Formatter::CoberturaFormatter` |
+| Go | `go test` + `gocover-cobertura` | `go test -coverprofile=cover.out && gocover-cobertura < cover.out > coverage.xml` |
+
+> [!TIP]
+> If your framework isn't listed above, check its documentation for Cobertura output support. Many tools either support it directly or can convert to Cobertura XML from other formats.
+
+## Step 2: Upload the coverage report
+
+After your tests generate a Cobertura XML report, upload it to {% data variables.product.github %} so coverage results appear on pull requests.
+
+1. Open your repository's CI workflow file (for example, `.github/workflows/ci.yml`).
+1. Add the following step after the step that runs your tests and generates the coverage report:
+
+   ```yaml copy
+   - name: Upload coverage report
+     if: {% raw %}github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository{% endraw %}
+     uses: actions/upload-code-coverage@v1
+     with:
+       report: COVERAGE-FILE-PATH.xml
+       language: LANGUAGE
+       label: LABEL
+   ```
+
+1. Replace the following values:
+   * **`COVERAGE-FILE-PATH.xml`**: The path to your Cobertura XML report (for example, `coverage.xml` or `target/site/jacoco/cobertura.xml`).
+   * **`LANGUAGE`**: The primary language of the code being covered (for example, `Python`, `Java`, `JavaScript`).
+   * **`LABEL`**: An optional label to identify this coverage report (for example, `code-coverage/pytest`).
+1. Commit and push the workflow change.
+
+### Full workflow example
+
+This example runs Python tests with `pytest-cov` and uploads the coverage report:
+
+```yaml annotate copy
+# This workflow runs your test suite, generates a Cobertura XML coverage report, and uploads it to {% data variables.product.github %}. Once this workflow is committed, coverage results appear automatically on every pull request.
+name: Code Coverage
+
+# Run on pushes to the default branch (to establish the baseline) and on pull requests (to compare against it). {% data variables.product.prodname_code_quality_short %} compares PR branch coverage to the default branch, so both triggers are needed.
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+# The `code-quality: write` permission is required to upload coverage data. No other elevated permissions are needed.
+permissions:
+  contents: read
+  code-quality: write
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      # Check out the PR head commit (not the merge commit) so coverage line numbers map correctly to the diff.
+      - uses: {% data reusables.actions.action-checkout %}
+        with:
+          ref: {% raw %}${{ github.event.pull_request.head.sha || github.sha }}{% endraw %}
+
+      # Replace this step with whatever language setup your project uses (Node.js, Java, Go, etc.). The upload action works with any language that produces a Cobertura XML report.
+      - uses: {% data reusables.actions.action-setup-python %}
+        with:
+          python-version: "3.x"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+          pip install pytest pytest-cov
+
+      # Adapt this step for your test framework. The key requirement is producing a Cobertura XML file. For other languages, see the framework table earlier in this article.
+      - name: Run tests with coverage
+        run: pytest --cov=. --cov-report=xml
+
+      # This step replaces any third-party coverage upload (Codecov, Coveralls, etc.). After this runs, the `{% data variables.code-quality.pr_commenter %}` bot posts a coverage summary directly on the pull request.
+      - name: Upload coverage report
+        if: {% raw %}github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository{% endraw %}
+        uses: actions/upload-code-coverage@v1
+        with:
+          report: coverage.xml
+          language: Python
+          label: code-coverage/pytest
+```
+
+## Step 3: View coverage results on pull requests
+
+1. Open a pull request (or push to an existing one) that triggers the workflow you configured.
+1. After the workflow completes, look for a comment from `{% data variables.code-quality.pr_commenter %}` on the pull request. The comment includes:
+   * The aggregate coverage percentage for the pull request branch compared to the default branch.
+   * A per-file breakdown showing which files gained or lost coverage.
+
+## Next steps
+
+* **Interpret results:** Understand coverage metrics and per-file breakdowns on your pull requests. See [AUTOTITLE](/code-security/how-tos/maintain-quality-code/interpret-results).

content/code-security/reference/code-quality/metrics-and-ratings.md

@@ -47,6 +47,22 @@ These ratings are used to summarize the overall reliability and maintainability
 | **Fair**             | Codebase has moderate-severity issues that may impact quality, but are not critical. | ≥1 "Warning" level finding              |
 | **Needs Improvement**| Codebase has high-severity issues, including bugs or major maintainability risks. | ≥1 "Error" level finding                |
 
+## Code coverage
+
+Code coverage measures what percentage of your source code is executed when your test suite runs. {% data variables.product.prodname_code_quality_short %} displays a coverage percentage on pull requests after you upload a Cobertura XML coverage report.
+
+### How coverage is calculated
+
+The coverage percentage represents the number of lines covered by tests divided by the total number of lines, expressed as a percentage. {% data variables.product.prodname_code_quality_short %} stores the latest upload for each branch (including the default branch) and compares the PR branch coverage to the default branch coverage.
+
+For example, if your default branch has 44% coverage and your PR branch has 65% coverage, the PR gained 21 percentage points of coverage.
+
+### Per-file delta
+
+The per-file breakdown on pull requests shows how coverage changed for each modified file. A positive delta means the file gained coverage on the PR branch compared to the default branch.
+
+To set up code coverage for your repository, see [AUTOTITLE](/code-security/how-tos/maintain-quality-code/set-up-code-coverage).
+
 ## Further reading
 
 * [AUTOTITLE](/code-security/code-quality/concepts/about-code-quality)

content/copilot/concepts/agents/cloud-agent/about-cloud-agent.md

@@ -148,6 +148,7 @@ You can customize {% data variables.copilot.copilot_cloud_agent %} in a number o
 * **{% data variables.product.prodname_copilot_short %} can only make changes in the repository specified when you start a task**. {% data variables.product.prodname_copilot_short %} cannot make changes across multiple repositories in one run.
 * **By default, {% data variables.product.prodname_copilot_short %} can only access context in the repository specified when you start a task**. The {% data variables.product.prodname_copilot_short %} MCP server is configured by default to allow {% data variables.product.prodname_copilot_short %} to access context (for example issues and historic pull requests) in the repository where it is working. You can, however, configure broader access. See [AUTOTITLE](/copilot/how-tos/use-copilot-agents/cloud-agent/extend-cloud-agent-with-mcp).
 * **{% data variables.product.prodname_copilot_short %} can only work on one branch at a time** and can open exactly one pull request to address each task it is assigned.
+* **Each {% data variables.copilot.copilot_cloud_agent %} session has a maximum execution time of 59 minutes**. This is a hard limit that cannot be extended or bypassed. If a task exceeds this limit, the session will time out and stop. For complex tasks that may require more time, consider breaking the work into smaller, more focused tasks. You can configure a shorter timeout using the `timeout-minutes` setting in your `copilot-setup-steps.yml` file. See [AUTOTITLE](/copilot/how-tos/use-copilot-agents/cloud-agent/customize-the-agent-environment).
 
 ### Limitations in {% data variables.copilot.copilot_cloud_agent %}'s compatibility with other features