repoactive 0.2.8.dev2__tar.gz → 0.3.1__tar.gz

{repoactive-0.2.8.dev2 → repoactive-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: repoactive
-Version: 0.2.8.dev2
+Version: 0.3.1
 Summary: Script-driven code changes with automated merge requests
 License-Expression: GPL-3.0-or-later
 License-File: LICENSE
@@ -27,27 +27,37 @@ Description-Content-Type: text/markdown
 
 # repoactive - Script-driven code changes with automated merge requests
 
+[![PyPI](https://img.shields.io/pypi/v/repoactive.svg)](https://pypi.org/project/repoactive/)
+[![CI](https://github.com/schmir/repoactive/actions/workflows/ci.yml/badge.svg)](https://github.com/schmir/repoactive/actions/workflows/ci.yml)
+[![Python versions](https://img.shields.io/pypi/pyversions/repoactive.svg)](https://pypi.org/project/repoactive/)
+[![License](https://img.shields.io/pypi/l/repoactive.svg)](LICENSE)
+
 > **Warning:** This project is in an early stage of development. Use at your
 > own risk.
 
 `repoactive` runs your scripts against a git repository and optionally keeps
 the corresponding merge requests up to date. You write the scripts that
 produce the code changes; `repoactive` handles the rest - branches, commits,
-and (with `--mode publish`) the full MR lifecycle.
+and (with `--mode publish`) the full MR lifecycle. This document says merge
+request (MR) throughout; on GitHub, read that as pull request (PR).
 
 ## Contents
 
 - [Use cases](#use-cases)
+  - [How it compares](#how-it-compares)
 - [Installation](#installation)
 - [Quick start](#quick-start)
 - [How it works](#how-it-works)
+  - [What a run produces](#what-a-run-produces)
   - [Keeping the local clone current](#keeping-the-local-clone-current)
-- [Usage](#usage)
+  - [Undoing a run](#undoing-a-run)
+- [Commands](#commands)
+  - [`repoactive run`](#repoactive-run)
+  - [`repoactive recent-commits`](#repoactive-recent-commits)
+  - [`repoactive validate-config`](#repoactive-validate-config)
+  - [`repoactive info jobs`](#repoactive-info-jobs)
+  - [`repoactive info tags`](#repoactive-info-tags)
   - [Environment variables](#environment-variables)
-- [Inspecting repoactive commits](#inspecting-repoactive-commits)
-- [Validating configuration](#validating-configuration)
-- [Listing jobs](#listing-jobs)
-- [Listing tags](#listing-tags)
 - [Configuration](#configuration)
   - [`[job-defaults]`](#job-defaults)
   - [`[job.<name>]`](#jobname)
@@ -55,20 +65,23 @@ and (with `--mode publish`) the full MR lifecycle.
   - [Example](#example)
   - [`[platform.<name>]`](#platformname)
   - [Config file locations](#config-file-locations)
+  - [Variables passed to job commands](#variables-passed-to-job-commands)
+  - [Passing secrets to commands with `secret_env`](#passing-secrets-to-commands-with-secret_env)
   - [Overriding values on the command line](#overriding-values-on-the-command-line)
-- [Selecting jobs with tags](#selecting-jobs-with-tags)
-  - [Keeping unmerged branches current](#keeping-unmerged-branches-current)
-- [Disabling jobs](#disabling-jobs)
-- [Running a job on a schedule](#running-a-job-on-a-schedule)
-  - [One run at a time per repository](#one-run-at-a-time-per-repository)
-- [Gating jobs with `run_only_if_changed`](#gating-jobs-with-run_only_if_changed)
-- [Throttling jobs with `cooldown_period`](#throttling-jobs-with-cooldown_period)
-- [Throttling a job when a superset lands with `cooldown_on`](#throttling-a-job-when-a-superset-lands-with-cooldown_on)
-- [Limiting job runtime with `timeout`](#limiting-job-runtime-with-timeout)
-- [Generating jobs dynamically](#generating-jobs-dynamically)
+- [Run control](#run-control)
+  - [Selecting jobs with tags](#selecting-jobs-with-tags)
+  - [Disabling jobs](#disabling-jobs)
+  - [Running a job on a schedule](#running-a-job-on-a-schedule)
+  - [Gating jobs with `run_only_if_changed`](#gating-jobs-with-run_only_if_changed)
+  - [Throttling jobs with `cooldown_period`](#throttling-jobs-with-cooldown_period)
+  - [Throttling a job when a superset lands with `cooldown_on`](#throttling-a-job-when-a-superset-lands-with-cooldown_on)
+  - [Limiting job runtime with `timeout`](#limiting-job-runtime-with-timeout)
+  - [Generating jobs dynamically](#generating-jobs-dynamically)
 - [Requirements](#requirements)
 - [Appendix](#appendix)
   - [jj revset aliases](#jj-revset-aliases)
+- [Changelog](#changelog)
+- [License](#license)
 
 ## Use cases
 
@@ -79,6 +92,23 @@ and (with `--mode publish`) the full MR lifecycle.
 - Automating any periodic code transformation that should go through a
   review process
 
+### How it compares
+
+[Renovate](https://docs.renovatebot.com/) and
+[Dependabot](https://docs.github.com/en/code-security/dependabot) are built
+around dependency updates; repoactive runs whatever script you write, so the
+change can be anything the repository generates - a lock-file upgrade is
+just the simplest case.
+[multi-gitter](https://github.com/lindell/multi-gitter) also runs your
+script and opens the MR, but as a one-shot bulk operation across
+repositories; repoactive is built for re-running against one repository: an
+unchanged diff leaves the MR untouched, a changed one updates it, branches
+are rebased onto the moving base branch, cooldowns keep a landed change from
+immediately reopening, and jobs can stack their MRs on one another. And it
+is a plain CLI working against your local clone - no hosted service and
+nothing to install into the repository - that talks to GitHub and GitLab,
+including self-hosted instances.
+
 ## Installation
 
 `repoactive` is published on [PyPI](https://pypi.org/project/repoactive/).
@@ -123,7 +153,7 @@ needs a GitHub or GitLab API token in the environment. See
 4. **Run the job locally.** In the default `local` mode nothing is pushed
    and no MR is created - repoactive just records the diff your script
    produced on the branch `repoactive/uv-lock-upgrade` and prints a
-   `jj op restore` command to undo the run:
+   `jj op restore` command to [undo the run](#undoing-a-run):
 
    ```bash
    repoactive run
@@ -156,14 +186,6 @@ With `--mode publish` it also:
 Branches and MR descriptions are managed automatically - the only code you
 need to write is the script that produces the change.
 
-```
-[your script] → diff → repoactive → branch
-                                       ↓ (with --mode push or --mode publish)
-                                    git push → merge request
-                                                    ↑ (with --mode publish)
-                                            (create or update)
-```
-
 1. `repoactive` creates a new commit on top of the base branch or on top of
    other repoactive managed branches.
 2. It runs the job's script against the working tree.
@@ -188,6 +210,46 @@ need to write is the script that produces the change.
 > `.gitignore` up to date so build artifacts, caches, and other stray files
 > your script produces do not end up in the diff.
 
+### What a run produces
+
+For the quick-start job above, a `--mode publish` run pushes the branch
+`repoactive/uv-lock-upgrade` and opens an MR titled
+`[repoactive] build: upgrade dependencies`. Its description holds the job's
+`description` (when set), the command and its captured output in a code
+block, and - for [stacked jobs](#stacking-mrs) - links to the parent MRs
+([a real example](https://github.com/schmir/repoactive/pull/7)):
+
+```
+$ uv lock --upgrade
+Using CPython 3.14.1
+Resolved 51 packages in 4.19s
+Updated annotated-types v0.7.0 -> v0.8.0
+Updated nox v2026.4.10 -> v2026.7.11
+Updated ruff v0.15.21 -> v0.16.0
+Updated ty v0.0.58 -> v0.0.63
+```
+
+The commit carries the same output (unless `output_in_commit` is disabled)
+plus the `Repoactive-Job` trailer that
+[`recent-commits`](#repoactive-recent-commits), the
+[cooldown check](#throttling-jobs-with-cooldown_period), and the
+[unmerged-branch refresh](#keeping-unmerged-branches-current) all key on:
+
+```
+[repoactive] build: upgrade dependencies
+
+,----[ uv lock --upgrade ]
+| Using CPython 3.14.1
+| Resolved 51 packages in 4.19s
+| Updated annotated-types v0.7.0 -> v0.8.0
+| Updated nox v2026.4.10 -> v2026.7.11
+| Updated ruff v0.15.21 -> v0.16.0
+| Updated ty v0.0.58 -> v0.0.63
+`----
+
+Repoactive-Job: uv-lock-upgrade
+```
+
 ### Keeping the local clone current
 
 `repoactive` works entirely from the **local** repository view and never
@@ -204,13 +266,39 @@ because the commit that would trigger it has not reached the local base
 branch. See
 [ADR 0005](docs/adr/0005-local-repository-is-the-source-of-truth.md).
 
-## Usage
+### Undoing a run
+
+Every `run` captures the jj operation id beforehand and prints a
+`jj op restore <id>` command at the end of the run (last, since a run can
+produce a lot of output). Run it to roll the local repository - commits,
+bookmarks and colocated git refs - back to the state it was in before the
+run. It only undoes local changes: a branch already pushed or an MR already
+created by a `--mode push`/`--mode publish` run is not affected, as the hint
+panel itself points out.
+
+## Commands
 
 ```bash
 # Print the installed version and exit
 repoactive --version
 ```
 
+Every command accepts `--repo`/`-r` and `--debug`/`-d`. The commands that
+read configuration - `run`, `validate-config`, `info jobs`, and
+`info tags` - also accept the same `--config`/`-c` and `--set`/`-s` options,
+described in the [`repoactive run`](#repoactive-run) table below.
+`recent-commits` works from the repository alone and reads no configuration.
+
+All commands exit with these status codes:
+
+| Code | Meaning                                                                                    |
+| ---- | ------------------------------------------------------------------------------------------ |
+| 0    | Success                                                                                    |
+| 1    | Failure (invalid configuration, a failed job, ...)                                         |
+| 2    | `run` only: another run holds the [per-repository lock](#one-run-at-a-time-per-repository) |
+
+### `repoactive run`
+
 ```
 repoactive run [OPTIONS] [JOBS]...
 ```
@@ -247,64 +335,7 @@ repoactive run --debug
 | `--tag TAG`                     | `-t`  | Run jobs carrying any of these tags (repeatable). With no tags/jobs the default run targets the `enabled` tag                |
 | `--debug`                       | `-d`  | Enable debug logging                                                                                                         |
 
-### Environment variables
-
-Besides the command-line options, repoactive reads a few `REPOACTIVE_*`
-environment variables that tune how it presents itself in the current
-environment (as opposed to the [configuration](#configuration), which
-describes the jobs to run). They are handled uniformly: all of them go
-through a single settings model and are validated together at startup, so a
-misconfigured variable fails immediately with a one-line error naming it
-instead of surfacing mid-run or being silently ignored. Values are
-case-insensitive.
-
-#### `REPOACTIVE_UI`
-
-`interactive` (default) or `noninteractive`.
-
-Every `run` captures the jj operation id beforehand and prints a
-`jj op restore <id>` command at the end of the run (last, since a run can
-produce a lot of output). Run it to roll the local repository - commits,
-bookmarks and colocated git refs - back to the state it was in before the
-run. It only undoes local changes: a branch already pushed or an MR already
-created by a `--mode push`/`--mode publish` run is not affected, as the hint
-panel itself points out.
-
-`noninteractive` suppresses these "how to undo" hint panels. Set it where
-nobody is at the keyboard, say an unattended CI job. This is an explicit
-switch rather than CI auto-detection, because a CI container someone has
-logged in to _is_ interactive.
-
-#### `REPOACTIVE_LOG_LEVEL`
-
-`debug`, `info`, `warning`, `error`, or `critical`; unset by default
-(logging off).
-
-Enables logging at that level without passing `--debug` on every invocation;
-an explicit `--debug` takes precedence.
-
-#### `REPOACTIVE_LOG_HANDLER`
-
-`rich` or `plain`; defaults to `rich`, or `plain` when `REPOACTIVE_UI` is
-`noninteractive`.
-
-How log records are rendered: a colorized column layout via
-[rich](https://github.com/Textualize/rich), or the stdlib's plain stream
-handler (e.g. when the output is collected by a log aggregator).
-
-#### `REPOACTIVE_PROGRESS_LINES`
-
-An integer (default: `8`).
-
-While a job's command runs in an interactive terminal, repoactive shows a
-live, scrolling block of its most recent output lines. The block stays on
-screen once the command finishes, with the job's status line printed below
-it. `REPOACTIVE_PROGRESS_LINES` sets how many lines that live tail shows;
-`0` or less disables the live block entirely. When output is not a terminal
-(piped or in CI) the block is disabled and the command's output is left
-untouched.
-
-## Inspecting repoactive commits
+### `repoactive recent-commits`
 
 ```
 repoactive recent-commits [OPTIONS] [JOBS]...
@@ -337,7 +368,7 @@ repoactive recent-commits --status unmerged
 | `--status [all\|merged\|unmerged]` | `-s`  | Filter by merge status into trunk (default: `all`)     |
 | `--debug`                          | `-d`  | Enable debug logging                                   |
 
-## Validating configuration
+### `repoactive validate-config`
 
 ```
 repoactive validate-config [OPTIONS]
@@ -364,10 +395,7 @@ code 1.
 Validation checks include unknown keys, missing required fields, invalid
 `depends_on` references, and circular job dependencies.
 
-The command accepts the same `--config`, `--set`, `--repo`, and `--debug`
-options as [`repoactive run`](#usage).
-
-## Listing jobs
+### `repoactive info jobs`
 
 ```
 repoactive info jobs [OPTIONS]
@@ -391,10 +419,7 @@ build           Build the project   enabled
     └── deploy  Deploy to staging   nightly, risky
 ```
 
-The command accepts the same `--config`, `--set`, `--repo`, and `--debug`
-options as [`repoactive run`](#usage).
-
-## Listing tags
+### `repoactive info tags`
 
 ```
 repoactive info tags [OPTIONS]
@@ -426,8 +451,54 @@ nightly:
   benchmark            Run nightly benchmarks  nightly
 ```
 
-The command accepts the same `--config`, `--set`, `--repo`, and `--debug`
-options as [`repoactive run`](#usage).
+### Environment variables
+
+Besides the command-line options, repoactive reads a few `REPOACTIVE_*`
+environment variables that tune how it presents itself in the current
+environment (as opposed to the [configuration](#configuration), which
+describes the jobs to run). They are handled uniformly: all of them go
+through a single settings model and are validated together at startup, so a
+misconfigured variable fails immediately with a one-line error naming it
+instead of surfacing mid-run or being silently ignored. Values are
+case-insensitive.
+
+#### `REPOACTIVE_UI`
+
+`interactive` (default) or `noninteractive`.
+
+`noninteractive` suppresses the ["how to undo" hint panels](#undoing-a-run)
+printed after each run. Set it where nobody is at the keyboard, say an
+unattended CI job. This is an explicit switch rather than CI auto-detection,
+because a CI container someone has logged in to _is_ interactive.
+
+#### `REPOACTIVE_LOG_LEVEL`
+
+`debug`, `info`, `warning`, `error`, or `critical`; unset by default
+(logging off).
+
+Enables logging at that level without passing `--debug` on every invocation;
+an explicit `--debug` takes precedence.
+
+#### `REPOACTIVE_LOG_HANDLER`
+
+`rich` or `plain`; defaults to `rich`, or `plain` when `REPOACTIVE_UI` is
+`noninteractive`.
+
+How log records are rendered: a colorized column layout via
+[rich](https://github.com/Textualize/rich), or the stdlib's plain stream
+handler (e.g. when the output is collected by a log aggregator).
+
+#### `REPOACTIVE_PROGRESS_LINES`
+
+An integer (default: `8`).
+
+While a job's command runs in an interactive terminal, repoactive shows a
+live, scrolling block of its most recent output lines. The block stays on
+screen once the command finishes, with the job's status line printed below
+it. `REPOACTIVE_PROGRESS_LINES` sets how many lines that live tail shows;
+`0` or less disables the live block entirely. When output is not a terminal
+(piped or in CI) the block is disabled and the command's output is left
+untouched.
 
 ## Configuration
 
@@ -450,14 +521,13 @@ block.
 
 ### `[job-defaults]`
 
-**MR/PR options:**
+**MR options:**
 
-- **`labels`** (default: `[]`) - Labels applied to every MR/PR. Per-job
+- **`labels`** (default: `[]`) - Labels applied to every MR. Per-job
   `labels` are merged with, not replaced by, this list.
 - **`auto_merge`** (default: `false`) - When `true`, enable auto-merge on
-  every MR/PR so it merges automatically once its pipeline passes. On
-  GitHub, the repository must have "Allow auto-merge" enabled in its
-  settings.
+  every MR so it merges automatically once its pipeline passes. On GitHub,
+  the repository must have "Allow auto-merge" enabled in its settings.
 - **`required_approvals`** (default: none) - Minimum number of approvals
   required before the MR can be merged. **GitLab only** - this sets the
   per-MR approval requirement. GitHub has no per-PR equivalent (required
@@ -467,13 +537,17 @@ block.
 **Branch and commit options:**
 
 - **`branch_prefix`** (default: `"repoactive/"`) - Prefix prepended to the
-  job name to form the branch name.
+  job name to form the branch name. Set to `""` to use the job name alone.
+  With an empty prefix the branch name is exactly the job name, so make sure
+  no job is named after your base branch (e.g. a job named `main`) - the two
+  branches would otherwise collide.
 - **`mr_title_prefix`** (default: `"[repoactive] "`) - Prefix prepended to
-  every MR/PR title. Set to `""` to disable.
+  every MR title. Set to `""` to disable.
 - **`commit_title_prefix`** (default: `"[repoactive] "`) - Prefix prepended
   to every commit title. Set to `""` to disable.
 - **`base_branch`** (default: repo default) - Target branch for all jobs
-  that do not set their own.
+  that do not set their own. May also be a jj revset expression such as
+  `trunk()`, `root()`, or a user-defined revset alias.
 
 **Run control:**
 
@@ -484,6 +558,18 @@ block.
 - **`timeout`** (default: `"2m"`) - Maximum runtime for a job's command.
   Same format as `cooldown_period`. See
   [Limiting job runtime with `timeout`](#limiting-job-runtime-with-timeout).
+- **`shell`** (default: `/bin/sh`) - Interpreter used to run job commands. A
+  bare name is resolved on `PATH` (e.g. `"bash"`); an absolute path also
+  works. The command runs as `<shell> -c <command>`. Arguments are not
+  allowed - the value must be a single binary.
+
+**Secrets:**
+
+- **`secret_env`** (default: `[]`) - Names of environment variables to mark
+  as secrets config-wide. Each marked name is stripped from every job
+  command's environment, but a job still reads one only by listing it in its
+  own `secret_env`; `job-defaults` marks names, it does not grant them. See
+  [Passing secrets to commands with `secret_env`](#passing-secrets-to-commands-with-secret_env).
 
 ### `[job.<name>]`
 
@@ -495,34 +581,35 @@ underscores.
 
 - **`command`** - Shell command (or executable path) run in the repository
   working directory. A non-zero exit is a failure.
-- **`title`** - MR/PR title (also the commit subject, after
+- **`title`** - MR title (also the commit subject, after
   `commit_title_prefix`).
 
-**MR/PR options:**
+**MR options:**
 
-- **`description`** - Body text of the MR/PR.
-- **`labels`** (default: `[]`) - Extra labels for this job's MR/PR, merged
-  with `job-defaults.labels`.
-- **`draft`** (default: `false`) - Open the MR/PR as a draft. On GitHub,
-  draft state cannot be changed after creation.
-- **`create_mr`** (default: `true`) - Whether to create an MR/PR: `true`
+- **`description`** - Body text of the MR.
+- **`labels`** (default: `[]`) - Extra labels for this job's MR, merged with
+  `job-defaults.labels`.
+- **`draft`** (default: `false`) - Open the MR as a draft. On GitHub, draft
+  state cannot be changed after creation.
+- **`create_mr`** (default: `true`) - Whether to create an MR: `true`
   (always), `false` (push the branch but skip the MR), or
   `"unless-superseded"` (skip when a dependent's MR from the same run
   already contains this job's changes - see [Stacking MRs](#stacking-mrs)).
 - **`auto_merge`** (default: inherited from `job-defaults`) - When `true`,
-  enable auto-merge on this job's MR/PR.
+  enable auto-merge on this job's MR.
 - **`required_approvals`** (default: inherited from `job-defaults`) -
   Minimum number of approvals required before this job's MR can be merged.
   GitLab only; see `job-defaults.required_approvals`.
 
 **Branch and commit options:**
 
-- **`base_branch`** (default: inherited) - Target branch for this job's
-  MR/PR.
+- **`base_branch`** (default: inherited) - Target branch for this job's MR.
+  May also be a jj revset expression such as `trunk()`, `root()`, or a
+  user-defined revset alias.
 - **`branch_prefix`** (default: inherited) - Override the branch-name prefix
   for this job only.
-- **`mr_title_prefix`** (default: inherited) - Override the MR/PR title
-  prefix for this job only.
+- **`mr_title_prefix`** (default: inherited) - Override the MR title prefix
+  for this job only.
 - **`commit_title_prefix`** (default: inherited) - Override the commit title
   prefix for this job only.
 - **`output_in_commit`** (default: `true`) - Append the job's command and
@@ -553,9 +640,20 @@ underscores.
 - **`timeout`** (default: inherited) - Maximum runtime for this job's
   command. Set to `"0s"` to disable the timeout entirely. See
   [Limiting job runtime with `timeout`](#limiting-job-runtime-with-timeout).
+- **`shell`** (default: inherited) - Interpreter used to run this job's
+  command, overriding `job-defaults.shell`. See
+  [`job-defaults.shell`](#job-defaults).
 - **`emits_jobs`** (default: `false`) - Generator job: the command writes
-  `*.toml` job fragments into `$REPOACTIVE_JOBS_DIR` instead of producing a
-  diff. See [Generating jobs dynamically](#generating-jobs-dynamically).
+  `*.toml` job fragments into `$RA_JOBS_DIR` instead of producing a diff.
+  See [Generating jobs dynamically](#generating-jobs-dynamically).
+
+**Secrets:**
+
+- **`secret_env`** (default: `[]`) - Names of environment variables holding
+  secrets this job's command may read. A marked name is stripped from every
+  command's environment; only a job that lists it here has it injected back
+  for its own command. See
+  [Passing secrets to commands with `secret_env`](#passing-secrets-to-commands-with-secret_env).
 
 ### Stacking MRs
 
@@ -569,14 +667,13 @@ Because a dependent's MR already contains its dependencies' changes, a
 dependency chain normally opens one MR per job that produced a diff. Setting
 `create_mr = "unless-superseded"` on the earlier jobs collapses that: such a
 job skips its MR when a dependent job produced an MR in the same run, so the
-chain yields a single MR on the topmost job that actually changed something
-
-- falling back to the job below it when the jobs above came up empty. The
-  branch is still pushed either way. Only the current run counts: a
-  dependent that is empty, failed, on cooldown, or not selected does not
-  suppress anything. See
-  [ADR 0009](docs/adr/0009-unless-superseded-mr-creation.md) for details and
-  limitations.
+chain yields a single MR on the topmost job that actually changed
+something - falling back to the job below it when the jobs above came up
+empty. The branch is still pushed either way. Only the current run counts: a
+dependent that is empty, failed, on cooldown, or not selected does not
+suppress anything. See
+[ADR 0009](docs/adr/0009-unless-superseded-mr-creation.md) for details and
+limitations.
 
 ### Example
 
@@ -658,6 +755,165 @@ directory of `*.toml` files, and may be repeated to merge several sources;
 later sources win. Explicit paths are resolved relative to the current
 directory, not `--repo`.
 
+### Variables passed to job commands
+
+`repoactive` injects a few `RA_`-prefixed environment variables into every
+job command's environment. These are distinct from the `REPOACTIVE_`
+variables [above](#environment-variables), which configure `repoactive`
+itself.
+
+| Variable               | Value                                                                                  | Set when                                                                            |
+| ---------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `RA_JOB_NAME`          | The name of the job the command belongs to.                                            | Always.                                                                             |
+| `RA_WORKSPACE_DIR`     | The temporary jj workspace created for the job (also the command's working directory). | Always.                                                                             |
+| `RA_JOB_BRANCH`        | The bookmark/branch repoactive uses for the job's output.                              | Always.                                                                             |
+| `RA_JOB_BASE_BRANCH`   | The branch the job's MR targets (`base_branch`, or `trunk()` by default).              | Always.                                                                             |
+| `RA_CONFIG_SOURCE_DIR` | The directory of the config file that defined the command.                             | The command came from a config file (not a `--set` override or a built-in default). |
+| `RA_JOBS_DIR`          | The directory a generator writes its `*.toml` job fragments into.                      | The command is a [generator](#generating-jobs-dynamically) (`emits_jobs`).          |
+
+#### `RA_JOB_NAME`
+
+`RA_JOB_NAME` holds the name of the job the command belongs to. A command
+shared by several jobs (for instance one set in `[job-defaults]` or emitted
+by a generator) can read it to tell which job is running:
+
+```toml
+[job.lint]
+command = "./run-check.sh $RA_JOB_NAME"
+title = "run the shared check script for this job"
+```
+
+#### `RA_WORKSPACE_DIR`
+
+A job's command runs in a temporary jj workspace, which is also its working
+directory. `RA_WORKSPACE_DIR` names that directory explicitly, so a command
+that changes directory can still find its way back:
+
+```toml
+[job.build]
+command = "cd subdir && make && cp result $RA_WORKSPACE_DIR/subdir/"
+title = "build in a subdirectory"
+```
+
+#### `RA_JOB_BRANCH`
+
+`RA_JOB_BRANCH` holds the bookmark (git branch) repoactive uses for the
+job's output, e.g. `repoactive/uv-lock-upgrade`. The command runs on a fresh
+commit while that bookmark still points at the **previous** run's commit, so
+a command can inspect what it produced last time - for example to build on
+it or diff against it:
+
+```toml
+[job.notes]
+command = "jj diff --from $RA_JOB_BRANCH --to @ > /tmp/delta || true; ./make-notes.sh"
+title = "regenerate release notes from what changed since last run"
+```
+
+The bookmark may not exist yet: a job's first run, a run that produced no
+diff, and a generator all leave it unset on the remote, so a command that
+reads it should tolerate a missing ref.
+
+#### `RA_JOB_BASE_BRANCH`
+
+`RA_JOB_BASE_BRANCH` holds the branch the job's merge request targets - its
+`base_branch`, or `trunk()` when that is unset. A command can use it to look
+at only what changed relative to the target, for instance to lint or
+reformat just the affected files:
+
+```toml
+[job.format]
+command = "treefmt $(git diff --name-only $RA_JOB_BASE_BRANCH)"
+title = "format files changed since the base branch"
+```
+
+This is the branch you _configured_ as the base. When a job stacks on
+another via `depends_on`, its commit actually sits on top of that other
+job's output, so `RA_JOB_BASE_BRANCH` names the ultimate target of the
+stack, not the immediate parent.
+
+#### `RA_CONFIG_SOURCE_DIR`
+
+Because the command runs in that throwaway workspace rather than in the
+directory its config lives in, a relative path cannot reach a helper file
+kept beside the config. `RA_CONFIG_SOURCE_DIR` bridges that: it holds the
+directory of the config file that defined the job's command:
+
+- a job defined in `.repoactive.toml` gets the directory holding it (the
+  repo directory, by default);
+- a job defined in `.repoactive.d/foo.toml` gets the `.repoactive.d`
+  directory.
+
+```toml
+[job.fixup]
+command = "$RA_CONFIG_SOURCE_DIR/fixup.sh"
+title = "run the fixup script kept beside the config"
+```
+
+The value is the config file's real location on disk, so it is the same
+whether the file was discovered automatically or named with `-c`. A command
+whose value came from a `--set` override has no config file, so
+`RA_CONFIG_SOURCE_DIR` is unset for it.
+
+### Passing secrets to commands with `secret_env`
+
+A job command inherits `repoactive`'s environment, so a secret exported
+before the run (an LLM key, a registry token) reaches it. Left unmanaged
+that secret reaches **every** job, whether it needs it or not. `secret_env`
+scopes secrets to the jobs that ask for them.
+
+The field separates two things:
+
+- **Marking** - naming a variable in _any_ `secret_env` (a job's or
+  `[job-defaults]`') marks it a secret and **removes it from every job
+  command's environment**.
+- **Granting** - a job reads a marked secret back only by listing it in
+  **its own** `secret_env`. `[job-defaults].secret_env` marks names but
+  grants to no job.
+
+So a secret is present only in the jobs that name it, never ambient:
+
+```toml
+[job-defaults]
+secret_env = ["OPENAI_API_KEY"]
+
+[job.rewrite-docs]
+command = "./llm-rewrite.sh"
+title = "docs: rewrite with the LLM"
+secret_env = ["OPENAI_API_KEY"]
+
+[job.format]
+command = "treefmt"
+title = "format the tree"
+```
+
+Here `OPENAI_API_KEY` is marked in `[job-defaults]`, so `format` (which does
+not grant it) runs without it in its environment; only `rewrite-docs`, which
+lists it in its own `secret_env`, can read it.
+
+A job that grants a secret which is **unset** in `repoactive`'s environment
+fails at its start with a clear error, rather than letting the command fail
+obscurely later. Secret **values** must never be written in config - a
+`.repoactive.toml` is checked into the repo; `secret_env` names variables,
+your environment (or your CI's secret store) supplies the values. The `RA_`
+and `REPOACTIVE_` prefixes are reserved and rejected.
+
+A [generated job](#generating-jobs-dynamically) may only grant a secret that
+the static config already marks; an emitted `secret_env` naming a variable
+no static job or `[job-defaults]` marked is rejected. Mark such a secret up
+front in `[job-defaults].secret_env` (or on the generator), and the emitted
+jobs grant it.
+
+A platform's `token_env` is normally stripped from every command
+([the platform token](#platformname) is kept out of jobs). A job that
+genuinely needs it can opt back in by naming that variable in its own
+`secret_env`; only that job then receives it.
+
+> **Note:** `secret_env` scopes _which jobs_ can read a secret. It does not
+> yet redact secret values from a command's captured output, so a command
+> that echoes a secret it was granted can still write it into the commit
+> message. Avoid printing granted secrets. See
+> [ADR 0017](docs/adr/0017-secret-env-redaction.md).
+
 ### Overriding values on the command line
 
 `--set NAME=VALUE`/`-s` tweaks individual config values without editing a
@@ -693,7 +949,13 @@ job across several flags - put a new job's required fields in one expression
 unknown key or malformed value is reported with the offending `--set`
 argument named.
 
-## Selecting jobs with tags
+## Run control
+
+The sections below cover the run-control options from the
+[configuration reference](#jobname) in detail: which jobs a run selects, how
+to schedule and throttle them, and how to generate jobs dynamically.
+
+### Selecting jobs with tags
 
 Which jobs a `repoactive run` touches is decided by **tags**. Every job has
 a set of tags, with a smart default:
@@ -728,8 +990,8 @@ mistyped one.
 Because assigning a tag removes the implicit `enabled` tag, **tags are
 load-bearing, not free-form labels**: tagging a job takes it out of the bare
 `repoactive run`. If you want a job to stay in the default run _and_ belong
-to a group, list both: `tags = ["enabled", "weekly"]`. (For MR/PR labels,
-use `labels` - a separate concept.)
+to a group, list both: `tags = ["enabled", "weekly"]`. (For MR labels, use
+`labels` - a separate concept.)
 
 Tag selection is _explicit_ selection, so - like naming a job - it ignores
 the `enabled`/`disabled` defaults and force-includes dependencies. The bare
@@ -737,7 +999,7 @@ the `enabled`/`disabled` defaults and force-includes dependencies. The bare
 itself selected is dropped
 (`==> [name] skipped (dependency not in default run)`).
 
-### Keeping unmerged branches current
+#### Keeping unmerged branches current
 
 The bare `repoactive run` additionally refreshes **any job that currently
 has an unmerged branch**, regardless of its tags. A branch is "unmerged"
@@ -756,7 +1018,7 @@ don't have to wait for the next weekly run to resolve a conflict with
 disabled job's unmerged branch is refreshed too: it was most likely created
 by an explicit run, and letting it drift out of date helps no one.)
 
-## Disabling jobs
+### Disabling jobs
 
 Set `disabled = true` on a `[job.<name>]` to keep it in the config but leave
 it out of normal runs; it is exactly sugar for `tags = ["disabled"]` (so the
@@ -777,7 +1039,7 @@ disabled = true
   `repoactive run --tag disabled`, which runs everything currently turned
   off.
 
-## Running a job on a schedule
+### Running a job on a schedule
 
 `repoactive` is not a daemon and has no built-in scheduler - the cadence of
 a job is whatever cadence you invoke it with. To run a job on a fixed
@@ -805,7 +1067,7 @@ inferring a schedule from `repoactive`'s own history: real cron is stateful
 and excludes the other days, whereas `repoactive` only ever sees what has
 _landed_ (see `cooldown_period` below).
 
-### One run at a time per repository
+#### One run at a time per repository
 
 A `repoactive run` takes an exclusive per-repository lock for its duration,
 so two runs against the same repository never interleave (and corrupt each
@@ -823,7 +1085,7 @@ The lock is an advisory `flock` on `.jj/repoactive.lock`; the OS releases it
 automatically if a run is killed, so a crashed run never leaves the
 repository locked.
 
-## Gating jobs with `run_only_if_changed`
+### Gating jobs with `run_only_if_changed`
 
 `run_only_if_changed` lets a job declare that it should only run when
 specific upstream jobs actually produced a diff. If none of the named jobs
@@ -831,12 +1093,12 @@ changed anything in the current run, the job is skipped.
 
 ```toml
 [job.prek-autoupdate]
-command = "./scripts/prek.sh autoupdate"
+command = "uvx prek autoupdate"
 title = "ci: update pre-commit hooks"
 tags = ["weekly"]
 
 [job.prek-run-all]
-command = "sh -c './scripts/prek.sh run -a; true'"
+command = "sh -c 'uvx prek run -a; true'"
 title = "ci: apply pre-commit fixes"
 depends_on = ["prek-autoupdate"]
 run_only_if_changed = ["prek-autoupdate"]
@@ -862,7 +1124,7 @@ Key behaviour:
   order can be listed; in practice most usages name a direct dependency, as
   in the example above.
 
-## Throttling jobs with `cooldown_period`
+### Throttling jobs with `cooldown_period`
 
 Every commit `repoactive` creates carries a `Repoactive-Job: <name>` trailer
 identifying the job that produced it. When a job sets `cooldown_period`,
@@ -885,7 +1147,7 @@ runs: `repoactive` does not fetch, so a clone that has not pulled the merge
 will not see the cooldown and will re-run the job. See
 [Keeping the local clone current](#keeping-the-local-clone-current).
 
-## Throttling a job when a superset lands with `cooldown_on`
+### Throttling a job when a superset lands with `cooldown_on`
 
 Some jobs are strict supersets of others. `uv lock --upgrade` refreshes
 every dependency group, so its diff already contains everything
@@ -925,7 +1187,7 @@ has an open, unmerged branch is always refreshed regardless of cooldown (see
 its branch is rebased and, if the change is now redundant, self-closes on
 the next run.
 
-## Limiting job runtime with `timeout`
+### Limiting job runtime with `timeout`
 
 A job's `command` can hang or run away. Setting `timeout` caps how long the
 command may run; when the limit is reached `repoactive` kills the command's
@@ -955,15 +1217,15 @@ title = "chore: fix lint"
 timeout = "0s"        # opt out of the timeout entirely
 ```
 
-## Generating jobs dynamically
+### Generating jobs dynamically
 
 Sometimes the useful set of jobs depends on the repository's contents - one
 job per package in a monorepo, one per entry in a manifest - and you don't
 want to hand-maintain them. A **generator** is an ordinary `[job.<name>]`
 with `emits_jobs = true`. Instead of producing a diff, its command writes
 one or more `*.toml` job fragments into the directory named by the
-`REPOACTIVE_JOBS_DIR` environment variable, and the jobs it emits run in the
-same invocation.
+`RA_JOBS_DIR` environment variable, and the jobs it emits run in the same
+invocation.
 
 ```toml
 [job.per-package]
@@ -978,7 +1240,7 @@ cooldown_period = "7d"
 The command writes fragments using the normal `[job.<name>]` syntax, e.g.
 
 ```toml
-# $REPOACTIVE_JOBS_DIR/pkg-a.toml
+# $RA_JOBS_DIR/pkg-a.toml
 [job.upgrade-pkg-a]
 command = "uv lock --upgrade --package pkg-a"
 title = "build: upgrade pkg-a"
@@ -986,7 +1248,7 @@ title = "build: upgrade pkg-a"
 
 Fragments may only contain `[job.<name>]` tables; anything else (e.g.
 `[job-defaults]`) fails the generator. To set defaults for the emitted jobs,
-set them on the generator itself — they are inherited (see below).
+set them on the generator itself - they are inherited (see below).
 
 Key points:
 
@@ -1033,13 +1295,8 @@ design.
 - [jj (Jujutsu)](https://github.com/jj-vcs/jj) - `repoactive` uses jj to
   manage branches and commits in the target repository
 - A configured jj user name and email - jj records them as the commit
-  author. Set them once with:
-
-  ```bash
-  jj config set --user user.name "My Name"
-  jj config set --user user.email "me@example.com"
-  ```
-
+  author. Set them once with the `jj config set` commands shown in
+  [Quick start](#quick-start) step 1.
 - A GitLab or GitHub API token exposed via the environment variable named in
   `platform.token_env` (default: `GITHUB_TOKEN` for GitHub.com,
   `GITLAB_TOKEN` for GitLab.com)
@@ -1067,3 +1324,12 @@ jj log -r 'repoactive_unmerged()'
 jj log -r 'repoactive() & committer_date(after:"2025-01-01")'
 jj log -r 'repoactive() & description(regex:"(?m)^Repoactive-Job: uv-lock-upgrade$")'
 ```
+
+## Changelog
+
+User-facing changes are recorded in [CHANGELOG.md](CHANGELOG.md).
+
+## License
+
+`repoactive` is licensed under the
+[GNU General Public License v3.0 or later](LICENSE).