Integrations

Active Development

Integration capabilities are being expanded. New tracker actions (label management, status transitions, etc.) are added as the platform evolves.

Aether supports multiple issue tracker integrations. This guide covers how to set up and configure each one.

Supported Integrations

Integration	Events Handled	Response Actions
GitHub	Issues, pull requests, comments	Add comment, update description, create label
GitLab	Issues, merge requests, comments	Add comment, update description
Jira Cloud	Issues, comments	Add comment, update description, transition issue
Jira Server/DC	Issues, comments	Add comment, update description, transition issue
Plane	Issues, comments	Add comment, update description

All webhooks are received at POST /webhook/:slug (e.g., /webhook/github).

Configuration Overview

All integrations are configured via environment variables in goway/.env. See the Configuration Guide for detailed environment setup.

GitHub Integration

Setup

1. Generate a Personal Access Token:

   • Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
   • Click "Generate new token (classic)"
   • Select scopes:
     • repo - Full control of repositories
     • admin:repo_hook - Manage webhooks
   • Generate and copy the token

2. Add to goway/.env:

GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

3. Set up webhook:
   • Go to repository Settings → Webhooks → Add webhook
   • Payload URL: http://your-aether-instance:8000/webhook/github
   • Content type: application/json
   • Select events: Issues, Pull requests, Issue comments, etc.
   • Add webhook

Supported Events

• issues (opened, edited, closed, reopened)
• pull_request (opened, edited, closed, reopened)
• issue_comment (created, edited, deleted)
• pull_request_review (submitted, edited, dismissed)

Response Actions

• PM tasks: Post as issue/PR comment
• TA tasks: Update issue/PR description (append "Technical Analysis" section)
• QA tasks: Post as issue/PR comment
• DEV tasks: Post as issue/PR comment

GitLab Integration

Setup

1. Generate a Personal Access Token:

   • Go to GitLab Settings → Access Tokens
   • Token name: "Aether Integration"
   • Select scopes:
     • api - Full API access
   • Create token and copy it

2. Add to goway/.env:

GITLAB_URL=https://gitlab.com  # or your self-hosted URL
GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx

3. Set up webhook:
   • Go to project Settings → Webhooks
   • URL: http://your-aether-instance:8000/webhook/gitlab
   • Trigger: Issues events, Merge request events, Comments
   • Add webhook

Supported Events

• Issue Hook (open, update, close, reopen)
• Merge Request Hook (open, update, close, reopen, merge)
• Note Hook (issue comment, MR comment)

Self-Hosted GitLab

For self-hosted GitLab, use your instance URL:

GITLAB_URL=https://gitlab.yourcompany.com

Jira Integration

Jira has two deployment types with different authentication:

Jira Cloud Setup

1. Generate API Token:

   • Go to https://id.atlassian.com/manage-profile/security/api-tokens
   • Create API token
   • Copy the token

2. Add to goway/.env:

JIRA_URL=https://yourcompany.atlassian.net
JIRA_EMAIL=your-email@company.com
JIRA_API_TOKEN=xxxxxxxxxxxxxxxxxxxx
JIRA_IS_CLOUD=true

3. Set up webhook:
   • Go to Settings → System → WebHooks
   • URL: http://your-aether-instance:8000/webhook/jira
   • Events: Issue created, updated, commented
   • Create webhook

Jira Server/Data Center Setup

1. Use username and password authentication

2. Add to goway/.env:

JIRA_URL=https://jira.yourcompany.com
JIRA_EMAIL=username  # Not email, just username
JIRA_API_TOKEN=your-password
JIRA_IS_CLOUD=false

3. Set up webhook (same as Cloud)

Supported Events

• jira:issue_created
• jira:issue_updated
• comment_created

Response Actions

• PM tasks: Post as issue comment
• TA tasks: Update issue description (append analysis)
• QA tasks: Post as issue comment

Plane Integration

Setup

1. Generate API Key:

   • Go to Plane Settings → API Tokens
   • Generate new token
   • Copy token and workspace slug

2. Add to goway/.env:

PLANE_API_URL=https://api.plane.so/api/v1
PLANE_API_KEY=plane_api_xxxxxxxxxxxxxxxxxxxx
PLANE_WORKSPACE_SLUG=your-workspace-slug

3. Set up webhook:
   • Go to Project Settings → Webhooks
   • URL: http://your-aether-instance:8000/webhook/plane
   • Events: issue.created, issue.updated, issue.activity.created
   • Create webhook

Supported Events

• issue.created
• issue.updated
• issue.activity.created (comments)

Testing Integrations

Test Connection

After configuring an integration, test the connection:

# GitHub
curl http://localhost:8000/api/integrations/github/test

# GitLab
curl http://localhost:8000/api/integrations/gitlab/test

# Jira
curl http://localhost:8000/api/integrations/jira/test

# Plane
curl http://localhost:8000/api/integrations/plane/test

Test Webhook Delivery

Most platforms provide webhook testing:

• GitHub: "Recent Deliveries" in webhook settings
• GitLab: "Test" button in webhook settings
• Jira: Send test webhook from webhook settings
• Plane: Test webhook functionality in settings

Debug Webhook Failures

Check Aether logs:

docker-compose logs -f goway

Look for:

• Webhook received messages
• Event normalization
• Task resolution
• Agent execution
• Response posting

Security Best Practices

1. Use HTTPS: Always use HTTPS for webhook endpoints in production
2. Webhook Secrets: Configure webhook secrets for HMAC verification
3. Token Rotation: Rotate API tokens regularly
4. Least Privilege: Use tokens with minimal required permissions
5. Service Accounts: Use dedicated service accounts for integrations
6. Network Security: Restrict webhook endpoint access via firewall rules

Troubleshooting

Connection Refused

• Check that Aether is running: curl http://localhost:8000/health
• Verify network connectivity from source to Aether
• Check firewall rules

Authentication Failed

• Verify token/credentials are correct
• Check token hasn't expired
• Ensure correct permissions/scopes
• For Jira Server, verify username (not email) is used

Webhooks Not Received

• Check webhook is active in source system
• Verify webhook URL is correct
• Check "Recent Deliveries" or equivalent
• Review Aether logs for incoming requests

Responses Not Posted

• Check TRACKER_UPDATES_ENABLED=true
• Verify agent execution succeeded
• Check response handler logs
• Verify token has write permissions

Next Steps

• Set Up Projects - Create projects for each integration
• Configure Webhooks - Set up event routing
• Troubleshooting - Common issues and solutions