feat: Audit logs PLUTO-952 (#2122)

* feat: Add page listing audit log events * wip: Highlight wip message * feat: Add policy events * wip: Add ongoing notes * feat: Clarify feature availability * clean: Rename file * fix: Typo * feat: Add new page for audit logs concept * feat: Add example to retrieve audit logs * fix: Fix links * feat: Update API example request and response * clean: Improved required role admonition * feat: Add concept * feat: Add action column to event tables; Tweaks * feat: Add some actions; Tweak * feat: Add retention period * fix: Typo * feat: Add feature to roles and permissions tables * wip: Add TODO * feat: Add FAQ page * WIP: SIgnalize page to delete * clean: Tweaks * feat: Remove pagination * feat: Update example to remove pagination * feat: Update example data * clean: Remove TODOs from example * feat: Add event actions * feat: Delete sign up event * clean: Tweak for completeness * feat: Add/update event actions * clean: Delete temporary page * fix: Fix action * feat: Rename business tier to business plan * feat: Improve event definition * feat: Add links to corresponding features * fix: Attempt to fix link * fix: Attempt to fix link * feat: Update example output * feat: Delete unlogged events * fix: Fix actions * feat: Add repository management permissions event * feat: Delete unlogged event * clean: Small tweak * feat: Update coding standard events * clean: Delete event actions TODOs * feat: Update endpoint link * feat: Remove link to API example * clean: Tweak * clean: Tweaks * clean: Delete audit API example * clean: Move provider links to first column for consistency; Tweaks * clean: Tweak for correctness --------- Co-authored-by: David Geirola <[email protected]> Co-authored-by: Nicola Klemenc <[email protected]> Co-authored-by: Francisco Azevedo <[email protected]>
codacy · Aug 7, 2024 · 9cf269c · 9cf269c
1 parent ccdd4c5
commit 9cf269c
Show file tree

Hide file tree

Showing 5 changed files with 110 additions and 2 deletions.
diff --git a/docs/assets/includes/paid.md b/docs/assets/includes/paid.md
@@ -9,3 +9,7 @@
 <!--paid-feature-start-->
 !!! info "This is a [paid feature](https://www.codacy.com/pricing)"
 <!--paid-feature-end-->
+
+<!--paid-feature-business-start-->
+!!! info "This feature is [only available on Business plan](https://www.codacy.com/pricing)"
+<!--paid-feature-business-end-->
diff --git a/docs/faq/general/does-codacy-keep-audit-logs.md b/docs/faq/general/does-codacy-keep-audit-logs.md
@@ -0,0 +1,5 @@
+# Does Codacy keep audit logs for my organization?
+
+On [Business plan](https://www.codacy.com/pricing), Codacy logs significant organization events that can be retrieved for audit reporting.
+
+See [Audit logs for organizations](../../organizations/audit-logs-for-organizations.md) for the complete list of events that Codacy logs, and how to obtain audit log data.
diff --git a/docs/organizations/audit-logs-for-organizations.md b/docs/organizations/audit-logs-for-organizations.md
@@ -0,0 +1,70 @@
+---
+description: List of events that Codacy can log for an organization.
+---
+
+# Audit logs for organizations
+
+{%
+    include-markdown "../assets/includes/paid.md"
+    start="<!--paid-feature-business-start-->"
+    end="<!--paid-feature-business-end-->"
+%}
+
+Codacy logs important events in your organization, reflecting when your team members execute specific operations. This enables the generation of comprehensive reports to assist you with the audit process. For example, you can track who added a repository to Codacy, or changed the settings of a coding standard.
+
+[Organization admins and organization managers](./roles-and-permissions-for-organizations.md) can obtain the audit log data of the organization events using the Codacy API endpoint [listAuditLogsForOrganization](https://api.codacy.com/api/api-docs#listauditlogsfororganization).
+
+The retention period of audit logs for organization events is one year.
+
+## Audit log events
+
+Each audit log tracks when a Codacy user executed a specific operation in your organization using the Codacy app or the [Codacy API](https://api.codacy.com/api/api-docs#codacy-api). Each operation is identified by an **action**. For the detailed content of each audit log, see the [Codacy API reference](https://api.codacy.com/api/api-docs#listauditlogsfororganization).
+
+The sections below list the events that Codacy logs for your organization at user, organization, and repository levels.
+
+### User
+
+|Event|Description|Action|
+|-----|-----------|------|
+|Log in|User logged in to Codacy|`user.login`|
+|Create [account API token](../codacy-api/api-tokens.md#account-api-tokens)|New account API token created|`user.tokens.create`|
+|Read account API token|List of account API tokens retrieved|`user.tokens.read`|
+|Delete account API token|Account API token deleted|`user.tokens.delete`|
+
+### Organization
+
+|Event|Description|Action|
+|-----|-----------|------|
+|[Add organization](./what-are-organizations.md#adding-an-organization)|Organization added to Codacy|`organizations.create`|
+|[Add people](./managing-people.md#adding-people) to organization|New people added to the organization|`organizations.people.create`|
+|[Join organization](./managing-people.md#joining)|User joined the organization|`organizations.join`|
+|Update [repository management permissions](./roles-and-permissions-for-organizations.md#change-analysis-configuration)|Repository management permissions updated|`organizations.analysisconfigurationminimumpermission.update`|
+|Assign [organization manager role](./roles-and-permissions-for-organizations.md#managing-the-organization-manager-role)|Organization manager role assigned to a team member|`organizations.security.managers.create`|
+|Revoke organization manager role|Organization manager role revoked from a team member|`organizations.security.managers.delete`|
+|Update [default Git provider configuration](./integrations/default-git-provider-integration-settings.md)|Default Git provider configuration for the organization updated|`organizations.integrations.providersettings.update`|
+|Apply default Git provider configuration to all repositories|Default Git provider configuration applied to all repositories of the organization|`organizations.integrations.providersettings.apply`|
+|Create new organization hook|New organization webhook created|`organizations.settings.hooks.create`|
+|Create new [gate policy](./using-gate-policies.md)|New gate policy created|`organizations.gatepolicies.create`|
+|Update gate policy|Quality gate definition updated|`organizations.gatepolicies.update`|
+|Apply gate policy to repositories|Gate policy applied to a list of repositories|`organizations.gatepolicies.repositories.apply`|
+|Make gate policy default|Gate policy was made the default for the organization|`organizations.gatepolicies.setdefault`|
+|Make Codacy gate policy default|Built-in Codacy gate policy was made the default for the organization|`organizations.gatepolicies.setcodacydefault`|
+|Delete gate policy|Gate policy deleted|`organizations.gatepolicies.delete`|
+|Create new [coding standard](./using-coding-standards.md) using preset sensitivity levels|New coding standard created|`organizations.presetsstandards.create`|
+|Create new coding standard draft using individual language and code pattern settings|New coding standard draft created|`organizations.codingstandards.create`|
+|Create new coding standard from draft|New coding standard created|`organizations.codingstandards.promote`|
+|Update coding standard from draft|Coding standard updated|`organizations.codingstandards.promote`|
+|Apply coding standard to repositories|Coding standard applied to a list of repositories|`organizations.codingstandards.repositories.apply`|
+|Make coding standard default|Coding standard was made the default|`organizations.codingstandards.setdefault`|
+|Delete coding standard|Coding standard deleted|`organizations.codingstandards.delete`|
+
+### Repository
+
+|Event|Description|Action|
+|-----|-----------|------|
+|Create new [post-commit hook](../repositories-configure/integrations/post-commit-hooks.md)|New repository hook created|`repositories.integrations.postcommithook`|
+|Create [repository API token](../codacy-api/api-tokens.md#repository-api-tokens)|New repository API token created|`repositories.tokens.create`|
+|Read repository API token|List of repository API tokens retrieved|`repositories.tokens.read`|
+|Delete repository API token|Repository API token deleted|`repositories.tokens.delete`|
+|Update Git provider integration settings<br>([GitHub](../repositories-configure/integrations/github-integration.md#configuring), [Bitbucket](../repositories-configure/integrations/bitbucket-integration.md#configuring), or [GitLab](../repositories-configure/integrations/gitlab-integration.md#configuring))|Git provider integration settings for the repository updated|`repositories.integrations.providersettings.update`|
+|Refresh Git provider integration<br>(applies only to [Bitbucket](../repositories-configure/integrations/bitbucket-integration.md#refreshing) and [GitLab](../repositories-configure/integrations/gitlab-integration.md#refreshing))|Git provider integration for the repository refreshed|`repositories.integrations.refreshprovider`|
diff --git a/docs/organizations/roles-and-permissions-for-organizations.md b/docs/organizations/roles-and-permissions-for-organizations.md
@@ -199,6 +199,15 @@ The table below maps the GitHub Cloud and GitHub Enterprise roles to the corresp
       <td class="yes">Yes</td>
       <td class="yes">Yes</td>
     </tr>
+    <tr>
+      <td>Obtain audit logs for organization events<sup>5</sup></td>
+      <td class="no">No</td>
+      <td colspan="2" class="no">No</td>
+      <td colspan="2" class="no">No</td>
+      <td class="no">No</td>
+      <td class="yes">Yes</td>
+      <td class="yes">Yes</td>
+    </tr>
     <tr>
       <td>Invite and accept members,<br/>modify billing</td>
       <td class="no">No</td>
@@ -223,7 +232,8 @@ The table below maps the GitHub Cloud and GitHub Enterprise roles to the corresp
 <sup>1</sup>: Outside collaborators aren't supported as members of organizations on Codacy. You can still [add outside collaborators to Codacy](managing-people.md#adding-people) so that Codacy analyzes their commits to private repositories, but they won't be able to join your Codacy organization.  
 <sup>2</sup>: Joining an organization may need an approval depending on your setting for [accepting new people](changing-your-plan-and-billing.md#allowing-new-people-to-join-your-organization).  
 <sup>3</sup>: These users can only see security items originating from Codacy repositories that they follow.  
-<sup>4</sup>: Requires that an organization owner has given the Codacy GitHub App access to the repositories to add or remove.
+<sup>4</sup>: Requires that an organization owner has given the Codacy GitHub App access to the repositories to add or remove.  
+<sup>5</sup>: [Audit logs](./audit-logs-for-organizations.md) are available only on [Business plan](https://www.codacy.com/pricing).
 
 ## Permissions for GitLab
 
@@ -353,6 +363,15 @@ The table below maps the GitLab Cloud and GitLab Enterprise roles to the corresp
       <td class="yes">Yes</td>
       <td colspan="2" class="yes">Yes</td>
     </tr>
+    <tr>
+      <td>Obtain audit logs for organization events<sup>4</sup></td>
+      <td class="no">No</td>
+      <td colspan="2" class="no">No</td>
+      <td class="no">No</td>
+      <td colspan="2" class="no">No</td>
+      <td class="yes">Yes</td>
+      <td colspan="2" class="yes">Yes</td>
+    </tr>
     <tr>
       <td>Invite and accept members,<br/>modify billing</td>
       <td class="no">No</td>
@@ -377,6 +396,7 @@ The table below maps the GitLab Cloud and GitLab Enterprise roles to the corresp
 <sup>1</sup>: External users aren't supported as members of organizations on Codacy. You can still [add external users to Codacy](managing-people.md#adding-people) so that Codacy analyzes their commits to private repositories, but they won't be able to join your Codacy organization.  
 <sup>2</sup>: Joining an organization may need an approval depending on your setting for [accepting new people](changing-your-plan-and-billing.md#allowing-new-people-to-join-your-organization).  
 <sup>3</sup>: These users can only see security items originating from Codacy repositories that they follow.  
+<sup>4</sup>: [Audit logs](./audit-logs-for-organizations.md) are available only on [Business plan](https://www.codacy.com/pricing).
 
 ## Permissions for Bitbucket
 
@@ -465,6 +485,12 @@ The table below maps the Bitbucket Cloud and Bitbucket Server roles to the corre
       <td class="yes">Yes</td>
       <td class="yes">Yes</td>
     </tr>
+    <tr>
+      <td>Obtain audit logs for organization events<sup>4</sup></td>
+      <td colspan="2" class="no">No</td>
+      <td class="yes">Yes</td>
+      <td class="yes">Yes</td>
+    </tr>
     <tr>
       <td>Invite and accept members,<br/>modify billing</td>
       <td colspan="2" class="no">No</td>
@@ -482,7 +508,8 @@ The table below maps the Bitbucket Cloud and Bitbucket Server roles to the corre
 
 <sup>1</sup>: Codacy can't distinguish the Bitbucket roles Read and Write because of a limitation on the Bitbucket API.  
 <sup>2</sup>: Joining an organization may need an approval depending on your setting for [accepting new people](changing-your-plan-and-billing.md#allowing-new-people-to-join-your-organization).  
-<sup>3</sup>: These users can only see security items originating from Codacy repositories that they follow.
+<sup>3</sup>: These users can only see security items originating from Codacy repositories that they follow.  
+<sup>4</sup>: [Audit logs](./audit-logs-for-organizations.md) are available only on [Business plan](https://www.codacy.com/pricing).
 
 ## See also
 

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -609,6 +609,7 @@ nav:
                 - Jira integration for Security and risk management: organizations/integrations/jira-integration.md
           - organizations/managing-security-and-risk.md
           - organizations/managing-people.md
+          - organizations/audit-logs-for-organizations.md
           - organizations/roles-and-permissions-for-organizations.md
           - organizations/changing-your-plan-and-billing.md
     - Your account:
@@ -638,6 +639,7 @@ nav:
                 - faq/general/how-does-codacy-support-bitbucket-server.md
                 - faq/general/how-does-codacy-keep-my-data-secure.md
                 - faq/general/how-does-codacy-protect-my-privacy.md
+                - faq/general/does-codacy-keep-audit-logs.md
                 - faq/general/how-do-i-allowlist-codacy-cloud-on-my-git-provider.md
                 - faq/general/how-can-i-change-or-cancel-my-plan.md
           - Repositories: