# Add an Audit Log to a Django REST Framework API from a Linear Issue

Yes. An agent takes a labelled Linear issue, adds an audit log app that records who changed what in your service layer, exposes it as an API, and opens a tested PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-audit-log/django-rest-framework/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads the issue, then reads where writes happen. In a project shaped like HackSoftware/Django-Styleguide-Example, `requirements/base.txt` pins `Django` 5.2.7, `djangorestframework` 3.16.1, `drf-jwt`, `django-filter` and `django-structlog`, and `config/django/base.py` lists the local apps under `styleguide_example`: `users`, `files`, `emails`, `api`, `errors` and the rest. Every model extends `BaseModel` from `common/models.py`, which carries `created_at` and `updated_at`. Writes go through services: `users/services.py` has `user_create` and `user_update` under `@transaction.atomic`, the latter through `model_update`, and `files/services.py` has `FileStandardUploadService` and `FileDirectUploadService` with their `create`, `start`, `finish` and `upload_local` steps. Reads go through selectors like `user_list`, which applies `BaseUserFilter`, and APIs are `APIView` classes with nested `InputSerializer`, `FilterSerializer` and `OutputSerializer` classes behind `ApiAuthMixin`, paginated with `LimitOffsetPagination` and `get_paginated_response`. Nothing records who changed a record.

The agent adds an app at `styleguide_example/audit` in the same shape. `models.py` defines `AuditLogEntry(BaseModel)` with `actor` as a nullable foreign key to `BaseUser` with `on_delete=SET_NULL`, an `action` choice field (`create`, `update`, `delete`, `upload`), a `GenericForeignKey` over `content_type` and `object_id` with an index on the pair, and `changes` as a `JSONField` holding the fields that changed with their old and new values. `services.py` has `audit_log_create(*, actor, action, obj, changes=None)` and the service calls that use it: `user_create` and `user_update` log with the request user passed in by the API, and the two file upload services log an `upload` entry once `upload_finished_at` is set. `selectors.py` has `audit_log_list(*, filters)` backed by a `django_filters` filter set on `actor`, `action`, `content_type` and a `created_at` range. `apis.py` has `AuditLogListApi(ApiAuthMixin, APIView)` with the same nested serializer and pagination pattern as `UserListApi`, wired under `styleguide_example/api/urls.py` beside `users` and `files`. `admin.py` registers a read-only `ModelAdmin` with `list_display` and `list_filter` matching the filter set.

The tests follow `users/tests/services/test_user_create.py`: `audit/tests/services/test_audit_log_create.py` asserts an entry per service call with the right actor, action and changes, that updating a user through `user_update` records only the fields that moved, and that deleting the actor leaves the entry with `actor` null. `audit/tests/apis/test_audit_log_list.py` uses the API client the way `authentication/tests/apis/test_user_login.py` does to check authentication is required and the filters narrow the page. The migration is generated with `makemigrations audit` and checked with `makemigrations --check`.

Before pushing, the agent runs what `.github/workflows/django.yml` runs: `ruff check .`, `mypy --config mypy.ini styleguide_example/` with the Django and DRF plugins, and `pytest` against the Postgres service with `config.django.test` from `pytest.ini`, plus `docker compose build` for the container job. It adds a section to `README.md` describing the app and the endpoint.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "codex",
  "input": "A Linear issue labelled agent says: \"Add an audit log. Every create, update and upload done through the API should record who did it, on which object, and what changed, and admins should be able to list and filter entries.\" Do the work in this repository. Read requirements/base.txt, config/django/base.py, config/urls.py, styleguide_example/api/urls.py, styleguide_example/api/mixins.py, styleguide_example/api/pagination.py, styleguide_example/common/models.py, styleguide_example/common/services.py, styleguide_example/users/models.py, services.py, selectors.py, apis.py, filters.py and urls.py, styleguide_example/files/models.py, services.py and apis.py, styleguide_example/users/tests/services/test_user_create.py, styleguide_example/authentication/tests/apis/test_user_login.py, pytest.ini, mypy.ini and .github/workflows/django.yml first. Add a styleguide_example/audit app with an AuditLogEntry model extending BaseModel (nullable actor foreign key with SET_NULL, action choices, a generic foreign key with an index, and a JSONField of changes), an audit_log_create service, calls to it from user_create, user_update and the two file upload services, an audit_log_list selector with a django_filters filter set on actor, action, content type and created_at range, an AuditLogListApi behind ApiAuthMixin with nested serializers and LimitOffsetPagination mounted under the api urls, and a read-only admin. Generate the migration. Add service tests and an API test following the existing test files. Run ruff check ., mypy --config mypy.ini styleguide_example/, pytest and makemigrations --check, paste the results in the pull request description, and document the app in README.md. Add no new dependency and do not change any existing API's input or output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request with the new `styleguide_example/audit` package (`models.py`, `services.py`, `selectors.py`, `filters.py`, `apis.py`, `urls.py`, `admin.py`, `apps.py`, one migration and the tests), the app added to `LOCAL_APPS` in `config/django/base.py`, the `audit_log_create` calls in `users/services.py` and `files/services.py`, the route in `api/urls.py`, and a README section. The description shows the ruff, mypy, pytest and `makemigrations --check` output from the sandbox.

The repository's `Django application` workflow runs on the pull request: the `build` job with its Postgres service runs ruff, mypy and pytest on Python 3.12.4, and the `docker_build` job repeats them inside the compose image, so the migration and the new tests run twice on a fresh database.

A reviewer checks that the log entry is written inside the same `transaction.atomic` block as the change it records, so a rolled-back write leaves no entry, that `changes` never includes `password` or `jwt_key`, that the list API requires authentication and an admin, and that no existing serializer changed. Then they decide which other services should log.

## Run it on every Linear issue labelled agent

In the Project that holds the API, add an automation with this prompt and a `linear` trigger on `linear.issue.labeled` filtered to the `agent` label. Each labelled issue starts its own run in its own sandbox and ends in its own pull request; the issue's text follows the prompt as data, so an issue that asks for a retention policy or an export of the log makes its own change.

Changes made by an app integration never fire the trigger, so the agent's own comments on the issue start no further runs, and the automation's `max_runs_per_hour` caps how many issues become runs at once.

## Why run it on Rush?

An audit log is only trustworthy if it is written in the same transaction as the change and never records a secret, and both properties are easy to break while the diff still looks fine. In a Rush sandbox the agent runs the project's own ruff, mypy and pytest against a real Postgres, exercises the services and the API in tests, and keeps every command and its output in the run's transcript, so the pull request shows the entries being written under the same conditions as production.

The result follows the repository's service, selector and API conventions rather than a plugin's, passes its own gates before a reviewer opens it, and adds no dependency. The same automation handles every compliance issue the team labels, one sandbox and one pull request each.

## Frequently asked questions

### Why not django-simple-history or django-auditlog?

Both record every model save through signals, which this codebase avoids on purpose: writes go through services under `transaction.atomic`, so the log entry belongs in the service beside the change. One explicit `audit_log_create` call per service keeps the actor and the changed fields exact, and adds no dependency to `requirements/base.txt`.

### What goes into the changes field?

For `user_update`, the fields `model_update` reported as changed with their old and new values; for `user_create`, the created fields; for uploads, the file name and type. `password` and `jwt_key` are excluded by name in the service, and the tests assert they never appear.

### Who can read the log?

The list API sits behind `ApiAuthMixin` like the file APIs and additionally requires `is_admin`, and the Django admin registration is read-only. Narrowing it further, for example to entries about the caller's own objects, is a selector change.

### Does this slow down the write path?

Each logged service call makes one extra insert inside the transaction it already opens. The entry table is indexed on the content type and object id pair and on `created_at`, so listing stays fast as it grows; archiving old entries would be a separate task.

## More Django REST Framework jobs

- [Add Test Coverage to CI for a Django REST Framework API](https://getrush.ai/run/add-coverage-to-ci/django-rest-framework/)
- [Add CSV Export to a Django REST Framework API](https://getrush.ai/run/add-csv-export/django-rest-framework/)
- [Add Cursor Pagination to a Django REST Framework API from a Linear Issue](https://getrush.ai/run/add-cursor-pagination/django-rest-framework/)

## The same job on other stacks

- [Add an Audit Log to a Fastify API](https://getrush.ai/run/add-audit-log/fastify/)
- [Add an Audit Log to a Filament Admin Panel](https://getrush.ai/run/add-audit-log/filament/)
- [Add an Audit Log to a Mongoose and Express API](https://getrush.ai/run/add-audit-log/mongoose/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
