Gitlab hero border pattern left svg Gitlab hero border pattern right svg

Category Direction - Audit Reports

Audit Reports

Stage Maturity Content Last Reviewed
Manage Planned 2020-04-28

Introduction and how you can help

Thanks for visiting this direction page on Audit Reports in GitLab. If you'd like to provide feedback on this page or contribute to this vision, please feel free to open a merge request for this page or comment in the corresponding epic for this category.

You can also join our Compliance Special Interest Group (SIG) where you have a direct line of communication with the PM for Manage:Compliance.

GitLab is a single application for the CI/CD toolchain. This means we already see all of the information that's necessary for an audit. The Audit Reports category seeks to provide you with the tools and features you need to quickly and easily generate audit reports, in a format that works for auditors, out of the box.


Organizations operating in regulated industries have an obligation to report on their compliance. This could be to external auditors, internal auditing teams, an information security team, regulators or executive leadership. These reports usually manifest as evidence artifacts such as logs, configurations, access lists, screenshots and more. The process of finding, aggregating and compiling this information is time-consuming and tedious. In many cases, the person responsible for managing the audit or compliance program doesn't have the expertise, access or tools necessary to build scripts and other services to simplify these tasks. Even if they did, that's still an investment of time away from other value-adding activities.

Comprehensive Audit Reports are necessary to satisfy the needs of an organization managing a compliance program. Towards this end, we'll be working on building reports that set a baseline for each major area of GitLab.

The first four areas of focus will be: access, activity, code deploys, and deployment pipelines.

These reports will evolve over time to ensure they meet the needs of our customers' varying compliance program requirements.

Target Audience

Challenges to address

GitLab is a large application with many moving parts. This means you need to dig into many projects, audit logs, settings, or other resources to get the data you need as audit evidence. This is challenging, requires a lot of time, and each compliance requirement will need different types of evidence. Taking screenshots, combing through logs and walking an auditor through processes might sound like fun, but in reality, it's an experience full of friction.

Your organization is complex with policies and proceduresd to follow. Correlating those activities to specific GitLab functionality is difficult. Your auditors will audit your operations against the policies your organization defines. This means the audit can be inherently complex too. Audit Reports should just works out of the box for your specific needs. This means the reports should be customizable. Every audit is different and no single report will satisfy 100% of an auditor's questions. You need to be able to customize these reports to suit their needs, which will vary based on your organization, your auditor, and maybe your mood for the week!

Where we are Headed

Audits are about showing an auditor your organization's policies and procedures (what your organization says it's doing) and demonstrating those policies and procedures in action. An auditor will initially scope the policies, procedures, systems, and other areas to be covered and then use this information to guide the audit. If an organization claims that every visitor must sign in and sign out, the auditor will ask to see that process, see the activity in action, and then ask for evidence of that activity happening outside of the audit. These are general assertions since every audit is different.

With the varied nature of audits, GitLab is focused on building a comprehensive audit report that satisfies as many scenarios as we can. We'd like to ensure the audit reports you generate within GitLab contain, at a minimum, the following elements:

In the spirit of iteration, we'll be focused on building MVCs for each of these reports and then leverage customer feedback to determine how best to improve them and consolidate them into a single, thorough report.

What's Next & Why

GitLab has insight into all of the important data you need to pass an audit with flying colors and with minimal effort invested in collecting evidence artifacts. The problem is this data is not currently aggregated or structured in a way that makes sense for auditors and is not easily discoverable or exported. To solve this, we'll be focused on creating exportable reports for audit events and user access as our first two MVCs in Audit Reports.

Audit Events

We'll be adding an option to export instance-level audit events to csv for self-managed administrators. This will add the first audit report to GitLab's capabilities, enabling customers to easily export, parse, and analyze the data they need to investigate an incident, provide the evidence artifact to auditors, or analyze specific activity within their instance for compliance management. The inclusion of this report will move Audit Reports into the minimal maturity state.

User Access

Our next MVC will focus on implementing a custom API endpoint for generating a list of users with their respective group and project memberships. This API endpoint is necessary to reduce the processing overhead of these database queries so we can provide the important access management report that organizations need to audit their GitLab environment. Once implemented, we'll be following up with the issues in this epic to provide a simple, friendlier option for exporting this data within the UI that doesn't require custom tooling. The completion of this report will move Audit Reports into the viable state


Audit Reports is currently in the planned state. GitLab does not currently provide features that allow for easy export of important data that could specifically serve as evidence artifacts for a compliance program or audit.

Achieving a minimal state for Audit Reports means providing at least one basic report that users can retrieve. We believe this could be a csv export of all audit events for a self-managed instance. This can provide a necessary evidence artifact and empower customers to retrieve this data without building custom scripts or tooling.

Advancing Audit Reports to the viable state requires additional export options that solve additional problems around audit reporting. Our current plan is to achieve this state by adding an additional report for user access. Looking to the future, we'll be exploring audit reports for things like:

User Success Metrics

We'll know we're on the right track with Audit Reports based on the following metrics:

Competitive landscape

To be completed.

Analyst landscape

We do not currently engage with analysts in this category.

Top Customer Success/Sales issue(s)

Top user issue(s)

Top Vision issue(s)

To be completed.