Integrations

Crow CI supports external secret store integrations, allowing you to fetch secrets directly from services like HashiCorp Vault or OpenBao during pipeline execution.

Overview

While Crow CI provides a built-in secret store using from_secret, integrations enable you to:

• Centralize secret management across your infrastructure
• Use existing secret rotation policies
• Leverage enterprise secret management features
• Access secrets without duplicating them in Crow CI

Supported Integrations

Type	Description
vault	HashiCorp Vault / OpenBao via AppRole authentication
azure_key_vault	Azure Key Vault via Service Principal authentication
infisical	Infisical via Universal Auth (Machine Identity)

Note

AppRole is HashiCorp Vault’s recommended authentication method for machine-to-machine scenarios. It uses a Role ID (like a username) and Secret ID (like a password) to authenticate applications securely.

Creating an Integration

1. Navigate to Integrations in the sidebar

2. Click Add integration

3. Configure the integration:

   • Name: A descriptive name for the integration
   • Type: Select the integration type (e.g., HashiCorp Vault)
   • Configuration: Provider-specific settings (see below)

4. Configure access control via allowlists (users, organizations, or repositories that can use this integration)

5. Click Save to create the integration

HashiCorp Vault / OpenBao Configuration

When configuring a Vault integration, provide the following settings:

Setting	Required	Description
Vault Address	Yes	Full URL to your Vault server
Role ID	Yes	AppRole Role ID for authentication
Secret ID	Yes	AppRole Secret ID for authentication
Auth Path	No	Mount path for AppRole auth (default: approle)
Mount Path	No	Secrets engine mount path (default: secret)
Namespace	No	Vault Enterprise namespace (leave empty for OSS)
Skip TLS Verify	No	Skip TLS certificate verification (not recommended for production)
CA Certificate	No	Custom CA certificate for TLS verification

AppRole Setup in Vault

To configure AppRole authentication in Vault:

# Enable AppRole auth method
vault auth enable approle

# Create a policy for Crow CI
vault policy write crow-ci - <<EOF
path "secret/data/crow/*" {
  capabilities = ["read"]
}
EOF

# Create an AppRole
vault write auth/approle/role/crow-ci \
  token_policies="crow-ci" \
  token_ttl=1h \
  token_max_ttl=4h

# Get the Role ID
vault read auth/approle/role/crow-ci/role-id

# Generate a Secret ID
vault write -f auth/approle/role/crow-ci/secret-id

Azure Key Vault Configuration

When configuring an Azure Key Vault integration, provide the following settings:

Setting	Required	Description
Vault URL	Yes	Full URL to your Key Vault (e.g., https://my-vault.vault.azure.net)
Tenant ID	Yes	Azure AD (Entra ID) Tenant ID
Client ID	Yes	Service Principal Application (Client) ID
Client Secret	Yes	Service Principal Client Secret

Azure Setup

To configure a Service Principal for Crow CI:

# Create a Service Principal
az ad sp create-for-rbac --name crow-ci --skip-assignment

# Note the appId (Client ID), password (Client Secret), and tenant (Tenant ID)

# Grant the Service Principal access to your Key Vault
az keyvault set-policy \
  --name my-vault \
  --spn <appId> \
  --secret-permissions get list

Alternatively, if using Azure RBAC for Key Vault access control, assign the Key Vault Secrets User role:

az role assignment create \
  --role "Key Vault Secrets User" \
  --assignee <appId> \
  --scope /subscriptions/<sub-id>/resourceGroups/<rg>/providers/Microsoft.KeyVault/vaults/<vault-name>

Azure Key Vault Secret Syntax

Azure Key Vault secrets are single-valued (each secret name maps to one value), unlike Vault’s key-value pairs. Use path for the secret name and set key to "value" by convention:

steps:
  - name: deploy
    image: alpine
    environment:
      DB_PASSWORD:
        from_secret:
          integration: "my-azure-kv"
          path: 'prod-db-password'    # Azure Key Vault secret name
          key: 'value'                # Convention for single-valued secrets

Note

Azure Key Vault version pinning is not currently supported. The latest version of the secret is always fetched.

Infisical Configuration

When configuring an Infisical integration, provide the following settings:

Setting	Required	Description
Site URL	Yes	Your Infisical instance URL (default: https://app.infisical.com)
Client ID	Yes	Machine Identity Client ID
Client Secret	Yes	Machine Identity Client Secret
Project ID	Yes	The Infisical project ID where secrets are stored
Environment	Yes	Environment slug (e.g., dev, staging, prod)
Secret Path	No	Folder path for secrets (default: /)

Infisical Setup

1. In Infisical, go to Organization Settings > Machine Identities and create a new identity

2. Under the identity, add Universal Auth and note the Client ID and Client Secret

3. Go to your Project Settings > Access Control > Machine Identities, add the identity, and assign the Viewer role (or a custom role with read access)

4. Note your Project ID from the project’s URL or settings page

Infisical Secret Syntax

Infisical secrets are scoped by project, environment, and path (configured in the integration). Use path for the secret key name and set key to "value" by convention:

steps:
  - name: deploy
    image: alpine
    environment:
      DB_PASSWORD:
        from_secret:
          integration: "infisical-prod"
          path: 'DATABASE_PASSWORD'   # Infisical secret key name
          key: 'value'                # Convention for single-valued secrets

Note

Create separate integrations for different project/environment combinations. For example, one integration for prod and another for staging.

Using External Secrets in Pipelines

Both internal (Crow CI) and external (Vault, Azure Key Vault, Infisical) secrets use the same from_secret keyword. The difference is in the value:

• String value = internal secret (from Crow CI’s secret store)
• Object value = external secret (from an integration like Vault)

Internal Secret (String)

steps:
  - name: deploy
    image: alpine
    environment:
      # Internal secret from Crow CI
      API_KEY:
        from_secret: my_api_key

External Secret (Object)

steps:
  - name: deploy
    image: alpine
    environment:
      # External secret from Vault
      API_KEY:
        from_secret:
          integration: 1              # Integration ID or name
          path: 'crow/myapp'
          key: 'api_key'

Syntax Reference

Field	Required	Description
integration	Yes	Integration ID (number) or name (string)
path	Yes	Secret path (Vault), secret name (Azure Key Vault), or key name (Infisical)
key	Yes	Key within the secret (Vault) or "value" (Azure Key Vault, Infisical)
version	No	Specific version to fetch (default: 0 = latest)

Using Integration by Name

You can reference integrations by their name for better readability:

steps:
  - name: deploy
    image: alpine
    environment:
      API_KEY:
        from_secret:
          integration: "vault-prod"   # Use integration name instead of ID
          path: 'crow/myapp'
          key: 'api_key'

Using in Plugin Settings

External secrets work in both environment and settings:

steps:
  - name: publish
    image: codefloe.com/crowci/buildx:latest
    settings:
      registry: registry.example.com
      repo: myorg/myapp
      tags: <your-tag>
      username: myuser
      password:
        from_secret:
          integration: 1
          path: 'crow/docker'
          key: 'password'

Access Control

Integrations use allowlists to control which pipelines can access secrets:

• User allowlist: Specific users who can use this integration
• Organization allowlist: All repositories in specified organizations
• Repository allowlist: Specific repositories

Caution

If no allowlist is configured, no pipelines can use the integration. You must explicitly allow at least one user, organization, or repository.

Mixing Internal and External Secrets

You can use both internal and external secrets in the same pipeline:

steps:
  - name: build
    image: alpine
    environment:
      # Internal secret from Crow CI (string value)
      INTERNAL_TOKEN:
        from_secret: my_token
      # External secret from Vault (object value)
      EXTERNAL_API_KEY:
        from_secret:
          integration: "vault-prod"
          path: 'crow/api'
          key: 'key'

Error Handling

External secret fetching uses strict error handling:

• If the external secret store is unreachable, the pipeline fails immediately
• If a secret path or key doesn’t exist, the pipeline fails with a clear error
• There are no silent fallbacks to prevent security issues

Note

External secrets are fetched once at pipeline start and cached for the duration of the pipeline execution. This minimizes API calls to your secret store.

Security Considerations

Tip

External secrets are automatically masked in log output, just like native secrets. Any occurrence of the secret value will be replaced with ********.

Best practices:

• Use dedicated AppRoles with minimal permissions
• Enable secret rotation in your Vault instance
• Limit integration access via allowlists
• Avoid logging secret values in pipeline output
• Use TLS and verify certificates in production

Testing Integrations

After creating an integration, use the Test Connection button to verify connectivity:

• Tests authentication (AppRole for Vault, Service Principal for Azure Key Vault, Universal Auth for Infisical)
• Verifies network connectivity to the secret store
• Does not access any actual secrets

A successful test shows “Connection test successful”.