Introduction

Adding a realtime avatar to a Django app sounds simple until you try to ship it through CI. Then you run into the usual failure modes: secrets leaking into test logs, flaky websocket or WebRTC-facing tests, environment drift between local and CI, and code paths that only work when a long-lived session is actually established. The goal of a good pipeline is not to “test the avatar video” in headless CI. It is to prove that the integration code is wired correctly, that your API calls are authenticated, that session creation logic behaves deterministically, and that the avatar surface you expose from Django is safe to deploy.

In this post, we’ll build a practical GitHub Actions pipeline for a Django app that integrates a realtime avatar backend. By the end, you should have a CI setup that:

• runs lint and unit tests on pull requests,

• keeps API keys out of the repository and logs,

• mocks external avatar/session calls in fast tests,

• optionally exercises a real API smoke test against a protected environment, and

• gives you confidence that the Django code driving the avatar feature is deployable.

What to test, and what not to test, in CI

Realtime avatars are not just another JSON API dependency. They usually sit behind a chain that includes your Django app, an auth boundary, a session-creation call, and a streaming transport such as WebRTC or a live media service. That means your test strategy should split along boundaries:

• Pure Django logic: serializers, permission checks, view behavior, webhook handling, and the code that maps app state to avatar/session requests.

• Integration points: the wrapper around the external avatar API, retry and timeout behavior, and any session lifecycle logic.

• End-to-end transport: actual audio/video negotiation, lip-sync timing, and browser playback. These are usually better covered in a staging environment or a separate manual smoke suite, not every PR.

The key mistake is to make CI depend on a full media session just to validate that your Django code imports. That gives you flaky pipelines and slow feedback. Instead, treat the avatar provider as an external system and verify your boundary layer with mocks in unit tests, then keep one narrow smoke test for real credentials where needed.

Project structure and dependencies

Assume a Django app with a small integration module that wraps the avatar/session API. Keep that wrapper isolated so the rest of your codebase never reaches into requests or SDK objects directly. That makes mocking easy and keeps tests deterministic.

A minimal dependency set might look like this:

pip install django pytest pytest-django requests python-dotenv

pip install django pytest pytest-django requests python-dotenv

pip install django pytest pytest-django requests python-dotenv

If you are using a Python SDK rather than raw HTTP, keep the same principle: create a thin adapter module around the SDK so the rest of your application depends on your own interface, not a third-party one. The pipeline does not care whether the adapter uses the SDK or direct REST calls; what matters is that it is testable.

Build the integration boundary first

For CI, the most useful code is not the avatar rendering code. It is the boundary where your Django app asks for a new session, stores the returned session identifier, and hands the client whatever token or URL it needs. Keep that logic small.

Here is a simple example using the REST API directly. The exact payload fields depend on the endpoint, so treat this as a shape, not a contract; check the docs for the current schema.

import os

return resp.json()

import os

return resp.json()

import os

return resp.json()

In Django, call this from a service function, not directly from the view. Then your unit test can patch create_avatar_session instead of trying to hit the network.

from unittest.mock import patch

self.assertTrue(True)

from unittest.mock import patch

self.assertTrue(True)

from unittest.mock import patch

self.assertTrue(True)

The point is not the placeholder assertion. The point is that your app’s behavior is now tested without requiring a live avatar service, which keeps CI fast and reliable.

GitHub Actions: lint, tests, and secure secrets

A sane CI pipeline for this kind of integration usually has three jobs:

1. Static checks: format, lint, type check if you use one.

2. Unit tests: all tests with external calls mocked.

3. Smoke test: a small, gated job that hits the real API only on a protected branch or manual dispatch.

Here is a compact workflow that covers the first two jobs and illustrates how to keep the API key out of the repo. It uses Python, pytest, and a Django test database.

name: ci

run: pytest -q

name: ci

run: pytest -q

name: ci

run: pytest -q

Two details matter here:

• Don’t expose secrets to untrusted PRs. For forked pull requests, GitHub does not provide repository secrets by default, which is what you want.

• Don’t rely on secrets for unit tests. If your unit test needs the real key, it is probably not a unit test anymore.

Use mocks for behavior, not for everything

When you mock the avatar API, mock at the boundary where your code leaves your process. If you mock too deeply, your tests become coupled to implementation details of the third-party client. If you mock too little, you end up doing network calls in CI.

A good pattern is:

• mock the adapter/service function in view tests,

• test request construction separately in a small unit test,

• validate error handling for 401, 429, and timeout cases, because those are realistic integration failures.

For example, a timeout test should verify that your app fails closed and surfaces a controlled error:

from requests.exceptions import Timeout

self.assertTrue(True)

from requests.exceptions import Timeout

self.assertTrue(True)

from requests.exceptions import Timeout

self.assertTrue(True)

This is especially important for realtime features because the user experience degrades badly if a session can be half-created and your app does not know how to recover.

A real smoke test for protected environments

For some teams, one gated smoke test is worth having. It should be narrow: authenticate, create a session, and confirm you got back a plausible response. Do not try to validate media quality in CI unless you have infrastructure explicitly designed for that.

If you want to hit the live REST API from a manual workflow or a protected branch, use a job like this:

name: smoke

PY

name: smoke

PY

name: smoke

PY

Keep this job separate from the main PR pipeline. If the smoke test fails because of an upstream outage or a rate limit, you want that failure to be visible without blocking every code review.

Where Protoface fits in this pipeline

This is the point where Protoface is useful: it gives you a concrete avatar/session boundary to integrate against while keeping your Django tests fast. If you are using the REST API directly, your CI can mock the outbound call and reserve the real request for a gated smoke test. If you are using the Python SDK, the same rule applies: wrap the SDK in your own service module and test that wrapper in isolation. The SDK repo is useful as a reference for how the client is organized, and the docs cover the current request/response shapes and auth flow.

For teams embedding avatars in agent stacks, the same CI discipline applies if you are using a LiveKit-based voice agent plugin or a Pipecat integration: keep the adapter logic thin, assert session setup deterministically, and treat streaming transport as a separate concern from your Django business logic.

Common CI gotchas

Three problems show up repeatedly:

• Leaking secrets in logs: avoid echo $PROTOFACE_API_KEY, and be careful with debug logging from HTTP clients.

• Flaky network assumptions: always set explicit timeouts on outbound calls, even in tests, so failures are fast and readable.

• Overreaching tests: if your PR pipeline tries to exercise browser playback or websocket media negotiation, expect intermittent failures unless you have dedicated infrastructure.

Also pay attention to rate limits. If your app creates sessions as part of test setup, make sure repeated CI runs do not accidentally drive usage or produce noisy failures. In practice, that means using mocks for PRs and reserving live calls for manual or scheduled checks.

Conclusion

A good CI pipeline for Django realtime avatar features is mostly about disciplined boundaries. Test your application logic locally and in GitHub Actions with mocks, keep credentials in secrets, and isolate live API checks to a small smoke test when you actually need one. That gives you high-confidence merges without turning CI into a fragile media lab.

If you want implementation details for the current REST schema, SDK behavior, or integration examples, start with the docs and the relevant GitHub examples. From there, adapt the pattern above to your own app: thin service layer, deterministic tests, and one controlled live check where it adds real value.