Audit log

Overview

The audit log answers who did what, to which resource, and when — for every change made through Gitmoap, every sign-in, every push and clone, and every read of a credential surface. It is the record you reach for when a repository was deleted and nobody will say by whom, when a compliance questionnaire asks how you evidence administrative access, or when a token has leaked and you need to know exactly what it touched before you revoked it.

It is also tamper-evident. Records are sealed into a hash chain as they are written, and you can replay that chain on demand to prove that nothing in it has been edited, removed or reordered since — including by us. Nothing here can be edited or deleted by anyone, through any interface.

Before you start

How it works

What gets recorded

Every audited request produces exactly one record, written after the request finishes and carrying the status it actually returned. Three kinds of thing are audited, and the category is on every record and on every row of the table.

Ordinary reads are not recorded. Viewing a repository, listing commits, opening a file, reading a merge request — none of these leave a record, and that is deliberate: a log in which the browsing outnumbers the acting is a log nobody reads.

Two things follow from this that surprise people. A refused attempt is still recorded: a 403 on a delete produces a record with an outcome of denied, and a failed request produces one with an outcome of failure, because a rejected attempt is the highest-value line in a security review. And git ref discovery is not recorded — the negotiation that runs at the start of every git command, including the ones that transfer nothing — while the push and the fetch themselves are.

Three chains, and which one you can read

Every record is filed into exactly one chain, and which one follows the target on the record — the most specific thing the request named. This is the single most common source of "why is that not in my log".

So an organisation's log is the record of what happened to your groups and repositories. It does not hold your people's sign-ins or the personal access tokens they mint on their own accounts, and it does not hold the later edits to an individual merge request or work item — those file under whoever made them. Reaching any of those needs the platform-wide view.

What a record lets you answer

One expanded record carries more than the table shows, and each field is there to close a specific question.

The actor's name and email are captured as they were at the time and never rewritten, so a record still names the person who acted even after they leave and their account is removed.

Ordering, and the delay you will notice

Records are written just after the request they describe rather than inside it, so a record typically appears within a second of the action and occasionally a little later. If you make a change and immediately reload the log, refresh once more.

Listings come back newest first by when the action happened, and stay in that order across pages, so following the cursor to the end gives you one correctly ordered stream. The sequence number on a record is the chain's own ordering — the order records were sealed — which is close to, but not the same as, the order they occurred. Read it as chain position, not as a timeline. Positions restart at zero at the start of each month, and every record carries the month it sits in, so a sequence number identifies a record only together with that month.

What verification proves

The chain works by sealing each record with a hash over its own contents and the hash of the record before it. Change one character of one record, remove a record, or swap two, and every hash after that point stops matching. Verification replays the whole window and reports the first place the arithmetic fails.

How to

Read your organisation's audit log

The organisation view is the whole estate in one table: every audited action against every group and every repository beneath the top-level group, newest first.

Narrowing the list is the point of the view. In the web app, Category and Time range are drop-downs, and you set the actor filter by clicking the actor on a row, which then sits beside the bar as a chip you can remove. Over the API and the CLI the same three are --category, --from/--to and --actor, and --resource narrows to a single target id alongside them. --scope is accepted here and changes nothing: an organisation's listing always reads that organisation's own chain.

The time bounds are RFC-3339 instants, so --from 2026-08-01T00:00:00Z. Send them in UTC, the way the records themselves are stamped: a bound is compared against the recorded timestamps as written rather than parsed, so an offset like +02:00 is taken at face value and not converted, and a differently punctuated date such as 2026/08/01 matches nothing at all rather than being refused. The lower bound is inclusive and the upper bound is exclusive, which makes --from 2026-08-01T00:00:00Z --to 2026-09-01T00:00:00Z exactly the month of August with no double-counted midnight.

The actor, category and resource filters are applied to each page after it is read, so a page can come back with fewer rows than you asked for, or with none at all, while still handing you a cursor. That is not the end of the results. Keep following next_cursor until a response comes back without one — that, and only that, is the end. Note that these listings page on cursor and next_cursor, unlike most Gitmoap listings, which use next_token.

Read the audit records for one repository

The repository view is the same table narrowed to one codebase, and it is the right view for handing a single team the record of their own repository without handing them the whole organisation's.

A record belongs to the most specific thing the request named, and that one fact decides both which listing shows it and which chain holds it. A repository's log therefore holds the actions whose target is the repository — its settings, visibility, transfer and deletion, its members, its branches and tags, its pushes and fetches, and the creation of something nested inside it, because the repository is the only id such a request carries. Once that thing exists, changing it names the thing itself: editing, merging or deleting a merge request, changing a work item, updating a webhook or a service account all file under the person who acted, so neither this listing nor the organisation's will show them. Following one of those takes a platform administrator reading that person's chain.

This listing walks the repository's whole history rather than the last two years, and its --from and --to bounds are applied to each page after it is read, exactly like --actor and --category. Both mean the same thing in practice: follow the cursor rather than judging by how full a page came back.

Check that the record has not been altered

Verification is a read: it recomputes hashes from what is stored and writes nothing, so you can run it as often as you like, and a scheduled run is a reasonable control to point an auditor at.

Left alone, the check covers the current month and the twelve before it. Narrow or widen it with --from-month and --to-month, both YYYY-MM, when you need to attest to a specific period — a quarter, or a year that has since rolled over. Give only --to-month and the window is still thirteen months long, ending there.

A failure names what stopped adding up, and each answer says something different about what happened:

Any of the three is a serious finding. Record the position it names, the month it falls in and the window you ran, do not clear anything, and raise it — the position is what lets an investigation start at the right record rather than at the beginning. Because the replay runs a month at a time and positions restart each month, narrow the window to a single month to pin down which one broke.

Read across every organisation

The two calls below belong to Gitmoap's platform administrators, not to an organisation's Owner. They need a token carrying audit:read or audit:verify and platform administrator rights, and they answer 403 FORBIDDEN otherwise.

Without a --scope, the platform-wide listing reads the platform's own chain. Give it --scope to read one organisation's or one person's chain — the value names the chain rather than the resource, so it is ROOT# followed by the top-level group's id, or USER# followed by the person's id — the same value that appears on every record it returns. This is how you reach the sign-in history of a single account, which no organisation-level view exposes. Give it --actor or --resource instead and it searches across every chain for one person or one target, which is the query to run when you know a token has leaked and need everything it touched, wherever it happened. Those three choose the listing in that order — a --scope wins over an --actor, and an --actor over a --resource — and whichever you did not choose is then applied to each page as an ordinary filter.

Verify any chain as an administrator

The administrator's verification takes the same month window as the organisation's and additionally lets you name which chain to replay, so a person's chain and the platform's own can be attested to as well.

Left alone it verifies the platform's own chain over the current month and the twelve before it.

Reference

Limits

Records are kept indefinitely. Nothing expires them, nothing prunes them, and no interface deletes one — expiry would leave holes in the chain, which is the one thing the chain exists to make impossible. Deleting a repository, a group or a person does not remove the records about them either; outliving what they describe is the whole point of an audit trail.

A page holds at most 100 records, and 20 if you do not ask. A larger limit is clamped to 100 rather than refused, so a request for 500 returns 100 and a cursor, not an error. Reading a longer period means following the cursor.

An organisation listing reaches back 24 months from the newest month it starts at. That is the default floor, and it applies when you set no lower bound — the web app's All time range sends none, so it stops there too. To read further back than two years, give an explicit --from, and the listing walks back to that month instead. The floor is a property of reading a chain: a repository's listing is served by target rather than by month and has no such limit, and neither does a platform-wide search by --actor or --resource.

Verification defaults to the current month and the twelve before it, and covers exactly the months you name when you set --from-month and --to-month. Each month in the window is replayed on its own, so read the record count in the result alongside the verdict: a window that names no months in which anything happened returns a pass over zero records, which is not the same as a pass.

There is no quota on reading the audit log and no charge for verifying it.

Troubleshooting

Examples

Pull a full month for one organisation

The listing pages, so an export is a loop over the cursor. This reads August in pages of 100 and writes one record per line:

Replace acme with your own top-level group; the CLI accepts either its path or its id. The upper bound is exclusive, so the window is August and nothing of September.

Find out what a leaked token did

Revoke the token first — that stops the bleeding, and the audit log will still name it, because the token's id is on every record it produced. Then read the organisation's log for the window between the token being minted and being revoked, and look for the access token id on the expanded records.

Anything the token did that named something more specific than a group or a repository — a merge request, a work item, a webhook — sits on the actor's own chain rather than the organisation's. Ask a platform administrator to search by actor across every chain, which is the one query that reaches all three.

Attest to a closed quarter

Keep the result: it names the verdict, how many records were checked and the chain positions the replay covered, which is what an auditor asks for. Check that count against what you expect of the quarter — a pass over far fewer records than the quarter's activity would produce is telling you the window was wrong, not that the quarter was quiet. Run it again whenever you need the attestation refreshed; verification reads and never writes, so it can be run any number of times over the same period.

FAQ

Related