forge-ci 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aaedbe8086290f0420daa471c104aa0715a3ddc1bcacdb7062f43a5e04e7fb13
-  data.tar.gz: 1e718244f274b8184db6c7647a9bbec5ee250020eb735d58d40eb099a04722c2
+  metadata.gz: b7deaf8a35cd853691e015e86e2d0b4ce097e83609a1669c4303d5c60f7fe240
+  data.tar.gz: 391fa1dcaa79c33f7bf7af876b551d06128893e8dfffe48ecc702b7074d6daf6
 SHA512:
-  metadata.gz: '0694a54d72604d0c2ff44f5ff65fa94abdd8d7225f450119c0367aac2beec0f77933285e597e34cb9ec144628c106309db1aa106728c17f373b5600519c71755'
-  data.tar.gz: 3a055b45785bf5e5a3032ea73a4b97d4cd5940267d172e5fe00f4be068af68f282116742baf1eede753cf311de0faf5efbe8089e8f3f250fdbbb1ce63722057c
+  metadata.gz: c6964b6831ccc946d970b2bb214dc9c2cfb9447779862d65e04e731dd1ea1837eeb7469f604d0e8643527a54066ae48934834f3c88858bcc7fdf3149b3d30f40
+  data.tar.gz: 1b88099b87e003cdc4816b48a83a8ea5f5eabeb59602dc13ca6f37d5f807288244bcd30acdd783b4e08e5918b5b1a9cfbe6a8f76db54901812083fe77d9eb9ed

data/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+Versions of the `forge-ci` gem (the compiler and CLI). The control plane and
+runner are deployed from this repository's `main` and aren't versioned
+separately.
+
+## Unreleased
+
+## 0.3.0 (2026-10-24)
+
+- `setup_remote_docker` takes `docker_layer_caching: true`: the compiler
+  passes it to the IR (`layer_caching: true`) and rejects non-boolean values.
+  With `FORGE_CI_BUILD_CACHE_REGISTRY` on the server, such jobs get a
+  registry-backed layer cache (`forge-ci-build`, or Kamal via
+  `FORGE_CI_BUILD_CACHE_IMAGE`).
+- `gem install forge-ci` is the documented install; `rake build`,
+  `rake install` and `rake release` work from a checkout.
+- Gemspec metadata: source and changelog links, MFA required to publish.
+- The bundled agent skill installs the CLI with `gem install forge-ci`, and
+  covers `docker_layer_caching`.
+
+## 0.2.0 (2026-10-22)
+
+- `forge-ci trigger` (start a pipeline through the admin API, `--wait` for
+  the result) and `forge-ci cancel`.
+- `forge-ci skill install` / `forge-ci skill show`: the bundled agent skill
+  ships in the gem.
+- `parallelism:` reaches the IR (with `circleci tests` splitting in the
+  runner).
+- The compiler accepts `setup_remote_docker`, bare or with options.
+
+## 0.1.0
+
+- First release: `forge-ci validate` and `forge-ci compile`, compiling
+  CircleCI 2.1 configs (executors, commands, parameters, workflows,
+  `requires`, `matrix`, branch filters, caches, workspaces, artifacts) into
+  ForgeCI's IR.

data/README.md

@@ -44,7 +44,12 @@ control plane.
 - **Parallel test splitting.** `parallelism: N` with `circleci tests glob`,
   `split` and `run`.
 - **Scale to zero.** Idle runners remove themselves; the control plane scales
-  them back up when jobs queue.
+  them back up when jobs queue. Only tested with AWS EC2 Spot runners so far
+  (see [TODO.md](TODO.md#tested-so-far)).
+- **Registry-backed Docker layer caching.** `docker_layer_caching: true`
+  exports image layers to your registry during a build and restores them on
+  the next runner, so Spot reclamation never costs a full rebuild
+  (see [configuration](docs/configuration.md#docker-layer-caching)).
 - **Secrets done carefully.** Contexts are encrypted, masked in logs and never
   given to pull requests from forks.
 - **GitHub native.** Pipelines on push and pull request, private repos and
@@ -74,14 +79,18 @@ Coolify, S3, scaling to zero) see **[DEPLOY.md](DEPLOY.md)**.
 - **From any script, without the App:** `forge-ci trigger .circleci/config.yml --project myapp --wait`
   ([setup](DEPLOY.md#use-it-without-the-github-app)).
 
-Check a config locally first; the compiler needs only Ruby 3.0+:
+Check a config locally first; the compiler needs only Ruby 3.0+. `gem install`
+puts the `forge-ci` CLI on your PATH:
 
 ```sh
-gem build forge-ci.gemspec && gem install ./forge-ci-0.2.0.gem
+gem install forge-ci
 forge-ci validate .circleci/config.yml
 forge-ci compile .circleci/config.yml --branch main   # the jobs that will run on main
 ```
 
+Working from a checkout of this repo? `rake install` builds the gem from
+source and installs it the same way (`rake build` just produces the `.gem`).
+
 ```yaml
 # .circleci/config.yml
 version: 2.1

data/lib/forge_ci/ir.rb

@@ -111,9 +111,13 @@ module ForgeCI
           { type: "add_ssh_keys", fingerprints: cfg["fingerprints"] || [] }
         when "setup_remote_docker"
           # The runner gives the job its own Docker daemon (see the runner's
-          # ALLOW_DOCKER_SOCKET). `version` and `docker_layer_caching` don't
-          # apply: the runner's daemon and its layer cache are used as is.
-          { type: "setup_remote_docker" }
+          # ALLOW_DOCKER_SOCKET). `version` is ignored (the runner's daemon is
+          # what it is); `docker_layer_caching` asks for the registry-backed
+          # layer cache (FORGE_CI_BUILD_CACHE_REGISTRY on the server) so builds
+          # survive ephemeral runners.
+          step = { type: "setup_remote_docker" }
+          step[:layer_caching] = true if cfg["docker_layer_caching"] == true
+          step
         else
           raise Error, "internal error: unknown step type #{type.inspect} reached IR normalization"
         end

data/lib/forge_ci/validator.rb

@@ -313,9 +313,14 @@ module ForgeCI
       errors.add(path, "\"store_test_results:\" needs a \"path:\" to the JUnit XML results directory")
     end
 
-    # `version:` and `docker_layer_caching:` are accepted and ignored: the
-    # runner's own Docker daemon is used.
-    def validate_setup_remote_docker(_cfg, _path, _errors); end
+    # `version:` is ignored (the runner's daemon is what it is).
+    # `docker_layer_caching:` turns on the registry-backed layer cache.
+    def validate_setup_remote_docker(cfg, path, errors)
+      dlc = cfg["docker_layer_caching"]
+      return unless cfg.key?("docker_layer_caching") && ![true, false].include?(dlc)
+
+      errors.add(path + ["docker_layer_caching"], "\"docker_layer_caching:\" must be true or false")
+    end
 
     def validate_add_ssh_keys(cfg, path, errors)
       return unless cfg.key?("fingerprints") && !cfg["fingerprints"].is_a?(Array)

data/lib/forge_ci.rb

@@ -16,5 +16,5 @@ require_relative "forge_ci/compiler"
 # JSON-serializable intermediate representation (IR) that a scheduler and
 # runner can execute. Pure Ruby, stdlib only, no network, no processes.
 module ForgeCI
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/skills/forge-ci/SKILL.md

@@ -30,7 +30,12 @@ Write standard CircleCI 2.1. These are the differences that matter:
   runners set up with `ALLOW_DOCKER_SOCKET=1` accept it, normally just the
   deploy runner, so use it only on jobs with that runner's `resource_class`;
   elsewhere the job fails with an error. Pull requests from forks never get
-  it. `version:` and `docker_layer_caching:` are accepted and ignored.
+  it. `version:` is accepted and ignored. `docker_layer_caching: true` keeps
+  the image layer cache in a registry, if the server has
+  `FORGE_CI_BUILD_CACHE_REGISTRY`: build with `forge-ci-build` (it takes
+  `docker build` arguments), or point Kamal's `builder: cache: image:` at
+  `FORGE_CI_BUILD_CACHE_IMAGE`. Without the server setting the job logs a
+  warning and builds uncached.
 - **Lists, not strings:** `branches: only: [main]`, not `only: main`.
 - **Absolute paths:** the runner expands `~` to `/root`, but `cimg/*` images
   run as the `circleci` user. Use `/home/circleci/project` for
@@ -83,13 +88,15 @@ steps:
 
 ## Validate before you commit
 
-The CLI needs only Ruby 3.0+. If `forge-ci` isn't installed, run it from a
-checkout:
+The CLI needs only Ruby 3.0+. If `forge-ci` isn't installed, install it with
+`gem install forge-ci`. If you can't install gems, run it from a checkout:
 
 ```sh
 git clone --depth 1 https://github.com/azmi2409/forge-ci.git /tmp/forge-ci
 alias forge-ci="ruby -I/tmp/forge-ci/lib /tmp/forge-ci/exe/forge-ci"
+```
 
+```sh
 forge-ci validate .circleci/config.yml                    # must print "valid"
 forge-ci compile .circleci/config.yml --branch main       # the jobs that will run on main
 forge-ci compile .circleci/config.yml --branch my-feature # ...and on a branch

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: forge-ci
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Azmi Muwahid
@@ -19,6 +19,7 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - MIT-LICENSE
 - README.md
 - exe/forge-ci
@@ -34,7 +35,10 @@ files:
 homepage: https://github.com/azmi2409/forge-ci
 licenses:
 - MIT
-metadata: {}
+metadata:
+  source_code_uri: https://github.com/azmi2409/forge-ci
+  changelog_uri: https://github.com/azmi2409/forge-ci/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib