Automated deployments

Automated deployments let an external build or release process tell DeployCrate to deploy a specific version into a specific environment. Use them after a successful manual deployment. The manual path confirms that the server, source credentials, environment targets, ports, secrets, and domain routing are already correct.

DeployCrate automation is environment-scoped. A staging deployment endpoint deploys to staging only. A production deployment endpoint deploys to production only. This keeps promotion explicit: build once, deploy to staging, verify, then trigger production with the same version.

Manual deployment path

A deployment resolves an artifact, creates a release record, sends a deployment request to each target server's operator, and records status as the operator reports progress.

For binary applications, the artifact is a release asset URL or direct URL. For Docker applications, the artifact is an image and tag plus optional registry credentials.

Run at least one manual deployment before wiring automation. That first deploy proves:

• the environment has one or more server targets
• DeployCrate can resolve the selected binary or image
• private GitHub, Docker Hub, or GHCR credentials work
• ports and deployment strategy are valid
• the application starts successfully on the server
• the domain points to the right server

Deployment endpoints

Each environment has a deployment endpoint URL and deployment endpoint secret. The endpoint URL is the API address your build system calls. The endpoint secret is sent as a bearer token so DeployCrate can reject unauthenticated triggers.

The endpoint is:

POST /api/v1/environments/:id/deployments

Use the full deployment endpoint URL shown in the environment page. Send the environment's deployment endpoint secret in the Authorization header:

Authorization: Bearer <deployment-endpoint-secret>

The request body identifies the version to deploy. For Docker images, send the image tag as source_version:

{
  "source_version": "v1.0.0"
}

For binary applications backed by GitHub Releases, send the release version and the release asset name:

{
  "source_version": "v1.0.0",
  "source_name": "my-app-linux-amd64"
}

DeployCrate returns 202 Accepted when the trigger is accepted. The response includes a status_url that can be polled by the calling system.

GitHub Actions setup

In GitHub Actions, store the deployment endpoint details as repository or environment secrets:

For a Docker application, a minimal workflow builds and pushes an image, then asks DeployCrate to deploy the same tag:

name: Deploy

on:
  push:
    tags:
      - "v*"

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4

      - name: Log in to GHCR
        run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u "${{ github.actor }}" --password-stdin

      - name: Build and push image
        run: |
          IMAGE="ghcr.io/${{ github.repository }}"
          TAG="${{ github.ref_name }}"
          docker build -t "$IMAGE:$TAG" .
          docker push "$IMAGE:$TAG"

      - name: Deploy staging
        run: |
          curl -fsS -X POST "${{ secrets.DEPLOYCRATE_STAGING_DEPLOY_URL }}" \
            -H "Content-Type: application/json" \
            -H "Authorization: Bearer ${{ secrets.DEPLOYCRATE_STAGING_DEPLOY_SECRET }}" \
            -d "{\"source_version\":\"${{ github.ref_name }}\"}"

For a binary application, publish a GitHub Release asset first, then trigger DeployCrate with the release tag and asset name:

- name: Deploy staging binary
  run: |
    curl -fsS -X POST "${{ secrets.DEPLOYCRATE_STAGING_DEPLOY_URL }}" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer ${{ secrets.DEPLOYCRATE_STAGING_DEPLOY_SECRET }}" \
      -d "{\"source_version\":\"${{ github.ref_name }}\",\"source_name\":\"my-app-linux-amd64\"}"

Use GitHub environments if you want a manual approval gate before production. In that setup, the staging job can run automatically on a tag, while the production job uses the production deployment endpoint only after approval.

GitHub releases

For GitHub Releases, DeployCrate uses the configured GitHub credential to resolve release assets from the selected repository. Use this when your build system publishes versioned binaries as release assets.

The source_version should match the release tag, such as v1.0.0. The source_name should match the asset DeployCrate should download from that release. If a release contains multiple assets, be precise: api-linux-amd64 and api-linux-arm64 are different deployable binaries.

Container image releases

For Docker images, DeployCrate deploys an image tag. Private Docker Hub and GHCR sources require credentials. Public images do not.

The source_version should be the tag to deploy. Prefer immutable tags for automated deployments. A Git tag like v1.0.0 or a commit SHA is easier to audit than repeatedly deploying latest.

For private images, make sure the DeployCrate Docker credential can pull the image from the target registry. The GitHub Actions credential that pushes an image and the DeployCrate credential that pulls it are separate pieces of access.

Deployment strategies

DeployCrate currently exposes immediate and blue/green strategies in the application setup flow.

The deployment endpoint does not choose the deployment strategy. It uses the strategy configured on the target environment. If staging is immediate and production is blue/green, the same version can be deployed through both endpoints while each environment keeps its own behavior.

Rollout behavior is also read from the environment. With all-at-once rollout, DeployCrate sends the deployment to every server target in that environment during the same operation.

Status and polling

The deployment endpoint returns a status URL when the deployment is accepted. A CI job can print that URL for debugging or poll it until the deployment finishes.

The status response includes the release status, source version, target counts, and per-target deployment statuses. Use it when you want CI to fail if DeployCrate accepts the trigger but the deployment later fails on a server target.

Failure handling

If a deployment fails, inspect the release status and operator response. Common causes are missing environment targets, missing source credentials, invalid artifact selection, unavailable registry credentials, or application health/startup failure on the target server.

For automated deployments, also check:

• the deployment endpoint URL points to the intended environment
• the bearer token matches that environment's deployment endpoint secret
• source_version matches an existing release tag or image tag
• binary deployments include the correct source_name
• the pushed image is available before the deployment endpoint is called
• production approval gates are not accidentally skipped in CI

Keep staging and production deployment endpoint secrets separate. A staging workflow should not have access to the production endpoint unless that workflow is intentionally allowed to promote releases.