Code repositories

Create a repository connector for GitHub, GitLab, Bitbucket, a local checkout, or an archive, test that the source is reachable, and browse its files to feed repository intelligence.

By the end of this page you will have a saved repository connector that reaches your source code, a confirmed reachability test, and a browse listing of the files and directories it exposes — ready to feed repository intelligence. Algenta supports five repository source types through one connector API: github_repo, gitlab_repo, bitbucket_repo, local_repo, and repo_archive.

Prerequisites: an API key and a base URL (see Authentication), and access to the source — a clone URL (with a token for private repositories), a filesystem path, or an archive path. Use https://api.algenta.ai for Algenta cloud, or your own origin such as http://localhost:8000 for a self-hosted deployment.

Repository connectors take these config fields. For github_repo, gitlab_repo, and bitbucket_repo: repository_url (aliases clone_url, url) — an http(s) clone URL — plus an optional access_token (aliases token, api_token) for private repositories. For local_repo: path — a filesystem path to a git working tree or directory the engine can read. For repo_archive: path — a filesystem path to a .tar, .tar.gz, or .zip archive, which the engine extracts and reads. These are the only fields the engine reads.

1

Set your credentials

Export your API key and base URL so every command below picks them up from the environment. For a private hosted repository, keep the access token in its own variable so it never appears in shell history inline.

export ALGENTA_API_KEY="$ALGENTA_API_KEY"
export ALGENTA_BASE_URL="https://api.algenta.ai"
export GITHUB_TOKEN="$GITHUB_TOKEN"

Verify the variables are set:

echo "${ALGENTA_API_KEY:?set ALGENTA_API_KEY}" >/dev/null && echo "key present"
echo "$ALGENTA_BASE_URL"

Expected result: key present and your base URL print without error. A token is only needed for private repositories.

2

Confirm the engine accepts repository types

Ask the engine which connector types it supports and confirm your repository type is in the list.

curl -s "$ALGENTA_BASE_URL/v1/connectors/types" \
  -H "Authorization: Bearer $ALGENTA_API_KEY"

Expected result: a JSON object with a types array that includes the repository types, for example {"types": ["github_repo", "gitlab_repo", "bitbucket_repo", "local_repo", "repo_archive", ...]}. If your type is present, the next step's config shape is accepted.

3

Create the repository connector

POST /v1/connectors stores the connector and returns it with status: "untested". Pick the tab that matches where your code lives.

GitHub

Use type github_repo with an http(s) repository_url. For a private repository, add an access_token — the engine uses it as the x-access-token clone credential.

curl -s -X POST "$ALGENTA_BASE_URL/v1/connectors" \
  -H "Authorization: Bearer $ALGENTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"name\": \"payments-service\",
    \"connector_type\": \"github_repo\",
    \"config\": {
      \"repository_url\": \"https://github.com/acme/payments-service.git\",
      \"access_token\": \"$GITHUB_TOKEN\"
    }
  }"

GitLab

Use type gitlab_repo with an http(s) repository_url. For a private project, add an access_token — the engine uses it as the oauth2 clone credential.

curl -s -X POST "$ALGENTA_BASE_URL/v1/connectors" \
  -H "Authorization: Bearer $ALGENTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"name\": \"billing-lib\",
    \"connector_type\": \"gitlab_repo\",
    \"config\": {
      \"repository_url\": \"https://gitlab.com/acme/billing-lib.git\",
      \"access_token\": \"$GITLAB_TOKEN\"
    }
  }"

Bitbucket

Use type bitbucket_repo with an http(s) repository_url. For a private repository, add an access_token — the engine uses it as the x-token-auth clone credential.

curl -s -X POST "$ALGENTA_BASE_URL/v1/connectors" \
  -H "Authorization: Bearer $ALGENTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"name\": \"web-app\",
    \"connector_type\": \"bitbucket_repo\",
    \"config\": {
      \"repository_url\": \"https://bitbucket.org/acme/web-app.git\",
      \"access_token\": \"$BITBUCKET_TOKEN\"
    }
  }"

Local checkout

Use type local_repo with a path to a checkout the engine can read. A git working tree lets the engine resolve a revision; a plain directory is read as-is.

curl -s -X POST "$ALGENTA_BASE_URL/v1/connectors" \
  -H "Authorization: Bearer $ALGENTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "monorepo-local",
    "connector_type": "local_repo",
    "config": {
      "path": "/srv/repos/monorepo"
    }
  }'

Archive

Use type repo_archive with a path to a .tar, .tar.gz, or .zip archive. The engine extracts it and reads the contents.

curl -s -X POST "$ALGENTA_BASE_URL/v1/connectors" \
  -H "Authorization: Bearer $ALGENTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "release-snapshot",
    "connector_type": "repo_archive",
    "config": {
      "path": "/srv/archives/release-1.4.0.tar.gz"
    }
  }'

Capture the returned id for the steps that follow:

export CONNECTOR_ID="$CONNECTOR_ID"

Expected result: a 201 response with the connector id, your connector_type, and "status": "untested". Any access_token is encrypted at rest — the connector object never returns your config back to you.

Hosted repository URLs must be http(s) clone URLs — SSH URLs (git@...) are rejected with Repository URL must be a http(s) clone URL. Convert to the HTTPS form and supply an access_token for private repositories.

4

Test that the source is reachable

POST /v1/connectors/{id}/test resolves the source for real — it shallow-clones a hosted repository, opens a local checkout, or extracts an archive — and reports the source and how many entries it found. On success the connector flips to live; on failure it flips to error.

curl -s -X POST "$ALGENTA_BASE_URL/v1/connectors/$CONNECTOR_ID/test" \
  -H "Authorization: Bearer $ALGENTA_API_KEY"

Expected result: {"success": true, "status": "live", "message": "Repository source reachable: https://github.com/acme/payments-service.git (4213 entries)."}, and the connector's stored status is now live. On failure, success is false; error_type (for example auth, not_found, or permission) plus recoverable tell you what to fix.

5

Browse the repository entries

GET /v1/connectors/{id}/browse lists the files and directories at the top of the source (up to 100 entries), so you can confirm the right code is reachable. This returns 409 not_connected if the connector is not live — run the test step first.

curl -s "$ALGENTA_BASE_URL/v1/connectors/$CONNECTOR_ID/browse" \
  -H "Authorization: Bearer $ALGENTA_API_KEY"

Expected result: a response whose items array holds repository entries (each with id, label, a kind of file or directory, a selection of {"path": "<relative path>"}, and — for files — a detected language and size), a total, and a message such as Found 42 repository entries.

Expected result

You have a saved repository connector with status: "live", a test that reports the source and its entry count, and a browse listing of its files and directories. The connector is now ready to drive repository intelligence — snapshots, triage, and governed decisions over your code.

Other ways to connect

The same endpoints back the de CLI and the Python SDK — all three hit the identical API.

de connectors create connector.json     # POST /v1/connectors from a JSON body
de connectors test $CONNECTOR_ID         # resolve and reach the source
de connectors browse $CONNECTOR_ID       # list the repository entries

import os
from decision_engine import AlgentaClient

client = AlgentaClient(
    api_key=os.environ["ALGENTA_API_KEY"],
    base_url="https://api.algenta.ai",
)

connector = client.create_connector(
    name="payments-service",
    connector_type="github_repo",
    config={
        "repository_url": "https://github.com/acme/payments-service.git",
        "access_token": os.environ["GITHUB_TOKEN"],
    },
)

test = client.test_connector(connector.id)
assert test.success, test.message

browse = client.browse_connector(connector.id)
print(browse.total, "repository entries")

Troubleshooting

Test fails with error_type: "auth". The access_token is missing, expired, or lacks read access to a private repository. Refresh the token and confirm it can read the target repository.

Repository URL must be a http(s) clone URL. The repository_url is an SSH URL or uses an unsupported scheme. Use the HTTPS clone URL and add an access_token for private access.

repository source not found for local_repo or repo_archive. The path does not exist where the engine runs. On a self-hosted deployment, mount the checkout or archive so the engine process can read it.

Test fails with a privacy-policy or error_type: "permission" message. The git host is outside your deployment's egress allowlist. Confirm the host and that the destination is permitted by your deployment's egress policy. See Troubleshooting for the full diagnosis flow.

Next

Triage a repositoryConnectors overviewConnectors reference