Manifest Reference
The manifest file (autokitteh.yaml
) is the configuration file that defines your AutoKitteh project. It specifies connections, triggers, variables, and other project settings.
File Structure
version: v2
project:
name: project_name
connections:
- name: connection_name
integration: integration_type
# Additional connection-specific configuration
triggers:
- name: trigger_name
type: webhook | schedule
event_type: event_type_name
connection: connection_name
call: file.py:function_name
filter: CEL_expression
vars:
- name: VAR_NAME
value: var_value
Top-Level Fields
version
Required. Specifies the manifest schema version.
Supported values:
v2
- Current recommended version (default)v1
- Legacy version (deprecated)
Example:
version: v2
project
Required. Contains all project configuration.
Project Fields
name
Required. The unique name of your project.
Type: String
Example:
project:
name: my_workflow
connections
Optional. List of connections to external services.
Each connection requires:
name
- Unique identifier for this connection (used in code)integration
- One of the supported integrations- Additional fields depend on the integration type
Example:
connections:
- name: my_slack
integration: slack
- name: my_github
integration: github
See the integrations documentation for integration-specific configuration.
triggers
Optional. List of triggers that start workflow sessions.
Each trigger can have:
Field | Required | Type | Description |
---|---|---|---|
name | Yes | String | Unique trigger identifier |
type | No | String | webhook or schedule |
event_type | No | String | Event type provided by the integration |
connection | No* | String | Connection name (required for integration triggers) |
call | Yes | String | Entry point in format file.py:function_name |
filter | No | String | CEL expression to filter events |
is_sync | No | Boolean | For webhooks: return HTTP response from workflow |
* connection
is required for integration-based triggers but not for standalone webhooks.
Example - Webhook Trigger:
triggers:
- name: http_endpoint
type: webhook
call: program.py:handle_webhook
Example - Integration Event Trigger:
triggers:
- name: on_github_issue
connection: my_github
event_type: issues
filter: data.action == 'opened'
call: program.py:handle_issue
Example - Scheduled Trigger:
triggers:
- name: daily_report
type: schedule
schedule: "0 9 * * *" # Daily at 9 AM
call: program.py:generate_report
Example - Synchronous Webhook:
triggers:
- name: api_endpoint
type: webhook
is_sync: true
call: program.py:api_handler
vars
Optional. List of environment variables available to your code.
Each variable requires:
name
- Variable name (accessible viaos.getenv()
)value
- Variable value
Example:
vars:
- name: CHANNEL_ID
value: "C12345678"
- name: API_ENDPOINT
value: "https://api.example.com"
Variables can also be set as secrets using the CLI:
ak var set --secret --env <env_id> TOKEN s3cr3t
See Working with Secrets for more information.
Filter Expressions
Filters use CEL (Common Expression Language) to selectively trigger executions.
Event Type Filtering
# Single event type
filter: event_type == 'issue_created'
# Multiple event types
filter: event_type == 'issue_created' || event_type == 'issue_updated'
# Pattern matching
filter: event_type.startsWith('issue_')
filter: event_type.endsWith('_created')
filter: event_type.contains('comment')
Data Filtering
# Simple field check
filter: data.action == 'opened'
# Multiple conditions
filter: data.method == 'POST' && data.url.path.endsWith('/api')
# List membership
filter: data.method in ['GET', 'HEAD']
# Size checks
filter: size(data.items) > 5
# Nested fields
filter: data.issue.state == 'open'
See the CEL specification for complete syntax.
Complete Examples
Simple HTTP Webhook
version: v2
project:
name: simple_webhook
triggers:
- name: incoming
type: webhook
call: program.py:on_request
GitHub Integration
version: v1
project:
name: github_notifier
connections:
- name: github_conn
integration: github
triggers:
- name: on_pr
connection: github_conn
event_type: pull_request
filter: data.action == 'opened'
call: program.py:handle_pr
vars:
- name: SLACK_CHANNEL
value: "#github-notifications"
Multi-Integration Project
version: v1
project:
name: workflow_automation
connections:
- name: slack_conn
integration: slack
- name: gmail_conn
integration: gmail
- name: sheets_conn
integration: googlesheets
triggers:
- name: slack_command
connection: slack_conn
event_type: slash_commands
call: program.py:handle_command
- name: new_email
connection: gmail_conn
event_type: message_received
filter: data.from.contains('@example.com')
call: program.py:process_email
- name: daily_sync
type: schedule
schedule: "0 0 * * *"
call: program.py:daily_sync
vars:
- name: SPREADSHEET_ID
value: "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
Best Practices
- Use descriptive names for projects, connections, and triggers
- Leverage filters to reduce unnecessary session creation
- Keep secrets out of the manifest - use the CLI's secret management instead
- Use environment variables for values that change between deployments
- Document your triggers with clear, descriptive names