Docs

Version Control

Connect FlyDocs to GitHub, GitLab, or Bitbucket for repo scanning, stack detection, and PR workflow automation.

FlyDocs connects to your version control provider for three things: scanning your repo to detect your stack, linking repos to workspaces for cross-project context, and automating PR creation as part of the workflow lifecycle.

How FlyDocs Uses Version Control

  • Repo scanning: during setup, FlyDocs scans your repository to detect frameworks, languages, and tooling. This drives skill recommendations and context generation.
  • Workspace linking: repos are linked to your FlyDocs workspace, enabling cross-repo context through service descriptors.
  • PR workflow: hooks fire after git operations to automate PR creation with issue context, linking code changes back to tracked work.

GitHub

Connect via OAuth in the FlyDocs portal. GitHub access is granted at the org or account level, and FlyDocs requests only the permissions needed for repo scanning and PR operations.

What you get

  • Automatic stack detection from repo contents
  • PR creation via the issues.py pr command
  • PR validation through the post-pr-check.py hook
  • Repo-to-workspace linking for service descriptor context

Setup

  1. Open the FlyDocs portal and navigate to workspace settings
  2. Select GitHub under version control providers
  3. Authorize via OAuth and select the org or account
  4. Choose which repositories to connect

GitLab

Connect via OAuth in the FlyDocs portal. GitLab access works at the group or project level. FlyDocs scans connected projects for stack detection and supports the merge request workflow.

What you get

  • Automatic stack detection from project contents
  • MR creation via the issues.py pr command (detects GitLab automatically)
  • MR validation through the post-pr-check.py hook
  • Project-to-workspace linking for service descriptor context

Setup

  1. Open the FlyDocs portal and navigate to workspace settings
  2. Select GitLab under version control providers
  3. Authorize via OAuth and select the group
  4. Choose which projects to connect

Bitbucket

Connect via OAuth in the FlyDocs portal. Bitbucket access works at the workspace or repository level. Same scanning and PR workflow as the other providers.

What you get

  • Automatic stack detection from repository contents
  • PR creation via the issues.py pr command
  • PR validation through the post-pr-check.py hook
  • Repo-to-workspace linking for service descriptor context

Setup

  1. Open the FlyDocs portal and navigate to workspace settings
  2. Select Bitbucket under version control providers
  3. Authorize via OAuth and select the workspace
  4. Choose which repositories to connect

PR Workflow

FlyDocs automates PR creation through hooks and scripts. The post-pr-check.py hook fires after git operations (PostToolUse: Bash), and the issues.py pr command creates PRs with full issue context.

Terminal 
python3 .claude/skills/flydocs-workflow/scripts/issues.py pr \
  --issue ENG-123 \
  --title "Add user avatar upload" \
  --base main

The script detects your VCS provider (GitHub, GitLab, or Bitbucket) automatically from the git remote URL. It populates the PR description with issue context, acceptance criteria, and links back to the tracked issue. Use --draft for work-in-progress PRs or --dry-run to preview without creating.

What the hook validates

  • Branch is not main or master (prevents direct commits to protected branches)
  • Commit messages follow the expected format
  • Issue reference is present when creating a PR from a workflow context

Service Descriptors

In multi-repo setups, each repository contains a service descriptor at flydocs/context/service.json. This file describes the service's role, dependencies, API contracts, and relationship to other services in the workspace.

flydocs/context/service.json 
{
  "name": "api-gateway",
  "type": "service",
  "description": "HTTP API gateway for client applications",
  "stack": {
    "language": "typescript",
    "framework": "express",
    "runtime": "node"
  },
  "dependencies": ["auth-service", "user-service"],
  "apis": {
    "provides": ["/api/v1/*"],
    "consumes": ["auth-service:/verify", "user-service:/users"]
  }
}

When repos are linked to a workspace, service descriptors provide cross-repo context. Your AI coding tool understands not just the current project, but how it fits into the broader system.

Next