Integrations

Connect HoxCore with external tools for enhanced project management

Overview

HoxCore is designed to integrate with existing tools rather than replace them. By referencing external systems in your entity definitions, you create a unified view of your project ecosystem while leveraging the specialized capabilities of each tool.

💡 Integration Model

HoxCore acts as a registry and orchestrator, not a replacement for specialized tools. It provides:

  • A single source of truth for project metadata
  • Declarative references to external systems
  • Unified querying across all your projects
  • Version-controlled integration configuration

Integration Categories

🔄 Version Control

GitHub, Azure DevOps, GitLab, Gitea, Overleaf

📋 Project Management

GitHub Projects, Azure Boards, Trello, OpenProject

📁 Storage & Docs

Google Drive, Notion, Confluence, SharePoint

🗄️ Databases

PostgreSQL, MySQL, SQLite, MongoDB

💬 Communication

Slack, Microsoft Teams, Discord

🚀 CI/CD

GitHub Actions, Azure Pipelines, Jenkins

Integration Philosophy

HoxCore follows a clear philosophy when it comes to integrations:

Core Principles

🔗 Reference, Don't Duplicate

Store references to external systems, not copies of their data. The external tool remains the source of truth for its domain.

📋 Declarative Configuration

All integrations are defined declaratively in YAML. No hidden configuration or magic connections.

🔒 Version Controlled

Integration configurations are part of your Git-tracked registry, providing full history and auditability.

🎯 Composable

Mix and match integrations as needed. Use GitHub for code, Notion for docs, and Trello for tasks—all in one project.

Integration Structure

All integrations follow a consistent structure in entity definitions:

# Generic integration format
integration_type:
  - name: identifier
    provider: provider_name
    url: https://external-system.com/resource
    # Additional provider-specific fields

Version Control Integrations

Connect your projects to version control systems where your code and documents live.

GitHub

Configuration

repositories:
  - name: main-repo
    provider: github
    url: https://github.com/username/repository
    branch: main
  
  - name: docs-repo
    provider: github
    url: https://github.com/username/docs
    branch: main

Features

  • Link to specific repositories
  • Reference branches or commits
  • Connect to GitHub Projects (see Project Management)
  • Integrate with GitHub Actions (see CI/CD)

Use Cases

  • Software development projects
  • Documentation repositories
  • Open source projects
  • Team collaboration

Azure DevOps

Configuration

repositories:
  - name: azure-repo
    provider: azure-devops
    url: https://dev.azure.com/org/project/_git/repository
    branch: develop

Features

  • Enterprise-grade version control
  • Integration with Azure Boards
  • Azure Pipelines support
  • Work item tracking

GitLab

Configuration

repositories:
  - name: gitlab-repo
    provider: gitlab
    url: https://gitlab.com/username/project
    branch: main

Features

  • Self-hosted or cloud options
  • Built-in CI/CD
  • Issue tracking
  • Container registry

Overleaf (LaTeX)

Configuration

repositories:
  - name: research-paper
    provider: overleaf
    url: https://www.overleaf.com/project/abc123def456
    description: "Research paper LaTeX source"

Features

  • Academic paper writing
  • Real-time collaboration
  • LaTeX compilation
  • Version history

Use Cases

  • Academic research projects
  • Scientific publications
  • Technical documentation
  • Thesis writing

Gitea (Self-Hosted)

Configuration

repositories:
  - name: internal-repo
    provider: gitea
    url: https://git.company.com/team/project
    branch: main

Features

  • Self-hosted Git service
  • Lightweight and fast
  • Private repositories
  • Issue tracking

Complete Example

type: project
title: "Multi-Repository Project"
description: "Project using multiple version control systems"

repositories:
  # Main codebase on GitHub
  - name: backend
    provider: github
    url: https://github.com/company/backend
    branch: main
  
  # Frontend on GitLab
  - name: frontend
    provider: gitlab
    url: https://gitlab.com/company/frontend
    branch: develop
  
  # Documentation on Overleaf
  - name: paper
    provider: overleaf
    url: https://www.overleaf.com/project/abc123
  
  # Internal tools on Gitea
  - name: internal-tools
    provider: gitea
    url: https://git.company.com/team/tools
    branch: main

Project Management Integrations

Connect to project management and task tracking tools.

GitHub Projects

Configuration

tools:
  - name: project-board
    provider: github-projects
    url: https://github.com/users/username/projects/1
    description: "Main project board"

Features

  • Kanban-style boards
  • Issue integration
  • Automation rules
  • Custom fields

Azure DevOps Boards

Configuration

tools:
  - name: azure-board
    provider: azure-devops-boards
    url: https://dev.azure.com/org/project/_boards
    description: "Sprint planning board"

Features

  • Agile planning tools
  • Sprint management
  • Work item tracking
  • Burndown charts

Trello

Configuration

tools:
  - name: trello-board
    provider: trello
    url: https://trello.com/b/abc123/project-name
    description: "Task tracking board"

Features

  • Simple, visual boards
  • Card-based tasks
  • Labels and due dates
  • Power-ups for extensions

OpenProject

Configuration

tools:
  - name: openproject
    provider: openproject
    url: https://openproject.company.com/projects/my-project
    description: "Enterprise project management"

Features

  • Open source project management
  • Gantt charts
  • Time tracking
  • Cost reporting

Jira

Configuration

tools:
  - name: jira-project
    provider: jira
    url: https://company.atlassian.net/browse/PROJ
    description: "Issue tracking"

Features

  • Advanced issue tracking
  • Agile boards
  • Custom workflows
  • Extensive reporting

Complete Example

type: project
title: "Agile Software Project"

tools:
  # Sprint planning
  - name: sprint-board
    provider: azure-devops-boards
    url: https://dev.azure.com/company/project/_boards
  
  # Issue tracking
  - name: issues
    provider: github-projects
    url: https://github.com/company/repo/projects/1
  
  # High-level roadmap
  - name: roadmap
    provider: trello
    url: https://trello.com/b/abc123/roadmap

Storage & Documentation Integrations

Link to document storage, knowledge bases, and collaboration platforms.

Google Drive

Configuration

storage:
  - name: project-docs
    provider: google-drive
    url: https://drive.google.com/drive/folders/abc123def456
    description: "Project documentation and assets"

Features

  • Cloud file storage
  • Real-time collaboration
  • Google Docs/Sheets/Slides
  • Sharing and permissions

Use Cases

  • Document collaboration
  • File sharing
  • Meeting notes
  • Presentations

Notion

Configuration

storage:
  - name: notion-workspace
    provider: notion
    url: https://notion.so/workspace/project-abc123
    description: "Project wiki and documentation"

Features

  • All-in-one workspace
  • Databases and wikis
  • Rich content blocks
  • Templates and views

Use Cases

  • Project wikis
  • Knowledge bases
  • Meeting notes
  • Documentation

Confluence

Configuration

storage:
  - name: confluence-space
    provider: confluence
    url: https://company.atlassian.net/wiki/spaces/PROJ
    description: "Team documentation space"

Features

  • Enterprise wiki
  • Page hierarchies
  • Jira integration
  • Advanced permissions

SharePoint

Configuration

storage:
  - name: sharepoint-site
    provider: sharepoint
    url: https://company.sharepoint.com/sites/project
    description: "Document library"

Features

  • Microsoft 365 integration
  • Document management
  • Version control
  • Enterprise features

Local Paths

Configuration

storage:
  - name: local-docs
    provider: local
    path: ./docs/project-documentation
    description: "Local documentation folder"
  
  - name: assets
    provider: local
    path: /shared/project-assets
    description: "Shared network drive"

Features

  • Reference local file systems
  • Network drives
  • Relative or absolute paths
  • No cloud dependency

Complete Example

type: project
title: "Documentation-Heavy Project"

storage:
  # Cloud collaboration
  - name: team-drive
    provider: google-drive
    url: https://drive.google.com/drive/folders/abc123
    description: "Shared team documents"
  
  # Knowledge base
  - name: wiki
    provider: notion
    url: https://notion.so/workspace/project-wiki
    description: "Project wiki and guides"
  
  # Local assets
  - name: design-files
    provider: local
    path: ./assets/design
    description: "Design mockups and assets"
  
  # Enterprise docs
  - name: official-docs
    provider: sharepoint
    url: https://company.sharepoint.com/sites/project
    description: "Official documentation"

Database Integrations

Reference databases used by your projects.

PostgreSQL

Configuration

databases:
  - name: production-db
    type: postgres
    url: postgres://user:pass@host:5432/dbname
    description: "Production database"
    environment: production

Security Note

⚠️ Credentials Management

Never store actual credentials in your registry. Use environment variables or reference credential management systems:

databases:
  - name: production-db
    type: postgres
    host: db.company.com
    port: 5432
    database: myapp
    credentials_ref: ${DB_CREDENTIALS}
    description: "Production database"

MySQL

Configuration

databases:
  - name: mysql-db
    type: mysql
    host: mysql.company.com
    port: 3306
    database: application
    credentials_ref: ${MYSQL_CREDENTIALS}
    description: "MySQL database"

SQLite

Configuration

databases:
  - name: local-db
    type: sqlite
    path: ./data/application.db
    description: "Local SQLite database"

Features

  • File-based database
  • No server required
  • Perfect for development
  • Portable

MongoDB

Configuration

databases:
  - name: mongo-db
    type: mongodb
    url: mongodb://host:27017/database
    credentials_ref: ${MONGO_CREDENTIALS}
    description: "MongoDB database"

Redis

Configuration

databases:
  - name: cache
    type: redis
    host: redis.company.com
    port: 6379
    credentials_ref: ${REDIS_PASSWORD}
    description: "Redis cache"

Complete Example

type: project
title: "Full-Stack Application"

databases:
  # Production database
  - name: prod-postgres
    type: postgres
    host: db.company.com
    port: 5432
    database: myapp_prod
    credentials_ref: ${PROD_DB_CREDENTIALS}
    environment: production
  
  # Development database
  - name: dev-sqlite
    type: sqlite
    path: ./dev-data/app.db
    environment: development
  
  # Cache layer
  - name: redis-cache
    type: redis
    host: cache.company.com
    port: 6379
    credentials_ref: ${REDIS_PASSWORD}
    description: "Application cache"
  
  # Analytics database
  - name: analytics-mongo
    type: mongodb
    url: mongodb://analytics.company.com:27017/analytics
    credentials_ref: ${MONGO_CREDENTIALS}
    description: "Analytics data store"

Communication Tool Integrations

Link to team communication channels and collaboration spaces.

Slack

Configuration

communication:
  - name: project-channel
    provider: slack
    url: https://company.slack.com/archives/C123ABC456
    channel: "#project-team"
    description: "Main project channel"

Features

  • Real-time messaging
  • Channel organization
  • File sharing
  • Integrations and bots

Microsoft Teams

Configuration

communication:
  - name: teams-channel
    provider: microsoft-teams
    url: https://teams.microsoft.com/l/channel/...
    team: "Engineering"
    channel: "Project Alpha"
    description: "Team collaboration space"

Features

  • Microsoft 365 integration
  • Video meetings
  • File collaboration
  • Enterprise features

Discord

Configuration

communication:
  - name: discord-server
    provider: discord
    url: https://discord.gg/abc123
    server: "Project Community"
    channel: "#general"
    description: "Community server"

Features

  • Voice and text channels
  • Community building
  • Bots and automation
  • Screen sharing

Complete Example

type: project
title: "Collaborative Project"

communication:
  # Internal team communication
  - name: team-slack
    provider: slack
    url: https://company.slack.com/archives/C123ABC
    channel: "#project-alpha"
    description: "Internal team channel"
  
  # Stakeholder updates
  - name: stakeholder-teams
    provider: microsoft-teams
    url: https://teams.microsoft.com/l/channel/...
    team: "Leadership"
    channel: "Project Updates"
    description: "Stakeholder communication"
  
  # Community engagement
  - name: community-discord
    provider: discord
    url: https://discord.gg/xyz789
    server: "Open Source Community"
    description: "Community discussions"

CI/CD Platform Integrations

Reference continuous integration and deployment pipelines.

GitHub Actions

Configuration

ci_cd:
  - name: main-pipeline
    provider: github-actions
    url: https://github.com/user/repo/actions
    workflow: "CI/CD Pipeline"
    description: "Main build and deploy pipeline"

Features

  • Integrated with GitHub
  • YAML-based workflows
  • Matrix builds
  • Marketplace actions

Azure Pipelines

Configuration

ci_cd:
  - name: azure-pipeline
    provider: azure-pipelines
    url: https://dev.azure.com/org/project/_build
    pipeline: "Build and Deploy"
    description: "Azure DevOps pipeline"

Features

  • Multi-platform builds
  • Release management
  • Deployment gates
  • Azure integration

Jenkins

Configuration

ci_cd:
  - name: jenkins-job
    provider: jenkins
    url: https://jenkins.company.com/job/project-build
    job: "project-build"
    description: "Jenkins build job"

Features

  • Self-hosted automation
  • Extensive plugin ecosystem
  • Pipeline as code
  • Distributed builds

GitLab CI/CD

Configuration

ci_cd:
  - name: gitlab-pipeline
    provider: gitlab-ci
    url: https://gitlab.com/user/project/-/pipelines
    description: "GitLab CI/CD pipeline"

Features

  • Integrated with GitLab
  • Auto DevOps
  • Container registry
  • Kubernetes integration

Complete Example

type: project
title: "Multi-Platform Application"

ci_cd:
  # Main build pipeline
  - name: build
    provider: github-actions
    url: https://github.com/company/app/actions
    workflow: "Build"
    description: "Build and test"
  
  # Deployment pipeline
  - name: deploy
    provider: azure-pipelines
    url: https://dev.azure.com/company/project/_build
    pipeline: "Deploy to Production"
    description: "Production deployment"
  
  # Legacy system
  - name: legacy-build
    provider: jenkins
    url: https://jenkins.company.com/job/legacy-build
    job: "legacy-build"
    description: "Legacy system build"

Custom Integrations

Define custom integrations for tools not covered by standard providers.

Generic Integration Format

custom_integrations:
  - name: custom-tool
    type: custom
    url: https://custom-tool.company.com/project/123
    api_endpoint: https://api.custom-tool.com/v1
    credentials_ref: ${CUSTOM_TOOL_TOKEN}
    metadata:
      project_id: "123"
      workspace: "engineering"
    description: "Custom internal tool"

API Integration

custom_integrations:
  - name: internal-api
    type: api
    base_url: https://api.internal.company.com
    endpoints:
      projects: /v1/projects/{id}
      tasks: /v1/projects/{id}/tasks
    auth_type: bearer
    credentials_ref: ${API_TOKEN}
    description: "Internal project API"

Webhook Integration

custom_integrations:
  - name: notification-webhook
    type: webhook
    url: https://hooks.company.com/project-updates
    method: POST
    headers:
      Content-Type: application/json
      Authorization: ${WEBHOOK_SECRET}
    description: "Project update notifications"

Complete Custom Example

type: project
title: "Enterprise Project with Custom Tools"

# Standard integrations
repositories:
  - name: github
    provider: github
    url: https://github.com/company/project

# Custom integrations
custom_integrations:
  # Internal project management system
  - name: internal-pms
    type: custom
    url: https://pms.company.com/projects/12345
    api_endpoint: https://api.pms.company.com/v2
    credentials_ref: ${PMS_TOKEN}
    metadata:
      project_id: "12345"
      department: "engineering"
    description: "Internal project management system"
  
  # Custom reporting tool
  - name: reporting-dashboard
    type: custom
    url: https://reports.company.com/dashboard/project-alpha
    description: "Custom reporting dashboard"
  
  # Integration webhook
  - name: status-webhook
    type: webhook
    url: https://hooks.company.com/project-status
    method: POST
    headers:
      Content-Type: application/json
    description: "Status update webhook"

Best Practices

Guidelines for effective integration management in HoxCore.

1. Security & Credentials

✅ Do

  • Use environment variables for credentials
  • Reference credential management systems
  • Use read-only access when possible
  • Regularly rotate credentials
  • Document required permissions

❌ Don't

  • Store passwords or tokens in YAML files
  • Commit credentials to Git
  • Use overly permissive access
  • Share credentials across projects unnecessarily

2. Organization & Naming

✅ Do

  • Use descriptive, consistent names
  • Group related integrations
  • Add meaningful descriptions
  • Document the purpose of each integration
  • Use consistent naming conventions

❌ Don't

  • Use cryptic or unclear names
  • Leave descriptions empty
  • Mix unrelated integrations
  • Use inconsistent naming patterns

3. Maintenance & Updates

✅ Do

  • Keep integration URLs up to date
  • Remove obsolete integrations
  • Document integration dependencies
  • Test integrations periodically
  • Version control integration changes

❌ Don't

  • Leave broken links in definitions
  • Accumulate unused integrations
  • Ignore integration failures
  • Make undocumented changes

4. Documentation

✅ Do

  • Document integration setup steps
  • Explain required permissions
  • Provide access instructions
  • List integration dependencies
  • Include troubleshooting tips

❌ Don't

  • Assume everyone knows how to access tools
  • Skip permission documentation
  • Leave setup undocumented
  • Ignore common issues

5. Integration Scope

✅ Do

  • Link only relevant integrations
  • Use specific URLs when possible
  • Separate concerns (code, docs, tasks)
  • Consider team access needs
  • Balance completeness with simplicity

❌ Don't

  • Link every possible tool
  • Use overly broad references
  • Mix unrelated resources
  • Create integration overload

Example: Well-Documented Integration

type: project
title: "Well-Integrated Project"
description: >
  This project demonstrates best practices for
  integration management in HoxCore.

# Version Control
repositories:
  - name: main-repo
    provider: github
    url: https://github.com/company/project
    branch: main
    description: "Main codebase - requires read access"

# Project Management
tools:
  - name: sprint-board
    provider: github-projects
    url: https://github.com/orgs/company/projects/1
    description: "Sprint planning board - team members have write access"

# Documentation
storage:
  - name: team-docs
    provider: notion
    url: https://notion.so/company/project-docs
    description: "Project documentation - all team members have edit access"

# Communication
communication:
  - name: team-channel
    provider: slack
    url: https://company.slack.com/archives/C123ABC
    channel: "#project-team"
    description: "Main team channel - join for project updates"

# CI/CD
ci_cd:
  - name: build-pipeline
    provider: github-actions
    url: https://github.com/company/project/actions
    workflow: "CI/CD"
    description: "Automated build and deployment - view-only for most team members"

# Database (credentials managed externally)
databases:
  - name: production-db
    type: postgres
    host: db.company.com
    port: 5432
    database: project_prod
    credentials_ref: ${PROD_DB_CREDENTIALS}
    description: "Production database - access via VPN, credentials in vault"
    environment: production

# Notes on access and setup
metadata:
  integration_notes: |
    Setup Instructions:
    1. Request GitHub org access from IT
    2. Join #project-team Slack channel
    3. Get Notion workspace invite from team lead
    4. VPN required for database access
    5. Credentials stored in company vault
    
    Troubleshooting:
    - GitHub access issues: Contact IT helpdesk
    - Slack channel not visible: Check workspace settings
    - Database connection: Verify VPN connection
    - CI/CD failures: Check GitHub Actions logs

Next Steps

Now that you understand integrations in HoxCore, explore related topics:

🤖 AI Features

Learn how to integrate LLM models and knowledge bases with your projects.

Explore AI Features →

📝 Templates

Create templates with pre-configured integrations for consistent project setup.

Learn About Templates →

📚 Core Concepts

Understand the fundamental concepts behind HoxCore's design.

Learn Core Concepts →

📖 CLI Reference

Explore all available commands for managing integrations.

View CLI Reference →