Skip to content

README.md

Latest commit

 

History

History
388 lines (297 loc) · 14.6 KB

README.md

File metadata and controls

388 lines (297 loc) · 14.6 KB
Raw

Gitfleet

Main License: MIT Coverage

Command every repository as one fleet.

Gitfleet

Table of Contents

Overview

Gitfleet manages repositories from creation and cloning through collaboration, delivery, security, analytics, and governance. It keeps portable concepts such as changes, pipelines, planning, and development environments consistent while retaining provider-specific capabilities when they exist.

The gitfleet and gf binaries are equivalent. Human-readable output is the default, and every automation workflow can opt into structured output with --json.

Architecture

Crate Responsibility
gitfleet-core Provider-neutral entities, capabilities, operations, infrastructure
gitfleet-providers GitHub and GitLab provider clients, wire types, normalization
gitfleet-cli Thin CLI surface over shared operations

Only gitfleet-providers performs HTTP requests. Unsupported operations return a capability error instead of pretending another provider supports them.

Features

  • Repository lifecycle, cloning, forks, synchronization, stale branches, and multi-repository workspaces.
  • Proposed changes, stacked changes, merge queues, reviews, suggestions, issues, discussions, notifications, and mentions.
  • Pipeline definitions, runs, logs, artifacts, caches, releases, deployments, environments, registries, and runners.
  • Planning boards, milestones, labels, templates, wikis, static sites, and license discovery.
  • Dependency review, advisories, attestations, secret scanning, CodeQL, compliance, audit logs, secrets, and variables.
  • Repository governance, policies, access management, account keys, analytics, code navigation, snippets, browser integration, and raw provider API access.
  • Named profiles, explicit JSON output, terminal themes, aliases, completion, reversible live playbooks.

Installation

Gitfleet is a Rust CLI. Install the CLI package from this checkout with Cargo:

cargo install --path gitfleet-cli

gitfleet version
gf version

This builds optimized release binaries and installs both commands into Cargo's binary directory.

Cargo installs binaries into ~/.cargo/bin; make sure that directory is on your PATH if the commands are not found.

After pulling new source changes, reinstall the local package to refresh the commands:

cargo install --path gitfleet-cli --force

Authentication

Authenticate with a provider token and inspect the resulting profile:

gitfleet auth login --token <token>
gitfleet auth status
gitfleet auth token

GitHub Enterprise is supported through an explicit host:

gitfleet auth login \
  --host github.example.com \
  --profile work \
  --token <token>

For CI, set GITFLEET_GITHUB_TOKEN or GITFLEET_GITLAB_TOKEN. Destructive operations in JSON or non-interactive mode require --yes.

GitHub Token Scopes

Choose the narrowest scopes required by the commands you use. For a classic personal access token, the relevant scopes are:

Scope Required for
repo Private repositories, changes, issues, code, and CI
public_repo Public-repository access without the full repo scope
workflow Adding or updating workflow files
notifications Inbox notification operations
read:discussion, write:discussion Reading or modifying GitHub discussions
read:user Account and activity information
read:org Organization, team, and runner reads
admin:org Organization membership and team mutations
read:project, project Reading or modifying GitHub planning projects
gist Hosted snippet operations
read:packages, write:packages Reading or publishing package registry content
delete:packages Deleting package versions
admin:repo_hook, admin:org_hook Repository and organization webhook management
security_events Code scanning and security event operations
read:audit_log Organization audit log access
codespace Hosted development environment operations
admin:public_key, admin:gpg_key SSH and GPG key management
delete_repo Destructive repository retirement workflows

Fine-grained tokens use repository and organization permissions instead of classic scopes. Grant each selected repository the permissions required by the commands you intend to run; some user-scoped endpoints may still require a classic token. See GitHub's official documentation for classic scopes and fine-grained permissions.

Configuration

Credentials are stored at ~/.config/gitfleet/credentials.toml with mode 0600. Repository-local profile selection uses .gitfleetrc.

Resolution follows explicit flags, environment configuration, the repository-local profile, the active profile, and then defaults. Repository targets come from --repo or the current Git remote.

Environment variables:

  • GITFLEET_GITHUB_TOKEN supplies the GitHub token in automation.
  • GITFLEET_GITLAB_TOKEN supplies the GitLab token in automation.
  • GITFLEET_PROFILE selects a named profile.
  • CI=true enables non-interactive behavior.

Profiles

Named profiles support separate provider accounts and hosts:

gitfleet auth login --profile personal --token <token>
gitfleet auth login --profile work --token <token>
gitfleet auth list
gitfleet auth switch work
gitfleet auth detect

The active profile supplies the provider, host, and token for subsequent operations. auth detect selects a profile from the current repository.

Commands

Use gitfleet help for the complete surface or target nested help directly:

gitfleet help
gitfleet help change
gitfleet help pipeline run
Family Purpose
auth Provider accounts and profiles
repo Repository lifecycle, forks, synchronization, and branches
change Proposed changes, stacks, checks, and merge automation
review Threads, comments, suggestions, reactions, and resolution
issue, discussion, inbox Collaboration and notification workflows
pipeline Definitions, runs, logs, artifacts, and caches
release, deploy, environment Delivery lifecycle
workspace Named fleets and bounded multi-repository execution
govern, policy Fleet governance and repository protection
planning Boards, work items, milestones, and iterations
wiki, site Repository documentation and publishing
search, code, browse, api Discovery, navigation, and provider escape hatches
label, template, license Repository metadata
deps, advisory, attestation, security Dependency and security operations
registry, dev, runner, webhook Build and delivery infrastructure
secret, variable Automation configuration
access, identity Organization access and account keys
analytics, snippet Reporting and hosted snippets
alias, completion, config, help Gitfleet utilities
version Version information

Selected Nested Commands

  • pipeline definition manages pipeline definitions.
  • pipeline run inspects, watches, reruns, and debugs runs.
  • pipeline cache manages pipeline caches.
  • security audit, security leaks, security dependabot, security compliance, and security codeql expose security capabilities.
  • analytics repo and analytics pipeline provide repository and pipeline reporting.
  • access org and access team manage organizations, groups, and teams.
  • identity ssh and identity gpg manage provider account keys.
  • change queue, planning milestone, policy branch, and repo fork expose provider capabilities without adding provider-specific root names.

Common Workflows

Change Review

gitfleet change create --title "Add feature"
gitfleet change list --state open
gitfleet change stack create --base main
gitfleet review threads 42
gitfleet review suggest 42 --file src/index.ts --line 12 --body "Use this"

Pipeline Delivery

gitfleet pipeline definition list
gitfleet pipeline run list
gitfleet pipeline run watch <run-id>
gitfleet pipeline cache inspect
gitfleet release list
gitfleet deploy list

Security Governance

gitfleet security compliance check --repos owner/repository
gitfleet security leaks scan --repo owner/repository
gitfleet policy list --repo owner/repository
gitfleet govern report --org example

Workspaces

gitfleet workspace define \
  --name platform \
  --repos owner/api \
  --repos owner/web
gitfleet workspace list
gitfleet workspace run --name platform --command "issue list --state open"

Workspace targets may be provider-qualified:

github@github.com:owner/repository
github@github.example.com:platform/repository

Output Formats

Human-readable output is the default:

gitfleet issue list

Use structured output explicitly:

gitfleet issue list --json

Global options include:

  • --json for machine-readable results.
  • --debug for a redacted diagnostic log.
  • --theme dark|light|auto for terminal color selection.

Safety

Destructive human-mode operations request confirmation. JSON and non-interactive operations require --yes; bulk mutations provide --dry-run when a useful preview is possible.

Playbooks

Live playbooks under gitfleet-playbooks/ validate command families against the GitHub API. They require explicit credentials and revert mutations during teardown.

REPO=owner/test-repository ORG=example bash gitfleet-playbooks/all.sh
SKIP="pipeline-run.sh,planning.sh" bash gitfleet-playbooks/all.sh
PARALLEL=1 bash gitfleet-playbooks/all.sh

Use a dedicated test repository and review each playbook before running it. Automated tests never make real HTTP requests.

Development

Build release binaries inside the repository when you want to inspect the local artifacts directly:

cargo build --release
./target/release/gitfleet version
./target/release/gf version

Run the required local gates before handing off changes:

cargo fmt --check
cargo clippy -- -D warnings
cargo check
cargo test --workspace
cargo llvm-cov --fail-under-lines 80
cargo build --release

The workspace currently lists 2,239 Rust test entries as reported by Cargo:

cargo test --workspace -- --list | grep -c ': test$'

Coverage must remain at or above 80 percent. See AGENTS.md for architecture, testing, style, playbook, and release requirements.

Repository Structure

gitfleet-core/        provider-neutral entities, capabilities, errors, operations,
                      infrastructure (config, git, output, prompts, secrets, workspace)
gitfleet-providers/   GitHub and GitLab provider clients, wire types, normalization
gitfleet-cli/         thin CLI surface over shared operations
gitfleet-playbooks/   live API test scripts (bash)

PLAN.md is the Gitfleet refactor contract. ROADMAP.md tracks the Rust rewrite and GitLab provider.

Contributing

Read CONTRIBUTING.md before proposing a change.

Security

Report vulnerabilities through the private process in SECURITY.md, not a public issue.

Support

For usage help, run gitfleet help [command...]. For reproducible bugs, open an issue with the Gitfleet version, operating system, command, expected behavior, actual behavior, and redacted --debug output.

Sponsorship

Gitfleet is maintained by Airscripts. If it helps your team manage repositories more effectively, sponsor ongoing maintenance and provider coverage through GitHub Sponsors.

License

MIT. See LICENSE.