# Getting started

## Pin to `@v1`

Reference everything at the moving major tag. `release` (release-please) cuts a
new version on merge to `main` and moves the `v1` tag to it automatically, so
`@v1` always points at the latest backward-compatible release.

```yaml
- uses: FSHTech/github-actions/setup-python@v1
# reusable workflow:
#   uses: FSHTech/github-actions/.github/workflows/pr-title.yml@v1
```

Breaking changes ship as `v2` (a new major tag); pin to a full version
(`@v1.3.0`) if you need to freeze.

## Composite actions vs reusable workflows

- **Composite actions** are *step* bundles — they go inside an existing job's
  `steps:`, after `actions/checkout` (and the relevant language setup). Use them
  to assemble a job whose shape is specific to your repo (e.g. `lint`).
- **Reusable workflows** are whole *jobs* — you call them with `uses:` at the
  job level and they bring their own runner, permissions and steps. Use them
  when the entire job is the same across repos (`pr-title`, `release`, `docs`).

## A typical Python repo

```yaml
# .github/workflows/lint.yml  — job graph stays local, built from actions
name: lint
on:
  push: { branches: [main] }
  pull_request:
  workflow_dispatch:
permissions:
  contents: read
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: FSHTech/github-actions/setup-python@v1
      - uses: FSHTech/github-actions/uv-sync@v1
        with: { args: --group dev --group lint }
      - uses: FSHTech/github-actions/just-run@v1
        with: { recipes: lint type-check }
  pre-commit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: FSHTech/github-actions/setup-python@v1
      - uses: FSHTech/github-actions/pre-commit@v1
  tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: FSHTech/github-actions/setup-python@v1
      - uses: FSHTech/github-actions/uv-sync@v1
        with: { args: --group dev }
      - uses: FSHTech/github-actions/just-run@v1
        with: { recipes: coverage-ci }
```

The recipes (`lint`, `type-check`, `coverage-ci`, …) live in your repo's
`justfile`. A node repo is the same shape — `setup-node` then `just-run` — so it
needs a `justfile` exposing the equivalent recipes (e.g. `lint`, `type-check`,
`build`, `test`) that wrap the underlying `yarn workspace …` calls.

```yaml
# .github/workflows/pr-title.yml  — thin caller for the reusable workflow
name: pr-title
on:
  pull_request:
    types: [opened, edited, synchronize, reopened]
jobs:
  validate:
    uses: FSHTech/github-actions/.github/workflows/pr-title.yml@v1
    with:
      scopes: |
        my-repo
        deps
        ci
        release
```

```yaml
# .github/workflows/release.yml  — thin caller for the reusable workflow
name: release
on:
  push: { branches: [main] }
jobs:
  release:
    uses: FSHTech/github-actions/.github/workflows/release-python.yml@v1
    secrets: inherit
    # monorepo: with: { all-packages: true, check-url: true }
```

See **[Reference](reference/index)** for the exact inputs of each action and
workflow, and **[Conventions](conventions)** for what your repo must provide
(uv layout, deploy keys, CodeArtifact / Cloudflare variables, …).