All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.

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

The same job on other stacks

Keep reading