Import a project into CodeGraph

Project import creates or refreshes a project from a Git repository or a local checkout. Get the UI and API URLs and permission for the target project group from your administrator. Replace <API_URL> with your instance address without /api/v1. The REST schema is at <API_URL>/api/docs (Swagger UI) and <API_URL>/api/openapi.json (OpenAPI JSON).

Import through UI or REST

In the UI, open <UI_URL>/dashboard/repositories, select a configured Git provider, find the repository, and choose Import. Check the result at <UI_URL>/dashboard/projects. A Git binding and a ready CPG are separate states.

If no provider is configured, obtain an access token by sending the JSON fields username and password to POST /api/v1/auth/token. Then call POST /api/v1/import/start with Authorization: Bearer <access-token> and Content-Type: application/json:

{
  "repo_url": "https://github.com/pallets/flask.git",
  "branch": "main",
  "mode": "full",
  "create_domain_plugin": false,
  "import_docs": false,
  "group_id": "<GROUP_ID_FROM_GET_GROUPS>"
}

Confirm that the sample branch exists before sending the request. Replace the URL and branch for your repository. Get group_id from GET /api/v1/groups. Never embed credentials in the repository URL. The response contains job_id; poll GET /api/v1/import/status/{job_id} to a terminal status, then inspect GET /api/v1/projects and the CPG. CPG (Code Property Graph) records relationships among code elements. import_docs: false skips project documentation import but still builds the CPG.

On a Windows workstation with PowerShell, after obtaining a token:

$api='<API_URL>/api/v1'
$headers=@{Authorization=('Bearer ' + $env:CODEGRAPH_TOKEN)}
$body=@{repo_url='https://github.com/pallets/flask.git';branch='main';mode='full';create_domain_plugin=$false;import_docs=$false;group_id='<GROUP_ID_FROM_GET_GROUPS>'} | ConvertTo-Json
$job=Invoke-RestMethod -Method Post -Uri "$api/import/start" -Headers $headers -ContentType 'application/json' -Body $body
Invoke-RestMethod -Uri "$api/import/status/$($job.job_id)" -Headers $headers

On a macOS or Ubuntu workstation with Bash and Python 3:

API='<API_URL>/api/v1'
TOKEN="${CODEGRAPH_TOKEN:?Set CODEGRAPH_TOKEN from your secret store}"
set -o pipefail
GROUP_ID='<GROUP_ID_FROM_GET_GROUPS>'
JOB_ID="$(printf 'Authorization: Bearer %s\n' "$TOKEN" | curl -fsS -X POST "$API/import/start" \
  -H @- -H 'Content-Type: application/json' \
  --data "{\"repo_url\":\"https://github.com/pallets/flask.git\",\"branch\":\"main\",\"mode\":\"full\",\"create_domain_plugin\":false,\"import_docs\":false,\"group_id\":\"$GROUP_ID\"}" \
  | python3 -c 'import json,sys; print(json.load(sys.stdin)["job_id"])')" || exit 1
printf 'Authorization: Bearer %s\n' "$TOKEN" | curl -fsS -H @- "$API/import/status/$JOB_ID"

Run these commands on a workstation that can reach the API. Keep the token out of repository files and shell history; use a secret store for persistent configuration.

Repeat the status request at an interval such as five seconds until completed, failed, or cancelled, using a bounded operational timeout. A job_id confirms registration, not completion. Inspect the error for failed; do not treat cancelled as graph readiness. After completed, check project registration and CPG freshness using the CLI guide. Do not start a replacement import solely because a response is delayed.

The examples require CODEGRAPH_TOKEN in the environment, obtained from your secret store. The Bash example also requires curl and Python 3. It sends the header through curl stdin to keep the token out of process arguments. The displayed status command performs one check; repeat it separately.

Server CLI

Run these commands over SSH on the Ubuntu server from the CodeGraph installation directory:

sudo docker compose -f docker-compose.yml exec -T api python -m src.cli import --help
sudo docker compose -f docker-compose.yml exec -T api python -m src.cli import \
  --repo 'https://github.com/pallets/flask.git' --branch main \
  --mode full --no-plugin --no-docs
sudo docker compose -f docker-compose.yml exec -T api python -m src.cli jobs
sudo docker compose -f docker-compose.yml exec -T api python -m src.cli projects list

CLI and REST may use different registration paths. If the CLI-imported project is absent from GET /api/v1/projects, the administrator registers it through POST /api/v1/projects with group_id, name, and the actual CPG db_path visible to the API container. Inspect the ProjectCreate schema in Swagger UI. Before auditing, check both the project listing and the fresh CPG.

When working from a complete CodeGraph checkout without Compose, run the commands from the repository root. First inspect python -m src.cli import --help. The CLI accepts exactly one source: --path for a local directory or --repo for Git. Available modes: --mode {full,selective,incremental}. Choose one of the two import commands below. As in the REST example, --no-docs skips documentation import, and --no-plugin skips domain plugin creation. The command builds a CPG for source code analysis.

The <source-directory> must be readable by the CLI process. When ENVIRONMENT=production, local-path import also requires API_LOCAL_IMPORT_ENABLED=1.

python -m src.cli import --path '<source-directory>' --mode full --no-plugin --no-docs
python -m src.cli import --repo 'https://github.com/pallets/flask.git' --branch main --mode full --no-plugin --no-docs
python -m src.cli jobs
python -m src.cli projects list
python -m src.cli projects info '<project-name>'

In projects list, find the imported project by name. Then run projects info with that name and compare Source Path, CPG Path, and DuckDB Path with the checkout and graph you intend to analyze. These commands show the registered project configuration; verify the graph’s source revision separately using the CLI guide.

Only an authorized operator changes the group default with python -m src.cli projects set-default '<project-name>'. Check that the CPG path and source revision belong to the selected project.