Workflow

Build from GitHub

Fetch a repository branch, build its Dockerfile locally, and start the resulting project container.

Overview

The GitHub workflow allows you to define a project that starts from source code. Dock fetches the branch and delegates the build to your local Docker installation.

Prerequisites

Git installed and accessible on your path.
Docker CLI & running Docker Engine on your machine.

1. Configure dock.yaml

Specify application.source with type: github and the repository in owner/repository format:

dock.yaml

name: hello-api

system:
  packages:
    - git

docker:
  enabled: true

application:
  source:
    type: github
    repository: owner/repository
    branch: main
  docker:
    dockerfile: Dockerfile
  ports:
    - host: 8000
      container: 8000
  healthcheck:
    type: http
    path: /
    port: 8000

Configuration Requirements

type: github must be explicitly specified.
repository must be formatted as owner/repository (e.g. my-org/my-api), not a full URL.
branch specifies the branch to pull (e.g. main).
docker.dockerfile specifies the Dockerfile filename in the repo root.

2. Build and Initialization Steps

Run the lifecycle workflow:

terminal

$ dock validate -c ./dock.yaml
✓ dock.yaml is valid

$ dock plan -c ./dock.yaml
Plan (hello-api):
  - Fetch github: owner/repository (branch: main)
  - Build local image with Dockerfile
  - Bind port: host 8000 -> container 8000
  - HTTP health check on port 8000

$ dock sync -c ./dock.yaml
(Read-only state comparison: git satisfied, image build pending, container pending)

$ dock init -c ./dock.yaml
✓ Cloning owner/repository (main)...
✓ Running docker build -t dock-hello-api .
✓ Container created and started
✓ HTTP health check passed (http://localhost:8000/health)

$ dock status --running -c ./dock.yaml
Project: hello-api
Status: Up (Healthy)
Containers (Running):
  - dock-hello-api (Up 1m, Ports: 0.0.0.0:8000->8000/tcp)