Configuring a Custom Action Server

Custom Actions with DeployHQ

Custom Actions allow you to run arbitrary commands inside Docker containers as part of your deployment pipeline. Instead of transferring files to a remote server, DeployHQ pulls a Docker image, uploads your repository source code into the container, and executes your commands.

This is useful for deployments that rely on CLI tools such as the AWS CLI, Terraform, kubectl, or any custom toolchain packaged in a Docker image.

Note: This feature is currently in beta. To use Custom Actions, you must first enable beta features in your account settings.

Prerequisites:

• Beta Features Enabled: Custom Action requires beta features to be enabled in your account
• Commands: At least one command to execute inside the container

How It Works

When a deployment runs with a Custom Action server, DeployHQ:

1. Checks out your repository at the target revision
2. Uploads the source code to the build server
3. Pulls the configured Docker image
4. Injects any configuration files (if enabled)
5. Runs each command sequentially inside the container, with your source code mounted at /data
6. Records the deployment result

Your commands run with the working directory set to /data, where your full repository is available.

Choosing an Image Source

Custom Actions support two image sources:

Curated Templates

Select from pre-configured templates for common tools. Each template provides a recommended Docker image and example commands to get you started.

Custom Image

Enter any public or private Docker image reference. This supports:

• Simple images: alpine:latest, ubuntu:22.04
• Namespaced images: myorg/mytool:v1.0
• Private registries: registry.example.com:5000/team/app:1.0

The image must be accessible from the DeployHQ build server. For private registries, ensure the build server can authenticate and pull the image.

Step-by-Step Configuration

1. Select Protocol: Navigate to your server settings within DeployHQ and select Custom Action as your server's protocol.

2. Choose Image Source: Select either Curated Template or Custom Image.

• For curated templates, select the template from the dropdown. The Docker image is set automatically.
• For custom images, enter the full Docker image reference (e.g., myorg/mytool:v2.0).

1. Enter Commands: Add the commands to run inside the container, one per line. Commands execute sequentially in the order listed.

   cd /data
   npm ci
   npm run deploy

1. Configure Error Handling: Choose whether to halt the deployment if a command fails.

• Halt on error (default): The deployment stops immediately if any command returns a non-zero exit code.
• Continue on error: All commands run regardless of individual failures. Failed commands are logged but do not stop the deployment.

1. Click Create Server to save your configuration.

Environment Variables

Custom Actions automatically set the following environment variables in the container:

Any environment variables you configure on the server are also exported and available to your commands.

Configuration Files

If your project uses configuration files, you can enable Copy configuration files on the deployment. Config files are injected into the container at their configured paths relative to /data before your commands run.

Text Variables

Custom Action commands support DeployHQ text variables for dynamic values. You can use placeholders like %branch%, %revision%, and other variables in your commands.

Example Use Cases

Deploy to AWS S3

Using the AWS CLI template:

aws s3 sync /data/ s3://my-bucket/ --delete --exclude ".git/*"

Set your AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY as environment variables on the server.

Apply Kubernetes Manifests

Using the Kubernetes template:

kubectl apply -f /data/k8s/
kubectl rollout status deployment/my-app -n production

Store your kubeconfig content in an environment variable or configuration file.

Run Terraform

Using the Terraform template:

cd /data/infrastructure
terraform init
terraform plan -out=tfplan
terraform apply tfplan

Custom Build and Deploy Script

Using a custom Node.js image:

cd /data
npm ci
npm run build
npm run deploy:production

Run Database Migrations

Using a custom image with your runtime:

cd /data
bundle install
RAILS_ENV=production bundle exec rails db:migrate

Timeout Limits

Custom Action deployments have a 30-minute overall timeout that covers the entire process, including source upload, image pull, configuration, and command execution. Each individual command also has a 30-minute timeout. When running multiple commands, the overall timeout is the effective limit since all steps share the same 30-minute window.

Tutorial Guides

For detailed, step-by-step tutorials on specific Custom Action use cases, see the following guides:

• Deploy Infrastructure with Terraform - Manage infrastructure as code with Terraform on AWS, GCP, or Azure
• Deploy with AWS CloudFormation - Create and update AWS CloudFormation stacks
• Deploy to Kubernetes with kubectl - Apply manifests and manage rollouts on Kubernetes clusters
• Deploy to Google Cloud with gcloud - Deploy to App Engine, Cloud Run, GKE, and other GCP services

Troubleshooting

Image Pull Fails:

• Verify the Docker image name is correct and the tag exists
• For private registries, ensure the image is accessible from the DeployHQ build server
• Check that the registry hostname and port are correct

Command Fails:

• Review the deployment log for the specific error output
• Verify your commands work locally in the same Docker image: docker run --rm -v $(pwd):/data -w /data IMAGE_NAME bash -c "YOUR_COMMAND"
• Check that required environment variables are configured on the server

Source Code Not Found:

• Your repository is mounted at /data inside the container
• Ensure your commands reference files relative to /data

Permission Issues:

• Commands must not use sudo - containers run with appropriate permissions
• If a command requires specific permissions, use a Docker image that has them pre-configured

Build Server Connection Error:

• The build server may be temporarily unavailable. Try the deployment again after a few minutes.
• If the issue persists, contact DeployHQ support.