Init Action

The Init Action is the foundation of all Quant Cloud GitHub workflows. It handles authentication, registry login, environment detection, and provides essential outputs for subsequent steps.

Repository: quantcdn/quant-cloud-init-action

What It Does

1. Validates credentials - Checks organization and API key
2. Authenticates Docker registry - Automatically logs you into Quant Cloud Image Registry
3. Detects environment - Determines environment name based on branch/tag
4. Checks existence - Verifies if app and environment already exist
5. Generates image tags - Provides image_suffix for consistent tagging

Always Use First

The Init Action should be the first Quant Cloud action in your workflow. It sets up everything needed for subsequent actions.

Inputs

Input	Required	Default	Description
quant_organization	Yes	-	Quant Cloud organization name
quant_api_key	Yes	-	Quant Cloud API key
quant_application	No	Repository name	Application name
master_branch_override	No	main and master	The one branch that maps to production
environment_name_override	No	Auto-detected	A fixed environment name. The image suffix becomes that name, and only tags count as production
base_url	No	https://dashboard.quantcdn.io	QuantGov: https://dash.quantgov.cloud (a trailing /api/v3 is also accepted)

Outputs

Output	Description	Example
project_exists	Whether app exists	true
environment_exists	Whether environment exists	false
quant_application	Determined app name	my-app
environment_name	Determined environment name	production
is_production	Is production environment	true
stripped_endpoint	Registry endpoint (no protocol), for image tags	<registry-host>
image_suffix	Image tag suffix with hyphen	-latest
image_suffix_clean	Image tag suffix without hyphen	latest

Environment Detection Logic

The action automatically determines environments based on Git context:

Branch/Tag	Environment	Image Suffix
main / master	production	-latest
develop	develop	-develop
feature/new-thing	feature-new-thing	-feature-new-thing
Pull Request #123	pr-123	-pr-123
Tag v1.0.0	production	-v1.0.0

Name Sanitization

Environment names are automatically sanitized to lowercase alphanumeric with hyphens only. Special characters (/, ., _) are converted to hyphens. Image suffixes keep dots (v1.0.0).

Pull request environments need the workflow to run on pull_request events: the Init Action reads the pull request number from the ref. See Pull request environments.

QuantGov

Set base_url: https://dash.quantgov.cloud on the Init Action and on every other Quant Cloud action. Without it, the action calls QuantCDN and fails with “Organization … does not exist or is not accessible”.

Basic Usage

- name: Initialize Quant Cloud
  uses: quantcdn/quant-cloud-init-action@v4
  id: init
  with:
    quant_organization: ${{ secrets.QUANT_ORGANIZATION }}
    quant_api_key: ${{ secrets.QUANT_API_KEY }}

# Docker is now automatically logged in
- name: Build and push
  run: |
    IMAGE=${{ steps.init.outputs.stripped_endpoint }}/${{ secrets.QUANT_ORGANIZATION }}/${{ steps.init.outputs.quant_application }}:app-${{ steps.init.outputs.image_suffix_clean }}
    docker build -t "$IMAGE" .
    docker push "$IMAGE"

The image path is <registry>/<organisation>/<application>:<service>-<suffix>. The tag must start with the compose service name (app here), or the environment cannot find the image.

With Custom Application Name

- uses: quantcdn/quant-cloud-init-action@v4
  id: init
  with:
    quant_organization: ${{ secrets.QUANT_ORGANIZATION }}
    quant_api_key: ${{ secrets.QUANT_API_KEY }}
    quant_application: my-custom-app

Using Image Suffix Output

The image_suffix output makes tagging consistent across your workflow:

- uses: quantcdn/quant-cloud-init-action@v4
  id: init
  with:
    quant_organization: ${{ secrets.QUANT_ORGANIZATION }}
    quant_api_key: ${{ secrets.QUANT_API_KEY }}

# Build multiple images with consistent tags
- name: Build web image
  uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
  with:
    push: true
    tags: ${{ steps.init.outputs.stripped_endpoint }}/${{ secrets.QUANT_ORGANIZATION }}/${{ steps.init.outputs.quant_application }}:web${{ steps.init.outputs.image_suffix }}

- name: Build worker image
  uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
  with:
    push: true
    tags: ${{ steps.init.outputs.stripped_endpoint }}/${{ secrets.QUANT_ORGANIZATION }}/${{ steps.init.outputs.quant_application }}:worker${{ steps.init.outputs.image_suffix }}

Conditional Steps Based on Outputs

Use outputs to control workflow behavior:

- uses: quantcdn/quant-cloud-init-action@v4
  id: init
  with:
    quant_organization: ${{ secrets.QUANT_ORGANIZATION }}
    quant_api_key: ${{ secrets.QUANT_API_KEY }}

# Create environment only if it doesn't exist
- name: Create environment
  if: steps.init.outputs.environment_exists == 'false'
  uses: quantcdn/quant-cloud-environment-action@v4
  with:
    operation: create
    environment_name: ${{ steps.init.outputs.environment_name }}

# Skip expensive operations for non-production
- name: Run full test suite
  if: steps.init.outputs.is_production == 'true'
  run: npm run test:all

Complete Example

name: Deploy to Quant Cloud

on:
  push:
    branches: [main, develop, 'feature/**']
    tags: ['v*']

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - name: Initialize Quant Cloud
        uses: quantcdn/quant-cloud-init-action@v4
        id: init
        with:
          quant_organization: ${{ secrets.QUANT_ORGANIZATION }}
          quant_api_key: ${{ secrets.QUANT_API_KEY }}

      # Docker login already handled by init!
      - name: Build and push image
        uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
        with:
          context: .
          push: true
          platforms: linux/arm64            # must match quant.architecture in the compose file
          tags: ${{ steps.init.outputs.stripped_endpoint }}/${{ secrets.QUANT_ORGANIZATION }}/${{ steps.init.outputs.quant_application }}:app-${{ steps.init.outputs.image_suffix_clean }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

      - name: Translate docker-compose.yml
        id: compose
        uses: quantcdn/quant-cloud-compose-action@v4
        with:
          api_key: ${{ secrets.QUANT_API_KEY }}
          organization: ${{ secrets.QUANT_ORGANIZATION }}
          compose_file: docker-compose.yml
          image_suffix: ${{ steps.init.outputs.image_suffix_clean }}

      - name: Create or update environment
        uses: quantcdn/quant-cloud-environment-action@v4
        with:
          api_key: ${{ secrets.QUANT_API_KEY }}
          organization: ${{ secrets.QUANT_ORGANIZATION }}
          app_name: ${{ steps.init.outputs.quant_application }}
          environment_name: ${{ steps.init.outputs.environment_name }}
          operation: ${{ steps.init.outputs.environment_exists == 'true' && 'update' || 'create' }}
          compose_spec: ${{ steps.compose.outputs.translated_compose }}

      - name: Redeploy existing environment
        if: steps.init.outputs.environment_exists == 'true'
        uses: quantcdn/quant-cloud-environment-state-action@v4
        with:
          api_key: ${{ secrets.QUANT_API_KEY }}
          organization: ${{ secrets.QUANT_ORGANIZATION }}
          application: ${{ steps.init.outputs.quant_application }}
          environment: ${{ steps.init.outputs.environment_name }}
          action: redeploy

On QuantGov, add base_url: https://dash.quantgov.cloud to every Quant Cloud step.

Error Handling

The action fails early with clear messages if:

• Organization doesn’t exist
• API key is invalid
• Registry credentials can’t be retrieved
• Docker login fails

Tips & Best Practices

1. Store in secrets - Always use repository secrets for quant_organization and quant_api_key
2. Reference by ID - Use id to reference outputs: steps.init.outputs.xxx
3. Check existence - Use environment_exists to decide create vs update
4. Use suffix everywhere - Apply image_suffix to all image tags for consistency
5. No manual login needed - Docker login is automatic, don’t add separate login steps

Next Steps

• Compose Action - Translate docker-compose files
• Environment Action - Create/update environments