Ascender – Copilot Agent Instructions

What This Repository Is

Ascender is a web-based UI, REST API, and task engine built on top of Ansible. It is a downstream fork of AWX, maintained by Ctrl IQ, Inc. It provides job scheduling, inventory management, credential storage, workflow automation, RBAC, and a REST API. ~987 Python source files, ~154 K lines of Python.

Trust these instructions. Search the repo only if the information below is incomplete or incorrect.

Runtime Environment

All development tooling runs inside the tools_ascender_1 Docker container. The repository root is mounted at /ascender_devel inside the container. The host working directory (/root/ascender) does not have the project's Python environment. Always prefix commands with:

docker exec tools_ascender_1 bash -c "cd /ascender_devel && <command>"

Supporting containers also running:

• tools_postgres_1 – PostgreSQL database (used by the running app and by the test suite)
• tools_valkey_1 – Valkey (Redis-compatible) cache

Runtime versions (inside container):

• Python 3.14.7
• Django 5.2.14
• psycopg 3.1.18
• ruff 0.16.6 | yamllint 1.38.0

Linting

Ruff (formatting)

Config in pyproject.toml under [tool.ruff] and [tool.ruff.format]: line-length = 160, quote-style = "preserve". Ruff replaced black here, and make black is still an alias for make format. Always auto-format new Python code before committing:

# Check (CI-style):
docker exec tools_ascender_1 bash -c "cd /ascender_devel && ruff format --check ascender"
# Auto-fix:
docker exec tools_ascender_1 bash -c "cd /ascender_devel && ruff format ascender"

Ruff (linting)

Config in pyproject.toml under [tool.ruff.lint]. Selects 48 rules explicitly rather than by class, ported from the [flake8] block this replaced: the E7xx statement checks, F4xx through F9xx, and W2xx/W3xx/W605. preview = true is required because E265, E266 and W391 are still preview rules and are silently inert without it. Excludes ascender/ui/node_modules, env.

docker exec tools_ascender_1 bash -c "cd /ascender_devel && ruff check ascender"

Yamllint

Config in .yamllint (root). line-length and truthy rules are disabled. Ignores .github, .tox, tools/docker-compose/_sources, and a few test data paths.

docker exec tools_ascender_1 bash -c "cd /ascender_devel && yamllint -s ."

Running Tests

Tests run against PostgreSQL, the same backend Ascender deploys on, with an in-memory channel layer. Settings: ascender.main.tests.settings_for_test (configured in pyproject.toml). Default pytest flags: --reuse-db --nomigrations --tb=native --timeout=300.

Unit tests (~15 seconds, run frequently)

docker exec tools_ascender_1 bash -c "cd /ascender_devel && PYTHONDONTWRITEBYTECODE=1 py.test -p no:cacheprovider -n auto --dist=loadfile ascender/main/tests/unit/"

Result: 1139 passed, 1 skipped.

Functional tests (~3 minutes)

docker exec tools_ascender_1 bash -c "cd /ascender_devel && PYTHONDONTWRITEBYTECODE=1 py.test -p no:cacheprovider -n auto --dist=loadfile ascender/main/tests/functional/"

Result: 1987 passed, 5 skipped.

Full test suite (all dirs, ~4 minutes)

docker exec tools_ascender_1 bash -c "cd /ascender_devel && PYTHONDONTWRITEBYTECODE=1 py.test -p no:cacheprovider -n auto --dist=loadfile ascender/main/tests/unit ascender/main/tests/functional ascender/conf/tests ascender/sso/tests"

Migration check (always run after model changes)

docker exec tools_ascender_1 bash -c "cd /ascender_devel && ascender-manage check_migrations --dry-run --check -n 'missing_migration_file'"

Expected output: No changes detected

Target a single test file

docker exec tools_ascender_1 bash -c "cd /ascender_devel && PYTHONDONTWRITEBYTECODE=1 py.test -p no:cacheprovider ascender/main/tests/unit/test_capacity.py"

Model Changes Require Migrations

After changing any Django model, always generate and commit the migration:

docker exec tools_ascender_1 bash -c "cd /ascender_devel && ascender-manage makemigrations"

Then verify no missing migration file:

docker exec tools_ascender_1 bash -c "cd /ascender_devel && ascender-manage check_migrations --dry-run --check -n 'missing_migration_file'"

Migration files live in ascender/main/migrations/ (218 existing files).

Project Layout

Key configuration files

CI/CD Workflows (.github/workflows/)

CI uses ansible-playbook tools/ansible/build.yml to build images. No automated lint or test runs in CI — validation is done locally before pushing.

Pre-commit Hook

pre-commit.sh runs ruff format --check on all staged Python files. Set AWX_IGNORE_RUFF=1 to skip it. Set up with:

make .git/hooks/pre-commit

Key Conventions

• ascender-manage is the Django management command (equivalent of django-admin with project settings loaded). It is in PATH inside the container.
• RBAC is implemented in ascender/main/access.py — one class per model, can_* methods.
• API views use a generic base in ascender/api/generics.py. Most views are in ascender/api/views/.
• Serializers are in ascender/api/serializers.py (large file, ~5000 lines) and ascender/api/fields.py.
• Tasks (background jobs) are in ascender/main/tasks/ — add new tasks there.
• Signals are in ascender/main/signals.py.
• URL routing: ascender/urls.py → ascender/api/urls/ for the API, ascender/main/urls.py for main app.
• Dynamic settings stored in DB use ascender/conf/ — settings definitions go in ascender/conf/conf.py and ascender/main/conf.py.