Allow checking out other repos in CI

[jpwilliams]

Summary

Allows checking out any repository, branch, tag, or commit from a ci.job(), as well as key a cache on another repository's files.

• checkout() now accepts checkout({ repo, ref })
• files("...") now accepts files("...", { repo, ref })
• Means that jobs with no natural repository such as cron runs can specify a repo too
• The chosen ref is resolved to a single commit and memoised per run

await checkout({ repo: "example/platform" });
await checkout({ repo: "example/platform", ref: "v2.1.0" });
await checkout({ ref: "main" });

const image = ci.job({
  id: "image",
  cache: {
    key: files("images/node-base/**", { repo: "example/platform", ref: "main" }),
  },
}, async () => {
  await checkout({ repo: "example/platform", ref: "main" });
  await $`docker build images/node-base`;
});

Checklist

• Added a docs PR that references this PR N/A Later bump
• Added unit/integration tests
• Added changesets if applicable

[changeset-bot]

🦋 Changeset detected

Latest commit: 9c9fedc

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@inngest/ci	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[Copilot]

🟡 Changes recommended

External refs are not pinned across invoked cache-build runs, and empty source options can be silently discarded.

2 open findings

• Cached builds may resolve a different source SHA · New
• Truthiness checks ignore explicitly empty repository or ref values · New

What changed in this PR

Adds cross-repository and ref-aware checkout and cache-file resolution to @inngest/ci.

Changes:

• Adds memoized repository/ref resolution with installation-aware authentication.
• Extends checkout() and files() with { repo, ref }.
• Adds tests, documentation, and a changeset.

File	Description
.changeset/​ci-checkout-repo.md	Records the minor release.
packages/​ci/​README.md	Documents cross-repository usage.
packages/​ci/​src/​cache/​cache.ts	Resolves and hashes files from selected sources.
packages/​ci/​src/​checkout/​checkout.ts	Checks out resolved external sources.
packages/​ci/​src/​github/​README.md	Lists the new source module.
packages/​ci/​src/​github/​auth.ts	Adds repository-scoped installation authentication.
packages/​ci/​src/​github/​source.test.ts	Tests source resolution and authentication.
packages/​ci/​src/​github/​source.ts	Implements memoized source resolution.
packages/​ci/​src/​index.ts	Exports FilesOptions.
packages/​ci/​src/​pipeline/​names.ts	Names ref-resolution steps.
packages/​ci/​src/​pipeline/​pipeline.ts	Initializes source memoization.
packages/​ci/​src/​pipeline/​scope.ts	Stores resolved sources per run.
packages/​ci/​src/​testing/​fakeGitHub.ts	Supports request-aware fake responses.
packages/​ci/​src/​types.ts	Defines file source options.
packages/​ci/​src/​util.ts	Adds repository parsing and memoization helpers.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[greptile-apps]

Confidence Score: 4/5

[High impact] Adds repository and ref resolution to the CI checkout system.

Pin remote commits across cached builds before merging so moving branches cannot break valid jobs.

Findings

1.  Moving branches break cached builds ▶
2.  Narrower patterns cannot fix truncation ▶

Fix with agent prompt

### Issue 1
packages/ci/src/cache/cache.ts:353
If a remote branch moves before a cached job's build starts, the build can fail permanently. `resolveKeySources()` pins the commit in the calling run, but `invokeBuild()` sends only the cache key, not the resolved sources. The build starts with an empty `sources` map and resolves the branch again. If matched files changed, `verifyBuildTarget()` rejects the build because its key differs.

Pass the pinned sources to the build and reuse them when checking the key and running `checkout()`.

### Issue 2
packages/ci/src/cache/cache.ts:221
The new error tells users to use narrower patterns, but both GitHub paths fetch the entire recursive tree. `hashTree()` rejects a truncated tree before applying patterns, so users following that advice get the same failure.

Remove that advice, or fetch only the requested subtrees so narrower patterns actually work.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

Adds repository and ref options to checkout() and files(), with shared commit lookup within each run.

• CI jobs can check out another repository at a chosen ref.
• Cache keys can follow files in another repository and ref.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A["checkout or files with repo/ref"] --> B["Resolve commit once in calling run"]
  B --> C["Checkout pinned commit"]
  B --> D["Hash matched files"]
  D --> E["Invoke cache build with computed key"]
  E --> F["Build starts with empty sources map"]
  F --> G["Resolve ref again"]
  G --> H{"Files still match caller's key?"}
  H -->|Yes| I["Reuse or build snapshot"]
  H -->|No| J["Reject build"]

Loading

_{Reviews (1) · Last reviewed commit: "refactor(ci): table the repeated source ..." · Reviewed by Greptile}