apify import and apify create --import: turn an existing repository into an Actor #1510

Problem

The CLI has two entry points for a project: apify create starts from nothing, and apify pull starts from an Actor that already exists. There is no path for the case many developers arrive with: a repository that already exists, possibly with several packages, that should become an Actor. apify init only writes actor.json; nothing binds the directory to an Actor or sets the repository as its Git source, so people wire it up in Apify Console by hand (#1425, #1428). The platform half exists: a version's gitRepoUrl accepts <url>#<branch>:<folder>, and the API routes that register a deployment key and enable builds on push accept an existing repository.

What we want

apify import, run inside an existing repository, binds the directory to a new or existing Actor and, optionally, sets the Actor's Git source to the repository, branch, and subdirectory, reusing the provider authorization that apify create --source uses. The same flow is reachable as apify create <name> --import, which imports the current directory instead of scaffolding; both spellings share one implementation.

• apify import [--dir <path>] creates the Actor named in .actor/actor.json (or a name given as a positional argument), or links an existing one with --actor <id or name>, and the next apify push from the directory targets it.
• With --source git (the default when the directory is inside a Git repository with a remote on GitHub, GitLab, or Bitbucket), the Actor's version gets sourceType: GIT_REPO and gitRepoUrl set to the remote URL plus #<branch>:<folder>, where the branch is the current branch unless --branch says otherwise and the folder is the directory relative to the repository root (omitted at the root); a private repository uses the SSH form, as Apify Console stores it.
• The deployment key is registered through POST /v2/integrations/git/{providerId}/register-deployment-key, and builds on push are enabled through PUT /v2/actors/{id}/versions/{v}/build-on-push; --auto-build off skips the webhook, as in apify create.
• --source none (or no remote) only binds the Actor, so a later apify push uploads the directory; nothing on the platform points at Git.
• apify create <name> --import runs the same flow for the current directory: no scaffold, no git init, no dependency install, and the same flags.
• An Actor that already builds from a different repository asks before switching; --force skips the question; a non-interactive run without --force fails with exit code 5 (InvalidInput).
• --json prints one document with the Actor (id, url) and the source that was set; nothing else reaches stdout.
• An Actor at actors/x of a repository shaped like apify/actor-monorepo-example ends up with #main:actors/x.

Design notes

• src/lib/git-source/gitSource.ts already holds the pieces: ensureUsableIntegration, the deployment-key registration, and enableAutomaticBuilds. Today runGitSourceFlow runs them after creating and cloning a new repository, sends gitRepoUrl without a #branch:folder fragment, and enableAutomaticBuilds targets version 0.0; parseGitRepoFlag accepts only workspace/name. Import needs the remote URL (git remote get-url origin), the current branch and the folder from the working copy, the target version number, and a provider picker that matches the remote's host and owner rather than the workspaces used to create a repository.
• The three integration routes have no tests, no OpenAPI entry, and no apify-client-js wrapper, and the deployment-key route merged with a note that it needs an RFC if it stays; track that hardening in apify-core as a dependency before the command leaves experimental.
• Builds on push are registered per Actor version, so several imported Actors on one repository each get their own webhook and every push rebuilds all of them; a repository-level model is the repo group sub-issue (apify/apify-core#31474).

Out of scope

• Scaffolding a new Actor into a monorepo (apify create --into, apify create assumes a greenfield standalone repo — no monorepo or existing-repo path #1425).
• apify push for monorepo Actors (Make apify push work for monorepo Actors that set dockerContextDir #595) and selecting which Actors to push (apify push: select which Actors to push in a repository with several #1499).
• Repository-level webhooks and bulk rebuilds (apify/apify-core#31474).

How it's tested

• test/local/commands/import.test.ts with a mocked client, modeled on push-git-source.test.ts and the create --source tests: bind only; bind plus a Git source at the root and in a subfolder; the SSH form for a private repository; the switch prompt, --force, and the non-interactive failure; --json; apify create --import giving the same calls as apify import.
• pnpm run update-docs for the new command and flag.
• One token-gated [api] case, planned with the lead.

Links

• Epic: apify/apify-core#28685, refinement 5
• The original request: apify import: turn an existing repository into an Actor #1452 (to close as a duplicate once this issue is accepted)
• Related: apify create assumes a greenfield standalone repo — no monorepo or existing-repo path #1425 (create into an existing repo), No CLI surface for git integrations — --source github dead-ends on an unconnected workspace #1428 (Git integration surface), feat: turn on automatic builds for a Git-sourced Actor #1377 (auto-build flag), Guided Actor creation flow in apify create (parity with Console wizard) #1153 (guided creation, which scoped "Import from Git" out)
• Prior art: vercel link