Pipeline configuration

How gittan detects your project type and how to customize with .gittan.yaml.

Automatic detection

gittan inspects your repo on every push and builds a pipeline based on the files it finds. A repo with package.json gets Node steps. A repo with Dockerfile gets a container build and publish. A repo with Pulumi.yaml gets infrastructure deployment.

Detection is additive — a repo with both package.json and Dockerfile gets Node steps followed by a container publish.

The .gittan.yaml file

For most repos, automatic detection is enough. When you need control, add a .gittan.yaml at the repo root.

steps:
  - name: install
    image: node:22-slim
    run: pnpm install --frozen-lockfile

  - name: test
    run: pnpm test
    needs: [install]

  - name: build
    run: pnpm build
    needs: [install]

  - name: publish
    run: pnpm publish
    needs: [test, build]
    only: main

Step fields

Field	Description
name	Step identifier. Must be unique within the pipeline.
image	Container image. Defaults to the detected project image if omitted.
run	Shell command to execute.
needs	List of step names that must pass before this step runs.
only	Only run on this branch. Commonly `main` for publish/deploy steps.
env	Environment variables. Use `${{ secrets.NAME }}` for secrets.
secrets	Secret names this step needs. Resolved from repo → team → org scope.
cache	Paths to cache between pipeline runs (e.g. `node_modules`).
timeout	Max duration for the step. Default: `10m`.

See the Pipeline YAML reference for the full list of step fields.

Parallel execution

Steps without dependencies run in parallel. Steps with needs wait for their dependencies. The pipeline is a DAG — gittan resolves the execution order automatically.

Publish overrides: .gittan.config.yaml

For repos that publish container images, a separate .gittan.config.yaml in the repo root overrides publish-step defaults. This is not the same file as .gittan.yaml — it controls image publishing, not pipeline steps.

image: my-custom-image-name
platform: linux/arm64

Field	Description
image	Override the published image name. Default: the repo name.
platform	Target platform for Docker builds (e.g. `linux/arm64`). Default: runner's native platform.

Cache behavior

The cache field on a step lists paths to persist between pipeline runs. Some paths are shared across all repos in the org (package manager stores), while others are scoped to the individual repo.

Org-wide (shared across repos):

Cache path	Mount point
.pnpm-store	/root/.local/share/pnpm/store
.npm	/root/.npm
.cache/pip	/root/.cache/pip
.cache/uv	/root/.cache/uv

All other cache paths (e.g. node_modules) are repo-scoped — different repos do not share them. Caches are mounted on every step in the pipeline, not just the declaring step, so downstream steps can access cached content.

Node.js: corepack and tooling

For steps using a Node.js image, gittan automatically enables corepack so that pnpm and yarn work out of the box. You do not need to add corepack enable to your pipeline steps — it runs once when the base container is prepared and the result is cached across steps.

Interaction with policies

Org-level policies can inject steps before or after your pipeline. These are mandatory — teams cannot skip them. Your .gittan.yaml controls your steps; policies control the org's guardrails.