Docs

Projects & Repos

Link GitHub repositories to workspaces, scan your stack, and manage projects from the FlyDocs portal.

Projects in the portal represent your codebases. Each project maps to a GitHub repository and belongs to a workspace. When you install the FlyDocs CLI in a repo on your machine, the cloud tier connects that local project to its portal counterpart through the workspace.

Connecting repos

Repos are connected through the GitHub integration. Once your org admin has authorized GitHub access (during onboarding or from Settings), your organization's repositories become available for linking.

Navigate to your workspace, then select Projects to see linked repos and add new ones. The portal shows which repos are already connected and which are available.

Repo scanning

When you connect a repository, the GitHub integration scans it to detect your stack. This includes:

  • Frameworks — React, Next.js, Astro, Express, etc.
  • Languages — TypeScript, Python, Go, Rust, etc.
  • Testing tools — Vitest, Jest, Playwright, pytest, etc.
  • Package managers — npm, pnpm, yarn, pip, cargo, etc.

The detected stack informs skill recommendations and project context. It's the same detection the CLI performs locally, but run against the repo through the GitHub API.

Project detail view

Each project page shows:

  • Project status and configuration
  • Linked repository and detected stack
  • Workspace assignment
  • Team members with access

Creating a new project

From the workspace, navigate to /projects/new. The setup wizard walks you through:

  1. Select a repository from your connected GitHub organization
  2. Confirm the detected stack
  3. Assign to the current workspace
  4. Run through any remaining configuration

Once the project exists in the portal, connect it from your local machine:

Terminal 
cd your-project
flydocs connect

This stores your API key globally at ~/.flydocs/credentials (the same path used by flydocs init and flydocs auth), updates .flydocs/config.json to cloud tier, and links your local project to the portal workspace.

Workspace-scoped projects

Projects belong to workspaces, not directly to organizations. This is intentional — workspaces represent team boundaries. A frontend workspace might contain your web app and design system repos, while a backend workspace holds your API and infrastructure repos.

Members only see projects in workspaces they belong to. Org admins can see and manage all projects across all workspaces.

The local-to-cloud relationship

Local: A repo on your machine where the FlyDocs CLI is installed.

Cloud: A project in the portal, linked to a GitHub repo, scoped to a workspace.

Bridge: The API key in .env and the cloud tier setting in .flydocs/config.json. When the CLI runs scripts, the relay API resolves which workspace and project the request belongs to.

Next