Projects

Active Development

Project configuration options are evolving. New fields may be added as routing features expand.

Projects in Aether are workspaces that group configuration together. They define how webhooks from external services are routed to agents.

What are Projects?

A project represents:

• A workspace (e.g., a GitHub repository, Jira project, or Plane workspace)
• Source mappings that link external projects to Aether
• Agent assignments for handling events
• Configuration for how events are processed

Project Structure

{
  "id": 1,
  "name": "My Application",
  "description": "Main application project",
  "source": "github",
  "source_project_id": "owner/repo",
  "created_at": "2024-01-01T00:00:00Z"
}

Fields

• id: Auto-generated unique ID
• name: Display name for the project
• description: Project description
• source: Source type (github, gitlab, jira, plane)
• source_project_id: External project identifier
• created_at: Creation timestamp

Creating Projects

Via UI

1. Navigate to Projects page
2. Click "Create Project"
3. Fill in:
   • Name: Project name
   • Description: Brief description
   • Source: Select integration type
   • Source Project ID: External identifier
4. Click "Save"

Via API

curl -X POST http://localhost:8000/api/projects \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Application",
    "description": "Main application repository",
    "source": "github",
    "source_project_id": "owner/repo"
  }'

Source Mappings

Source mappings link external projects to Aether projects:

GitHub

{
  "source": "github",
  "source_project_id": "owner/repository"
}

Example: "amansrivastava/hacky-automation"

GitLab

{
  "source": "gitlab",
  "source_project_id": "project-id"
}

Example: "12345678" (GitLab project ID)

Jira

{
  "source": "jira",
  "source_project_id": "PROJECT"
}

Example: "MYPROJ" (Jira project key)

Plane

{
  "source": "plane",
  "source_project_id": "workspace-slug/project-id"
}

Example: "my-workspace/abc123def"

Project Configuration

Agent Assignment

Agents are assigned to projects through task mappings:

# Tasks assigned to project
- canonical_trigger: issue.created
  task_id: pm_analyze

- canonical_trigger: pr.opened
  task_id: qa_review

Webhook Routing

When a webhook arrives:

1. Extract source and project ID
2. Look up Aether project by source mapping
3. Normalize event to canonical trigger
4. Resolve tasks for that trigger
5. Execute assigned agents

Managing Projects

List Projects

curl http://localhost:8000/api/projects

Get Single Project

curl http://localhost:8000/api/projects/1

Update Project

curl -X PUT http://localhost:8000/api/projects/1 \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Name",
    "description": "Updated description"
  }'

Delete Project

curl -X DELETE http://localhost:8000/api/projects/1

Best Practices

1. One Project Per Repository/Workspace: Create separate Aether projects for each external project
2. Descriptive Names: Use clear, descriptive names that match external project names
3. Consistent IDs: Use exact identifiers from source systems
4. Documentation: Add descriptions explaining project purpose

Examples

GitHub Repository

{
  "name": "Hacky Automation",
  "description": "Main repository for Aether webhook automation",
  "source": "github",
  "source_project_id": "amansrivastava/hacky-automation"
}

Jira Project

{
  "name": "Engineering Tasks",
  "description": "Main engineering task tracking project",
  "source": "jira",
  "source_project_id": "ENG"
}

Plane Workspace

{
  "name": "Product Development",
  "description": "Product development workspace",
  "source": "plane",
  "source_project_id": "acme/project-abc123"
}

Next Steps

• Configure Integrations - Set up external service connections
• Create Agents - Define AI agents
• Webhook Mappings - Configure event routing