Provider credentials

Provider credentials let Openship pull private images or update DNS. A credential belongs to one organization. Reads expose public fields and masked secret indicators; creating, changing, verifying, or removing a credential requires administration access.

Discover supported providers

Read provider definitions before building a credential form. Each definition includes its ID, capability, selector requirements, and field keys. Use those keys in the values object when creating a credential.

const providers = await ship.credentials.listProviders();
console.log(providers);

curl "$OPENSHIP_URL/api/credentials/providers" \
  -H "Authorization: Bearer $OPENSHIP_TOKEN"

Create or update a credential

Updates accept name, selector, and values. The provider cannot be changed. Use values from your credential form or secret store; masked values returned by reads are not replacement secrets.

Verify a saved credential

const credential = await ship.credentials.verify("cred_123");
console.log(credential.status, credential.lastError);

curl -X POST "$OPENSHIP_URL/api/credentials/cred_123/verify" \
  -H "Authorization: Bearer $OPENSHIP_TOKEN"

Verification returns the credential's status, lastVerifiedAt, and lastError. Check that status before using the credential for a deployment. See DNS providers for the DNS connection workflow.

Private HTTPS registries

Self-hosted Openship can verify registries on a private network. The registry certificate must match its hostname, and the Openship API process must trust its issuing CA. For an internal CA, mount the CA's PEM file into the API container and set NODE_EXTRA_CA_CERTS to that path. For example, add this to a Compose override alongside your installation's existing configuration:

services:
  api:
    environment:
      NODE_EXTRA_CA_CERTS: /etc/openship/registry-ca.pem
    volumes:
      - ./registry-ca.pem:/etc/openship/registry-ca.pem:ro

Recreate the API container with the override so the runtime loads the CA at startup. Docker daemons on servers that pull the images need their own registry CA configuration. Adding trust to the API does not configure those servers. Openship Cloud rejects private network registry targets.

Use the release's pinned Bun runtime, currently 1.3.14, when running the API under Bun. Bun 1.3.3 and 1.3.10 can reject a valid hostname certificate on Openship's pinned-IP HTTPS path. Bun 1.4.0 has an upstream regression in asynchronous WebSocket upgrades, which affects terminals. The API image, release runtime pin, and network regression tests use 1.3.14; Node 22 is also covered for development and desktop. Rebuild or update the API image to apply the runtime fix permanently.

Registry authentication realms are checked separately from TLS. Credentials are sent only to the registry's origin (scheme, hostname, and port) or the supported Docker Hub and GitLab.com authentication origins. For private GitLab on port 5050 advertising a token endpoint on port 443, expose the token endpoint through the registry origin and configure GitLab to advertise that URL. Trusting its CA or updating Bun does not authorize a different authentication origin.

Operations