Managed repository connections

Managed repository connections let administrators import extension bundles from private GitHub and Bitbucket repositories. The Control API authenticates to the repository, resolves the requested branch or tag to an immutable commit, and mirrors the archive into organization-scoped object storage. Repository credentials never appear in governance configuration or reach developer machines. Clients receive an artifact_id and SHA-256 digest, then use their existing harness session to request a short-lived object-storage download.

Repository archives can contain executable hooks, plugins, and helper binaries. Grant repository access only to reviewed namespaces and inspect the capability mappings before publishing a package.

Prerequisites

Before adding a connection, prepare:

A dedicated, non-expiring S3-compatible bucket for package artifacts.
The organization slug used by Blue, such as the control_api.bootstrap.organization_slug value for the bootstrap organization.
A read-only GitHub App or Bitbucket access token.
A mounted PEM CA bundle when an enterprise provider uses a private certificate authority.

The Compose stack creates the package-artifacts MinIO bucket automatically. Production deployments must create the bucket separately and set HARNESS_PACKAGE_BUCKET.

Configure artifact storage

Package artifacts must not use the raw-session bucket because session retention policies may delete objects still referenced by historical governance revisions.

blue.yaml

control_api:
  package_artifacts:
    bucket: os.environ/HARNESS_PACKAGE_BUCKET

Compose fixes the package-artifact bucket name in deploy/docker-compose.yml; setting HARNESS_PACKAGE_BUCKET in deploy/.env does not override it. Change the Compose service environment explicitly when you need another bucket. The Control API uses the same S3 endpoint, region, public endpoint, path-style setting, and ambient AWS credentials configured under control_api.blob_storage.

Configure a provider

Add connections under control_api.package_sources.connections. Connection IDs must contain only letters, numbers, hyphens, and underscores. Each organization entry maps a Blue organization slug to the repository namespaces it may import.

GitHub.com
GitHub Enterprise
Bitbucket Cloud
Bitbucket Data Center

Create a GitHub App, grant it read-only Contents permission, and install it on the target organization or account. Select only the repositories Blue should import.

blue.yaml

control_api:
  package_sources:
    connections:
      - id: github-com
        name: GitHub
        provider: github
        app_id: os.environ/HARNESS_GITHUB_APP_ID
        private_key: file:///run/secrets/github-app-private-key.pem
        organizations:
          dev:
            - BlocksOrg

app_id is the GitHub App ID, not the OAuth client ID. Blue creates a repository-scoped installation token when an administrator inspects a source.

Register and install a GitHub App on the Enterprise Server instance. Set api_base_url to the REST API root, normally /api/v3.

blue.yaml

control_api:
  package_sources:
    connections:
      - id: corporate-github
        name: Corporate GitHub
        provider: github
        api_base_url: https://github.example.com/api/v3
        app_id: os.environ/HARNESS_GHES_APP_ID
        private_key: file:///run/secrets/ghes-app-private-key.pem
        ca_bundle: file:///run/secrets/corporate-ca.pem
        download_hosts:
          - github-assets.example.com
        organizations:
          dev:
            - platform-engineering

Add a hostname to download_hosts only when the configured server redirects archive downloads to that trusted hostname. Same-host downloads require no entry.

Create a repository, project, or workspace access token with read-only repository permission. Prefer the narrowest token that covers the approved repositories.

blue.yaml

control_api:
  package_sources:
    connections:
      - id: bitbucket-cloud
        name: Bitbucket Cloud
        provider: bitbucket_cloud
        token: os.environ/HARNESS_BITBUCKET_TOKEN
        organizations:
          dev:
            - product-engineering

Namespace entries are Bitbucket workspace slugs. Blue sends the access token as a Bearer token and resolves refs through the Bitbucket Cloud API.

Create a read-only HTTP access token for the repository or project. Set api_base_url to the instance root, including any deployment context path.

blue.yaml

control_api:
  package_sources:
    connections:
      - id: corporate-bitbucket
        name: Corporate Bitbucket
        provider: bitbucket_data_center
        api_base_url: https://bitbucket.example.com/bitbucket
        token: os.environ/HARNESS_BITBUCKET_DC_TOKEN
        ca_bundle: file:///run/secrets/corporate-ca.pem
        download_hosts:
          - bitbucket-assets.example.com
        organizations:
          dev:
            - PLATFORM

Namespace entries are Bitbucket project keys. Archive access requires at least repository read permission.

Supply deployment secrets

Environment references use os.environ/NAME or env://NAME. File references use file:///absolute/path. Keep private keys and tokens outside the repository. For Compose, add the environment variables and read-only secret mounts to the Control API service:

docker-compose.override.yml

services:
  control-api:
    environment:
      HARNESS_GITHUB_APP_ID: "123456"
      HARNESS_BITBUCKET_TOKEN: ${HARNESS_BITBUCKET_TOKEN}
    volumes:
      - ./secrets/github-app-private-key.pem:/run/secrets/github-app-private-key.pem:ro
      - ./secrets/corporate-ca.pem:/run/secrets/corporate-ca.pem:ro

Connection secrets and referenced files are loaded when the Control API starts. Restart the service after rotating a key, token, URL reference, or CA bundle. Already mirrored artifacts remain installable after provider credentials change.

Control organization access

The organizations map is an authorization boundary, not a display filter. The Control API rejects a namespace before contacting the provider when it is not allowed for the authenticated administrator’s organization.

organizations:
  dev:
    - BlocksOrg
    - blocks-internal
  security:
    - security-engineering

Namespace comparisons are case-insensitive. A "*" entry permits every namespace accessible to the connection credential and should be reserved for single-organization deployments with an equivalent trust boundary.

Start and verify the connection

Restart the Control API

Rebuild or restart the service after changing the server configuration or secrets.

(cd deploy && docker compose up -d --build control-api dashboard)

Check startup health

Confirm the service starts without secret, URL, CA, database migration, or object-storage errors.

(cd deploy && docker compose logs --tail=100 control-api)
curl -fsS http://127.0.0.1:8080/health

Inspect a repository

Open Extensions, select Add extension, then choose Managed repository. Select the connection, enter namespace/repository and a branch, tag, or commit, and select Inspect source.

Confirm immutable metadata

Verify that the form shows a resolved commit, archive size, and SHA-256 digest. Add the capability mappings and publish the pending governance revision.

Verify client installation

Run blue apply or launch an allowed harness. The client requests a fresh download with its harness session, verifies the digest, and installs the compatible package contents.

Configuration fields

Field	Required	Description
`id`	Yes	Stable connection identifier shown in artifact provenance.
`name`	No	Dashboard label; defaults to `id`.
`provider`	Yes	`github`, `bitbucket_cloud`, or `bitbucket_data_center`.
`app_id`	GitHub	GitHub App ID or environment/file reference.
`private_key`	GitHub	RSA private key generated for the GitHub App.
`token`	Bitbucket	Read-only repository, project, or workspace access token.
`api_base_url`	Enterprise	GitHub REST API root or Bitbucket Data Center instance root.
`web_base_url`	Optional	Bitbucket Cloud web origin override; omit for `bitbucket.org`.
`ca_bundle`	Optional	PEM CA bundle or secret reference for a private enterprise CA.
`download_hosts`	Optional	Additional trusted cross-host archive redirect destinations.
`organizations`	Yes	Blue organization slugs mapped to allowed repository namespaces.

Troubleshooting

Symptom	Resolution
No managed repository connections appear	Confirm the signed-in organization slug has an entry under `organizations`, then restart the Control API.
Namespace is not allowed	Add the exact GitHub owner, Bitbucket workspace, or Bitbucket project key to that organization’s allowlist.
GitHub App cannot access the repository	Confirm the App is installed on the owner, the repository is selected, and Contents permission is read-only or greater.
Ref resolution returns `401` or `403`	Rotate the Bitbucket token or verify the GitHub App installation and provider permissions.
Archive redirects to an untrusted host	Verify the provider’s archive hostname, then add only that trusted hostname to `download_hosts`.
Provider CA bundle is invalid	Mount a PEM bundle readable by the Control API and check the `file://` path.
Archive exceeds 100 MiB	Remove unrelated repository content or publish a smaller purpose-built extension archive.
Client cannot install a new artifact offline	Restore access to the Control API for the first download. Digest-cached packages continue to work offline.

See Managed packages for capability mapping and client installation behavior, and Production deployment for storage and secret-management requirements.

Start here

Deployment

Concepts

CLI

Administration

Development

Reference

API reference

Managed repository connections

Prerequisites

Configure artifact storage

Configure a provider

Supply deployment secrets

Control organization access

Start and verify the connection

Configuration fields

Troubleshooting

​Prerequisites

​Configure artifact storage

​Configure a provider

​Supply deployment secrets

​Control organization access

​Start and verify the connection

​Configuration fields

​Troubleshooting

Prerequisites

Configure artifact storage

Configure a provider

Supply deployment secrets

Control organization access

Start and verify the connection

Configuration fields

Troubleshooting