helpers¶
Functions that return groups of steps.
Scripts are programs: repeated shapes become functions, and a "template" is a function that returns steps.
flowchart LR
s0["ui lint"]
s1["ui test"]
s2["ui build"]
s3["api lint"]
s4["api test"]
s5["api build"]
s0 --> s2
s1 --> s2
s3 --> s5
s4 --> s5The steps this script plans for a push about which nothing is known. An arrow is a needs.
# Scripts are programs: repeated shapes become functions, and a "template" is
# a function that returns steps.
def lint_test_build(name, image, directory, lint, test, build):
"""The usual three steps for one component, chained."""
common = dict(image = image, inputs = [directory])
in_dir = "cd {} && ".format(directory)
lint_step = step(name + " lint", run = in_dir + lint, **common)
test_step = step(name + " test", run = in_dir + test, **common)
build_step = step(name + " build", run = in_dir + build, needs = [lint_step, test_step], **common)
return [lint_step, test_step, build_step]
def ci(ctx):
components = {
"ui": lint_test_build("ui", "node:22-bookworm-slim", "ui", "npm ci && npm run lint", "npm ci && npm test", "npm ci && npm run build"),
"api": lint_test_build("api", "python:3.13-slim", "api", "pip install ruff && ruff check .", "pip install -e . && pytest -q", "pip install build && python -m build"),
}
# Keep the components this commit touched; all of them if it is not known.
wanted = [name for name in components if name in ctx.changed_dirs] or list(components)
steps = []
for name in wanted:
steps += components[name]
return steps
# Generated by `starci compile` from helpers.ci.star. Edit that, not this.
#
# Each job is one step of the plan: the same image, command, tools and
# packages, given only the step's inputs. A job skips its work when it has
# already passed with the same inputs.
#
# What does not carry over:
# - The script decides by which files a commit changed. A workflow file
# cannot, so it does what the script does when nothing is known about the
# changes, on every run.
# - Passes are remembered in this repository's Actions cache, which GitHub
# scopes by branch and evicts when old. starci's own store has neither
# limit.
name: CI
on:
push:
branches: ['**']
tags: ['**']
pull_request:
workflow_dispatch:
jobs:
ui-lint:
name: "ui lint"
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
sparse-checkout-cone-mode: false
sparse-checkout: |
/ui
- name: Has this already passed with these inputs?
id: passed
uses: actions/cache@v4
with:
path: ${{ runner.temp }}/starci-passed
key: starci-passed-ui-lint-c037eb6d9c922cc2-${{ hashFiles('ui', 'ui/**') }}
- name: "ui lint"
if: steps.passed.outputs.cache-hit != 'true'
env:
STARCI_RUN: |-
cd ui && npm ci && npm run lint
run: |
docker run --rm \
-v "$PWD:/workspace" \
-w /workspace \
node:22-bookworm-slim sh -c "$STARCI_RUN"
- name: Remember this pass
if: steps.passed.outputs.cache-hit != 'true'
run: mkdir -p "$RUNNER_TEMP/starci-passed" && date > "$RUNNER_TEMP/starci-passed/at"
ui-test:
name: "ui test"
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
sparse-checkout-cone-mode: false
sparse-checkout: |
/ui
- name: Has this already passed with these inputs?
id: passed
uses: actions/cache@v4
with:
path: ${{ runner.temp }}/starci-passed
key: starci-passed-ui-test-0118b2623beebd99-${{ hashFiles('ui', 'ui/**') }}
- name: "ui test"
if: steps.passed.outputs.cache-hit != 'true'
env:
STARCI_RUN: |-
cd ui && npm ci && npm test
run: |
docker run --rm \
-v "$PWD:/workspace" \
-w /workspace \
node:22-bookworm-slim sh -c "$STARCI_RUN"
- name: Remember this pass
if: steps.passed.outputs.cache-hit != 'true'
run: mkdir -p "$RUNNER_TEMP/starci-passed" && date > "$RUNNER_TEMP/starci-passed/at"
ui-build:
name: "ui build"
runs-on: ubuntu-latest
needs: [ui-lint, ui-test]
steps:
- uses: actions/checkout@v4
with:
sparse-checkout-cone-mode: false
sparse-checkout: |
/ui
- name: Has this already passed with these inputs?
id: passed
uses: actions/cache@v4
with:
path: ${{ runner.temp }}/starci-passed
key: starci-passed-ui-build-1e34ee4c5cc5856a-${{ hashFiles('ui', 'ui/**') }}
- name: "ui build"
if: steps.passed.outputs.cache-hit != 'true'
env:
STARCI_RUN: |-
cd ui && npm ci && npm run build
run: |
docker run --rm \
-v "$PWD:/workspace" \
-w /workspace \
node:22-bookworm-slim sh -c "$STARCI_RUN"
- name: Remember this pass
if: steps.passed.outputs.cache-hit != 'true'
run: mkdir -p "$RUNNER_TEMP/starci-passed" && date > "$RUNNER_TEMP/starci-passed/at"
api-lint:
name: "api lint"
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
sparse-checkout-cone-mode: false
sparse-checkout: |
/api
- name: Has this already passed with these inputs?
id: passed
uses: actions/cache@v4
with:
path: ${{ runner.temp }}/starci-passed
key: starci-passed-api-lint-4055ddfc2c0f40d1-${{ hashFiles('api', 'api/**') }}
- name: "api lint"
if: steps.passed.outputs.cache-hit != 'true'
env:
STARCI_RUN: |-
cd api && pip install ruff && ruff check .
run: |
docker run --rm \
-v "$PWD:/workspace" \
-w /workspace \
python:3.13-slim sh -c "$STARCI_RUN"
- name: Remember this pass
if: steps.passed.outputs.cache-hit != 'true'
run: mkdir -p "$RUNNER_TEMP/starci-passed" && date > "$RUNNER_TEMP/starci-passed/at"
api-test:
name: "api test"
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
sparse-checkout-cone-mode: false
sparse-checkout: |
/api
- name: Has this already passed with these inputs?
id: passed
uses: actions/cache@v4
with:
path: ${{ runner.temp }}/starci-passed
key: starci-passed-api-test-5bc1e5c11433e410-${{ hashFiles('api', 'api/**') }}
- name: "api test"
if: steps.passed.outputs.cache-hit != 'true'
env:
STARCI_RUN: |-
cd api && pip install -e . && pytest -q
run: |
docker run --rm \
-v "$PWD:/workspace" \
-w /workspace \
python:3.13-slim sh -c "$STARCI_RUN"
- name: Remember this pass
if: steps.passed.outputs.cache-hit != 'true'
run: mkdir -p "$RUNNER_TEMP/starci-passed" && date > "$RUNNER_TEMP/starci-passed/at"
api-build:
name: "api build"
runs-on: ubuntu-latest
needs: [api-lint, api-test]
steps:
- uses: actions/checkout@v4
with:
sparse-checkout-cone-mode: false
sparse-checkout: |
/api
- name: Has this already passed with these inputs?
id: passed
uses: actions/cache@v4
with:
path: ${{ runner.temp }}/starci-passed
key: starci-passed-api-build-efa05516f6cbb15c-${{ hashFiles('api', 'api/**') }}
- name: "api build"
if: steps.passed.outputs.cache-hit != 'true'
env:
STARCI_RUN: |-
cd api && pip install build && python -m build
run: |
docker run --rm \
-v "$PWD:/workspace" \
-w /workspace \
python:3.13-slim sh -c "$STARCI_RUN"
- name: Remember this pass
if: steps.passed.outputs.cache-hit != 'true'
run: mkdir -p "$RUNNER_TEMP/starci-passed" && date > "$RUNNER_TEMP/starci-passed/at"
# Generated by `starci compile --target circleci` from helpers.ci.star. Edit that, not this.
#
# Each job is one step of the plan: the same image, command, tools and
# packages, given only the step's inputs. A job skips its work when it has
# already passed with the same inputs.
#
# What does not carry over:
# - The script reads ctx.changed_dirs, so its plan depends on the commit. This
# file is the plan for a commit about which nothing is known, and is the
# same for every push: steps the script would add or drop for a particular
# branch or set of changed files are not represented.
# - Passes are remembered in this project's CircleCI cache, which expires.
# starci's own store does not.
version: 2.1
jobs:
ui-lint:
machine:
image: ubuntu-2404:current
resource_class: medium
steps:
- checkout
- run:
name: "Keep only this step's inputs"
command: |
git sparse-checkout set --no-cone '/ui'
- run:
name: "Identify the inputs"
command: |
git ls-files -s -- ':(top,literal)ui' > /tmp/starci-inputs
- restore_cache:
name: Has this already passed with these inputs?
keys:
- starci-passed-ui-lint-c037eb6d9c922cc2-{{ checksum "/tmp/starci-inputs" }}
- run:
name: "Stop here if it has"
command: |
if [ -e ~/starci-passed/at ]; then
echo "Passed before with the same inputs, on $(cat ~/starci-passed/at). Nothing to do."
circleci-agent step halt
fi
- run:
name: "ui lint"
environment:
STARCI_RUN: |-
cd ui && npm ci && npm run lint
command: |
docker run --rm \
-v "$PWD:/workspace" \
-w /workspace \
node:22-bookworm-slim sh -c "$STARCI_RUN"
- run:
name: "Remember this pass"
command: |
mkdir -p ~/starci-passed && date > ~/starci-passed/at
- save_cache:
key: starci-passed-ui-lint-c037eb6d9c922cc2-{{ checksum "/tmp/starci-inputs" }}
paths:
- ~/starci-passed
ui-test:
machine:
image: ubuntu-2404:current
resource_class: medium
steps:
- checkout
- run:
name: "Keep only this step's inputs"
command: |
git sparse-checkout set --no-cone '/ui'
- run:
name: "Identify the inputs"
command: |
git ls-files -s -- ':(top,literal)ui' > /tmp/starci-inputs
- restore_cache:
name: Has this already passed with these inputs?
keys:
- starci-passed-ui-test-0118b2623beebd99-{{ checksum "/tmp/starci-inputs" }}
- run:
name: "Stop here if it has"
command: |
if [ -e ~/starci-passed/at ]; then
echo "Passed before with the same inputs, on $(cat ~/starci-passed/at). Nothing to do."
circleci-agent step halt
fi
- run:
name: "ui test"
environment:
STARCI_RUN: |-
cd ui && npm ci && npm test
command: |
docker run --rm \
-v "$PWD:/workspace" \
-w /workspace \
node:22-bookworm-slim sh -c "$STARCI_RUN"
- run:
name: "Remember this pass"
command: |
mkdir -p ~/starci-passed && date > ~/starci-passed/at
- save_cache:
key: starci-passed-ui-test-0118b2623beebd99-{{ checksum "/tmp/starci-inputs" }}
paths:
- ~/starci-passed
ui-build:
machine:
image: ubuntu-2404:current
resource_class: medium
steps:
- checkout
- run:
name: "Keep only this step's inputs"
command: |
git sparse-checkout set --no-cone '/ui'
- run:
name: "Identify the inputs"
command: |
git ls-files -s -- ':(top,literal)ui' > /tmp/starci-inputs
- restore_cache:
name: Has this already passed with these inputs?
keys:
- starci-passed-ui-build-1e34ee4c5cc5856a-{{ checksum "/tmp/starci-inputs" }}
- run:
name: "Stop here if it has"
command: |
if [ -e ~/starci-passed/at ]; then
echo "Passed before with the same inputs, on $(cat ~/starci-passed/at). Nothing to do."
circleci-agent step halt
fi
- run:
name: "ui build"
environment:
STARCI_RUN: |-
cd ui && npm ci && npm run build
command: |
docker run --rm \
-v "$PWD:/workspace" \
-w /workspace \
node:22-bookworm-slim sh -c "$STARCI_RUN"
- run:
name: "Remember this pass"
command: |
mkdir -p ~/starci-passed && date > ~/starci-passed/at
- save_cache:
key: starci-passed-ui-build-1e34ee4c5cc5856a-{{ checksum "/tmp/starci-inputs" }}
paths:
- ~/starci-passed
api-lint:
machine:
image: ubuntu-2404:current
resource_class: medium
steps:
- checkout
- run:
name: "Keep only this step's inputs"
command: |
git sparse-checkout set --no-cone '/api'
- run:
name: "Identify the inputs"
command: |
git ls-files -s -- ':(top,literal)api' > /tmp/starci-inputs
- restore_cache:
name: Has this already passed with these inputs?
keys:
- starci-passed-api-lint-4055ddfc2c0f40d1-{{ checksum "/tmp/starci-inputs" }}
- run:
name: "Stop here if it has"
command: |
if [ -e ~/starci-passed/at ]; then
echo "Passed before with the same inputs, on $(cat ~/starci-passed/at). Nothing to do."
circleci-agent step halt
fi
- run:
name: "api lint"
environment:
STARCI_RUN: |-
cd api && pip install ruff && ruff check .
command: |
docker run --rm \
-v "$PWD:/workspace" \
-w /workspace \
python:3.13-slim sh -c "$STARCI_RUN"
- run:
name: "Remember this pass"
command: |
mkdir -p ~/starci-passed && date > ~/starci-passed/at
- save_cache:
key: starci-passed-api-lint-4055ddfc2c0f40d1-{{ checksum "/tmp/starci-inputs" }}
paths:
- ~/starci-passed
api-test:
machine:
image: ubuntu-2404:current
resource_class: medium
steps:
- checkout
- run:
name: "Keep only this step's inputs"
command: |
git sparse-checkout set --no-cone '/api'
- run:
name: "Identify the inputs"
command: |
git ls-files -s -- ':(top,literal)api' > /tmp/starci-inputs
- restore_cache:
name: Has this already passed with these inputs?
keys:
- starci-passed-api-test-5bc1e5c11433e410-{{ checksum "/tmp/starci-inputs" }}
- run:
name: "Stop here if it has"
command: |
if [ -e ~/starci-passed/at ]; then
echo "Passed before with the same inputs, on $(cat ~/starci-passed/at). Nothing to do."
circleci-agent step halt
fi
- run:
name: "api test"
environment:
STARCI_RUN: |-
cd api && pip install -e . && pytest -q
command: |
docker run --rm \
-v "$PWD:/workspace" \
-w /workspace \
python:3.13-slim sh -c "$STARCI_RUN"
- run:
name: "Remember this pass"
command: |
mkdir -p ~/starci-passed && date > ~/starci-passed/at
- save_cache:
key: starci-passed-api-test-5bc1e5c11433e410-{{ checksum "/tmp/starci-inputs" }}
paths:
- ~/starci-passed
api-build:
machine:
image: ubuntu-2404:current
resource_class: medium
steps:
- checkout
- run:
name: "Keep only this step's inputs"
command: |
git sparse-checkout set --no-cone '/api'
- run:
name: "Identify the inputs"
command: |
git ls-files -s -- ':(top,literal)api' > /tmp/starci-inputs
- restore_cache:
name: Has this already passed with these inputs?
keys:
- starci-passed-api-build-efa05516f6cbb15c-{{ checksum "/tmp/starci-inputs" }}
- run:
name: "Stop here if it has"
command: |
if [ -e ~/starci-passed/at ]; then
echo "Passed before with the same inputs, on $(cat ~/starci-passed/at). Nothing to do."
circleci-agent step halt
fi
- run:
name: "api build"
environment:
STARCI_RUN: |-
cd api && pip install build && python -m build
command: |
docker run --rm \
-v "$PWD:/workspace" \
-w /workspace \
python:3.13-slim sh -c "$STARCI_RUN"
- run:
name: "Remember this pass"
command: |
mkdir -p ~/starci-passed && date > ~/starci-passed/at
- save_cache:
key: starci-passed-api-build-efa05516f6cbb15c-{{ checksum "/tmp/starci-inputs" }}
paths:
- ~/starci-passed
workflows:
ci:
jobs:
- ui-lint
- ui-test
- ui-build:
requires: [ui-lint, ui-test]
- api-lint
- api-test
- api-build:
requires: [api-lint, api-test]
Download: helpers.ci.star, GitHub Actions, CircleCI