GitHub Integration: Architecture Docs in Your Workflow | Archyl
Integrate Archyl with GitHub for architecture drift checks in CI/CD pipelines, webhooks for architecture changes, and Architecture as Code in your repositories.
Keep architecture documentation in sync with your code
Connect Archyl to GitHub with webhooks, CI/CD integration, and Architecture as Code stored directly in your repositories. Detect architecture drift in pull requests and ensure documentation stays current as your codebase evolves.
GitHub + Archyl: Architecture Documentation in Your Workflow | Webhooks & CI/CD
Integrate Archyl with GitHub for architecture drift checks in CI/CD pipelines, webhooks for architecture changes, and Architecture as Code in your repositories.
GitHub architecture documentation, architecture webhooks GitHub, GitHub CI/CD architecture, architecture drift GitHub, Architecture as Code GitHub
Architecture as Code in your repos
Connect your GitHub repositories
Link your GitHub organization or specific repositories to Archyl. The platform indexes your codebase to understand your actual implementation.
Architecture as Code lives in your repo
Define your C4 model in YAML files committed to your repository. Changes to architecture documentation go through the same PR review process as code changes.
CI/CD pipelines validate architecture
Add Archyl drift checks to your CI/CD pipeline. Pull requests are automatically checked for architecture conformance, and drift scores are reported directly on the PR.
Webhooks for Architecture Changes
Receive real-time notifications when architecture changes occur. Forward events to Slack, Teams, Discord, or your own systems via configurable webhooks.
Drift Checks in CI/CD
Add architecture conformance checks to your GitHub Actions workflows. Block merges when drift scores exceed your threshold, keeping documentation in sync with code.
Architecture as Code in Repos
Store your C4 model as YAML files in your repository. Version, review, and collaborate on architecture documentation using the same Git workflow you use for code.
AI Discovery from Code
Archyl's AI analyzes your GitHub repositories to automatically discover architecture elements, relationships, and technology stacks from your actual codebase.
Pull Request Architecture Checks
Automatically validate that code changes conform to documented architecture. Get comments on PRs when changes introduce drift or violate conformance rules.
Link Archyl releases to GitHub tags and deployments. Track how your architecture evolves across versions with full traceability.
Connect GitHub to Archyl
Go to your team's Integrations page in Archyl and connect your GitHub organization. Authorize the Archyl GitHub App to access your repositories.
Set up webhooks in Archyl to receive notifications on architecture changes. Choose your destination (Slack, Teams, Discord, or custom endpoint) and select which events to listen for.
# Example webhook payload for architecture change { "event": "component.updated", "project": "payment-platform", "element": { "type": "component", "name": "Payment Processor", "container": "API Gateway" }, "changes": { "description": "Updated to support...", "technology": ["Go", "gRPC"] }, "author": "vincent@archyl.com", "timestamp": "2026-03-27T10:30:00Z" }
Add drift checks to CI/CD
Add the Archyl drift check step to your GitHub Actions workflow. Configure the drift score threshold that must pass before a PR can be merged.
# .github/workflows/architecture.yml name: Architecture Check on: [pull_request] jobs: drift-check: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Check architecture drift uses: archyl/drift-action@v1 with: api-key: ${{ secrets.ARCHYL_API_KEY }} project-id: "your-project-id" threshold: 85
Commit Architecture as Code
Export your C4 model as YAML and commit it to your repository. Architecture documentation now follows the same review process as your code.
# archyl/architecture.yaml systems: - name: Payment Platform description: Handles all payment processing containers: - name: API Gateway technology: [Go, chi] components: - name: Payment Processor description: Processes card payments technology: [Go, Stripe SDK] - name: Invoice Generator description: Creates PDF invoices technology: [Go, gopdf]
Example: Architecture drift check in GitHub Actions
# GitHub Actions output Architecture Drift Check - Payment Platform ============================================ Overall Drift Score: 92/100 (PASS) Components checked: 24 Conformance rules: 12 Violations: 1 (low severity) Warning: Invoice Generator component has an undocumented dependency on Notification Service. Consider adding this relationship to your C4 model. Result: PASS (threshold: 85)
Does Archyl need access to my source code?
For AI discovery, Archyl analyzes your repository structure and code to identify architecture elements. For Architecture as Code and drift checks, Archyl only reads the YAML architecture files in your repository. You can configure repository access at a granular level.
Can I use Archyl with GitHub Enterprise?
Yes. Archyl supports GitHub.com and GitHub Enterprise Server. Contact our team for Enterprise Server setup assistance.