Pipelines

Overview

Pipelines build and deploy your GitHub repository onto a connected Foster server. The panel creates a pipeline record; your server agent claims builds, clones the repo, builds an image with Kaniko, and replaces the pipeline’s container with a stable name.

Open Pipelines from the sidebar, or start from a repository under GitHub with the deploy wizard.

• Push-to-deploy via webhook (GitHub App or fine-grained PAT).
• Manual Run build from the pipeline page.
• Env from Credentials vault and/or inline pipeline secrets.
• Optional email + in-app notifications when builds finish.

Sources

Each pipeline uses one clone source:

GitHub App

• Pick a repo from your connected installation.
• Foster uses the App installation token to clone private and public repos you granted.
• Push events fan out to matching github_app pipelines for that repo and branch.

Fine-grained PAT

• Provide GitHub username, a fine-grained PAT (Contents: Read + Metadata), and the repo URL.
• The token is stored encrypted on the pipeline.
• You must add a repository webhook so pushes enqueue builds (see Webhooks).

Create a pipeline

From Pipelines

1. Open Pipelines → New pipeline.
2. Details: choose source, name, repo (or PAT fields), and branch.
3. Continue with Next: ENV Variables.
4. Paste or upload .env, optionally save via Credentials, then Create pipeline.

GitHub App creates usually enqueue a first build immediately. PAT creates show a webhook setup dialog first — confirm the hook, then continue to enqueue the first build so GitHub’s create-ping does not race a second build.

From GitHub deploy

Open a repo → configure stack → environment → finalize. Deploy creates a github_app pipeline on the active server and enqueues a build.

Environment & Credentials

Build and runtime env come from a Credentials vault entry and/or an encrypted map on the pipeline.

Save via Credentials (recommended)

• Check Save and use via Credentials and set a Credential ID (^[A-Z][A-Z0-9_]*$, e.g. MY_APP_PROD_ENV).
• Paste or upload .env content; edit parsed keys as needed.
• On create/deploy, Foster saves (or updates) an env credential and stores credential_key on the pipeline.
• At claim time the agent receives the resolved env map from the vault (plus any inline overrides).

Inline only

Uncheck Credentials to keep env only on the pipeline. Prefer the vault so restarts and rebuilds reuse the same secrets without re-pasting.

Autofill from the repo

When using the GitHub App, inspect may read a gitignored .env / .env.local / .env.example (first found) only to prefill the wizard. Prefer suggesting a vault id from fosterfile.json credential or FOSTER_ENV_CREDENTIAL in a local env file — never commit real env into the repo.

fosterfile.json

Commit fosterfile.json at the repository root so Foster can deploy without guessing stack, Dockerfile path, or credential linkage. Inspect prefers this file over heuristics.

Minimal example

{
  "stack": "dockerfile",
  "dockerfile": "Dockerfile",
  "context": ".",
  "port": 3000,
  "build_args": {},
  "credential": "MY_APP_PROD_ENV"
}

Fields

• stack (recommended) — Label or known stack (dockerfile, Node.js / Next.js, PHP / Laravel, …). Used when a Dockerfile is missing.
• dockerfile (recommended) — Path relative to repo root (default Dockerfile).
• context (recommended) — Build context directory (default .). Must not be absolute or contain ...
• port (optional) — Container listen port. Host mapping avoids privileged 80/443 by default.
• build_args (optional) — String map passed to Kaniko as --build-arg. Do not put secrets here; use Credentials for runtime env.
• credential (optional) — Vault credential id only (^[A-Z][A-Z0-9_]*$), e.g. MY_APP_PROD_ENV. Prefills deploy / create-pipeline. Values stay in the vault — never in git. Same idea as FOSTER_ENV_CREDENTIAL in a local .env (which must stay gitignored).
• runtime_version, build_command, start_command (optional) — Display aids in the deploy wizard; not required for Docker builds.

Detection order (inspect)

1. fosterfile.json
2. Root Dockerfile / docker-compose.yml
3. composer.json / package.json heuristics (agent may generate a thin Dockerfile at build time when needed)

Why commit it

• Stable Dockerfile/context across branches and teammates.
• Point the panel at a Credentials vault id with credential (id only — not keys or values).

Builds & deploy

Each run is a pipeline build with a status lifecycle:

• queued → claimed → clone / build / load / deploy → succeeded or failed (or cancelled).
• The agent respects server concurrency and resource pressure before claiming.
• Images are built with Kaniko; the running container uses a stable name (fp-pipe-…) so deploys replace the previous instance for that pipeline.
• Webhook builds are idempotent per commit SHA — retries do not spawn duplicate rows. Manual Run build always creates a new build.

Open a build for live logs. Cancel an active build from the pipeline or build page; the agent stops Kaniko when possible.

Webhooks

GitHub App

Push events to the installation are matched to enabled pipelines for that repository and branch. No per-repo webhook setup is required for App-sourced pipelines.

Fine-grained PAT

After creating a PAT pipeline, add a GitHub webhook on the repository:

• Payload URL — shown in the create dialog (pipeline webhook endpoint).
• Content type — application/json.
• Secret — the pipeline webhook secret from the dialog.
• Events — at least push.

GitHub’s automatic ping when you save the hook is acknowledged and does not enqueue a build. Real pushes (and your first manual continue after setup) start builds.

Pipeline controls

• Enabled — disabled pipelines do not accept new enqueues / webhook deploys.
• Notify — when on, successful and failed builds email you. Both must be on: the pipeline Notify toggle and Settings → Notification → Pipelines → Email.
• Run build — enqueue a manual build on the pipeline’s server.
• Delete — removes the pipeline and build history; running containers are not stopped automatically.

In-app alerts for pipeline create and build outcomes appear in the header notification inbox when Settings → Notification → Pipelines in-app is enabled.

Notes