Merge branch 'master' into new-doc-framework--its-xmas-baby

Author: DMarinhoCodacy

.github/workflows/mkdocs.yml

@@ -10,9 +10,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
-          token: ${{ secrets.DEPLOYMENT_PERSONAL_ACCESS_TOKEN }}
+          token: ${{ secrets.GITHUB_TOKEN }}
           submodules: true
           # git-revision-date-localized-plugin and mkdocs-rss-plugin need full git history depth
           fetch-depth: 0
@@ -96,7 +96,7 @@ jobs:
         uses: peaceiris/actions-gh-pages@v4
         if: github.ref == 'refs/heads/master'
         with:
-          personal_token: ${{ secrets.DEPLOYMENT_PERSONAL_ACCESS_TOKEN }}
+          github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./site
           destination_dir: ./
           keep_files: true

docs/enterprise-cloud/github-enterprise-cloud.md

@@ -1,56 +1,56 @@
 # GitHub Enterprise Cloud
 
-Use your GitHub Enterprise credentials when signup or login to Codacy and all your GitHub Enterprise organizations that you belong to, will be available to be added as Organizations on Codacy.
+Use your GitHub Enterprise credentials when signing up or logging in to Codacy and all your GitHub Enterprise organizations that you belong to, will be available to be added as Organizations on Codacy.
 
-Codacy also has a dedicated Enterprise area where GitHub Enterprise admins and owners of the enterprise will be able to manage them.
+Codacy also has a dedicated Enterprise area where GitHub Enterprise admins and owners of the enterprise will be able to manage their respective organizations.
 
 ### GitHub Enterprise types
-Codacy supports both [GitHub Enterprises types](https://docs.github.com/en/enterprise-cloud@latest/admin/managing-iam/understanding-iam-for-enterprises/choosing-an-enterprise-type-for-github-enterprise-cloud), Managed Users and Personal Accounts.
+Codacy supports both [GitHub Enterprise types](https://docs.github.com/en/enterprise-cloud@latest/admin/managing-iam/understanding-iam-for-enterprises/choosing-an-enterprise-type-for-github-enterprise-cloud), Managed Users and Personal Accounts.
 
 ## Access cloud Enterprises 
-Access you enterprises in Codacy by setting up its integration:
+Access your Enterprises in Codacy by setting up its integration:
 
-1. In codacy app, click on your avatar image, in the top right corner
-1. then navigate throught "My account" and "Access management"
+1. In Codacy, click on your avatar, in the top right corner
+2. Navigate through "My account" and "Access management"
 1. There, you'll be able to add a **GitHub Enterprise Cloud** access token. 
 
-Once generated and added in Codacy you will start seeing all infomration you have access to regarding your cloud enterprises. 
-You can revoke the cloud enterpises access at any time in the same place.
+Once generated and added in Codacy you will start seeing all the information you have access to regarding your Cloud Enterprises. 
+You can revoke the Cloud Enterpises' access at any time in the same place.
 ![Enterprise cloud manage enterprises access](images/Codacy-Access-Management.png)
 
 
 ## Manage Enterprises 
 - [Enterprise organizations list](#enterprise-organizations-list)
 - [Seats management](#seats)
-- [Enterprise Limitations](#limitations)
+- [Enterprise limitations](#limitations)
 
-Once signup or login with your GitHub Enterprise credentials and, [setup access to could enterprises](#access-cloud-enterprises), navigate to your Enterprises area to manage your enterprises in Codacy, as well its organizations and seats management. 
+Once you sign up or log in with your GitHub Enterprise credentials and, [set up access to Cloud Enterprise](#access-cloud-enterprises), navigate to your Enterprise area to manage your Enterprises in Codacy, as well as its organizations and seats management. 
 
 !!! note 
     If you only have one Enterprise, Codacy will skip this screen and directs you to the [enterprise organizations list](#enterprise-organizations-list). 
 
 ![Enterprise cloud manage enterprises](images/Codacy-Enterprises.png)
 
 ### Enterprise organizations list
-Choose to view a enterprise and access its list of existing organizations, that you have access to.
+Select an Enterprise and access its list of existing organizations that you have access to.
 ![Enterprise cloud manage organizations](images/Codacy-Enterprise-Organizations.png)
 
 ### Seats
-View and export your enterprise seats and its activity by:
+View and export your Enterprise seats and its activity by:
 
-1. Choose and view an enterprise organization
-1. Navigate to **People** on the left-handside navigation
+1. Choose and view an Enterprise organization
+1. Navigate to **People** on the left-hand side navigation
 1. View, search and export the list of author seats
 
 !!! note 
-    - Codacy members won't be part of this list, only authors, users that have done commits. 
-    - In some Enterprise plans, **Members** are people that signup and joined an Organization in Codacy, and **Authors** are people that contribute to code changes. It can happen that Authors aren't Codacy Members. 
+    - Codacy members won't be part of this list; only authors and users that have committed. 
+    - In some Enterprise plans, **Members** are people that signed up and joined an Organization in Codacy, and **Authors** are people that contribute to code changes. It can happen that Authors aren't Codacy Members. 
     - Only Enterprise **Owners** or **Admins** will be able to view and export the list of authors. 
 
 ### Limitations
 Currently, the integration between Codacy and GitHub Enterprise has the following limitations:
 
--   **Repositories with visibility Internal** will, in Codacy, have the same behavior as Private visibility. Although you see the repository in the provider, if you aren't part of the repository in the provider, you won't be able to see it in Codacy.
+-   **Repositories with visibility set to Internal** will, in Codacy, have the same behavior as those with Private visibility. Although you see the repository in the provider, if you aren't part of the repository in the provider, you won't be able to see it in Codacy.
 -   **Same email connected to multiple GitHub accounts.** Codacy won't allow you to connect your enterprise account if that email is already associated with a different GitHub account. You can manage your [associated emails in the provider GitHub](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/adding-an-email-address-to-your-github-account).
 -   **GitHub Cloud data residency is not supported.** Codacy is incompatible with GitHub Enterprise Cloud's data residency features. If your GitHub Enterprise Cloud has data residency enabled, Codacy won't be able to access or process your repositories. 
 

docs/getting-started/codacy-quickstart.md

@@ -7,9 +7,9 @@ nav_step: 0
 
 Codacy is an automated code quality and coverage platform that analyzes your source code and identifies issues as you go, helping your team ship robust software by scanning over 40 programming languages, such as JavaScript, Python, Java, C#, and PHP.
 
-Check out our product demo for an overview of Codacy's main features (recorded on May 13, 2024):
+Check out our product demo for an overview of Codacy's main features (recorded on November, 2025):
 
-<div style="position: relative; padding-bottom: 61.224489795918366%; height: 0;"><iframe src="https://www.loom.com/embed/1ed27d66b659427883ddd28e57468c22" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"></iframe></div>
+<div style="position: relative; padding-bottom: 61.224489795918366%; height: 0;"><iframe src="https://www.loom.com/embed/b4dbb1342309493c8e34097e9e797549" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"></iframe></div>
 
 By integrating with your Git provider, Codacy keeps track of your team’s work, analyzes relevant commits, highlights problems, suggests improvements, and protects your codebase from unwelcome changes. From organization and repository level to individual files, pull requests, and commits, Codacy monitors the following metrics across your projects:
 

docs/getting-started/configuring-your-repository.md

@@ -19,7 +19,7 @@ To configure your repository, follow these steps:
 
 ## 1. Ignoring files {: id="ignoring-files"}
 
-[Ignore any files and directories](../repositories-configure/ignoring-files.md) that aren't relevant for the Codacy analysis, such as generated code or any third-party libraries included in your repositories.
+[Ignore any files and directories](../repositories-configure/ignoring-files.md) that aren't relevant for the Codacy analysis, such as generated code or any third-party libraries included in your repositories. Learn more about [Ignoring files](../repositories-configure/ignoring-files.md).
 
 ![Ignoring files](../repositories-configure/images/ignored-files.png)
 

docs/organizations/codacy-usage.md

@@ -0,0 +1,83 @@
+# Codacy usage
+
+The **Codacy usage** dashboard provides an overview of your organization's configurations and their impact. You can filter repositories by quality gates and coverage, select specific repositories, or use [the segments that you have set up](segments.md).
+
+![Codacy usage dashboard](images/codacy-usage-dashboard.png)
+
+!!! important
+    The repositories **not in Codacy** metric is only available to GitHub accounts.
+
+To view the **Codacy usage** dashboard:
+
+- Select an organization from the top navigation bar.
+- On the organization overview page, click the Codacy usage tab.
+
+The **Codacy usage dashboard** includes the following sections/charts to help you monitor Codacy adoption:
+
+- [Repositories](#repositories)
+- [Repositories evolution](#repositories-evolution)
+- [Merged pull requests](#merged-pull-requests)
+- [Repositories list](#repositories-list)
+
+!!! tip
+    In each section, you can click on the ellipsis icon in the top right corner to export that section's data to CSV or JSON.
+
+## Repositories
+
+This chart displays the distribution of repositories that are and are not in Codacy. The doughnut chart also details the breakdown of Codacy repositories based on their configurations: those without quality gates, without coverage, without either gates or coverage, and those with both gates and coverage. Users can interact with the doughnut chart or the numerical data to filter the results. Applying a filter will also affect the repositories displayed in the evolution chart and the results will appear in the **Repositories list**.
+
+!!! note
+    Repository coverage data is based on the last merged pull request, meaning that if a repository has coverage setup but coverage was not sent in the last merged PR, it will not count as a repository with Coverage.
+
+![Repositories distribution](images/repositories-distribution.png)
+
+## Repositories evolution
+
+This chart shows the trend of repositories in your organization over time, considering the filters applied, affecting the **Repositories list**. You can hover over the chart to see the number of repositories on a specific date. You can also click on the chart to filter results.
+
+![Repositories evolution](images/repositories-evolution.png)
+
+## Merged pull requests
+
+This chart tracks the total volume of pull requests merged across your Codacy-managed repositories. It serves as a high-level health check to ensure that your team's development velocity is aligned with your quality standards. 
+Interacting with the chart allows you to filter the data, with the resulting repositories displayed in the **Repositories list**.
+
+### Understanding the categories
+
+- Passing Gates: These PRs met all your quality standards (e.g., coverage, complexity, security) before being merged.
+- Failing Gates: PRs merged despite failing one or more quality checks.
+- Without Gates: PRs merged into repositories where no quality gates are configured. 
+- Never Analyzed: PRs that reached a "Merged" status without Codacy completing an analysis.
+
+#### Why are some PRs "Never analyzed"?
+
+If you see high numbers here, it usually boils down to two scenarios:
+
+1. A developer merged the PR immediately after opening it, before the Codacy analysis could finish. To improve this, ensure your team adjusts their workflow to wait for the "Codacy/Analysis" check to turn green before merging or by making the Codacy status check mandatory.
+
+2. In organizations with manual user management (check your billing settings), if a PR is authored by an email/user not yet added to your Codacy seat count, the analysis may be skipped. You should check your [seat management](../organizations/managing-people.md) to confirm that all active contributors are correctly mapped to a Codacy seat.”
+
+
+#### Why are some PRs merged with "Failing gates"?
+
+Pull requests are merged with failing Quality Gates usually due to two reasons:
+
+1. Quality Gates are advisory, not blocking. [Protect your pull requests](../getting-started/integrating-codacy-with-your-git-workflow.md#blocking-pull-requests).
+
+2. Intentional exceptions or risk acceptance:
+    - Developers/maintainers may override failing checks to address urgent fixes, unblock critical work, or accept a known risk temporarily.
+
+    - Sometimes pull requests are small and diff coverage / coverage variation may fail. Make sure your team follows the practices that were agreed upon within the organization.
+
+Interacting with the chart allows you to filter the data, with the resulting repositories displayed in the **Repositories list**.
+
+!!! note
+    Merged pull requests data is only from repositories that are in Codacy.
+
+![Merged pull requests](images/merged-pull-requests.png)
+
+## Repositories list
+
+The list shows a maximum of 10 repositories from your Git provider. You can use filters to display repositories that aren't yet in Codacy, or repositories that are already in Codacy. For repositories in Codacy, the list can also group them by specific metrics such as gates, coverage, and merged pull request information. Despite the 10 repository limit, the Repositories list section allows you to download a list up to 100 repositories.
+
+![Repositories list](images/repositories-list.png)