source

The repository a declaration's code comes from, and what a push does.

A source is a repository and what a push to it does. A service, worker or job that names it in its build is rebuilt and redeployed from each push to the source's branch. Neither is infrastructure: together they are the repository connection the Deploy on push panel makes by hand, written in the file instead.

ackee.ack

ackee 1
project "shop" {
  cloud      = "gcp"
  region     = "us-east1"
  gcpProject = "acme-shop"
}
source "app" {
  repository = "acme/storefront"
  branch     = "main"
  deploy     = "plan"
}
# Runs the hello image until the first push is built.
service "web" {
  image  = "us-docker.pkg.dev/cloudrun/container/hello"
  public = true
  build  = { source = "app", image = "us-east1-docker.pkg.dev/acme-shop/apps/web:{sha}", root = "web" }
}
worker "mailer" {
  image = "us-docker.pkg.dev/cloudrun/container/hello"
  build = { source = "app", image = "us-east1-docker.pkg.dev/acme-shop/apps/mailer:{sha}", root = "mailer" }
}

source fields

Field	Takes	Meaning
repositoryrequired	string	The GitHub repository, as `"owner/name"`.
branch	string default "main"	The branch whose pushes deploy.
deploy	"plan" \| "apply" default "plan"	`plan`: each push builds and plans, and waits for approval. `apply`: a push whose plan only creates and changes deploys without waiting; one that replaces or destroys anything still waits. Needs a plan that includes auto-apply.

The build field

A service, worker or job — or a node of a compute type — takes a build map that says which source it builds from and how:

Field	Takes	Meaning
sourcerequired	string	The name of a `source` in the file.
imagerequired	string	Where each push's image goes and is deployed from. `{sha}` is replaced with the pushed commit, and is required when Ackee builds, so every deploy names exactly the commit it came from.
root	string default the repository's root	The directory to build in.
dockerfile	string default "Dockerfile"	The Dockerfile's name inside `root`, for the dockerfile method.
method	"auto" \| "dockerfile" \| "buildpacks" \| "railpack" \| "none" default "auto"	How the image is built. `auto` detects the stack and uses the repository's Dockerfile or writes one. `none` builds nothing: your own CI pushes the image, and a push deploys it.

The declaration's own image is what runs until the first push is built; from then on each push replaces it. build never becomes part of the declaration's configuration, so adding or removing it changes no resource.

Where builds run

Cloud	Builds in
Google Cloud	Cloud Build, in your project
Azure	ACR Tasks, in your subscription
AWS	Not yet: use `method = "none"` and have your CI push the image (AK212)

What applying the file does

Applying the file in the editor writes each build's repository connection — creating it, or updating the one the declaration already has. The editor lists what changed.
A push to the repository needs a webhook. If the connection already holds a GitHub token you gave it under Deploy on push, Ackee registers the webhook with it. Otherwise the editor shows the webhook URL and its secret — once — to add to the repository yourself. Applying a file never uses any other token.
A push never changes repository connections, even when the pushed file's build differs; the delivery says what differs, and applying the file from the editor updates them.

Removing build from a file does not disconnect the repository. Disconnect it under Deploy on push on the card.

Mistakes are reported at the build's line: an undeclared source (AK218), a build on something that runs no code (AK219), a built image without {sha} (AK302).