CI pipelines

This guide walks through wiring the Facets CLI (raptor) into a CI job that builds a container image, pushes it to a registry, registers it with Facets, and (optionally) triggers a release.

Prerequisites

• raptor installed on the CI runner. See Installation or Facets-cloud/raptor-releases.
• A Facets project with a container registry configured (see Container registries).
• A personal API token from the Control Plane (Account Settings → Personal Token).

Step 1: Authenticate

Set three environment variables in your CI job's secret store:

export FACETS_USERNAME=<your-username>
export FACETS_TOKEN=<your-api-token>
export CONTROL_PLANE_URL=<your-control-plane-url>

All raptor commands pick these up automatically. No explicit login step is needed in CI.

Step 2: Authenticate Docker against the project's registry

raptor fetches short-lived credentials for the registry configured in your project and runs docker login for you:

raptor get registries -p <project>
raptor get registry-credentials <registry-name> -p <project>

Use the --docker-config flag instead if your CI benefits from a docker config.json file rather than an inline login.

Step 3: Build and push the image

Standard Docker workflow against the URI shown in Step 2:

docker build -t <registry-uri>/<image>:<tag> .
docker push <registry-uri>/<image>:<tag>

Step 4: Register the image with Facets

Register the pushed image to an environment, git ref, or release stream so blueprints can resolve it:

# By environment
raptor set artifact-uri <artifact-name> -p <project> -e <env> \
  --uri <registry-uri>/<image>:<tag> \
  --external-id "${CI_RUN_ID}"

# By git ref
raptor set artifact-uri <artifact-name> -p <project> --git-ref <branch> \
  --uri <registry-uri>/<image>:<tag>

# By release stream
raptor set artifact-uri <artifact-name> -p <project> --release-stream <stream> \
  --uri <registry-uri>/<image>:<tag>

If the artifact does not exist yet, create it once:

raptor create artifact -p <project> <artifact-name>

For zip-file artifacts (AWS Lambda, Azure Functions, etc.), use raptor set artifact-zip instead. See Attach image for how artifacts attach to services in the blueprint, and run raptor set artifact-uri --help / raptor set artifact-zip --help for the full flag set.

Step 5: Trigger a release (optional)

Only deploy from CI if your workflow requires it. Use --target so the release deploys only the services affected by the image you just pushed, not the entire environment:

raptor create release -p <project> -e <env> \
  --target service/<artifact-name> \
  -w

-w tails release logs to completion so the CI job fails if the release fails.

Reference

For full command syntax and flag detail, see Facets-cloud/raptor-releases or run raptor <command> --help.