build

How an application becomes an image: the method that builds it, the directory the build runs in, the command that starts it, and which file changes are worth a build at all.

Changing any of this rebuilds nothing on its own. The running application keeps the image it already has until the next build, which --deploy starts. That is a longer wait than an environment variable change, which needs only a deployment rather than a build.

build get

Show how an application is built.

Usage

outplane build get [flags]

Flags

The global flags apply as well.

Output

Examples

Show the linked application's build settings

outplane build get

Show another application's

outplane build get --app checkout

Read one setting in a script

outplane build get --json --fields buildMethod,directory

{
  "buildMethod": "dockerfile",
  "directory": "/api"
}

What to Know

• source decides which fields mean anything. A container-registry application has an image and a start command; its buildMethod is prebuilt-image and its directory and filters are null and cannot be set.
• Both filters are one string with a pattern per line, which is how the platform stores them. build set takes them as a repeatable flag instead.
• An empty filter means every push builds. It is null rather than an empty string.

Errors

Beyond 0 for success, this command exits with:

The code on the error object is one of context.no_app, app.not_found. Branch on that, or on the exit status. The message is prose and changes.

build set

Change how an application is built.

Usage

outplane build set [flags]

Flags

The global flags apply as well.

Output

Examples

Build with buildpacks instead of a Dockerfile

outplane build set --method buildpack

Build only when the API directory changes

outplane build set --include-paths 'api/**' --include-paths package.json

Remove the start command

outplane build set --start-command ""

See what would be written, without writing it

outplane build set --dir /api --dry-run --json

{
  "buildMethod": "dockerfile",
  "changed": false,
  "directory": "/api",
  "source": "repository",
  "startCommand": "node server.js"
}

Move a registry application to a new image tag, and deploy it

outplane build set --image ghcr.io/acme/api:1.4.2 --app checkout --deploy

What to Know

• A flag that is not given keeps its current value. The endpoint writes every field it is given, so this command reads the current settings and sends them back with the change applied; two callers changing different settings at the same time can therefore lose one of the changes.
• An empty value clears, for the start command and both filters. --dir cannot be emptied and returns build.directory_required; --dir / is how to build from the repository root.
• A container-registry application refuses --method, --dir and the filters with build.not_built_here, and a repository application refuses --image with build.not_an_image. Neither is sent, because the server would ignore them in silence.
• The filters are a repeatable flag here and one newline-separated string in the result, which is how the platform stores them.
• Nothing rebuilds on its own. Without --deploy the running application keeps the image it was built from, which is a longer wait than an environment variable: the change takes effect only after a build, not after a restart.
• Calling this twice with the same flags leaves the same state, so a retry after a timeout is safe.

Errors

Beyond 0 for success, this command exits with:

The code on the error object is one of build.method_invalid, build.directory_required, build.image_required, build.filter_too_long, build.not_built_here, build.not_an_image, usage.no_change, context.no_app, app.not_found. Branch on that, or on the exit status. The message is prose and changes.

Related