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

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

Using External Secrets in Pipelines

Both internal (Crow CI) and external (Vault) 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	Path to the secret in Vault (without the secret/data/ prefix)
key	Yes	Key within the secret to retrieve
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: codeberg.org/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 AppRole authentication
• Verifies network connectivity to Vault
• Does not access any actual secrets

A successful test shows “Connection test successful”.