Autohive Integrations Tooling

Validation tools and CI/CD workflows for Autohive integrations.

📖 Building an integration? See the SDK documentation for the tutorial, structure reference, and patterns.

Requires: Python 3.13+

What's Included

File	Description
action.yml	Composite GitHub Action for cross-repo integration validation (usage)
scripts/validate_integration.py	Structure and config validation (docs)
scripts/check_code.py	Syntax, import, JSON, lint, format, security, dependency, and config sync checks (docs)
scripts/check_imports.py	Import availability checker (docs)
scripts/check_readme.py	README update verification (docs)
scripts/check_version_bump.py	Version bump verification with bump-level recommendations (docs)
scripts/check_config_sync.py	Config-code sync checker (docs)
scripts/run_tests.py	Unit test runner with coverage (docs)
scripts/get_changed_dirs.py	Changed directory detection (docs)
.github/workflows/validate-integration.yml	PR validation pipeline
.github/workflows/self-test.yml	Regression guard for tooling scripts
.github/workflows/conv-commits.yml	Conventional commit enforcement
requirements-dev.txt	Dev tool dependencies (ruff, bandit, pip-audit, pytest, pytest-asyncio, pytest-cov)
ruff.toml	Ruff linter and formatter configuration
CONTRIBUTING.md	Contributor guide
LOCAL_DEVELOPMENT.md	Local development workflow and documentation map
INTEGRATION_CHECKLIST.md	Manual review checklist
tests/examples/	Test fixtures for validation scripts

CI Pipeline

flowchart TB
    subgraph triggers["Triggers"]
        PR["Pull Request"]
        PUSH_SCRIPTS["Push — scripts/ or tests/ changed"]
        PUSH_MAIN["Push — master/main"]
    end

    subgraph wf1["validate-integration.yml"]
        ACTION["action.yml (composite action)"]
        ACTION --> GCD[get_changed_dirs.py]
        GCD -->|dirs| COND{dirs empty?}
        COND -->|Yes| SKIP[Skip all checks]
        COND -->|No| VI[validate_integration.py]
        VI --> CC[check_code.py]
        CC --> RT[run_tests.py]
        RT --> CR[check_readme.py]
        CR --> VB[check_version_bump.py]
        VB --> CMT_POST[Post PR comment]
    end

    subgraph wf2["self-test.yml"]
        ST[Run scripts against tests/examples/]
    end

    subgraph wf3["conv-commits.yml"]
        PRT[Validate PR title]
        CMT[Validate commit messages]
    end

    subgraph external["External Repos"]
        EXT["uses: autohive-ai/autohive-integrations-tooling@1.0.0"]
    end

    PR --> wf1
    PR --> wf2
    PR --> wf3
    PUSH_SCRIPTS --> wf2
    PUSH_MAIN --> wf3
    EXT -.-> ACTION

Loading

What each step checks:

Step	Script	Checks
Detect changes	get_changed_dirs.py	git diff → extract top-level dirs, filter out .github, scripts, tests
Structure check	validate_integration.py	Folder name, required files, config.json schema, __init__.py, requirements.txt, tests/, icon size, unused scopes
Code check	check_code.py	pip install, py_compile, check_imports, JSON validity, ruff check, ruff format, bandit, pip-audit, check_config_sync
Tests	run_tests.py	Installs each integration's dependencies, then discovers and runs test_*_unit.py files with pytest per-integration. Warns (does not fail) if no unit tests exist
README check	check_readme.py	New integration files added → was README.md also updated?
Version check	check_version_bump.py	Version in config.json incremented? Recommends major/minor/patch based on config and code changes

Usage as GitHub Action

This repository provides a composite GitHub Action that other repos can use to validate integrations.

Basic usage

name: Validate Integration

on:
  pull_request:
    branches: [master, main]

jobs:
  validate:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: autohive-ai/autohive-integrations-tooling@1.0.0
        with:
          base_ref: origin/${{ github.base_ref }}

Inputs

Input	Required	Default	Description
base_ref	No*	—	Git ref to diff against for detecting changed directories
directories	No*	—	Space-separated list of directories to validate (skips auto-detection)
python_version	No	3.13	Python version to use
post_comment	No	true	Post a sticky PR comment with results

* Either base_ref or directories must be provided.

Outputs

Output	Description
directories	Space-separated list of validated directories
structure_result	success or failure
code_result	success or failure
tests_result	success or failure
readme_result	success or failure
version_result	success or failure
structure_output	Full output of the structure check
code_output	Full output of the code check
tests_output	Full output of the test runner
readme_output	Full output of the README check
version_output	Full output of the version check

PR Comment

When post_comment is enabled, the action posts a sticky comment on the PR with a summary table showing ✅ Passed, ⚠️ Passed with warnings, or ❌ Failed for each check, along with expandable full output.

Versioning

The major version of this tooling matches the Autohive Integrations SDK major version it targets. The minor and patch versions are the tooling's own iteration and do not correspond to SDK releases.

For example, 2.1.0 means "the second tooling release for SDK v2" — it does not imply an SDK 2.1.0 exists.

Tooling version	Meaning
2.0.0	Initial tooling release for SDK v2
2.1.0	New checks or features (still SDK v2)
2.1.1	Bug-fix to the tooling (still SDK v2)
3.0.0	Tooling targeting SDK v3

Setup

uv python install 3.13
uv venv --python 3.13
source .venv/bin/activate   # Linux/macOS
# .venv\Scripts\activate    # Windows
uv pip install -r requirements-dev.txt

Local Testing

# Validate structure and config
python scripts/validate_integration.py my-integration

# Run code quality checks (syntax, imports, JSON, lint, format, security, deps, config sync)
python scripts/check_code.py my-integration

# Check all imports in a file
python scripts/check_imports.py my-integration/main.py

# Validate all integrations (auto-discovers at repo root)
python scripts/validate_integration.py

Running unit tests

The test runner discovers test_*_unit.py files and runs them with pytest and coverage:

# Run unit tests for specific integrations
python scripts/run_tests.py my-integration

# Run unit tests for multiple integrations
python scripts/run_tests.py hackernews bitly notion

# Run unit tests for all integrations (auto-discovers)
python scripts/run_tests.py

Integrations without test_*_unit.py files are skipped with a warning. The test infrastructure (pyproject.toml, conftest.py, requirements-test.txt) lives in the integrations repo — see its CONTRIBUTING.md for how to write and run tests locally.

Integration Requirements

See INTEGRATION_CHECKLIST.md for full details.

Required Files

• config.json - Integration configuration
• {name}.py - Main implementation
• __init__.py - Package init (minimal, optional for modular integrations with actions/)
• requirements.txt - Dependencies (must include autohive-integrations-sdk)
• README.md - Documentation
• icon.png or icon.svg - Integration icon (512x512 pixels)
• tests/ - Test folder with __init__.py, context.py, and test_*.py

Integrations

Integration	Description	Auth Type