55 Commits
Author SHA1 Message Date
Gitea Bot e91adade9a Update the runner reference pages (#651)
Automated update of the generated runner reference pages from gitea/runner (main for the develop docs, the newest stable tag for every documented series), opened by the "update runner reference" scheduled workflow.

<!-- cloudflare-preview --> Preview: https://pr-651.docs-gitea-com.pages.dev

Reviewed-on: https://gitea.com/gitea/docs/pulls/651
Reviewed-by: silverwind <[email protected]>
Co-authored-by: Gitea Bot <[email protected]>
2026-11-17 08:38:34 +00:00
Gitea Bot d1af53182b Update the latest api documents (#650)
Automated update of static/swagger-latest.json and static/openapi3-latest.json from the gitea main branch, opened by the "update api spec files" scheduled workflow.

<!-- cloudflare-preview --> Preview: https://pr-650.docs-gitea-com.pages.dev

Reviewed-on: https://gitea.com/gitea/docs/pulls/650
Reviewed-by: silverwind <[email protected]>
Co-authored-by: Gitea Bot <[email protected]>
2026-11-17 08:38:24 +00:00
Renovate Botandsilverwind 01ce0b389a fix(deps): update dependencies (#649)
This PR contains the following updates:

| Package | Change | [Age](https://docs.renovatebot.com/merge-confidence/) | [Confidence](https://docs.renovatebot.com/merge-confidence/) |
|---|---|---|---|
| [@astrojs/starlight](https://starlight.astro.build) ([source](https://github.com/withastro/starlight/tree/HEAD/packages/starlight)) | [`0.42.8` → `0.42.10`](https://renovatebot.com/diffs/npm/@astrojs%2fstarlight/0.42.8/0.42.10) | ![age](https://developer.mend.io/api/mc/badges/age/npm/@astrojs%2fstarlight/0.42.10?slim=true) | ![confidence](https://developer.mend.io/api/mc/badges/confidence/npm/@astrojs%2fstarlight/0.42.8/0.42.10?slim=true) |
| [@astrojs/starlight-docsearch](https://starlight.astro.build) ([source](https://github.com/withastro/starlight/tree/HEAD/packages/docsearch)) | [`0.8.0` → `0.8.1`](https://renovatebot.com/diffs/npm/@astrojs%2fstarlight-docsearch/0.8.0/0.8.1) | ![age](https://developer.mend.io/api/mc/badges/age/npm/@astrojs%2fstarlight-docsearch/0.8.1?slim=true) | ![confidence](https://developer.mend.io/api/mc/badges/confidence/npm/@astrojs%2fstarlight-docsearch/0.8.0/0.8.1?slim=true) |
| [astro](https://astro.build) ([source](https://github.com/withastro/astro/tree/HEAD/packages/astro)) | [`7.4.5` → `7.4.7`](https://renovatebot.com/diffs/npm/astro/7.4.5/7.4.7) | ![age](https://developer.mend.io/api/mc/badges/age/npm/astro/7.4.7?slim=true) | ![confidence](https://developer.mend.io/api/mc/badges/confidence/npm/astro/7.4.5/7.4.7?slim=true) |
| [astro](https://astro.build) ([source](https://github.com/withastro/astro/tree/HEAD/packages/astro)) | [`^7.0.2` → `^7.4.7`](https://renovatebot.com/diffs/npm/astro/7.0.2/7.4.7) | ![age](https://developer.mend.io/api/mc/badges/age/npm/astro/7.4.7?slim=true) | ![confidence](https://developer.mend.io/api/mc/badges/confidence/npm/astro/7.0.2/7.4.7?slim=true) |
| [pnpm](https://pnpm.io) ([source](https://github.com/pnpm/pnpm/tree/HEAD/pnpm/npm/pnpm)) | [`12.17.0` → `12.20.0`](https://renovatebot.com/diffs/npm/pnpm/12.17.0/12.20.0) | ![age](https://developer.mend.io/api/mc/badges/age/npm/pnpm/12.20.0?slim=true) | ![confidence](https://developer.mend.io/api/mc/badges/confidence/npm/pnpm/12.17.0/12.20.0?slim=true) |
| [starlight-openapi](https://github.com/HiDeoo/starlight-openapi) ([source](https://github.com/HiDeoo/starlight-openapi/tree/HEAD/packages/starlight-openapi)) | [`0.27.0` → `0.27.1`](https://renovatebot.com/diffs/npm/starlight-openapi/0.27.0/0.27.1) | ![age](https://developer.mend.io/api/mc/badges/age/npm/starlight-openapi/0.27.1?slim=true) | ![confidence](https://developer.mend.io/api/mc/badges/confidence/npm/starlight-openapi/0.27.0/0.27.1?slim=true) |

---

### Astro: Image endpoint in @&#8203;astrojs/node can read files from a case-variant sibling of the output directory on case-sensitive filesystems
[CVE-2026-126364](https://nvd.nist.gov/vuln/detail/CVE-2026-126364) / [GHSA-r3h5-4585-7x3w](https://github.com/advisories/GHSA-r3h5-4585-7x3w)

<details>
<summary>More information</summary>

#### Details
##### Summary

The `/_image` endpoint used by the `@astrojs/node` adapter checks that a requested local image is inside the build output directory before reading it from disk. That check compared paths case-insensitively. On case-sensitive filesystems (such as Linux), a directory whose path differs from the output directory only by letter case is a different directory, but it passed the check.

For example, with the client output directory at `/srv/app/dist/client/`, a request such as:

```text
/_image?href=/../../DIST/client/secret.png&w=32&f=png
```

resolved to `/srv/app/DIST/client/secret.png` and was served, even though that file is outside the output directory.

##### Impact

An unauthenticated attacker can read image files from outside the output directory, but only when all of the following are true:

- The site uses on-demand rendering with the `@astrojs/node` adapter.
- The server runs on a case-sensitive filesystem.
- A directory exists whose path matches the output directory except for letter case (for example `DIST/client` next to `dist/client`). Such a layout is unusual, and the attacker cannot create it.

Only files the image service accepts can be read. Raster images are returned after resizing; SVG files are returned unchanged. Other file types fail during processing. Plain path traversal outside the output directory (for example `/../../secret.png`) was already rejected and is not affected.

##### Affected versions

`astro` >= 5.14.3, <= 7.4.6, when used with `@astrojs/node` (all versions up to 11.1.11). The vulnerable image endpoint is provided by `astro` and used by the `@astrojs/node` adapter.

##### Patches

Fixed in `astro` 7.4.7. The path check now compares paths exactly, and only ignores letter case for Windows drive-letter paths. The fix ships in `astro`, so upgrading `@astrojs/node` alone is not enough.

##### Workarounds

Upgrade to `astro` 7.4.7 or later. Before upgrading, make sure no directory next to the build output directory has a path that differs from it only by letter case.

##### Credits

Reported by @&#8203;zachariah-mithani.

#### Severity
- CVSS Score: 6.3 / 10 (Medium)
- Vector String: `CVSS:4.0/AV:N/AC:H/AT:P/PR:N/UI:N/VC:L/VI:N/VA:N/SC:N/SI:N/SA:N`

#### References
- [https://github.com/withastro/astro/security/advisories/GHSA-r3h5-4585-7x3w](https://github.com/withastro/astro/security/advisories/GHSA-r3h5-4585-7x3w)
- [https://nvd.nist.gov/vuln/detail/CVE-2026-126364](https://nvd.nist.gov/vuln/detail/CVE-2026-126364)
- [https://github.com/withastro/astro/commit/7da442bb286e0c29e1c9e1add6727b7cbf434f1a](https://github.com/withastro/astro/commit/7da442bb286e0c29e1c9e1add6727b7cbf434f1a)
- [https://github.com/withastro/astro](https://github.com/withastro/astro)
- [https://github.com/withastro/astro/releases/tag/[email protected]](https://github.com/withastro/astro/releases/tag/[email protected])

This data is provided by [OSV](https://osv.dev/vulnerability/GHSA-r3h5-4585-7x3w) and the [GitHub Advisory Database](https://github.com/github/advisory-database) ([CC-BY 4.0](https://github.com/github/advisory-database/blob/main/LICENSE.md)).
</details>

---

### Astro: Cross-site scripting via unescaped transition:* directive values on hydrated islands
[CVE-2026-59727](https://nvd.nist.gov/vuln/detail/CVE-2026-59727) / [GHSA-7pw4-f3q4-r2p2](https://github.com/advisories/GHSA-7pw4-f3q4-r2p2)

<details>
<summary>More information</summary>

#### Details
##### Summary

When a `transition:persist`, `transition:scope`, or `transition:persist-props` directive is applied to a client-hydrated (`client:*`) component, Astro copied the directive value onto the rendered `<astro-island>` element **without HTML-escaping it**. If a developer reflects attacker-controlled input into one of these directives, an attacker can break out of the attribute and inject arbitrary HTML/JavaScript into the server-rendered output, resulting in reflected cross-site scripting (XSS).

##### Severity

Although a generic reflected XSS scores in the Medium range, exploitation here requires the application developer to have written a non-idiomatic pattern — passing untrusted, request-derived input directly into a transition directive. Astro applications that do not route untrusted input into these directives are unaffected. This mitigating precondition places the real-world severity at Low.

##### Details

In `generateHydrateScript()` (`packages/astro/src/runtime/server/hydration.ts`), every island property is HTML-escaped before serialization — the `attrs`, `props`, and `opts` assignments all pass through `escapeHTML()`. The transition directives, however, were copied verbatim:

```ts
transitionDirectivesToCopyOnIsland.forEach((name) => {
  if (typeof props[name] !== 'undefined') {
    island.props[name] = props[name]; // not escaped
  }
});
```

The `<astro-island>` element is serialized via `renderElement('astro-island', island, false)` with `shouldEscape=false`, and `toAttributeString()` returns the value unchanged in that mode. As a result there is no downstream re-escaping, and the raw directive value reaches the HTML response. This is the same output sink previously addressed for slot names in GHSA-8hv8-536x-4wqp.

The affected directives are:

- `data-astro-transition-scope` (`transition:scope`)
- `data-astro-transition-persist` (`transition:persist`)
- `data-astro-transition-persist-props` (`transition:persist-props`)

Note that `transition:persist` is typed `boolean | string`, so passing a string value is a supported use of the API.

##### Proof of Concept

A component that reflects a query parameter into a transition directive:

```astro
---
const persist = Astro.url.searchParams.get('persist') ?? 'default';
---
<Island client:load transition:persist={persist} />
```

Request:

```
https://example.com/?persist="><img src=x onerror=alert(document.domain)>
```

Rendered output (before the fix):

```html
<astro-island … data-astro-transition-persist=""><img src=x onerror=alert(document.domain)>></astro-island>
```

The `"` closes the attribute and the injected `<img onerror=…>` executes in the victim's browser.

##### Impact

Reflected XSS. An attacker who can induce a victim to visit a crafted URL can execute arbitrary script in the victim's session on the origin, subject to the requirement that the target application reflects untrusted input into one of the affected transition directives.

##### Affected Versions

`astro >= 3.10.0, < 7.0.4` (introduced in 3.10.0, PR #&#8203;7861).

##### Patched Versions

`astro >= 7.0.4`. Fixed in PR #&#8203;17212 by HTML-escaping transition directive values before they are rendered onto the island element.

##### Workarounds

Do not pass untrusted or request-derived input into `transition:persist`, `transition:scope`, or `transition:persist-props`. If such input is required, HTML-escape or strictly validate it before passing it to the directive. Upgrading to `[email protected]` or later removes the need for manual mitigation.

##### Credits

Reported by @&#8203;jlgore.

#### Severity
- CVSS Score: 2.1 / 10 (Low)
- Vector String: `CVSS:4.0/AV:N/AC:L/AT:P/PR:N/UI:A/VC:N/VI:N/VA:N/SC:L/SI:L/SA:N`

#### References
- [https://github.com/withastro/astro/security/advisories/GHSA-7pw4-f3q4-r2p2](https://github.com/withastro/astro/security/advisories/GHSA-7pw4-f3q4-r2p2)
- [https://nvd.nist.gov/vuln/detail/CVE-2026-59727](https://nvd.nist.gov/vuln/detail/CVE-2026-59727)
- [https://github.com/withastro/astro/pull/17212](https://github.com/withastro/astro/pull/17212)
- [https://github.com/withastro/astro/commit/7ba0bb1dc7516e88caff9abd7767322af44b0294](https://github.com/withastro/astro/commit/7ba0bb1dc7516e88caff9abd7767322af44b0294)
- [https://github.com/withastro/astro](https://github.com/withastro/astro)
- [https://github.com/withastro/astro/releases/tag/[email protected]](https://github.com/withastro/astro/releases/tag/[email protected])

This data is provided by [OSV](https://osv.dev/vulnerability/GHSA-7pw4-f3q4-r2p2) and the [GitHub Advisory Database](https://github.com/github/advisory-database) ([CC-BY 4.0](https://github.com/github/advisory-database/blob/main/LICENSE.md)).
</details>

---

### Astro: composable `astro/hono` pipeline bypasses `security.checkOrigin` when `middleware()` is absent or misordered
[CVE-2026-73423](https://nvd.nist.gov/vuln/detail/CVE-2026-73423) / [GHSA-8mv7-9c27-98vc](https://github.com/advisories/GHSA-8mv7-9c27-98vc)

<details>
<summary>More information</summary>

#### Details
##### Summary

In the composable `astro/hono` pipeline, the `security.checkOrigin` protection is only installed by the `middleware()` primitive. The `actions()` and `pages()` primitives each dispatch to user code independently, so a pipeline that mounts either primitive before (or without) `middleware()` will bypass the origin check for those requests.

##### Details

`security.checkOrigin` (default: `true`) is intended to reject cross-site `POST`/`PUT`/`PATCH`/`DELETE` form submissions. In the classic pipeline (`astro()` all-in-one), the check always runs because Astro injects a virtual middleware module even when the user has no `src/middleware.ts`. In the composable `astro/hono` pipeline, the user assembles primitives manually. The check is only installed inside `middleware()` — so:

- Mounting `actions()` before `middleware()` allows cross-origin form-encoded action requests to execute before the gate runs. The `examples/advanced-routing` example and the Cloudflare `hono` docs shipped this order.
- Omitting `middleware()` entirely (reasonable for apps with no custom middleware) silently drops `checkOrigin` protection for all on-demand endpoints and pages dispatched through `pages()`.

The attack is a blind write-only CSRF: the attacker can trigger a state-mutating action or endpoint handler using the victim's cookies, but cannot read the cross-origin response body.

##### Affected versions

Astro `>= 7.0.0` when using the composable `astro/hono` pipeline with either:
- `actions()` mounted before `middleware()`, or
- `pages()` used without `middleware()`

The default (non-composable) pipeline is not affected.

##### Fix

The origin check is now applied at each dispatch sink (`ActionHandler.handle` and `PagesHandler.handleWithErrorFallback`), gated on `manifest.checkOrigin`, using the same predicate as the middleware. The check is order-independent and a no-op when `middleware()` has already run.

Fix: https://github.com/withastro/astro/pull/17250

##### Workaround

Ensure `middleware()` is mounted before both `actions()` and `pages()` in the composable pipeline, and that it is always included even when no custom middleware logic is needed:

```ts
app.use(middleware());
app.use(actions());
app.use(pages());
```

#### Severity
- CVSS Score: 5.1 / 10 (Medium)
- Vector String: `CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:A/VC:N/VI:N/VA:N/SC:N/SI:L/SA:N`

#### References
- [https://github.com/withastro/astro/security/advisories/GHSA-8mv7-9c27-98vc](https://github.com/withastro/astro/security/advisories/GHSA-8mv7-9c27-98vc)
- [https://github.com/withastro/astro/pull/17250](https://github.com/withastro/astro/pull/17250)
- [https://github.com/withastro/astro/commit/0b30b35f864310bee8485c952d1877e82e2b9b1a](https://github.com/withastro/astro/commit/0b30b35f864310bee8485c952d1877e82e2b9b1a)
- [https://github.com/withastro/astro](https://github.com/withastro/astro)
- [https://github.com/withastro/astro/releases/tag/[email protected]](https://github.com/withastro/astro/releases/tag/[email protected])

This data is provided by [OSV](https://osv.dev/vulnerability/GHSA-8mv7-9c27-98vc) and the [GitHub Advisory Database](https://github.com/github/advisory-database) ([CC-BY 4.0](https://github.com/github/advisory-database/blob/main/LICENSE.md)).
</details>

---

### Astro: XSS via unescaped spread attribute names in renderHTMLElement (incomplete fix for CVE-2026-54298)
[CVE-2026-59729](https://nvd.nist.gov/vuln/detail/CVE-2026-59729) / [GHSA-f48w-9m4c-m7f5](https://github.com/advisories/GHSA-f48w-9m4c-m7f5)

<details>
<summary>More information</summary>

#### Details
##### Summary

The fix for CVE-2026-54298 (GHSA-jrpj-wcv7-9fh9) added an `INVALID_ATTR_NAME_CHAR` guard to `addAttribute()` so that spread-prop attribute names containing `"' >/=` or whitespace are dropped. A second attribute-rendering path, `renderHTMLElement()` in `packages/astro/src/runtime/server/render/dom.ts`, has its own inline attribute loop that does not go through `addAttribute()` and was not updated. It interpolates the attribute name unescaped and only escapes the value, so untrusted prop keys spread onto a native-`HTMLElement`-subclass component can still break out of the attribute context, resulting in XSS.

##### Details

`renderHTMLElement` builds attributes directly:

```js
for (const attr in props) {
  attrHTML += ` ${attr}="${toAttributeString(await props[attr])}"`;
}
```

The attribute name (`attr`) is interpolated raw; only the value is escaped via `toAttributeString`. By contrast, the hardened `addAttribute` in `util.ts` rejects invalid names:

```js
if (INVALID_ATTR_NAME_CHAR.test(key)) { return ''; } // /[\s"'>/=]/
```

`renderHTMLElement` is reached from `component.ts` when the component is a native `HTMLElement` subclass:

```js
if (!renderer && typeof HTMLElement === 'function' && componentIsHTMLElement(Component)) {
  const output = await renderHTMLElement(result, Component, _props, slots);
}
```

where `_props` carries spread props verbatim.

##### Reachability

The branch only runs when `typeof HTMLElement === 'function'` at SSR time. In default Node SSR `HTMLElement` is `undefined`, so the branch is dead. It becomes reachable when the SSR runtime exposes a global `HTMLElement` (Deno, Bun with a DOM shim, or jsdom/happy-dom in Node) **and** a class extending `HTMLElement` is used directly as an Astro component that receives untrusted-keyed spread props.

##### Proof of Concept

Given malicious spread props:

```js
const maliciousProps = {
  'onmouseover=alert(document.domain) x': 'y',
  'x><script>alert(1)</script>': 'z',
};
```

- `addAttribute` (post-fix) → `<my-el></my-el>` (key stripped — safe)
- `renderHTMLElement` → `<my-el onmouseover=alert(document.domain) x="y" x><script>alert(1)</script>="z"></my-el>` (handler + `<script>` injected — XSS)

Equivalent Astro template, served by an SSR runtime that defines a global `HTMLElement`:

```astro
---
import MyElement from '../MyElement.js'; // class MyElement extends HTMLElement {}
const userInput = Astro.url.searchParams;  // untrusted keys
---
<MyElement {...Object.fromEntries(userInput)} />
```

##### Impact

Cross-site scripting (CWE-79) via attribute-name breakout — the same vulnerability class as CVE-2026-54298, in a code path its fix did not cover. An attacker who controls the keys of an object spread onto a native-`HTMLElement`-subclass component can inject arbitrary event-handler attributes or sibling elements (including `<script>`) into the SSR output. Reachability is constrained by the runtime and component preconditions described above.

#### Severity
- CVSS Score: 5.1 / 10 (Medium)
- Vector String: `CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:A/VC:N/VI:N/VA:N/SC:L/SI:L/SA:N`

#### References
- [https://github.com/withastro/astro/security/advisories/GHSA-f48w-9m4c-m7f5](https://github.com/withastro/astro/security/advisories/GHSA-f48w-9m4c-m7f5)
- [https://nvd.nist.gov/vuln/detail/CVE-2026-59729](https://nvd.nist.gov/vuln/detail/CVE-2026-59729)
- [https://github.com/withastro/astro/pull/17251](https://github.com/withastro/astro/pull/17251)
- [https://github.com/withastro/astro/commit/5240e26c9dd91f9bc7140dcfacdb48d5a132830d](https://github.com/withastro/astro/commit/5240e26c9dd91f9bc7140dcfacdb48d5a132830d)
- [https://github.com/withastro/astro](https://github.com/withastro/astro)
- [https://github.com/withastro/astro/releases/tag/[email protected]](https://github.com/withastro/astro/releases/tag/[email protected])

This data is provided by [OSV](https://osv.dev/vulnerability/GHSA-f48w-9m4c-m7f5) and the [GitHub Advisory Database](https://github.com/github/advisory-database) ([CC-BY 4.0](https://github.com/github/advisory-database/blob/main/LICENSE.md)).
</details>

---

### Astro: Reflected XSS via unescaped View Transition animation properties
[CVE-2026-73422](https://nvd.nist.gov/vuln/detail/CVE-2026-73422) / [GHSA-4g3v-8h47-v7g6](https://github.com/advisories/GHSA-4g3v-8h47-v7g6)

<details>
<summary>More information</summary>

#### Details
##### Summary

Astro's server-side View Transition CSS generator interpolates animation properties into an inline `<style>` element without escaping them for the CSS and HTML contexts.

An attacker-controlled value passed to an animation property such as `duration` can contain a `</style>` sequence, terminate the generated style element, and inject arbitrary HTML or JavaScript.

This is similar to GHSA-8hv8-536x-4wqp, but exploits a different injection point: unescaped View Transition animation values in a server-generated `<style>` element rather than an unescaped slot name in a hydration template.

Like GHSA-8hv8-536x-4wqp, exploitation requires an application to pass attacker-controlled data to an Astro API. However, the value is subsequently inserted into the HTML response without context-appropriate escaping by Astro.

##### Details

`packages/astro/src/runtime/server/transition.ts`

The generated stylesheet is wrapped in a `<style>` element and marked as HTML-safe:

```ts
const css = sheet.toString();
result._metadata.extraHead.push(markHTMLString(`<style>${css}</style>`));
```

Animation properties are added to the stylesheet without escaping:

```ts
if (anim.duration) {
  addAnimationProperty(builder, 'animation-duration', toTimeValue(anim.duration));
}
```

For string values, `toTimeValue()` returns the input unchanged:

```ts
export function toTimeValue(num: number | string) {
  return typeof num === 'number' ? num + 'ms' : num;
}
```

As a result, a `duration` value containing `</style>` can escape from the generated style element.

Other `TransitionAnimation` properties, including `easing`, `direction`, `delay`, `fillMode`, and `name`, are serialized by the same animation builder. The following PoC only relies on the official `fade()` helper and its `duration` option.

##### PoC

Using:

- `[email protected]`
- `@astrojs/[email protected]`

##### `astro.config.mjs`

```js
import node from '@astrojs/node';
import { defineConfig } from 'astro/config';

export default defineConfig({
  output: 'server',
  adapter: node({ mode: 'standalone' }),
});
```

##### `src/pages/index.astro`

```astro
---
import { fade } from 'astro:transitions';

const duration = Astro.url.searchParams.get('duration') ?? '300ms';
---

<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>PoC</title>
  </head>
  <body>
    <div transition:animate={fade({ duration })}>
      Animated content
    </div>
  </body>
</html>
```

##### Payload:

open:

```text
http://localhost:4321/?duration=%3C%2Fstyle%3E%3Cscript%3Ealert(1)%3C%2Fscript%3E%3C!--
```

The browser interprets `</style>` as the end of the generated style element and executes the injected script. An alert dialog is displayed when the page is opened.

<img width="1307" height="681" alt="image" src="https://github.com/user-attachments/assets/0834236d-008f-415f-9f23-db509ab6f8f6" />

##### Impact

An attacker who can control a View Transition animation value can execute arbitrary JavaScript in the origin of the affected Astro application.

The query-based reflected XSS scenario affects on-demand/server-rendered routes, such as:

- projects configured with `output: "server"`;
- pages using `export const prerender = false`;
- other server-side data flows that pass attacker-controlled values into a View Transition animation definition.

Successful exploitation may allow access to sensitive page data and authenticated actions available to the victim.

##### Suggested Fix

Animation values should be serialized using context-appropriate CSS escaping or validation before being added to the generated stylesheet.

Additionally, content inserted into a raw `<style>` element must not be able to contain an HTML end-tag sequence such as `</style>`. The final generated CSS should be made safe for the HTML raw-text context before it is passed to `markHTMLString()`.

#### Severity
- CVSS Score: 5.3 / 10 (Medium)
- Vector String: `CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:P/VC:N/VI:N/VA:N/SC:L/SI:L/SA:N`

#### References
- [https://github.com/withastro/astro/security/advisories/GHSA-4g3v-8h47-v7g6](https://github.com/withastro/astro/security/advisories/GHSA-4g3v-8h47-v7g6)
- [https://github.com/withastro/astro/pull/17393](https://github.com/withastro/astro/pull/17393)
- [https://github.com/withastro/astro/commit/092da560eea77ee63a3e2c583c80d8238544e42b](https://github.com/withastro/astro/commit/092da560eea77ee63a3e2c583c80d8238544e42b)
- [https://github.com/withastro/astro](https://github.com/withastro/astro)
- [https://github.com/withastro/astro/releases/tag/[email protected]](https://github.com/withastro/astro/releases/tag/[email protected])

This data is provided by [OSV](https://osv.dev/vulnerability/GHSA-4g3v-8h47-v7g6) and the [GitHub Advisory Database](https://github.com/github/advisory-database) ([CC-BY 4.0](https://github.com/github/advisory-database/blob/main/LICENSE.md)).
</details>

---

### Astro: Authorization bypass from missing path-segment boundary check when stripping the configured base
[CVE-2026-84376](https://nvd.nist.gov/vuln/detail/CVE-2026-84376) / [GHSA-376h-93r7-7g6f](https://github.com/advisories/GHSA-376h-93r7-7g6f)

<details>
<summary>More information</summary>

#### Details
##### Summary

Astro stripped a configured `base` path from request pathnames using a string-prefix check that did not verify a path-segment boundary. With `base: "/app"`, a request to `/appX/admin` was treated as being under the base and resolved internally to the `/admin` route, while middleware still observed the public pathname `/appX/admin`. Middleware that authorizes routes by inspecting `context.url.pathname` could therefore be bypassed.

##### Impact

An unauthenticated remote attacker can bypass pathname-based middleware authorization in applications that:

- Configure a non-root `base`.
- Protect base-prefixed routes in middleware using `context.url.pathname`.

Because routing and middleware resolved different effective pathnames, a request such as `/appX/admin` (or other single-character extensions like `/app2/admin` or `/app-/admin`) reached the protected `/admin` route without passing the middleware check that guards `/app/admin`. Astro's authentication guide demonstrates protecting routes in middleware via `context.url.pathname`, so this is a reasonable and expected pattern.

##### Affected versions

`astro` <= 7.2.3.

##### Patches

Fixed in `astro` 7.2.4. Base stripping now requires the pathname to equal the base without its trailing slash, or to be followed by a `/`, so a prefix that does not end on a path-segment boundary is no longer treated as being under the base. Routing and `context.url.pathname` now resolve the same pathname.

##### Workarounds

Upgrade to `astro` 7.2.4 or later. As a mitigation before upgrading, avoid relying solely on prefix checks of `context.url.pathname` for authorization, or reject requests whose pathname does not begin with the configured base followed by a path-segment boundary.

##### Credits

Reported by @&#8203;Ryoga-exe.

#### Severity
- CVSS Score: 6.3 / 10 (Medium)
- Vector String: `CVSS:4.0/AV:N/AC:L/AT:P/PR:N/UI:N/VC:L/VI:L/VA:N/SC:N/SI:N/SA:N`

#### References
- [https://github.com/withastro/astro/security/advisories/GHSA-376h-93r7-7g6f](https://github.com/withastro/astro/security/advisories/GHSA-376h-93r7-7g6f)
- [https://nvd.nist.gov/vuln/detail/CVE-2026-84376](https://nvd.nist.gov/vuln/detail/CVE-2026-84376)
- [https://github.com/withastro/astro/pull/17701](https://github.com/withastro/astro/pull/17701)
- [https://github.com/withastro/astro/commit/05763a0884aabb1da78a2749d5bb9d41ae620527](https://github.com/withastro/astro/commit/05763a0884aabb1da78a2749d5bb9d41ae620527)
- [https://github.com/withastro/astro](https://github.com/withastro/astro)
- [https://github.com/withastro/astro/releases/tag/[email protected]](https://github.com/withastro/astro/releases/tag/[email protected])

This data is provided by [OSV](https://osv.dev/vulnerability/GHSA-376h-93r7-7g6f) and the [GitHub Advisory Database](https://github.com/github/advisory-database) ([CC-BY 4.0](https://github.com/github/advisory-database/blob/main/LICENSE.md)).
</details>

---

### Astro: Remote code execution through AVIF image optimization
[GHSA-26w7-cxv4-gfx2](https://github.com/advisories/GHSA-26w7-cxv4-gfx2)

<details>
<summary>More information</summary>

#### Details
A vulnerability in `libheif`, used by the default Sharp image service in Astro, can lead to remote code execution when a malicious AVIF image is optimized.

Projects are affected when an attacker can cause Astro to process an untrusted AVIF image.

The fix was released in Astro 7.2.8, which requires Sharp 0.35.4.

#### Severity
- CVSS Score: 9.8 / 10 (Critical)
- Vector String: `CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H`

#### References
- [https://github.com/strukturag/libheif/security/advisories/GHSA-g89c-p67h-r497](https://github.com/strukturag/libheif/security/advisories/GHSA-g89c-p67h-r497)
- [https://github.com/withastro/astro/security/advisories/GHSA-26w7-cxv4-gfx2](https://github.com/withastro/astro/security/advisories/GHSA-26w7-cxv4-gfx2)
- [https://github.com/withastro/astro/commit/ecb4082131490b4fe9a56aa44fda84b54ef8967b](https://github.com/withastro/astro/commit/ecb4082131490b4fe9a56aa44fda84b54ef8967b)
- [https://github.com/withastro/astro](https://github.com/withastro/astro)
- [https://github.com/withastro/astro/releases/tag/[email protected]](https://github.com/withastro/astro/releases/tag/[email protected])

This data is provided by [OSV](https://osv.dev/vulnerability/GHSA-26w7-cxv4-gfx2) and the [GitHub Advisory Database](https://github.com/github/advisory-database) ([CC-BY 4.0](https://github.com/github/advisory-database/blob/main/LICENSE.md)).
</details>

---

### Astro: Reflected/Stored XSS via unescaped <script>/<style> tag content in JSX/MDX rendering
[CVE-2026-114128](https://nvd.nist.gov/vuln/detail/CVE-2026-114128) / [GHSA-98hj-9722-w3j8](https://github.com/advisories/GHSA-98hj-9722-w3j8)

<details>
<summary>More information</summary>

#### Details
##### Summary

Astro's JSX and MDX rendering pipeline treated string children of `<script>` and `<style>` elements as trusted HTML. When a dynamic value was passed through a JSX expression, such as `<script>{value}</script>`, an attacker-controlled value containing `</script>` or `</style>` could terminate the element and inject arbitrary HTML and JavaScript.

Other JSX expression contexts escaped dynamic strings automatically. This behavior was limited to `<script>` and `<style>` children rendered through Astro's `astro:jsx` renderer, including MDX components.

##### Details

The affected rendering paths marked all string children of `<script>` and `<style>` elements as safe HTML, without distinguishing literal content generated by the compiler from dynamic expression values. An application was vulnerable when attacker-controlled data, such as a query parameter or CMS field, was interpolated directly into one of these elements.

For example, a value containing `</script><script>alert(1)</script>` passed to `<script>{value}</script>` was emitted without escaping. The browser interpreted the first closing tag as markup and executed the injected script.

The fix preserves raw rendering for literal script and style content while escaping dynamic string children like other JSX expression values.

##### Impact

Affected applications could be vulnerable to reflected or stored cross-site scripting. Exploitation required an application to pass attacker-controlled data directly as a dynamic child of a `<script>` or `<style>` element in MDX or through the `astro:jsx` runtime. Successful exploitation allowed arbitrary JavaScript execution in the victim's browser under the application's origin.

##### Patches

This issue is patched in `[email protected]`.

##### Workarounds

Do not interpolate untrusted dynamic values directly into `<script>` or `<style>` element children. Applications that cannot upgrade should validate and contextually encode these values before rendering them.

##### Credit

Reported by [@&#8203;RKasai127](https://github.com/RKasai127).

#### Severity
- CVSS Score: 6.5 / 10 (Medium)
- Vector String: `CVSS:3.1/AV:N/AC:L/PR:N/UI:R/S:U/C:N/I:H/A:N`

#### References
- [https://github.com/withastro/astro/security/advisories/GHSA-98hj-9722-w3j8](https://github.com/withastro/astro/security/advisories/GHSA-98hj-9722-w3j8)
- [https://nvd.nist.gov/vuln/detail/CVE-2026-114128](https://nvd.nist.gov/vuln/detail/CVE-2026-114128)
- [https://github.com/withastro/astro/pull/17896](https://github.com/withastro/astro/pull/17896)
- [https://github.com/withastro/astro/commit/a548223607b9bb146d5d90ddda495343f9a2a739](https://github.com/withastro/astro/commit/a548223607b9bb146d5d90ddda495343f9a2a739)
- [https://github.com/withastro/astro](https://github.com/withastro/astro)
- [https://github.com/withastro/astro/releases/tag/[email protected]](https://github.com/withastro/astro/releases/tag/[email protected])

This data is provided by [OSV](https://osv.dev/vulnerability/GHSA-98hj-9722-w3j8) and the [GitHub Advisory Database](https://github.com/github/advisory-database) ([CC-BY 4.0](https://github.com/github/advisory-database/blob/main/LICENSE.md)).
</details>

---

### Astro: XSS via attribute injection in dynamic tag names
[CVE-2026-126361](https://nvd.nist.gov/vuln/detail/CVE-2026-126361) / [GHSA-mh32-jxcr-mh9f](https://github.com/advisories/GHSA-mh32-jxcr-mh9f)

<details>
<summary>More information</summary>

#### Details
##### Summary

When a dynamic tag (`const Tag = ...; <Tag />`) resolves to a string, Astro renders it as a raw HTML element name. The name was filtered to remove characters that could inject attributes, but the filter did not handle `/`. Because HTML parsers treat `/` inside a tag as an attribute separator, a tag name such as `img/src/onerror=alert(1)` was rendered as an `<img>` element with an `onerror` attribute. The JSX renderer used for MDX did not filter string tag names at all.

For example:

```astro
---
const Tag = Astro.url.searchParams.get('as') ?? 'div';
---
<Tag>hello</Tag>
```

rendered `?as=img/src/onerror=alert(1)` as live HTML.

##### Impact

Reflected or stored cross-site scripting, but only in applications that use untrusted input (such as a request parameter or an uncontrolled CMS field) as all or part of an element name. Astro itself never derives element names from request data.

Applications that let content choose an element should map that input to a fixed set of known tags. Letting untrusted input choose an element name is unsafe even with a correct filter, because it can still select elements such as `script` or `iframe`.

##### Affected versions

`astro` <= 7.4.4.

##### Patches

Fixed in `astro` 7.4.5. String tag names in `.astro` dynamic tags, JSX, and MDX now render only the leading valid element name, so characters such as `/` or `=` can no longer change the generated markup. Strings that do not start with a valid element name now throw an error.

##### Workarounds

Upgrade to `astro` 7.4.5 or later. Before upgrading, do not use untrusted input as an element name, or map it to a fixed set of known tags.

##### Credits

Reported by @&#8203;uttej-badwane.

#### Severity
- CVSS Score: 2.3 / 10 (Low)
- Vector String: `CVSS:4.0/AV:N/AC:L/AT:P/PR:N/UI:P/VC:L/VI:L/VA:N/SC:L/SI:L/SA:N`

#### References
- [https://github.com/withastro/astro/security/advisories/GHSA-mh32-jxcr-mh9f](https://github.com/withastro/astro/security/advisories/GHSA-mh32-jxcr-mh9f)
- [https://nvd.nist.gov/vuln/detail/CVE-2026-126361](https://nvd.nist.gov/vuln/detail/CVE-2026-126361)
- [https://github.com/withastro/astro/pull/18520](https://github.com/withastro/astro/pull/18520)
- [https://github.com/withastro/astro/commit/e023abac912d7cb6af2b9fb5107ef5dabc667096](https://github.com/withastro/astro/commit/e023abac912d7cb6af2b9fb5107ef5dabc667096)
- [https://github.com/withastro/astro](https://github.com/withastro/astro)
- [https://github.com/withastro/astro/releases/tag/[email protected]](https://github.com/withastro/astro/releases/tag/[email protected])

This data is provided by [OSV](https://osv.dev/vulnerability/GHSA-mh32-jxcr-mh9f) and the [GitHub Advisory Database](https://github.com/github/advisory-database) ([CC-BY 4.0](https://github.com/github/advisory-database/blob/main/LICENSE.md)).
</details>

---

### Release Notes

<details>
<summary>withastro/starlight (@&#8203;astrojs/starlight)</summary>

### [`v0.42.10`](https://github.com/withastro/starlight/blob/HEAD/packages/starlight/CHANGELOG.md#04210)

[Compare Source](https://github.com/withastro/starlight/compare/@astrojs/[email protected]...@astrojs/[email protected])

##### Patch Changes

- [#&#8203;4354](https://github.com/withastro/starlight/pull/4354) [`56b8587`](https://github.com/withastro/starlight/commit/56b85878982b6e2502310fd0e427a9331f90ea8f) Thanks [@&#8203;jasikpark](https://github.com/jasikpark)! - Improves the color contrast of the search input placeholder text

- [#&#8203;4337](https://github.com/withastro/starlight/pull/4337) [`c5d0a7f`](https://github.com/withastro/starlight/commit/c5d0a7fb0b9788d52d8f5345c6661f18e100359e) Thanks [@&#8203;moonmeister](https://github.com/moonmeister)! - Fixes search not loading when the search script runs after the page has finished loading, for example when a Content Security Policy requires scripts to be added dynamically

- [#&#8203;4352](https://github.com/withastro/starlight/pull/4352) [`3edab29`](https://github.com/withastro/starlight/commit/3edab29e42a9d786c7f79054b402fb3b7c6ba531) Thanks [@&#8203;delucis](https://github.com/delucis)! - Fixes the Astro `trailingSlash` and `build.format` options not being applied correctly to sidebar links that include a query string or hash

### [`v0.42.9`](https://github.com/withastro/starlight/blob/HEAD/packages/starlight/CHANGELOG.md#0429)

[Compare Source](https://github.com/withastro/starlight/compare/@astrojs/[email protected]...@astrojs/[email protected])

##### Patch Changes

- [#&#8203;4218](https://github.com/withastro/starlight/pull/4218) [`effea21`](https://github.com/withastro/starlight/commit/effea2172f631f00a6e4d38643587fc4ab22ff71) Thanks [@&#8203;delucis](https://github.com/delucis)! - Reduces install size by \~400 KB by switching the YAML parser used internally for projects using Astro 7.3.6 or later

- [#&#8203;4316](https://github.com/withastro/starlight/pull/4316) [`8679b1c`](https://github.com/withastro/starlight/commit/8679b1c3326b6a3992aa0869b1c968cd2af2608a) Thanks [@&#8203;clean99](https://github.com/clean99)! - Fixes localized routes and language switcher links for pages in directories named like `Object.prototype` properties, such as `constructor`.

- [#&#8203;4341](https://github.com/withastro/starlight/pull/4341) [`e1ac1b4`](https://github.com/withastro/starlight/commit/e1ac1b47aaae2504cb48285ec384c011fa6c4675) Thanks [@&#8203;delucis](https://github.com/delucis)! - Prevents tables overflowing and clipping when printing a page

</details>

<details>
<summary>withastro/starlight (@&#8203;astrojs/starlight-docsearch)</summary>

### [`v0.8.1`](https://github.com/withastro/starlight/blob/HEAD/packages/docsearch/CHANGELOG.md#081)

[Compare Source](https://github.com/withastro/starlight/compare/@astrojs/[email protected]...@astrojs/[email protected])

##### Patch Changes

- [#&#8203;4337](https://github.com/withastro/starlight/pull/4337) [`c5d0a7f`](https://github.com/withastro/starlight/commit/c5d0a7fb0b9788d52d8f5345c6661f18e100359e) Thanks [@&#8203;moonmeister](https://github.com/moonmeister)! - Fixes DocSearch not loading when its script runs after the page has finished loading, for example when a Content Security Policy requires scripts to be added dynamically

</details>

<details>
<summary>withastro/astro (astro)</summary>

### [`v7.4.7`](https://github.com/withastro/astro/blob/HEAD/packages/astro/CHANGELOG.md#747)

[Compare Source](https://github.com/withastro/astro/compare/[email protected]@7.4.7)

##### Patch Changes

- [`7da442b`](https://github.com/withastro/astro/commit/7da442bb286e0c29e1c9e1add6727b7cbf434f1a) Thanks [@&#8203;matthewp](https://github.com/matthewp)! - Fixes the image endpoint treating directories whose names differ only by letter case as being inside the build output directory on case-sensitive filesystems
- Updated dependencies \[[`7da442b`](https://github.com/withastro/astro/commit/7da442bb286e0c29e1c9e1add6727b7cbf434f1a)]:
  - [@&#8203;astrojs/internal-helpers](https://github.com/astrojs/internal-helpers)@0.13.1
  - [@&#8203;astrojs/markdown-satteri](https://github.com/astrojs/markdown-satteri)@0.4.7

### [`v7.4.6`](https://github.com/withastro/astro/blob/HEAD/packages/astro/CHANGELOG.md#746)

[Compare Source](https://github.com/withastro/astro/compare/[email protected]@7.4.6)

##### Patch Changes

- [#&#8203;18565](https://github.com/withastro/astro/pull/18565) [`cd09986`](https://github.com/withastro/astro/commit/cd0998612eb9f48946991479d68590a1407ee5e0) Thanks [@&#8203;praveen-kumary](https://github.com/praveen-kumary)! - Avoids attributing client-only components or scripts to unrelated pages importing `astro:i18n` by bounding top-level page graph traversal at virtual page entries

- [#&#8203;18608](https://github.com/withastro/astro/pull/18608) [`babd96d`](https://github.com/withastro/astro/commit/babd96d1f16b8ea5a699693fb725a759d9fa03de) Thanks [@&#8203;umeraamir69](https://github.com/umeraamir69)! - Fixes an extra page reload on the first page load after starting `astro dev` without an existing `.astro` directory

- [#&#8203;18589](https://github.com/withastro/astro/pull/18589) [`402c0fa`](https://github.com/withastro/astro/commit/402c0fae01d251c97298c255804008ff566802f9) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes `astro check` exiting with code 0 when `@astrojs/check` or `typescript` is not installed. The command now exits with code 1 so CI fails instead of silently skipping type checking.

- [#&#8203;18503](https://github.com/withastro/astro/pull/18503) [`54fcdd5`](https://github.com/withastro/astro/commit/54fcdd5dedc982a77f1590e26247d57dd1802da9) Thanks [@&#8203;SwastikTripathi](https://github.com/SwastikTripathi)! - Preserves the last-modified date of cached font files and unchanged public files when copying them into the build output. Public-file timestamp preservation respects the resolved public-directory configuration, follows source symlinks, and avoids backdating files overwritten by build plugins.

- [#&#8203;18605](https://github.com/withastro/astro/pull/18605) [`76cd239`](https://github.com/withastro/astro/commit/76cd2398642bd77b61b9880dcfc7b78d513cb048) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes the `glob()` loader adding files from a folder excluded with a negation pattern such as `!_docs` when they change during `astro dev`

- [#&#8203;18432](https://github.com/withastro/astro/pull/18432) [`ed60d82`](https://github.com/withastro/astro/commit/ed60d82935d5768c3fcf67ce508e1f4edbfe25d6) Thanks [@&#8203;alexmv](https://github.com/alexmv)! - Improves the `MissingSharp` error to include the reason Sharp failed to load, such as its prebuilt binaries not supporting the current CPU

- [#&#8203;18474](https://github.com/withastro/astro/pull/18474) [`59543c3`](https://github.com/withastro/astro/commit/59543c3ad52e7141bcd6365cd70e8b51f18ccbd4) Thanks [@&#8203;miottid](https://github.com/miottid)! - Fixes i18n fallback for on-demand rendered pages. A locale-prefixed request for a page that only exists in the fallback locale (for example `/de/about` with `fallback: { de: 'en' }`) was answered with status `302` and no `Location` header. Such requests are now rewritten or redirected to the fallback locale according to `i18n.routing.fallbackType`, including encoded paths and sites with a configured `base`. Query strings are preserved, and explicit page statuses and redirects are left unchanged.

- [#&#8203;18541](https://github.com/withastro/astro/pull/18541) [`cfa2d2b`](https://github.com/withastro/astro/commit/cfa2d2b9e36ad610f6e7c27643e9157be3584a79) Thanks [@&#8203;ump45nose](https://github.com/ump45nose)! - Fixes `matchAllRoutes` to consider `fallbackRoutes`, matching `matchRoute` and the production router. Dev-server i18n fallback requests now resolve to the source route's metadata instead of the 404 route, and SSR-only fallback candidates can fall through the prerender handler.

- [#&#8203;18602](https://github.com/withastro/astro/pull/18602) [`d856064`](https://github.com/withastro/astro/commit/d8560645033aac84fe61d4f4b3462f55a9d2eb89) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes `astro check` losing the end of its output, including the `Result` summary, when stdout is piped to a slow reader. When the reader closes the pipe early, for example `astro check | head`, `astro check` now exits with code 1 instead of crashing with an `EPIPE` stack trace.

- [#&#8203;18574](https://github.com/withastro/astro/pull/18574) [`da0f149`](https://github.com/withastro/astro/commit/da0f149de58001fa5564d083acbae34e7b4a1b1f) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes an unnecessary full page reload in `astro dev` when a content loader calls `store.clear()` or `store.delete()` and the content store has no asset imports

- [#&#8203;18570](https://github.com/withastro/astro/pull/18570) [`e71c038`](https://github.com/withastro/astro/commit/e71c038f31194280b44515bf53cf449a5313baf9) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes pages using `<ClientRouter />` briefly showing the top of the page on reload before jumping back to the previous scroll position. Full reloads now use the browser's native scroll restoration.

- [#&#8203;18531](https://github.com/withastro/astro/pull/18531) [`f75553b`](https://github.com/withastro/astro/commit/f75553b8bbe6cb9b72d8fda0059198ab3330f089) Thanks [@&#8203;praveen-kumary](https://github.com/praveen-kumary)! - Fixes an unhandled `TypeError: Cannot convert undefined or null to object` when calling `route.generate()` without arguments on static routes

</details>

<details>
<summary>pnpm/pnpm (pnpm)</summary>

### [`v12.20.0`](https://github.com/pnpm/pnpm/releases/tag/v12.20.0): pnpm 12.20

[Compare Source](https://github.com/pnpm/pnpm/compare/v12.19.0...v12.20.0)

pnpm 12.20.0 records the specifiers of local directory dependencies in the experimental v13 lockfile and fixes several `nodeLinker: hoisted`, peer dependency, and `overrides` bugs. The bundled `node-gyp` no longer ships the undici version that security scanners flag. Remote resolution and shared build caches no longer work with pnpr 0.1.0-alpha.19 or older.

##### Minor Changes

- With `lockfile.format: v13`, `pnpm install` records the dependency specifiers of local directory packages. Frozen installs reject changed specifiers even when the locked versions still satisfy them.

##### Patch Changes

##### Upgrading and security

- Remote resolution, shared build caches, and release notes no longer work with pnpr 0.1.0-alpha.19 or older. pnpm now reads the capabilities a pnpr server advertises under `pnpr.protocols`. Installs fail when the server does not confirm the requested resolution and verification policies.

- The `node-gyp` bundled with pnpm no longer ships undici 6, which security scanners flag for CVE-2026-84947. On Node.js 26, `node-gyp` downloads through a proxy or with a custom CA file no longer crash with "invalid onError method" [#&#8203;17941](https://github.com/pnpm/pnpm/issues/17941).

##### Resolving dependencies

- Version-selector `overrides` entries such as `"ms@^2.0.0": "2.1.1"` now apply to dependencies declared with the `catalog:` protocol when the catalog entry's range matches the selector [#&#8203;17922](https://github.com/pnpm/pnpm/issues/17922).

- A root `overrides` entry that points a package at a `workspace:` path, such as `workspace:./packages/foo`, now also applies when a registry package depends on that package [pnpm/tasks#270](https://github.com/pnpm/tasks/issues/270).

- Git dependencies now accept npm's `::` separator between fragment parameters, such as `github:owner/repo#v1.0.0::path:packages/foo`. Before, pnpm read the whole fragment as a branch name and failed to resolve it [#&#8203;17827](https://github.com/orgs/pnpm/discussions/17827).

- `pnpm dedupe` now keeps a locked runtime version, from `devEngines.runtime` or from a dependency's `engines.runtime`, when the declared range still admits it. `pnpm dedupe --check` no longer fails each time a newer Node.js release in the range comes out [#&#8203;17984](https://github.com/pnpm/pnpm/issues/17984).

- With `autoInstallPeersFromHighestMatch`, conflicting non-semver peer dependencies now remain missing, and identical non-semver peer specifiers are preserved. Preferred registry versions no longer replace local paths or protocol-prefixed specifiers when pnpm installs missing peers [pnpm/tasks#272](https://github.com/pnpm/tasks/issues/272).

##### Hoisted node linker

- With `nodeLinker: hoisted`, a package now keeps its nested copy of a dependency that it resolved at a version other than the top-level one, including a peer dependency its parent supplies. Before, pnpm could remove that copy as a duplicate or give the top-level slot to a peer variant found deeper in the graph. The package then loaded the top-level version.

##### Lockfile and peer dependency graphs

- Fixed `pnpm install` keeping stale peer bindings after dependency changes. Required dependencies no longer remain marked optional when another workspace project removes a shared package [pnpm/tasks#221](https://github.com/pnpm/tasks/issues/221).

- Repeated installs now keep the same dependency links when packages form cycles with several peer dependency variants [pnpm/tasks#221](https://github.com/pnpm/tasks/issues/221).

- Fixed writing `lockfile.format: v13` for dependency cycles with missing, optional, or transitive peers. Frozen installs also accept unchanged injected packages whose peers use catalogs. With `--no-optional`, frozen installs reject required catalog children recorded only as optional dependencies [pnpm/tasks#221](https://github.com/pnpm/tasks/issues/221).

- `pnpm deploy` preserves an injected workspace package's resolved dependencies when they differ from the workspace project's own dependencies. This also applies to packages with `publishConfig.directory` [pnpm/tasks#221](https://github.com/pnpm/tasks/issues/221).

##### Running scripts and runtimes

- Scripts that pnpm runs in a process group of their own are now ended when pnpm is killed right after starting them. A parallel run that was killed before pnpm registered its scripts left all of them running.

- When a command name matches no script and pnpm falls back to running it as a command, the install that runs before scripts now runs once. Its errors and warnings print once [#&#8203;17977](https://github.com/pnpm/pnpm/issues/17977).

- Failed downloads by project-aware global runtime commands now explain which configuration applies. Node.js failures also list the global mirror settings and environment variables to check.

##### Other commands and settings

- Fixed `pnpm` occasionally crashing on the first HTTPS request, mostly on Windows virtual machines under load. pnpm now seeds TLS randomness from the operating system's random number generator [pnpm/tasks#239](https://github.com/pnpm/tasks/issues/239).

- Fixed `pnpm deprecate`, `pnpm undeprecate`, and `pnpm unpublish` failing with revision conflicts when a registry cache serves stale package metadata.

- `pnpm sbom` now reports malformed workspace manifests. Before, it omitted their packages [pnpm/tasks#59](https://github.com/pnpm/tasks/issues/59).

- Fixed `pnpm store status` reporting approved builds of git dependencies as modified when the store contains legacy build metadata.

- pnpm now recognizes Capawesome Cloud and RWX as CI environments.

<!-- sponsors -->

#### Platinum Sponsors

<table>
  <tbody>
    <tr>
      <td align="center" valign="middle">
        <a href="https://bit.cloud/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer"><img src="https://pnpm.io/img/users/bit.svg" width="80" alt="Bit"></a>
      </td>
      <td align="center" valign="middle">
        <a href="https://openai.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/openai_dark.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/openai_light.svg" />
            <img src="https://pnpm.io/img/users/openai_dark.svg" width="160" alt="OpenAI" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://notion.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/notion.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/notion_light.svg" />
            <img src="https://pnpm.io/img/users/notion.svg" width="80" alt="Notion" />
          </picture>
        </a>
      </td>
    </tr>
    <tr>
      <td align="center" valign="middle">
        <a href="https://coderabbit.ai/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/coderabbit.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/coderabbit_light.svg" />
            <img src="https://pnpm.io/img/users/coderabbit.svg" width="220" alt="CodeRabbit" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://www.cloudflare.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/cloudflare.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/cloudflare_light.svg" />
            <img src="https://pnpm.io/img/users/cloudflare.svg" width="160" alt="Cloudflare" />
          </picture>
        </a>
      </td>
    </tr>
  </tbody>
</table>

#### Gold Sponsors

<table>
  <tbody>
    <tr>
      <td align="center" valign="middle">
        <a href="https://sanity.io/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/sanity.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/sanity_light.svg" />
            <img src="https://pnpm.io/img/users/sanity.svg" width="120" alt="Sanity" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://discord.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/discord.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/discord_light.svg" />
            <img src="https://pnpm.io/img/users/discord.svg" width="220" alt="Discord" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://vite.dev/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer"><img src="https://pnpm.io/img/users/vitejs.svg" width="42" alt="Vite"></a>
      </td>
    </tr>
    <tr>
      <td align="center" valign="middle">
        <a href="https://serpapi.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/serpapi_dark.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/serpapi_light.svg" />
            <img src="https://pnpm.io/img/users/serpapi_dark.svg" width="160" alt="SerpApi" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://stackblitz.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/stackblitz.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/stackblitz_light.svg" />
            <img src="https://pnpm.io/img/users/stackblitz.svg" width="190" alt="Stackblitz" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://workleap.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/workleap.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/workleap_light.svg" />
            <img src="https://pnpm.io/img/users/workleap.svg" width="190" alt="Workleap" />
          </picture>
        </a>
      </td>
    </tr>
    <tr>
      <td align="center" valign="middle">
        <a href="https://nx.dev/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/nx.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/nx_light.svg" />
            <img src="https://pnpm.io/img/users/nx.svg" width="50" alt="Nx" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://latitude.so/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/latitude.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/latitude_light.svg" />
            <img src="https://pnpm.io/img/users/latitude.svg" width="160" alt="Latitude" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://syntax.fm/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/syntaxfm.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/syntaxfm_light.svg" />
            <img src="https://pnpm.io/img/users/syntaxfm.svg" width="90" alt="Syntax" />
          </picture>
        </a>
      </td>
    </tr>
  </tbody>
</table>

<!-- sponsors end -->

### [`v12.19.0`](https://github.com/pnpm/pnpm/releases/tag/v12.19.0): pnpm 12.19

[Compare Source](https://github.com/pnpm/pnpm/compare/v12.18.0...v12.19.0)

pnpm 12.19.0 adds `pnpm fund`, lets the `loaded` node linker handle packages that need a build, and adds the `projectScopedOptionalPeers` setting and an experimental JSON lockfile format. It also includes a security fix: an offline install error no longer prints registry credentials. pnpm now checks the `engines` and platform fields of every workspace project, and many hoisted-linker and frozen-lockfile bugs are fixed.

##### Minor Changes

- Added `pnpm fund`, which lists the funding URLs declared by the installed dependencies in the same tree `npm fund` prints. Use `--json` for the `npm fund --json` report and `--recursive` or `--filter` to report on workspace projects. `pnpm fund <pkg>` opens the funding URL of an installed package, and `--which` picks one when it lists several [#&#8203;7354](https://github.com/pnpm/pnpm/issues/7354).

- With `nodeLinker.type: loaded`, packages that need a build no longer have to be listed in `nodeLinker.excluded`. A package with a matching side-effects cache entry loads from the store. If side-effects cache reads and writes are enabled, pnpm builds an approved package once, saves the result to the side-effects cache, and then loads it from the store. This includes a build that changes no files in its package, so its script does not run again in other projects that use the same store. List a package in `sideEffectsCache.exclude` if its build must run in every project, such as a git hook installer. pnpm materializes other cache misses, packages with native `.node` addons, and their dependencies automatically.

  pnpm also scans JavaScript sources for filesystem imports and for `__dirname` or `import.meta`, and materializes matching packages. The scan does not detect computed imports. List such packages in `nodeLinker.excluded`.

- Added the `projectScopedOptionalPeers` setting. When it is `true`, a project gets a missing optional peer dependency only if the project's own dependencies install a version of it. Another workspace project's dependencies, such as its `devDependencies`, no longer supply one. `dedupePeerDependents` keeps deduplicating everything else [#&#8203;16666](https://github.com/orgs/pnpm/discussions/16666).

- Added the experimental `lockfile.format: v13` setting. With it, pnpm writes `pnpm-lock.yaml` in a JSON-like syntax, indented with tabs, with a trailing comma after every entry. The file is still valid YAML. The file has one `packages` entry per package version in place of the `packages` and `snapshots` sections, and each entry records the versions of its peer dependencies as its properties. Updating a peer dependency then changes only the lines that record its version. pnpm reads lockfiles in both formats whatever the setting is.

- `pnpm store add` now accepts directories of tarballs, such as `pnpm store add ./tarballs`, and adds every `.tgz`, `.tar.gz`, and `.tar` file inside them recursively. `pnpm store add` is now faster when it adds many packages or local tarballs [#&#8203;17875](https://github.com/pnpm/pnpm/issues/17875).

- With `supportedArchitectures` set, `pnpm install` and `pnpm fetch` also store, without linking them, the dependencies of the archives kept for the other listed platforms. A platform added to the setting gets its archives and their dependencies on the next install. Optional dependencies a listed platform cannot run are not stored, and one that fails to download is skipped. Dependencies from git repositories are not stored for other platforms.

- When `supportedArchitectures` names exactly one platform and not `current`, pnpm links that platform's variant of a package published with platform variants, together with that variant's dependencies. This holds for the list form and for the `os`, `cpu`, and `libc` form. A variant whose floor or ABI the listed platform does not state is not linked for it: pnpm links another variant that fits, or the version's own archive. Changing the setting, or the platform of the host, such as a `node_modules` mounted into a musl container or a Node.js with another ABI, relinks the package on the next install, even from a frozen lockfile.

- pnpm now provides a prebuilt binary for NetBSD 10 on x64 [#&#8203;17803](https://github.com/pnpm/pnpm/issues/17803).

##### Patch Changes

##### Security

- The error for a tarball that is missing from the store in offline mode no longer prints the credentials or token in the tarball URL.

##### Installs that failed or hung

- `pnpm install`, `pnpm ci`, and `pnpm install-test` outside a workspace now fail with `ERR_PNPM_NO_PKG_MANIFEST` when the directory has no `package.json`, `package.json5`, or `package.yaml`. They no longer create a `package.json`, a lockfile, and `node_modules` there [#&#8203;17727](https://github.com/pnpm/pnpm/issues/17727).

- Fixed `pnpm install` hanging when a concurrent tarball download or manifest read is cancelled while other tasks are waiting on the same archive.

- Running a global command such as `node` in a project that pins its version no longer hangs while pnpm installs that version. The hang kept starting new processes until the machine ran out of memory.

- A global command such as `node` now runs the version a project pins when `PNPM_CONFIG_LOCKFILE_DIR`, `PNPM_CONFIG_VIRTUAL_STORE_ONLY`, or `PNPM_CONFIG_SYMLINK` is set in the environment. Before, the dispatch failed with "the installed node executable is not under" the store.

- `pnpm install` now fetches fresh metadata for a package when a version allowed by `minimumReleaseAgeExclude` is missing from the cached metadata. Before, it could fail with `ERR_PNPM_NO_MATCHING_VERSION` without contacting the registry [#&#8203;17723](https://github.com/pnpm/pnpm/issues/17723).

- A `${VAR}` placeholder in a registry URL in `pnpm-workspace.yaml` or the project `.npmrc` now fails the command. pnpm does not expand environment variables in these files. Before, pnpm ignored such a URL and resolved packages from another registry, such as npmjs.org. pnpm now warns when it ignores a placeholder in a proxy, `pnprServer`, or `userAgent` setting in `pnpm-workspace.yaml` [#&#8203;17762](https://github.com/pnpm/pnpm/issues/17762).

- Fixed local package installs failing while a workspace lockfile is being written.

- `pnpm self-update` and switching to the `packageManager` version now work behind a proxy that ends a response by closing the TLS connection without a `close_notify` alert. The registry signature check failed there with `ERR_PNPM_PNPM_ENGINE_IDENTITY_UNVERIFIABLE` [#&#8203;17763](https://github.com/pnpm/pnpm/issues/17763).

- A package tarball that keeps failing to download now fails the install after `fetchRetries` retries. pnpm used to download it again with a second full set of retries, which doubled the wait. The error now names the actual download failure.

- When the native binary of the pnpm version a project pins fails to download, pnpm now reports the download error. It used to report only that no native binary was found for the host.

- POSIX bin shims and the `pnpm`, `pn`, `pnpx`, and `pnx` launchers now run inside a Nix build on macOS with the sandbox enabled. Installing again replaces the shims already in `node_modules` [#&#8203;17750](https://github.com/pnpm/pnpm/issues/17750).

- Fixed pnpm leaving process pipes open after it exits on macOS [pnpm/tasks#229](https://github.com/pnpm/tasks/issues/229).

##### Engines and platform checks

- `pnpm install`, `pnpm add`, `pnpm update`, and `pnpm remove` now check the `engines`, `os`, `cpu`, and `libc` fields of every workspace project, including the workspace root. `pnpm run -r` and `pnpm exec -r` check them before running anything. An incompatible `engines.pnpm` fails the command. An incompatible `engines.node` prints a warning, or fails the command with `engineStrict` enabled. An unsupported platform prints a warning. A project that downloads its own Node.js through `devEngines.runtime` is checked against that Node.js [#&#8203;17751](https://github.com/pnpm/pnpm/issues/17751) [pnpm/tasks#281](https://github.com/pnpm/tasks/issues/281) [pnpm/tasks#299](https://github.com/pnpm/tasks/issues/299).

- Fixed missing warnings when a required dependency does not support the current Node.js version.

- An optional dependency that declares no `os`, `cpu`, or `libc` field is no longer skipped because its name contains only an operating system word, such as `get-windows` on macOS. pnpm now infers its platform from the name only when the name also has a cpu or libc token, such as `-win32-x64` [#&#8203;17774](https://github.com/pnpm/pnpm/issues/17774).

##### Peer dependencies

- With `dedupePeerDependents: false`, a missing optional peer is no longer resolved from a version that only another workspace project depends on. The workspace root's dependencies still count if `resolvePeersFromWorkspaceRoot` is `true`. Before, a tool in one project's `devDependencies`, such as `webpack-cli`, could become an optional peer of another project's production dependencies [#&#8203;16666](https://github.com/orgs/pnpm/discussions/16666).

- `pnpm install` no longer gives a project an optional peer dependency that it skipped because a required peer would conflict with the project's dependencies. Before, `dedupePeerDependents` merged the project's copy of the package that declares the peer with another project's copy that resolves it [#&#8203;17781](https://github.com/pnpm/pnpm/issues/17781).

- `pnpm install` no longer fills in a missing optional peer dependency if a required peer it brings in conflicts with a version the project depends on. Before, such a peer was installed along with it and reported as unmet [#&#8203;17718](https://github.com/orgs/pnpm/discussions/17718).

- `pnpm install --filter` in a sparse checkout now counts the dependencies of workspace projects that are missing from disk when it resolves peer dependencies and marks packages as optional. The lockfile it writes no longer differs from a full checkout in those entries [#&#8203;17791](https://github.com/pnpm/pnpm/issues/17791).

##### Frozen lockfile and workspace links

- `pnpm install --frozen-lockfile` now succeeds when a workspace project recorded in `pnpm-lock.yaml` has an empty directory, such as a git submodule that was not checked out [#&#8203;17712](https://github.com/pnpm/pnpm/issues/17712).

- `pnpm install --frozen-lockfile` now fails with `ERR_PNPM_OUTDATED_LOCKFILE` when a workspace package linked through a plain semver range, such as `^7.9.5`, has changed to a version outside that range [#&#8203;17806](https://github.com/pnpm/pnpm/issues/17806).

- `pnpm install --frozen-lockfile` and `verifyDepsBeforeRun` now accept a `workspace:` dependency on a project whose version is not valid semver, such as `workspace:1` on a project at version `1`. Before, they reported the lockfile that `pnpm install` had just written as out of date.

- `pnpm install --frozen-lockfile` now accepts a lockfile when an injected workspace package declares a `file:` or `link:` dependency with backslashes, such as `file:..\vendor`, or with a slash after the protocol, such as `file:/./vendor`. Before, the install reported the lockfile as out of date right after `pnpm install` had written it [#&#8203;17720](https://github.com/pnpm/pnpm/pull/17720).

- When a package injected through a path, such as `file:../lib` or `../lib`, gives one of its dependencies a `catalog:` specifier, `pnpm install --frozen-lockfile` now reports the lockfile as outdated. For a bare path such as `../lib`, `pnpm install` now also fails the way a fresh resolution does. Before, these installs accepted the existing lockfile [#&#8203;17722](https://github.com/pnpm/pnpm/pull/17722).

- Dependencies declared as `workspace:` entries in catalogs now remain in the lockfile when `excludeLinksFromLockfile` is enabled. Frozen installs can restore these links after `node_modules` is removed [pnpm/tasks#260](https://github.com/pnpm/tasks/issues/260).

- With `dedupeDirectDeps`, `pnpm install` now compares `link:` dependencies by the directory they point at. A project's `link:` dependency is removed when the workspace root links the same directory under a different path. It is kept when the root's `link:` dependency has the same text but points at another directory. pnpm reports a dependency the root provides as removed only once, when it removes the project's link. The summary shows the package version of a removed `link:` dependency [pnpm/tasks#293](https://github.com/pnpm/tasks/issues/293).

##### Hoisted node linker and custom modulesDir

- With `nodeLinker: hoisted`, a package that runs a lifecycle script or has a patch is now cloned or copied into `node_modules`, as with the isolated linker. A build that rewrites one of its files no longer changes the store copy shared with other projects.

- With `nodeLinker: hoisted`, pnpm no longer deletes a directory outside `node_modules` when it removes a package whose scope directory is a symlink.

- With `nodeLinker: hoisted`, `pnpm install --filter` in a sparse checkout now drops previously installed workspace projects that are missing from disk from the hoisted `node_modules` tree. It no longer recreates `node_modules` inside a missing project's directory. Packages that only the missing project used are also removed from the root `node_modules`.

- With `nodeLinker: hoisted` and `dedupeDirectDeps`, `pnpm install` now removes a project's `link:` dependency that the workspace root provides, and reports each `link:` dependency it removes. Removing the last scoped `link:` dependency of a scope also removes the empty `@scope` directory.

- With `nodeLinker: hoisted` and a custom `modulesDir`, pnpm now installs a workspace project's dependencies that cannot be hoisted to the root into the project's `modulesDir`. The next install that relinks the project removes the copies that earlier installs left in its `node_modules`. A later install restores the project's `modulesDir` when it was removed. Package directories that pnpm did not install are now also moved to `.ignored` in a custom `modulesDir`.

- Fixed installs in a workspace whose `modulesDir` is an absolute path, including one that goes through a symlink such as `/tmp` on macOS, or a path that starts with `..`. Dependencies of workspace projects no longer end up outside the workspace, and the root project's dependencies, `link:` dependencies, and commands are linked into the configured directory. `pnpm bin`, `pnpm root`, `pnpm run`, `pnpm exec`, and `pnpm version` now use that directory too [pnpm/tasks#285](https://github.com/pnpm/tasks/issues/285).

##### Store and builds

- Concurrent installs into a global virtual store no longer wait on each other. A package that needs a build is built in a private directory and moved into the store once its build has finished, so another project never links a half-built package. An install with `--ignore-scripts` links the packages it does not build from their own store directories, and `pnpm store prune` removes the build directories of installs that were interrupted [#&#8203;15568](https://github.com/pnpm/pnpm/issues/15568).

- Packages that an older pnpm version added to the store now run their install scripts. Before, pnpm could skip those scripts and hardlink the package's files to the store.

- `pnpm install` now keeps patches to bundled dependencies when it restores a package from the side-effects cache, including files a patch adds [#&#8203;17734](https://github.com/pnpm/pnpm/issues/17734).

- Local installs on macOS now keep cached clones separate from the global virtual store. `pnpm store prune` removes this cache, so unused cached packages no longer accumulate [#&#8203;17907](https://github.com/pnpm/pnpm/issues/17907).

- `pnpm store prune` now stops if a dependency link cannot be read. This keeps installed packages from being removed after an incomplete scan.

- A repeat `pnpm install` now runs a full install when the `runtimeOnFail` setting changes. Before, it printed "Already up to date" and did not install the runtime a project declares in `devEngines.runtime` [pnpm/tasks#303](https://github.com/pnpm/tasks/issues/303).

- The sync of an injected workspace dependency now copies a file whose source has reached the filesystem's limit on hard links. `pnpm patch-commit` now copies a file into its scratch directory when the filesystem refuses to hard link it, unless the path is missing or already occupied [pnpm/tasks#283](https://github.com/pnpm/tasks/issues/283).

##### Speed

- `pnpm install` is faster when it clones files from the store, which it does by default on macOS. On a Mac with endpoint security software, a cold install of a project with about 1,350 packages took 29% less time [pnpm/tasks#280](https://github.com/pnpm/tasks/issues/280).

- `pnpm install` unpacks packages that contain many files faster. Unpacking `typescript` took 30% less time in our measurements [pnpm/tasks#288](https://github.com/pnpm/tasks/issues/288).

- Resolving against a registry that sends `Cache-Control: no-cache`, such as Azure Artifacts, is fast again when the lockfile already decides the version. pnpm reads the cached metadata for a pinned version, or for a range the lockfile version is proven to win, without a registry request [#&#8203;17758](https://github.com/pnpm/pnpm/issues/17758).

- POSIX bin shims start fewer processes. Running a dependency's bin through its shim from Git Bash on Windows starts 7 processes where it started 15. Installing again replaces the shims already in `node_modules`.

##### Windows

- pnpm now installs dependencies and runs lifecycle scripts from projects on mapped Windows network drives. When a network share refuses the links in `node_modules`, the error now suggests setting `nodeLinker: hoisted` or moving the project to a local drive [#&#8203;17747](https://github.com/pnpm/pnpm/issues/17747).

- `packageImportMethod: auto` now tries hardlinking before cloning, as it does on Linux. Installs from a warm store on a Dev Drive are faster. An install no longer fails when the store refuses a hardlink with an access-denied error, and pnpm tries cloning or copying the file next [#&#8203;17809](https://github.com/pnpm/pnpm/issues/17809).

- `pnpm run` and `pnpm setup` no longer clear the visible terminal when a project path contains non-ASCII characters.

- A failed attempt to create a directory junction in `node_modules` no longer leaves a `.pnpm-junction-*` directory behind.

- `pnpm` starts faster. It loads system libraries such as `user32.dll` and `shell32.dll` the first time a command uses them, so `pnpm --version` loads 11 libraries where it loaded 25.

##### pnpm deploy

- `pnpm deploy` now runs the build scripts of a workspace project that it installs as a `file:` dependency, without a machine-specific `allowBuilds` key. An `allowBuilds` entry that denies the project still applies [#&#8203;17740](https://github.com/pnpm/pnpm/issues/17740).

- `pnpm deploy` no longer fails when the deployed project depends on a workspace package that sets `publishConfig.directory`. pnpm installs that package from its publish directory and runs its build scripts [#&#8203;17771](https://github.com/pnpm/pnpm/pull/17771).

- `pnpm deploy` without a shared workspace lockfile now resolves a relative `workspace:` path, such as `workspace:../lib`, from the source project's directory. It used to be resolved from the deploy target and fail [#&#8203;17804](https://github.com/pnpm/pnpm/issues/17804).

- `pnpm deploy --offline --trust-lockfile` now reuses dependencies pinned in the source lockfile from a populated store when registry metadata is unavailable. This works with per-project lockfiles, `--legacy`, and npm aliases [#&#8203;17888](https://github.com/pnpm/pnpm/issues/17888).

##### Other commands and settings

- `pnpm dist-tag` and `pnpm unpublish` now offer browser-based authentication when the account's two-factor authentication uses a security key. Before, they asked for a one-time password in that case [#&#8203;17832](https://github.com/pnpm/pnpm/issues/17832).

- `pnpm publish` with provenance now downloads Sigstore's current signing configuration before signing. A failed or slow download is retried with the same retry policy and deadline as the signing requests.

- `pnpm pack` and `pnpm publish` now apply the first rule of a `.npmignore` or `.gitignore` that starts with a UTF-8 BOM.

- `pnpm outdated` now checks dependencies when the project has no lockfile, for example with `lockfile: false`. The `Current` column shows the installed version, or the lowest version allowed by the declared range if the dependency is not installed [#&#8203;17811](https://github.com/pnpm/pnpm/issues/17811).

- `pnpm self-update` now updates the project's `engines.pnpm` range along with its pnpm pin, keeping the `^` or `~` operator [#&#8203;17732](https://github.com/pnpm/pnpm/issues/17732).

- On Linux and macOS, `pnpm run` no longer sometimes reports a lifecycle failure after `Ctrl+C` interrupts a script.

- Config dependencies use the declared registry `serverType` when recording and installing packages [pnpm/tasks#236](https://github.com/pnpm/tasks/issues/236).

- Relative directory selectors set on `config.filter` or `config.filterProd` by an `updateConfig` hook now resolve from the workspace root even when `--dir` is passed or `pnpm` runs from a subdirectory [#&#8203;17906](https://github.com/pnpm/pnpm/issues/17906).

- Commands that add settings to `pnpm-workspace.yaml` now fail with an error if the file contains only `null`, and leave the file unchanged. Before, they wrote invalid YAML.

- Shell tab-completion now completes directory and file paths for path options such as `-C`, `--dir`, `--prefix`, `--store-dir`, and `--env-file`. Before, options without a fixed list of values offered command names [#&#8203;17884](https://github.com/pnpm/pnpm/issues/17884).

<!-- sponsors -->

#### Platinum Sponsors

<table>
  <tbody>
    <tr>
      <td align="center" valign="middle">
        <a href="https://bit.cloud/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer"><img src="https://pnpm.io/img/users/bit.svg" width="80" alt="Bit"></a>
      </td>
      <td align="center" valign="middle">
        <a href="https://openai.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/openai_dark.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/openai_light.svg" />
            <img src="https://pnpm.io/img/users/openai_dark.svg" width="160" alt="OpenAI" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://notion.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer"><img src="https://pnpm.io/img/users/notion.svg" width="80" alt="Notion"></a>
      </td>
    </tr>
    <tr>
      <td align="center" valign="middle">
        <a href="https://coderabbit.ai/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/coderabbit.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/coderabbit_light.svg" />
            <img src="https://pnpm.io/img/users/coderabbit.svg" width="220" alt="CodeRabbit" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://www.cloudflare.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/cloudflare.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/cloudflare_light.svg" />
            <img src="https://pnpm.io/img/users/cloudflare.svg" width="160" alt="Cloudflare" />
          </picture>
        </a>
      </td>
    </tr>
  </tbody>
</table>

#### Gold Sponsors

<table>
  <tbody>
    <tr>
      <td align="center" valign="middle">
        <a href="https://sanity.io/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/sanity.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/sanity_light.svg" />
            <img src="https://pnpm.io/img/users/sanity.svg" width="120" alt="Sanity" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://discord.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/discord.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/discord_light.svg" />
            <img src="https://pnpm.io/img/users/discord.svg" width="220" alt="Discord" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://vite.dev/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer"><img src="https://pnpm.io/img/users/vitejs.svg" width="42" alt="Vite"></a>
      </td>
    </tr>
    <tr>
      <td align="center" valign="middle">
        <a href="https://serpapi.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/serpapi_dark.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/serpapi_light.svg" />
            <img src="https://pnpm.io/img/users/serpapi_dark.svg" width="160" alt="SerpApi" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://stackblitz.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/stackblitz.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/stackblitz_light.svg" />
            <img src="https://pnpm.io/img/users/stackblitz.svg" width="190" alt="Stackblitz" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://workleap.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/workleap.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/workleap_light.svg" />
            <img src="https://pnpm.io/img/users/workleap.svg" width="190" alt="Workleap" />
          </picture>
        </a>
      </td>
    </tr>
    <tr>
      <td align="center" valign="middle">
        <a href="https://nx.dev/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/nx.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/nx_light.svg" />
            <img src="https://pnpm.io/img/users/nx.svg" width="50" alt="Nx" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://latitude.so/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer"><img src="https://pnpm.io/img/users/latitude.svg" width="160" alt="Latitude"></a>
      </td>
      <td align="center" valign="middle">
        <a href="https://syntax.fm/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/syntaxfm.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/syntaxfm_light.svg" />
            <img src="https://pnpm.io/img/users/syntaxfm.svg" width="90" alt="Syntax" />
          </picture>
        </a>
      </td>
    </tr>
  </tbody>
</table>

<!-- sponsors end -->

### [`v12.18.0`](https://github.com/pnpm/pnpm/releases/tag/v12.18.0): pnpm 12.18

[Compare Source](https://github.com/pnpm/pnpm/compare/v12.17.0...v12.18.0)

pnpm 12.18.0 packs, publishes, and installs packages with platform variants on pnpr registries. It also adds per-skill approval of agent skills and `pnpm store add` for offline installs from downloaded tarballs. Repeat installs and `verifyDepsBeforeRun` no longer read the `package.json` of unchanged workspace projects. The release fixes several peer dependency resolution bugs too.

##### Minor Changes

##### Agent skills

- pnpm now names the link to a dependency's agent skill after the skill alone. A skill that the `@acme/kit` package ships in `skills/auth/` is linked as `.claude/skills/auth`, not `.claude/skills/pnpm-@acme+kit-auth`. The next install replaces links with the old names. pnpm lists the linked skills in a `# pnpm` block of each agent skill directory's `.gitignore` [#&#8203;17455](https://github.com/pnpm/pnpm/discussions/17455).

  When two approved packages ship a skill of the same name, or the name is already taken in an agent skill directory, pnpm links the skill as `pnpm-<package>-<skill>`. Before, the install failed.

- `pnpm approve` now asks which agent skills to link when a package ships more than one. pnpm records the chosen skills as a list, such as `permissions.<pkg>.skills: [guide, migrate]`, and does not offer the other skills for approval again. The first time a project approves a skill, `pnpm approve` also asks which agent directories to link skills into, and records the answer under `skills.dirs`.

- pnpm links agent skills nested in category directories, such as `skills/engineering/implement/SKILL.md`, up to three levels below `skills/`. Before, it linked only the skills directly under `skills/`.

##### Platform variants

These features need a registry declared with `serverType: pnpr`.

- `pnpm pack` packs one archive per entry of `publishConfig.variants`, each platform variant as `<name>-<version>~<tag>.tgz`. `pnpm pack --variant <target>` packs only the archive whose entry lists that target. `pnpm pack --json` prints the `integrity` and `size` of every archive it writes.

- `pnpm publish` publishes a package's `publishConfig.variants`. pnpm uploads every archive before the publish request that references them. Publishing variants to any other registry is refused unless `--no-variants` is given, which publishes only the archive that targets `any`.

- `pnpm publish --upload-variant <target>` uploads the archive of one `publishConfig.variants` entry to the registry's staging area and prints `<target>=<integrity>`. `pnpm publish --variant-integrity <target>=<integrity>` then publishes the version from archives that other jobs uploaded. With `--recursive`, each value names its package as `<name>~<target>=<integrity>`.

- `pnpm publish -r --batch` now uploads each package archive on its own request and skips archives the registry already holds, so the batch request no longer grows with the archives it publishes. A batch of more than 256 packages still carries every archive inline. Packages with `publishConfig.variants` can be published in a batch. A batch with variants that would reference more than 256 archives on one registry fails with `ERR_PNPM_BATCH_PUBLISH_TOO_MANY_ARCHIVES` [pnpm/tasks#244](https://github.com/pnpm/tasks/issues/244).

- `pnpm publish --provenance` signs one statement that names every archive of a version with `publishConfig.variants`. A platform variant's archive is named by the version's package URL with a `variant` qualifier.

- Rerunning `pnpm publish` after the version was already published now succeeds when the published version is the same release. pnpm compares the archives, the provenance statement when the rerun signs one, and the dist-tag. When the published version differs, the publish fails with `ERR_PNPM_PUBLISHED_RELEASE_DIFFERS`, which names what differs.

- pnpm installs the platform variant of a package that fits the host, or the package's own archive when none does. The lockfile records every variant. A version published with variants only, and no archive for other hosts, installs on a host one of the variants fits. On any other host, an optional dependency is skipped, and any other dependency fails with an error that lists the platforms the version is published for.

- `supportedArchitectures` platform lists accept platform tags, the same tags `publishConfig.variants` entries name. An entry can state floors and an ABI, such as `linux-x64-manylinux_2_28`, `darwin-arm64-macos_14_0`, `linux-x64-napi8` or `linux-x64-node127`, and any Node.js OS and CPU, such as `freebsd-x64`. The spellings accepted before still work.

- With `supportedArchitectures` set, pnpm also fetches into the store the variants that the other listed platforms need, when it downloads a package with platform variants.

##### pnpr registries

- pnpm downloads less metadata from a registry declared with `serverType: pnpr`. A large package document leaves out the manifests of rarely picked versions, and pnpm fetches one only when it picks that version. In a benchmark that resolves 787 packages, the package documents shrank from 30.3 MB to 2.5 MB gzipped. pnpm caches these documents in `v12/metadata-pnpr`, and the `pnpm cache` commands cover them.

  pnpm warns when a registry that is not declared `serverType: pnpr` turns out to be pnpr. For a registry declared `serverType: pnpr`, a `minimumReleaseAge` longer than 30 days fails with `ERR_PNPM_UNSUPPORTED_MINIMUM_RELEASE_AGE`.

- `pnpm publish` sends release notes to registries declared with `serverType: pnpr`. A package's notes are the section for its version in `CHANGELOG.md`, or the notes that `pnpm version -r` composed from change intents. `--release-notes <file>` gives the notes from a file, and `--no-release-notes` sends none. `--publication-name` names a release published with `--batch`.

  In a workspace that uses pnpm's versioning, `pnpm version -r --release-notes <file>` puts a summary above the composed notes of the release.

  `pnpm view <pkg>@<version> releaseNotes`, `pnpm outdated --notes`, and `pnpm update --interactive` show the release notes from these registries.

##### Store and hooks

- `pnpm store add` now prepares the store for offline installs from package tarballs downloaded some other way. After `pnpm store add ./tarballs/*.tgz`, `pnpm install --offline --frozen-lockfile` installs each registry package whose lockfile entry pins one of those tarballs [#&#8203;2978](https://github.com/pnpm/pnpm/issues/2978).

- Custom pnpmfile fetchers can use `fetchers.gitHostedTarball`, `fetchers.git`, and `fetchers.binary` [pnpm/tasks#191](https://github.com/pnpm/tasks/issues/191).

##### Patch Changes

##### Installing packages

- Running `node` or `pnpm install` in a project that pins a Node.js version pnpm has not downloaded yet no longer hangs when a `globalPnpmfile` is configured [#&#8203;17530](https://github.com/pnpm/pnpm/issues/17530).

- `pnpm install` with `enableGlobalVirtualStore` no longer fails on Windows for a dependency from a named registry, such as `gh:` or `npmjs:` [#&#8203;17665](https://github.com/pnpm/pnpm/issues/17665).

- Concurrent installs that share a global virtual store no longer fail with `ERR_PNPM_CMD_SHIM_SYMLINK_BIN` when they link the same executable at the same time [#&#8203;17587](https://github.com/pnpm/pnpm/issues/17587).

- `pnpm install` and `pnpm ci` now succeed when dependency skills are approved but no agent skill directory exists. The skills stay unlinked until a directory exists [#&#8203;17574](https://github.com/pnpm/pnpm/issues/17574).

- Commands run from a workspace package now use the same default store as the workspace root. Before, `pnpm add` in a package could fail with `ERR_PNPM_UNEXPECTED_STORE` when the workspace root was its own mount point and the home store was on another volume, as in a sandbox or a container.

  A workspace installed with the old behavior may need one `pnpm install --force` from the workspace root.

- `pnpm deploy` now keeps a symlink in the project whose target is missing from the source, such as a link into a `node_modules` directory that was removed after the build. Deploy used to drop such a link silently [#&#8203;17571](https://github.com/pnpm/pnpm/issues/17571).

- `pnpm install` now links the runtime that an earlier `pnpm install --no-runtime` skipped, and `pnpm install --no-runtime` removes a runtime that an earlier install linked [#&#8203;17542](https://github.com/pnpm/pnpm/issues/17542).

- With `enableGlobalVirtualStore`, `pnpm install` again runs a dependency's build scripts in a project whose global virtual store slot another project already built, unless the side-effects cache has build output to restore for it. A build that writes only outside its own package, such as a git hook installer, now takes effect in every project [#&#8203;17526](https://github.com/pnpm/pnpm/issues/17526).

- Commands of a package whose `bin` paths contain excess parent directory segments, such as `../dist/cli.js`, are no longer missing. Such paths now resolve inside the package [#&#8203;17586](https://github.com/pnpm/pnpm/issues/17586).

- Generated POSIX shell shims now quote their paths, so shell special characters in a path stay literal.

##### Lockfile and local paths

- Packages from the default registry keep plain lockfile keys, even when a prefix such as `npmjs` points at the registry set as `registry`. A dependency written with such a prefix shares the plain entry of the same package. The next install rewrites keys that earlier versions qualified this way [#&#8203;17575](https://github.com/pnpm/pnpm/issues/17575).

- `pnpm install --frozen-lockfile`, `pnpm approve-builds`, and `pnpm rebuild` now accept a lockfile that resolves a `*` dependency to a prerelease `latest` version. pnpm wrote such a lockfile and then reported it as outdated [#&#8203;17594](https://github.com/pnpm/pnpm/issues/17594).

- `pnpm install --frozen-lockfile` now accepts a lockfile written with `excludeLinksFromLockfile` and `linkWorkspacePackages` on, when a project depends on a workspace package through a `catalog:` entry. It used to fail with `ERR_PNPM_OUTDATED_LOCKFILE`.

- `pnpm install --frozen-lockfile` no longer rejects a freshly generated lockfile when `addMissingPeerTypes` is enabled and an injected workspace package has peer dependencies [#&#8203;17668](https://github.com/pnpm/pnpm/issues/17668).

- Relative local paths in root `overrides` now resolve from the workspace root when each project has its own lockfile [#&#8203;17691](https://github.com/pnpm/pnpm/issues/17691).

  Installing a local directory dependency no longer fails when another project's install is writing a lockfile in that directory.

- Relative local paths in root catalogs now resolve for dependencies and peers [#&#8203;17690](https://github.com/pnpm/pnpm/issues/17690).

- `pnpm install` now resolves auto-installed relative `workspace:` and `file:` peers from the directory of the package that declares them [#&#8203;17676](https://github.com/pnpm/pnpm/issues/17676), [#&#8203;17689](https://github.com/pnpm/pnpm/issues/17689).

- `pnpm dedupe --check` leaves `pnpm-lock.yaml` untouched while it looks for deduplication changes. If `configDependencies` changed since the last install, the check keeps the lockfile they sync, as `pnpm install` does [#&#8203;17628](https://github.com/pnpm/pnpm/issues/17628).

- `pnpm dedupe --check` no longer fails when the only difference is the integrity of a locked version that the registry now reports with a stronger algorithm, such as a `sha512` integrity replacing the `sha1` shasum it reported when the lockfile was written [#&#8203;17692](https://github.com/pnpm/pnpm/issues/17692).

##### Peer dependencies

- Peer deduplication no longer gives a project different copies of a dependency across direct and transitive paths when an optional peer has no provider [#&#8203;17666](https://github.com/pnpm/pnpm/issues/17666).

- Dependencies no longer bind to another project's peer variant when the provider has nested peers, including providers that finish resolving later [#&#8203;17593](https://github.com/pnpm/pnpm/issues/17593).

- Re-resolving a lockfile no longer preserves optional peer bindings from other projects when no provider is in scope [#&#8203;17592](https://github.com/pnpm/pnpm/issues/17592).

- `pnpm peers check` warns when a required peer is resolved without a provider declared by the project or its dependency ancestors, with `autoInstallPeers: false` and `dedupePeerDependents: true`. These warnings do not change the command's exit code or cause `strictPeerDependencies` failures.

##### Speed and memory

- `pnpm install`, and `pnpm run` and `pnpm exec` with `verifyDepsBeforeRun`, no longer read the `package.json` of workspace projects whose files did not change since the last install. This also holds with a pnpmfile, `configDependencies`, or `sharedWorkspaceLockfile: false`. In an up-to-date workspace with `sharedWorkspaceLockfile: false`, `pnpm install` no longer runs the install of each project [pnpm/tasks#256](https://github.com/pnpm/tasks/issues/256).

- A recursive `pnpm run` or `pnpm exec` with `verifyDepsBeforeRun` set no longer reads every `package.json` in the workspace once per project when `sharedWorkspaceLockfile` is `false`. In a 300-project workspace, `pnpm -r exec true` went from 490 ms to 42 ms [pnpm/tasks#256](https://github.com/pnpm/tasks/issues/256).

- `pnpm install` makes fewer `stat` calls when it hardlinks files from the store, as few as 12.7.0 made [#&#8203;17543](https://github.com/pnpm/pnpm/issues/17543).

- Picking versions from registry metadata uses less temporary memory.

##### verifyDepsBeforeRun and repeat installs

- With `verifyDepsBeforeRun`, `pnpm run` and `pnpm exec` now report dependencies as out of date after a dependency is added to the `package.json` of a local directory dependency, such as `"lib": "file:../lib"`. Before, the command ran without the new dependency installed.

- `verifyDepsBeforeRun` no longer reports a `file:` directory dependency as out of date after an edit to `package.json` that leaves its dependencies unchanged [#&#8203;17697](https://github.com/pnpm/pnpm/issues/17697).

- `verifyDepsBeforeRun` no longer reports dependencies as out of sync when only the `version` field of a single-project repository changed [#&#8203;17560](https://github.com/pnpm/pnpm/issues/17560). The same holds for a workspace project that no dependency can resolve to. A script run after such a change no longer starts an install first.

- A repeat `pnpm install` now rewrites the bin shims after `extendNodePath` changes. Before, it reported "Already up to date" and the shims kept the `NODE_PATH` of the previous setting.

##### Adding and updating dependencies

- `pnpm add <pkg>` without a version now saves the range that the other workspace projects declare for the package, or the one a matching override sets. A `catalog:` reference still comes first, and the `tag` setting is used only when none of these exists [pnpm/tasks#191](https://github.com/pnpm/tasks/issues/191).

- `pnpm update` with only negated selectors, such as `pnpm update '!foo'`, now leaves the dependencies listed in `update.ignoreDeps` unchanged. Negated `crate:` and `pypi:` selectors, such as `!crate:sha2`, now exclude that dependency and update the rest [pnpm/tasks#243](https://github.com/pnpm/tasks/issues/243).

- `pnpm update --latest` keeps three kinds of Cargo dependencies where they are, unless the crate is named on the command line. Before, it moved each one to the newest release and left a workspace that did not build.

  - A renamed dependency, such as `tower-0-4 = { package = "tower", version = "0.4" }`, stays within its requirement if the workspace also declares the crate under its own name.
  - A crate replaced through `[patch.crates-io]` keeps its version, with a warning.
  - A crate whose newest release is older than its current version, such as a prerelease newer than the latest stable release, keeps its version, with a warning. Only an explicit version, such as `pnpm update crate:foo@1`, moves it back.

  Other new major versions are still selected and may need code changes.

- `pnpm update` now keeps a Cargo dependency at its current version, with a warning, if the new version lacks a feature the workspace enables on it. If the crate is named on the command line, as in `pnpm update --latest crate:sha2`, the update fails with an error that names the missing features.

- `pnpm update` now keeps the operator of every existing Cargo requirement, so `~1.0.0` is updated to `~1.1.0`, and an exact `=` requirement stays exact unless the selector gives a range, such as `crate:foo@^2`. The `savePrefix` and `saveExact` settings apply only to new Cargo dependencies. Saved Cargo requirements omit build metadata.

- `pnpm update` now updates a Cargo dependency whose inline table spans several lines, such as one with a multi-line `features` array. It failed with "its Cargo.toml dependency declaration is not a string or single-line inline table".

- `pnpm update` no longer applies the `savePrefix` and `saveExact` settings to Python requirements. A `savePrefix` such as `^` made `pnpm update` fail in a project with Python dependencies.

  `pnpm update` now keeps the precision of a `~=` requirement, so `~=1.0` is updated to `~=1.5` and still allows any 1.x release. With `--latest`, a `==1.*` requirement is updated to `==2.*`.

##### Store

- `pnpm store prune` now keeps packages linked from a configured modules directory [pnpm/tasks#230](https://github.com/pnpm/tasks/issues/230).

- `pnpm store prune` now removes aliases of pruned packages.

- `pnpm store status` no longer reports untouched packages as modified when the global virtual store is enabled. If the installed global-store layout cannot be verified, the command reports `ERR_PNPM_STORE_STATUS_UNVERIFIABLE` and asks for a reinstall [#&#8203;17631](https://github.com/pnpm/pnpm/issues/17631).

- `pnpm store add` now fails with `ERR_PNPM_FROZEN_STORE_WRITE` when `frozenStore` is enabled. It used to write package files into the read-only store without recording them, so no install could use them.

- `pnpm cat-index <name>@<version>` no longer shows the index of a package whose name differs only in letter case.

##### Other commands and settings

- `pnpm link` now fails without changing `package.json` or `pnpm-workspace.yaml` when the linked package's name is not a valid npm package name. It used to write that name to both files, which made every later install fail [#&#8203;17475](https://github.com/pnpm/pnpm/issues/17475).

- `pnpm link <dir>` now resolves a relative `<dir>` against the current directory. In a directory without a `package.json`, such as a workspace's `packages` folder, `pnpm link .` used to link the nearest project above it into itself [#&#8203;17475](https://github.com/pnpm/pnpm/issues/17475).

- A Node.js version range such as `>=26.13`, for example in `devEngines.runtime`, now resolves to the newest stable release that satisfies it. pnpm picks a prerelease only when no stable release matches [#&#8203;17516](https://github.com/pnpm/pnpm/issues/17516).

- Switching to the pnpm version a project pins no longer writes a temporary `_tmp_*` file into the project directory, which file watchers reported on every command [#&#8203;17681](https://github.com/pnpm/pnpm/issues/17681).

- pnpm now reads the `linkWorkspacePackages`, `injectWorkspacePackages`, `extendNodePath`, `frozenStore`, and `optimisticRepeatInstall` settings from `PNPM_CONFIG_*` environment variables, such as `PNPM_CONFIG_LINK_WORKSPACE_PACKAGES=true`. `--config.extend-node-path` now applies too.

- Recursive scripts run with `--sequential` or `--workspace-concurrency=1` print GitHub Actions log groups again [#&#8203;17629](https://github.com/pnpm/pnpm/issues/17629).

- When `pnpm docs` cannot open a browser, the URL it prints no longer includes the query string or the fragment.

<!-- sponsors -->

#### Platinum Sponsors

<table>
  <tbody>
    <tr>
      <td align="center" valign="middle">
        <a href="https://bit.cloud/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer"><img src="https://pnpm.io/img/users/bit.svg" width="80" alt="Bit"></a>
      </td>
      <td align="center" valign="middle">
        <a href="https://openai.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/openai_dark.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/openai_light.svg" />
            <img src="https://pnpm.io/img/users/openai_dark.svg" width="160" alt="OpenAI" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://notion.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer"><img src="https://pnpm.io/img/users/notion.svg" width="80" alt="Notion"></a>
      </td>
    </tr>
    <tr>
      <td align="center" valign="middle">
        <a href="https://coderabbit.ai/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/coderabbit.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/coderabbit_light.svg" />
            <img src="https://pnpm.io/img/users/coderabbit.svg" width="220" alt="CodeRabbit" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://www.cloudflare.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/cloudflare.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/cloudflare_light.svg" />
            <img src="https://pnpm.io/img/users/cloudflare.svg" width="160" alt="Cloudflare" />
          </picture>
        </a>
      </td>
    </tr>
  </tbody>
</table>

#### Gold Sponsors

<table>
  <tbody>
    <tr>
      <td align="center" valign="middle">
        <a href="https://sanity.io/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/sanity.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/sanity_light.svg" />
            <img src="https://pnpm.io/img/users/sanity.svg" width="120" alt="Sanity" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://discord.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/discord.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/discord_light.svg" />
            <img src="https://pnpm.io/img/users/discord.svg" width="220" alt="Discord" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://vite.dev/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer"><img src="https://pnpm.io/img/users/vitejs.svg" width="42" alt="Vite"></a>
      </td>
    </tr>
    <tr>
      <td align="center" valign="middle">
        <a href="https://serpapi.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/serpapi_dark.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/serpapi_light.svg" />
            <img src="https://pnpm.io/img/users/serpapi_dark.svg" width="160" alt="SerpApi" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://stackblitz.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/stackblitz.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/stackblitz_light.svg" />
            <img src="https://pnpm.io/img/users/stackblitz.svg" width="190" alt="Stackblitz" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://workleap.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/workleap.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/workleap_light.svg" />
            <img src="https://pnpm.io/img/users/workleap.svg" width="190" alt="Workleap" />
          </picture>
        </a>
      </td>
    </tr>
    <tr>
      <td align="center" valign="middle">
        <a href="https://nx.dev/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/nx.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/nx_light.svg" />
            <img src="https://pnpm.io/img/users/nx.svg" width="50" alt="Nx" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://latitude.so/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer"><img src="https://pnpm.io/img/users/latitude.svg" width="160" alt="Latitude"></a>
      </td>
      <td align="center" valign="middle">
        <a href="https://syntax.fm/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/syntaxfm.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/syntaxfm_light.svg" />
            <img src="https://pnpm.io/img/users/syntaxfm.svg" width="90" alt="Syntax" />
          </picture>
        </a>
      </td>
    </tr>
  </tbody>
</table>

<!-- sponsors end -->

</details>

<details>
<summary>HiDeoo/starlight-openapi (starlight-openapi)</summary>

### [`v0.27.1`](https://github.com/HiDeoo/starlight-openapi/blob/HEAD/packages/starlight-openapi/CHANGELOG.md#0271)

[Compare Source](https://github.com/HiDeoo/starlight-openapi/compare/[email protected]@0.27.1)

##### Patch Changes

- [#&#8203;187](https://github.com/HiDeoo/starlight-openapi/pull/187) [`5ca2798`](https://github.com/HiDeoo/starlight-openapi/commit/5ca27989b77dbf8a4eb9e09a16ff2203e499f5ff) Thanks [@&#8203;HiDeoo](https://github.com/HiDeoo)! - Fixes an issue where some metadata of schemas using `oneOf` or `anyOf` could be missing or incorrectly repeated.

</details>

---

### Configuration

📅 **Schedule**: (UTC)

- Branch creation
  - Between 12:00 AM and 03:59 AM, only on Monday (`* 0-3 * * 1`)
- Automerge
  - At any time (no schedule defined)

🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied.

♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox.

👻 **Immortal**: This PR will be recreated if closed unmerged. Get [config help](https://github.com/renovatebot/renovate/discussions) if that's undesired.

---

 - [ ] <!-- rebase-check -->If you want to rebase/retry this PR, check this box

---

This PR has been generated by [Mend Renovate CLI](https://github.com/renovatebot/renovate).
<!--renovate-debug:eyJjcmVhdGVkSW5WZXIiOiI0NC4yMjIuNSIsInVwZGF0ZWRJblZlciI6IjQ0LjIzOS4xIiwidGFyZ2V0QnJhbmNoIjoibWFpbiIsImxhYmVscyI6W119-->

<!-- cloudflare-preview --> Preview: https://pr-649.docs-gitea-com.pages.dev

---------

Co-authored-by: silverwind <[email protected]>
Reviewed-on: https://gitea.com/gitea/docs/pulls/649
Reviewed-by: silverwind <[email protected]>
Co-authored-by: Renovate Bot <[email protected]>
2026-11-17 08:32:28 +00:00
c0e2b5ae00 Document FORCE_USER_ACTIVITY_VISIBILITY (#624)
Documents the `[service] FORCE_USER_ACTIVITY_VISIBILITY` option from https://github.com/go-gitea/gitea/pull/40002, which replaced the earlier `change_activity_visibility` disabled feature.

_Written by Claude (Opus 5.5)._

---------

Co-authored-by: Lunny Xiao <[email protected]>
Co-authored-by: silverwind <[email protected]>
Co-authored-by: Shivansh Garg <[email protected]>
Reviewed-on: https://gitea.com/gitea/docs/pulls/624
Reviewed-by: Lunny Xiao <[email protected]>
Co-authored-by: SHIVANSH GARG <[email protected]>
2026-11-16 00:14:44 +00:00
silverwindandLunny Xiao c9c3e39b0f Document OpenID 2.0 removal (#633)
Documents https://github.com/go-gitea/gitea/pull/40231 for main, which removes OpenID 2.0 authentication. Drops the `[openid]` settings and OpenID 2.0 mentions from the current docs in all three languages. OpenID Connect docs are unchanged.

_Written by Claude (Opus 5.5)._

---------

Co-authored-by: Lunny Xiao <[email protected]>
Reviewed-on: https://gitea.com/gitea/docs/pulls/633
Reviewed-by: Lunny Xiao <[email protected]>
Co-authored-by: silverwind <[email protected]>
2026-11-15 23:56:06 +00:00
silverwindandLunny Xiao 01c8000cfd Document multiple LDAP hosts (#635)
Documents https://github.com/go-gitea/gitea/pull/40201 for main, which lets the LDAP Host field list several servers as hosts or `ldap://`, `ldaps://` and `ldap+starttls://` URLs. WIP until that PR merges.

_Written by Claude (Opus 5.5)._

---------

Co-authored-by: Lunny Xiao <[email protected]>
Reviewed-on: https://gitea.com/gitea/docs/pulls/635
Reviewed-by: Lunny Xiao <[email protected]>
Co-authored-by: silverwind <[email protected]>
2026-11-15 23:55:57 +00:00
silverwindandLunny Xiao cfd22c91bd Remove repository adoption docs (#639)
Documents https://github.com/go-gitea/gitea/pull/40181 for main, which removes repository adoption and the `ALLOW_ADOPTION_OF_UNADOPTED_REPOSITORIES` and `ALLOW_DELETION_OF_UNADOPTED_REPOSITORIES` settings.

The FAQ entry now points to the Gitea importer for importing repositories from disk. Draft until the Gitea PR merges.

_Written by Claude (Opus 5.5)._

---------

Co-authored-by: Lunny Xiao <[email protected]>
Reviewed-on: https://gitea.com/gitea/docs/pulls/639
Reviewed-by: Lunny Xiao <[email protected]>
Co-authored-by: silverwind <[email protected]>
2026-11-15 23:50:35 +00:00
bircni bf8f4ce394 update to 28.4.0 (#648)
Bump the v28 docs to the 28.4.0 release:

- point the `28` version variables (`version`, `sourceVersion`, `dockerVersion`, `displayVersion`) at 28.4.0
- update the v28 entry in `update_api_docs.sh` to `28.4.0`
- regenerate `static/swagger-28.json` and `static/openapi3-28.json` from the `v28.4.0` tag, which marks `path` as required in `CreatePullReviewComment` (go-gitea/gitea#40260)

Reviewed-on: https://gitea.com/gitea/docs/pulls/648
Reviewed-by: TheFox0x7 <[email protected]>
2026-11-15 21:03:40 +00:00
silverwind 757fb1927a Document code search and its query syntax (#615)
Documents https://github.com/go-gitea/gitea/pull/39403: a new user page for code search with the query syntax, results and API endpoints, and an update to the repository indexer page saying that `git grep` search needs Git with PCRE.

_Written by Claude._

Reviewed-on: https://gitea.com/gitea/docs/pulls/615
Reviewed-by: Lunny Xiao <[email protected]>
Co-authored-by: silverwind <[email protected]>
2026-11-13 18:45:17 +00:00
silverwind d5a68736bd Remove the DSA minimum key size option (#646)
Documents https://github.com/go-gitea/gitea/pull/40332 for main, which removes SSH DSA key support. Drops the `DSA` option of `[ssh.minimum_key_sizes]` from the current docs in all three languages. Draft until the Gitea PR merges.

_Written by Claude (Opus 5.5)._

Reviewed-on: https://gitea.com/gitea/docs/pulls/646
Reviewed-by: Lunny Xiao <[email protected]>
Co-authored-by: silverwind <[email protected]>
2026-11-12 18:22:57 +00:00
silverwindandLunny Xiao cb63f3ef8a Remove the builtin:checkout docs (#643)
Follow-up to https://gitea.com/gitea/runner/pulls/1407, which removes the runner's builtin actions. Drops `builtin:checkout` from the develop runner docs and the current comparison page, and lists the removal under the 6.0 breaking changes. Versioned docs keep it, as released runners still ship it, with their `builtin-actions.md` links pinned to the latest 4.x and 5.x tags since the file leaves runner main.

Co-authored-by: Lunny Xiao <[email protected]>
Reviewed-on: https://gitea.com/gitea/docs/pulls/643
Reviewed-by: Lunny Xiao <[email protected]>
Co-authored-by: silverwind <[email protected]>
2026-11-12 06:23:01 +00:00
silverwind fa8c890d01 Document running the macOS runner in the login session (#644)
Rewrites the `launchd (macOS)` section of the runner's binary installation page, in the develop and version 5 docs.

The old steps started the runner at boot as a service user, with directories that do not exist on macOS and a `PATH` that missed Homebrew on Apple silicon. Jobs started that way have no login keychain and no GUI.

The section now describes one setup: the runner runs in the login session of an existing user, with automatic login. It also covers the two problems that setup runs into: macOS blocks the runner from hosts on the Mac's own subnet, and Git's keychain helper can stop a job at a dialog.

The runner repository gets the same content as an example in https://gitea.com/gitea/runner/pulls/1408.

Reviewed-on: https://gitea.com/gitea/docs/pulls/644
Reviewed-by: Lunny Xiao <[email protected]>
Co-authored-by: silverwind <[email protected]>
2026-11-11 10:34:40 +00:00
Renovate BotandLunny Xiao e707e2838a chore(deps): update dependencies (#640)
This PR contains the following updates:

| Package | Change | [Age](https://docs.renovatebot.com/merge-confidence/) | [Confidence](https://docs.renovatebot.com/merge-confidence/) | Type | Update | Pending |
|---|---|---|---|---|---|---|
| [@astrojs/starlight](https://starlight.astro.build) ([source](https://github.com/withastro/starlight/tree/HEAD/packages/starlight)) | [`0.42.7` → `0.42.8`](https://renovatebot.com/diffs/npm/@astrojs%2fstarlight/0.42.7/0.42.8) | ![age](https://developer.mend.io/api/mc/badges/age/npm/@astrojs%2fstarlight/0.42.8?slim=true) | ![confidence](https://developer.mend.io/api/mc/badges/confidence/npm/@astrojs%2fstarlight/0.42.7/0.42.8?slim=true) | dependencies | patch | `0.42.10` (+1) |
| [@pagefind/default-ui](https://github.com/Pagefind/pagefind) | [`1.5.2` → `1.6.0`](https://renovatebot.com/diffs/npm/@pagefind%2fdefault-ui/1.5.2/1.6.0) | ![age](https://developer.mend.io/api/mc/badges/age/npm/@pagefind%2fdefault-ui/1.6.0?slim=true) | ![confidence](https://developer.mend.io/api/mc/badges/confidence/npm/@pagefind%2fdefault-ui/1.5.2/1.6.0?slim=true) | dependencies | minor |  |
| [astro](https://astro.build) ([source](https://github.com/withastro/astro/tree/HEAD/packages/astro)) | [`7.4.2` → `7.4.5`](https://renovatebot.com/diffs/npm/astro/7.4.2/7.4.5) | ![age](https://developer.mend.io/api/mc/badges/age/npm/astro/7.4.5?slim=true) | ![confidence](https://developer.mend.io/api/mc/badges/confidence/npm/astro/7.4.2/7.4.5?slim=true) | dependencies | patch | `7.4.7` (+1) |
| [pnpm](https://pnpm.io) ([source](https://github.com/pnpm/pnpm/tree/HEAD/pnpm/npm/pnpm)) | [`12.16.1` → `12.17.0`](https://renovatebot.com/diffs/npm/pnpm/12.16.1/12.17.0) | ![age](https://developer.mend.io/api/mc/badges/age/npm/pnpm/12.17.0?slim=true) | ![confidence](https://developer.mend.io/api/mc/badges/confidence/npm/pnpm/12.16.1/12.17.0?slim=true) | packageManager | minor | `12.18.0` |
| [pnpm/action-setup](https://github.com/pnpm/action-setup) ([changelog](https://github.com/pnpm/action-setup/compare/0977fd99725f1db4007ccb2928dbb4e90d06cc86..73e46992e05b19abd31f2f3c20e0e7370d762115)) | `0977fd9` → `73e4699` |  |  | action | digest |  |

---

### Release Notes

<details>
<summary>withastro/starlight (@&#8203;astrojs/starlight)</summary>

### [`v0.42.8`](https://github.com/withastro/starlight/blob/HEAD/packages/starlight/CHANGELOG.md#0428)

[Compare Source](https://github.com/withastro/starlight/compare/@astrojs/[email protected]...@astrojs/[email protected])

##### Patch Changes

- [#&#8203;4309](https://github.com/withastro/starlight/pull/4309) [`3490c80`](https://github.com/withastro/starlight/commit/3490c803a5fd02019fd3c9357982e9e3753e335d) Thanks [@&#8203;athulsreekumar](https://github.com/athulsreekumar)! - Fixes autogenerated sidebar groups omitting directories whose names match `Object.prototype` properties, such as `constructor` or `toString`

- [#&#8203;4290](https://github.com/withastro/starlight/pull/4290) [`bf93823`](https://github.com/withastro/starlight/commit/bf938239f5f9775318baeaea1adc1ef93768628c) Thanks [@&#8203;RaphaelFakhri](https://github.com/RaphaelFakhri)! - Fixes missing last-updated dates in production builds for pages whose file path contains special characters

- [#&#8203;4295](https://github.com/withastro/starlight/pull/4295) [`af9557e`](https://github.com/withastro/starlight/commit/af9557ea8c957173ea9174e19a87d80fce22a983) Thanks [@&#8203;delucis](https://github.com/delucis)! - Fixes a formatting issue in some error messages impacting projects with Zod ≥4.5 installed

- [#&#8203;4299](https://github.com/withastro/starlight/pull/4299) [`a103f38`](https://github.com/withastro/starlight/commit/a103f383bcd99a7bd0b9c62a678c41ec5202497b) Thanks [@&#8203;clean99](https://github.com/clean99)! - Fixes empty sidebars when autogenerating entries from the docs root directory using `directory: ''`

</details>

<details>
<summary>Pagefind/pagefind (@&#8203;pagefind/default-ui)</summary>

### [`v1.6.0`](https://github.com/Pagefind/pagefind/blob/HEAD/CHANGELOG.md#v160-November-1-2026)

[Compare Source](https://github.com/Pagefind/pagefind/compare/v1.5.2...v1.6.0)

👋 A little overdue, but this release knocks out a healthy selection of bug reports, and includes a lot of work from the community. Thanks to everyone who contributed ❤️ - [@&#8203;bglw](https://github.com/bglw)

##### Multilingual Segmentation

Pagefind's extended build now segments Chinese, Japanese, and Thai pages with ICU4X, replacing the previous dependency (PR [#&#8203;1383](https://github.com/Pagefind/pagefind/issues/1383)). Alongside producing a smaller binary, ICU4X segments a lot closer to the `Intl.Segmenter` used in the browser on the search query (which is ICU4C). This closes out a mixture of latent and reported issues where the different segmentation between indexing and searching makes for iffy results. It's not perfect yet, but it's a darn sight closer.

Bonuses:

- Segmentation is smarter in languages such as Thai, and doesn't break inside a grapheme cluster
- Japanese katakana has special handling, but should still be improved over 1.5.2
- Japanese voiced and semi-voiced sound marks are no longer normalized into each other

##### Fewer Fragment Files

Pagefind now has an option to limit the total number of fragment files produced, for hosting providers that cap the number of uploaded files. Contributed in PR [#&#8203;1020](https://github.com/Pagefind/pagefind/issues/1020) — thanks [@&#8203;yakovsh](https://github.com/yakovsh) !

This limit is set with `--max-fragments` / `max_fragments`, and applies per language. When applied, multiple fragments are bundled together and loaded as a set when required.

See [📘 Max fragments](https://pagefind.app/docs/config-options/#max-fragments).

##### Explicit Sub-Result Titles

Added support for explicit sub-result titles. Any element with both an `id` and a `data-pagefind-title` attribute can be used as a sub-result (PR [#&#8203;1282](https://github.com/Pagefind/pagefind/issues/1282) — thanks [@&#8203;samuel-williams-shopify](https://github.com/samuel-williams-shopify) !)

See [📘 Defining a sub result explicitly](https://pagefind.app/docs/sub-results/#defining-a-sub-result-explicitly).

##### Component UI

- Added a `sort` attribute to `<pagefind-config>`, to order results by a [sort key](https://pagefind.app/docs/js-api-sorting/) (PR [#&#8203;1326](https://github.com/Pagefind/pagefind/issues/1326))
- Added a `max-sub-results` attribute to `<pagefind-searchbox>` (PR [#&#8203;1324](https://github.com/Pagefind/pagefind/issues/1324))
- Added a `placeholder` setter to `<pagefind-searchbox>` and `<pagefind-modal-trigger>` (PR [#&#8203;1321](https://github.com/Pagefind/pagefind/issues/1321))
- `configureInstance` now applies to an instance that already exists but has not loaded yet (PR [#&#8203;1323](https://github.com/Pagefind/pagefind/issues/1323))
- Fixed the UI language being resolved after the first render, which could flash the wrong translations (PR [#&#8203;1332](https://github.com/Pagefind/pagefind/issues/1332))
- Fixed component cleanup after being disconnected (PR [#&#8203;1322](https://github.com/Pagefind/pagefind/issues/1322))
- Fixed IME composition keystrokes support (PR [#&#8203;1284](https://github.com/Pagefind/pagefind/issues/1284) — thanks [@&#8203;oharu121](https://github.com/oharu121) !)
- Fixed the modal staying open when clicking a result for the current page (PR [#&#8203;1327](https://github.com/Pagefind/pagefind/issues/1327))
- Fixed the filter panel checkbox shrinking when its label wraps (PR [#&#8203;1166](https://github.com/Pagefind/pagefind/issues/1166) — thanks [@&#8203;mbrambilla](https://github.com/mbrambilla) !)
- Hid the keyboard shortcut badge on touch-only devices (PR [#&#8203;1325](https://github.com/Pagefind/pagefind/issues/1325))

##### Search Results & Options

- Added an `excerptEllipsis` option to mark the truncated ends of excerpts (PR [#&#8203;1320](https://github.com/Pagefind/pagefind/issues/1320))
  - See [📘 Excerpt ellipsis](https://pagefind.app/docs/search-config/#excerpt-ellipsis)
- Fixed phrase search across diacritic variants, so searching `"cafe latte"` can match a page containing `café latte` (PR [#&#8203;1386](https://github.com/Pagefind/pagefind/issues/1386) — thanks [@&#8203;sean0407](https://github.com/sean0407) !)
- Fixed filters not matching values containing escaped characters such as quotes or backslashes (PR [#&#8203;1392](https://github.com/Pagefind/pagefind/issues/1392))
- Fixed compound words being counted twice in metadata coverage, which could overvalue a metadata match (PR [#&#8203;1319](https://github.com/Pagefind/pagefind/issues/1319))
- Fixed a bug which could build excerpts from the wrong words (PR [#&#8203;1318](https://github.com/Pagefind/pagefind/issues/1318))
- Fixed decoding for HTML entities in the automatic `image` and `image_alt` metadata (PR [#&#8203;1393](https://github.com/Pagefind/pagefind/issues/1393) — thanks [@&#8203;digilist](https://github.com/digilist) !)

##### Indexing & Performance

- More work making the index deterministic between builds (PR [#&#8203;1124](https://github.com/Pagefind/pagefind/issues/1124) — thanks [@&#8203;gissimo](https://github.com/gissimo) !)
- Improved search performance on a bunch of broad queries (PR [#&#8203;1334](https://github.com/Pagefind/pagefind/issues/1334))
- Fixed a bug where a word with many variants could produce an oversized index chunk (PR [#&#8203;1316](https://github.com/Pagefind/pagefind/issues/1316))
- Searches no longer request index chunks for empty terms (PR [#&#8203;1317](https://github.com/Pagefind/pagefind/issues/1317))
- More minor search performance work (PR [#&#8203;1238](https://github.com/Pagefind/pagefind/issues/1238) — thanks [@&#8203;sanjaiyan-dev](https://github.com/sanjaiyan-dev) !)

##### Fixes & Tweaks

- Search terms that normalize to nothing are now dropped, rather than searching for an empty term (PR [#&#8203;1382](https://github.com/Pagefind/pagefind/issues/1382))
- Improved some compound indexing, so `sysconfig.is_python_build` can be found by searching `is_python_build`
- Fixed a way that output files could be truncated in service-mode (PR [#&#8203;1272](https://github.com/Pagefind/pagefind/issues/1272) — thanks [@&#8203;zelinskyy](https://github.com/zelinskyy) !)
- Fixed `--exclude-selectors` hard-erroring when a single selector could not be parsed (PR [#&#8203;1312](https://github.com/Pagefind/pagefind/issues/1312) — thanks [@&#8203;dualfroz](https://github.com/dualfroz) !)
- Improved handling of percent-encoded page URLs (PR [#&#8203;1315](https://github.com/Pagefind/pagefind/issues/1315), PR [#&#8203;1335](https://github.com/Pagefind/pagefind/issues/1335) — thanks [@&#8203;dualfroz](https://github.com/dualfroz) !)
- Failed index fetches are now evicted from the cache correctly and are retried (PR [#&#8203;1329](https://github.com/Pagefind/pagefind/issues/1329))
- Per-page warnings are now only logged with `--verbose` (PR [#&#8203;1314](https://github.com/Pagefind/pagefind/issues/1314))

##### UI Translations

- Added Macedonian (mk) translations (PR [#&#8203;1353](https://github.com/Pagefind/pagefind/issues/1353) — thanks [@&#8203;I90rche](https://github.com/I90rche) !)
- Added Bulgarian (bg) translations (PR [#&#8203;1341](https://github.com/Pagefind/pagefind/issues/1341) — thanks [@&#8203;salif](https://github.com/salif) !)
- Improved French (fr) translations (PR [#&#8203;1145](https://github.com/Pagefind/pagefind/issues/1145) — thanks [@&#8203;maxonss](https://github.com/maxonss) !)
- Improved German (de) translations (PR [#&#8203;1096](https://github.com/Pagefind/pagefind/issues/1096) — thanks [@&#8203;randomguy-2650](https://github.com/randomguy-2650) !)
- Improved Persian (fa) translations (PR [#&#8203;1204](https://github.com/Pagefind/pagefind/issues/1204) — thanks [@&#8203;Goudarz](https://github.com/Goudarz) !)
- Improved Swahili (sw) translations (PR [#&#8203;1185](https://github.com/Pagefind/pagefind/issues/1185) — thanks [@&#8203;gully223](https://github.com/gully223) !)

</details>

<details>
<summary>withastro/astro (astro)</summary>

### [`v7.4.5`](https://github.com/withastro/astro/blob/HEAD/packages/astro/CHANGELOG.md#745)

[Compare Source](https://github.com/withastro/astro/compare/[email protected]@7.4.5)

##### Patch Changes

- [#&#8203;18558](https://github.com/withastro/astro/pull/18558) [`fac3c50`](https://github.com/withastro/astro/commit/fac3c50463ce9c290bdccb1d6dba30dc7ca4d779) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes `astro dev status` and other background server commands deleting the lock file of a running dev or preview server when run from a sandbox or as another user that is not permitted to signal its process

- [#&#8203;18559](https://github.com/withastro/astro/pull/18559) [`10dae2f`](https://github.com/withastro/astro/commit/10dae2f31486cc0a6a04d1f3d7f5ab7fa8889b30) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes `import.meta.env` values containing `$` sequences (such as `$$` or `$&`) being corrupted in `astro build` when server code reads the `import.meta.env` object directly, for example with `const { MY_SECRET } = import.meta.env`

- [#&#8203;18544](https://github.com/withastro/astro/pull/18544) [`e3bec3d`](https://github.com/withastro/astro/commit/e3bec3d2c770cb53771dad723db57a2ebf931b42) Thanks [@&#8203;skezo](https://github.com/skezo)! - Fixes request paths with invalid percent-encoding (e.g. `/%C0%AF` or a bare `%`) being logged as an `Invalid URL encoding` error and routed with the undecoded path. These requests now return a `400`, the same as a path that is encoded too many times.

- [#&#8203;18520](https://github.com/withastro/astro/pull/18520) [`e023aba`](https://github.com/withastro/astro/commit/e023abac912d7cb6af2b9fb5107ef5dabc667096) Thanks [@&#8203;matthewp](https://github.com/matthewp)! - Makes rendering of string tag names stricter and consistent across `.astro` dynamic tags, JSX, and MDX. Only the leading part of the string that is a valid element name is rendered, so characters such as `/` or `=` can no longer change the generated markup. A string that does not start with a valid element name (for example `'!--'` or `''`) now throws an error instead of producing invalid HTML.

### [`v7.4.4`](https://github.com/withastro/astro/blob/HEAD/packages/astro/CHANGELOG.md#744)

[Compare Source](https://github.com/withastro/astro/compare/[email protected]@7.4.4)

##### Patch Changes

- [#&#8203;18344](https://github.com/withastro/astro/pull/18344) [`df838da`](https://github.com/withastro/astro/commit/df838da6c6d965504fae0d89e12d3e67bdd0f4c6) Thanks [@&#8203;edmundhung](https://github.com/edmundhung)! - Allows `astro add` to configure tagged versions of official adapters

### [`v7.4.3`](https://github.com/withastro/astro/blob/HEAD/packages/astro/CHANGELOG.md#743)

[Compare Source](https://github.com/withastro/astro/compare/[email protected]@7.4.3)

##### Patch Changes

- [#&#8203;18488](https://github.com/withastro/astro/pull/18488) [`e4e25fa`](https://github.com/withastro/astro/commit/e4e25fa7d47e702985cbb1ee633d4ffb92f8dad6) Thanks [@&#8203;umeraamir69](https://github.com/umeraamir69)! - CSP no longer hashes empty children on external stylesheets and scripts, which was inserting the SHA-256 of the empty string into `script-src` and `style-src`.

- [#&#8203;18500](https://github.com/withastro/astro/pull/18500) [`e5a3a1b`](https://github.com/withastro/astro/commit/e5a3a1bdec268933f01a0da3fbeb4e38bdf455c9) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes `<Image>` and `<Picture>` emitting duplicate `srcset` candidates when `densities` contains equivalent values such as `1` and `'1x'`

- [#&#8203;18517](https://github.com/withastro/astro/pull/18517) [`c3185b7`](https://github.com/withastro/astro/commit/c3185b764e14f50664b0e63ec665804fdecf685e) Thanks [@&#8203;okxint](https://github.com/okxint)! - Fix unhandled `AbortError` rejection when `ClientRouter` skips a pending view transition

- [#&#8203;18497](https://github.com/withastro/astro/pull/18497) [`c712113`](https://github.com/withastro/astro/commit/c7121132acc25ee3a7f3dc6dd36240f031537878) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes an uncaught `TypeError` in the browser when a `server:defer` island request fails due to a network error. The fallback content is kept, as it is for non-200 responses.

- [#&#8203;18525](https://github.com/withastro/astro/pull/18525) [`d0240b9`](https://github.com/withastro/astro/commit/d0240b9d5738a97f0b8ad100b76bce8b7527e4cd) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes a `DEP0190` deprecation warning printed by `astro info` on Node.js 24 and later

- [#&#8203;18522](https://github.com/withastro/astro/pull/18522) [`776b9a6`](https://github.com/withastro/astro/commit/776b9a6124a8d5aef8e280a8af4f8ba68c80e65b) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes `memoryCache()` serving an empty body for cached pages that return an empty `404` or `500` response. These responses now render the `404` or `500` error page on every request.

- [#&#8203;18511](https://github.com/withastro/astro/pull/18511) [`d060ff9`](https://github.com/withastro/astro/commit/d060ff9b68f737af2788e521635afb6f6a84b029) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes `transition:name` styles missing in dev when the element is inside a component that is only rendered through another component with no styles or scripts

- [#&#8203;18494](https://github.com/withastro/astro/pull/18494) [`5fe699c`](https://github.com/withastro/astro/commit/5fe699c888d0423db75cac3f0939409d7eb28e37) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes the `astro` CLI refusing to run on StackBlitz by allowing Node.js `>=22.22.0` inside WebContainers, whose Node.js version users cannot change

- [#&#8203;18506](https://github.com/withastro/astro/pull/18506) [`bf43a60`](https://github.com/withastro/astro/commit/bf43a6042f8a9e87c2cef1b4c36700d4e941c35f) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes `<ClientRouter />` animating scroll restoration on back/forward navigation when `scroll-behavior: smooth` is set. Saved scroll positions are now restored instantly, matching the browser's native behavior.

- [#&#8203;18476](https://github.com/withastro/astro/pull/18476) [`8ea79a2`](https://github.com/withastro/astro/commit/8ea79a282e53b83c65f69c9013f5eeb5d97aadb1) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes a `DataCloneError` crash when building pages that render SVG imports with `<Image />` or `getImage()` while `experimental.parallelPrerender` is enabled.

- [#&#8203;18504](https://github.com/withastro/astro/pull/18504) [`6dbd737`](https://github.com/withastro/astro/commit/6dbd73764f8a0f16d696f276b634e32631982aab) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes `<Picture>` emitting a duplicate `1x` candidate in `<source>` `srcset` when `densities` includes `1`

- [#&#8203;18524](https://github.com/withastro/astro/pull/18524) [`7524889`](https://github.com/withastro/astro/commit/75248890363ce7de03e5d9b56605958323752dc4) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes type errors reported in Astro's built-in `<Image />`, `<Picture />`, `<Code />`, `<Debug />` and `<ClientRouter />` components when type-checking a project that extends `astro/tsconfigs/strictest` with `tsc` and `@astrojs/ts-content-mapper`

- [#&#8203;18493](https://github.com/withastro/astro/pull/18493) [`3773941`](https://github.com/withastro/astro/commit/377394179293d1f898c49d38a5b28cf9b21641a9) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes scoped styles of unused Astro components being included in the build when those components are re-exported from a barrel file

- [#&#8203;18512](https://github.com/withastro/astro/pull/18512) [`1151b9e`](https://github.com/withastro/astro/commit/1151b9e0d05e850fa3638a927ac9f66179010e00) Thanks [@&#8203;jp-knj](https://github.com/jp-knj)! - Fixes CSP hashes added with `Astro.csp` from components rendered inside `<body>` being left out of the CSP `<meta>` element in static builds, including MDX pages

- Updated dependencies \[[`6cf3423`](https://github.com/withastro/astro/commit/6cf3423e4c62af5e54a2676c8304a209ab1e064d), [`edfbf4a`](https://github.com/withastro/astro/commit/edfbf4ab34ff007ae8f7188af76a023a15c9443d)]:
  - [@&#8203;astrojs/telemetry](https://github.com/astrojs/telemetry)@3.4.2
  - [@&#8203;astrojs/markdown-satteri](https://github.com/astrojs/markdown-satteri)@0.4.6

</details>

<details>
<summary>pnpm/pnpm (pnpm)</summary>

### [`v12.17.0`](https://github.com/pnpm/pnpm/releases/tag/v12.17.0): pnpm 12.17

[Compare Source](https://github.com/pnpm/pnpm/compare/v12.16.1...v12.17.0)

pnpm 12.17.0 adds `pnpm peers check --global`, dependency-group selectors and wildcards in `overrides`, and runtime, package manager, Cargo, and Python updates in `pnpm outdated` and `pnpm update`. It also fixes files that other users could not read in Docker images, and repeat installs that missed changes to local dependencies.

##### Minor Changes

- `pnpm peers check` now accepts `--global` (`-g`) to check globally installed packages. After a global install or update, the peer dependency warning now suggests `pnpm peers check -g` [#&#8203;17504](https://github.com/pnpm/pnpm/issues/17504).

- `pnpm outdated` and `pnpm update` now inspect and update package manager and runtime versions in `devEngines.packageManager`, `packageManager`, `devEngines.runtime`, `engines.runtime`, and `runtime:` dependencies. With `cargo.enabled` or `python.enabled`, `pnpm outdated` and `pnpm update` also inspect and update Cargo dependencies in `Cargo.toml` and `Cargo.lock` and Python dependencies in `pyproject.toml` and `pylock.toml`.

- `overrides` selectors now support `:prod`, `:optional`, and `:peer` pseudo-selectors that target a single dependency group. They also support `*` wildcard patterns on parent and target package names. An override with a non-range value, such as `npm:` or `file:`, no longer adds a peer dependency to `dependencies`. Removing an optional dependency with `"-"` now also removes the duplicate entry from `dependencies` [#&#8203;5391](https://github.com/pnpm/pnpm/issues/5391).

##### Patch Changes

##### Installing packages

- Files that pnpm creates in a project now get the permissions the umask gives any new file, such as `0644`. Before, several of them were readable only by the user who ran pnpm, which broke Docker images that run as a different user [#&#8203;17435](https://github.com/orgs/pnpm/discussions/17435).

  The fix applies to:

  - `node_modules/.pnpm-workspace-state-v1.json`. A different user running `pnpm run` reinstalled the dependencies because it could not read this file.
  - `pnpm-workspace.yaml`
  - the files written by `pnpm deploy`
  - patch files from `pnpm patch-commit`
  - the lockfile restored by `pnpm dedupe --check`
  - the Cargo and Python files that pnpm writes

  When pnpm edits an existing file, the file keeps its permissions.

- `pnpm install` no longer writes broken dependency links when the project's `node_modules` is a symlink to another directory, such as another project's `node_modules`. The install reported success, but the links it wrote did not resolve [#&#8203;17448](https://github.com/pnpm/pnpm/issues/17448).

- Commands installed with `pnpm add --global` now find the dependencies that pnpm hoists for their package. A package that loads a dependency it does not declare, such as a native addon's platform-specific package, failed with "Cannot find module". Reinstall such a package with `pnpm add --global` to update its existing command [#&#8203;17503](https://github.com/pnpm/pnpm/issues/17503).

- When pnpm switches to the version a project pins, it now installs that version's native binary for the current host, even if the project's `supportedArchitectures` excludes the host. Before, pnpm could not use the pinned version and kept running the installed one. pnpm also repairs a pinned version that an earlier install left without the host's binary.

- With the global virtual store, a change to a dependency of one package in a dependency cycle now gives every package in that cycle a new directory. Before, the other packages kept their directories and still linked the old copy of the changed package, so the project could load two copies of it [#&#8203;17466](https://github.com/pnpm/pnpm/issues/17466).

  Packages in a dependency cycle, and packages that depend on one, move to new global virtual store directories once after this update. Those that run a build miss the side-effects cache once.

- With `nodeLinker: hoisted`, when two workspace projects need the same package version and it cannot be hoisted to the root, each project now keeps the copy installed in its own `node_modules`. Build scripts run in each of these copies. Before, the second project's copy was replaced with a symlink to the first project's, so every repeat install imported it again [#&#8203;17498](https://github.com/pnpm/pnpm/issues/17498).

- The Node.js `latest` selector now chooses the newest stable release [#&#8203;17490](https://github.com/pnpm/pnpm/issues/17490).

- Hardlinking from the store now stats each store file once per install. Since pnpm 12.8.0, a store file was stat'ed again for every package that links it. On an offline install of a large workspace, that added up to 15% system CPU [#&#8203;17500](https://github.com/pnpm/pnpm/issues/17500).

##### Repeat installs and local dependencies

- `pnpm install --frozen-lockfile` no longer reports an outdated lockfile right after the install that wrote it. This happened when a pnpmfile `readPackage` hook or `packageExtensions` changed the dependencies or peer dependencies of a local directory dependency outside the workspace projects. It affected a `file:` dependency, an injected `workspace:../dir` dependency outside the workspace patterns, and an injected workspace package left out by `--filter` [#&#8203;17447](https://github.com/pnpm/pnpm/issues/17447) [#&#8203;17473](https://github.com/pnpm/pnpm/issues/17473).

  A repeat `pnpm install` now takes the fast path when `ignoredOptionalDependencies` removes an optional dependency of a `file:` directory dependency. It used to resolve again on every run.

- `pnpm install` now resolves again after an edit to an injected `workspace:../dir` dependency outside the workspace patterns under a shared lockfile. It used to keep the lockfile unchanged. The next `pnpm install --frozen-lockfile` then failed [#&#8203;17476](https://github.com/pnpm/pnpm/issues/17476).

- `pnpm install` now resolves a local directory again after its `package.json` changes when an override or a package extension adds it to the dependencies of a registry package. `pnpm install --frozen-lockfile` fails on a lockfile that still records the old dependencies of such a directory [#&#8203;17486](https://github.com/pnpm/pnpm/issues/17486).

- With `injectWorkspacePackages` and per-project lockfiles, `pnpm install` now updates a project's lockfile when a local tarball that an injected workspace project depends on is replaced. The project's lockfile kept the old version and integrity before.

- `pnpm install` now detects a change to a local tarball or directory that only a pnpmfile `readPackage` hook depends on. A repeat install reported "Already up to date" and kept the old contents before [pnpm/tasks#227](https://github.com/pnpm/tasks/issues/227).

- `pnpm install` now relinks a `workspace:` or `link:` dependency whose link was deleted from `node_modules`. It used to report "Already up to date" and leave the link missing [#&#8203;17485](https://github.com/pnpm/pnpm/issues/17485).

- A repeat `pnpm install` reports "Already up to date" again when a pnpmfile `readPackage` hook changes the dependencies of a workspace project. Since 12.15.0, every such install ran in full [#&#8203;17468](https://github.com/pnpm/pnpm/issues/17468).

  After an edit to a project's `package.json`, `pnpm install` and `verifyDepsBeforeRun` now run the pnpmfile's `readPackage` hook on the edited manifest before comparing it with the lockfile. They could report the project up to date when the hook rewrote the edited dependency to a specifier the lockfile did not record.

##### Adding and updating dependencies

- `pnpm update --latest` with package selectors now updates the dependencies of the selected packages within their declared ranges. Excluded packages and their dependencies keep their locked versions [#&#8203;17444](https://github.com/pnpm/pnpm/issues/17444).

- `pnpm add <pkg>@<tag>` now uses a catalog entry set to that same dist-tag. The dependency is saved as `catalog:` and the entry stays as written [pnpm/tasks#225](https://github.com/pnpm/tasks/issues/225).

  When `pnpm add` adds a new dist-tag such as `vue@legacy` to a catalog, the catalog entry records the exact version the tag points to. The same applies to a dependency added without a version when the `tag` setting names a dist-tag other than `latest`.

- `pnpm add` now saves the resolved version range of an npm alias. For example, `pnpm add v2@npm:vue` and `pnpm add v2@npm:vue@^3.0.0` both save `npm:vue@^3.5.13`.

##### Running scripts and commands

- Programs that a script or `pnpm exec` command leaves running, such as a browser opened by the `open` package, now outlive pnpm exactly when they would outlive the command run without pnpm. Before, on Windows, a failed command, `Ctrl+C`, or a closed terminal ended all of them. pnpm still ends them when it is killed or crashes.

  When a recursive or parallel run bails, the scripts still running now receive `SIGTERM` on Unix and are killed only if they are still running two seconds later. On Windows, everything those scripts started is ended, including detached processes whose parent has already exited. Before, a bail killed them at once [#&#8203;17465](https://github.com/pnpm/pnpm/issues/17465).

- On Windows, the shell shim of a `.cmd` or `.bat` bin now runs it under Git Bash when MSYS argument conversion is off, such as with `MSYS_NO_PATHCONV=1` or `MSYS2_ARG_CONV_EXCL='*'`. The shim used to start an interactive cmd.exe prompt [#&#8203;17480](https://github.com/pnpm/pnpm/issues/17480).

- `pnx` and `pnpm create` now run the command in the directory selected by `--dir` or `--workspace-root`. Without either flag, the command still runs in the directory pnpm was started in.

- `pnpm --env-file` now reads files the way `node --env-file` does. Values are taken as written, so `$VAR` is no longer expanded and Windows paths such as `C:\Users\me` load unchanged. A file is no longer rejected for its contents.

##### Settings and messages

- `pnpm version` no longer creates a git commit and tag when `gitTagVersion` is set to `false` [#&#8203;17460](https://github.com/pnpm/pnpm/issues/17460).

- `pnpm publish` now reads the `publishBranch` setting from `pnpm-workspace.yaml` and from `PNPM_CONFIG_PUBLISH_BRANCH`. The `--publish-branch` flag overrides it.

- `pnpm` now accepts `--strict-ssl` and `--local-address <ip>` on the command line.

- `pnpm doctor` uses a 15-second timeout when checking registry connectivity.

- `pnpm-workspace.yaml` parse errors now report `ERR_PNPM_INVALID_SETTING`.

- The error for a dependency with an invalid name in a project's manifest now names the project's directory. It used to say only "The current package", which did not tell which workspace project to fix [#&#8203;17475](https://github.com/pnpm/pnpm/issues/17475).

<!-- sponsors -->

#### Platinum Sponsors

<table>
  <tbody>
    <tr>
      <td align="center" valign="middle">
        <a href="https://bit.cloud/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer"><img src="https://pnpm.io/img/users/bit.svg" width="80" alt="Bit"></a>
      </td>
      <td align="center" valign="middle">
        <a href="https://openai.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/openai_dark.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/openai_light.svg" />
            <img src="https://pnpm.io/img/users/openai_dark.svg" width="160" alt="OpenAI" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://notion.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer"><img src="https://pnpm.io/img/users/notion.svg" width="80" alt="Notion"></a>
      </td>
    </tr>
    <tr>
      <td align="center" valign="middle">
        <a href="https://coderabbit.ai/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/coderabbit.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/coderabbit_light.svg" />
            <img src="https://pnpm.io/img/users/coderabbit.svg" width="220" alt="CodeRabbit" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://www.cloudflare.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/cloudflare.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/cloudflare_light.svg" />
            <img src="https://pnpm.io/img/users/cloudflare.svg" width="160" alt="Cloudflare" />
          </picture>
        </a>
      </td>
    </tr>
  </tbody>
</table>

#### Gold Sponsors

<table>
  <tbody>
    <tr>
      <td align="center" valign="middle">
        <a href="https://sanity.io/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/sanity.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/sanity_light.svg" />
            <img src="https://pnpm.io/img/users/sanity.svg" width="120" alt="Sanity" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://discord.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/discord.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/discord_light.svg" />
            <img src="https://pnpm.io/img/users/discord.svg" width="220" alt="Discord" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://vite.dev/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer"><img src="https://pnpm.io/img/users/vitejs.svg" width="42" alt="Vite"></a>
      </td>
    </tr>
    <tr>
      <td align="center" valign="middle">
        <a href="https://serpapi.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/serpapi_dark.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/serpapi_light.svg" />
            <img src="https://pnpm.io/img/users/serpapi_dark.svg" width="160" alt="SerpApi" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://stackblitz.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/stackblitz.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/stackblitz_light.svg" />
            <img src="https://pnpm.io/img/users/stackblitz.svg" width="190" alt="Stackblitz" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://workleap.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/workleap.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/workleap_light.svg" />
            <img src="https://pnpm.io/img/users/workleap.svg" width="190" alt="Workleap" />
          </picture>
        </a>
      </td>
    </tr>
    <tr>
      <td align="center" valign="middle">
        <a href="https://nx.dev/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/nx.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/nx_light.svg" />
            <img src="https://pnpm.io/img/users/nx.svg" width="50" alt="Nx" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://latitude.so/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer"><img src="https://pnpm.io/img/users/latitude.svg" width="160" alt="Latitude"></a>
      </td>
      <td align="center" valign="middle">
        <a href="https://syntax.fm/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/syntaxfm.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/syntaxfm_light.svg" />
            <img src="https://pnpm.io/img/users/syntaxfm.svg" width="90" alt="Syntax" />
          </picture>
        </a>
      </td>
    </tr>
  </tbody>
</table>

<!-- sponsors end -->

</details>

---

### Configuration

📅 **Schedule**: (UTC)

- Branch creation
  - Between 12:00 AM and 03:59 AM, only on Monday (`* 0-3 * * 1`)
- Automerge
  - At any time (no schedule defined)

🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied.

♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox.

👻 **Immortal**: This PR will be recreated if closed unmerged. Get [config help](https://github.com/renovatebot/renovate/discussions) if that's undesired.

---

 - [ ] <!-- rebase-check -->If you want to rebase/retry this PR, check this box

---

This PR has been generated by [Mend Renovate CLI](https://github.com/renovatebot/renovate).
<!--renovate-debug:eyJjcmVhdGVkSW5WZXIiOiI0NC4xOTkuMiIsInVwZGF0ZWRJblZlciI6IjQ0LjIyMi41IiwidGFyZ2V0QnJhbmNoIjoibWFpbiIsImxhYmVscyI6W119-->

<!-- cloudflare-preview --> Preview: https://pr-640.docs-gitea-com.pages.dev

---------

Co-authored-by: Lunny Xiao <[email protected]>
Reviewed-on: https://gitea.com/gitea/docs/pulls/640
Reviewed-by: Lunny Xiao <[email protected]>
Co-authored-by: Renovate Bot <[email protected]>
2026-11-09 04:54:24 +00:00
Gitea Bot 4d38601dc2 Update the runner reference pages (#642)
Automated update of the generated runner reference pages from gitea/runner (main for the develop docs, the newest stable tag for every documented series), opened by the "update runner reference" scheduled workflow.

<!-- cloudflare-preview --> Preview: https://pr-642.docs-gitea-com.pages.dev

Reviewed-on: https://gitea.com/gitea/docs/pulls/642
Reviewed-by: Lunny Xiao <[email protected]>
Co-authored-by: Gitea Bot <[email protected]>
2026-11-09 04:31:01 +00:00
Gitea Bot 6779b1d6d8 Update the latest api documents (#641)
Automated update of static/swagger-latest.json and static/openapi3-latest.json from the gitea main branch, opened by the "update api spec files" scheduled workflow.

<!-- cloudflare-preview --> Preview: https://pr-641.docs-gitea-com.pages.dev

Reviewed-on: https://gitea.com/gitea/docs/pulls/641
Reviewed-by: Lunny Xiao <[email protected]>
Co-authored-by: Gitea Bot <[email protected]>
2026-11-09 03:12:46 +00:00
878c885050 docs(packages): document terraform module registry (#433)
Ref: https://github.com/go-gitea/gitea/pull/38040

Adds docs/usage/packages/terraform-module.md describing the v1 scope,
naming rules, authentication, service discovery, HTTP API surface and
[packages] settings for the new private Terraform Module Registry.

---------

Co-authored-by: silverwind <[email protected]>
Co-authored-by: silverwind <[email protected]>
Co-authored-by: Lunny Xiao <[email protected]>
Reviewed-on: https://gitea.com/gitea/docs/pulls/433
Reviewed-by: silverwind <[email protected]>
Co-authored-by: Michael Lopez <[email protected]>
2026-11-07 11:43:22 +00:00
silverwind 6135d1dabf Trim the Actions comparison to actual differences (#638)
`$/` is [GitHub's self-repository prefix](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#example-using-an-action-in-the-same-repository-as-the-workflow-at-the-running-commit-recommended) with the same semantics, so it is no Gitea addition. The `builtin:checkout` input list was outdated since https://gitea.com/gitea/runner/pulls/1277 made it match `actions/checkout`.

Reviewed-on: https://gitea.com/gitea/docs/pulls/638
Reviewed-by: Lunny Xiao <[email protected]>
Co-authored-by: silverwind <[email protected]>
2026-11-07 09:42:48 +00:00
wxiaoguangandLunny Xiao 0ddb9a2071 codeowners (#634)
https://github.com/go-gitea/gitea/pull/40243
Co-authored-by: Lunny Xiao <[email protected]>
Reviewed-on: https://gitea.com/gitea/docs/pulls/634
Reviewed-by: Lunny Xiao <[email protected]>
Co-authored-by: wxiaoguang <[email protected]>
2026-11-06 20:00:46 +00:00
silverwind 71869c6e24 Document MSSQL database preparation (#636)
The database preparation page covered only MySQL and PostgreSQL. MSSQL setups without schema permissions break on upgrades, like in https://github.com/go-gitea/gitea/issues/40256.

The new section shows the login, database and user setup with the roles Gitea needs, for main and 28, including zh-cn and zh-tw.

_Written by Claude (Opus 5.5)._

Reviewed-on: https://gitea.com/gitea/docs/pulls/636
Reviewed-by: Lunny Xiao <[email protected]>
Co-authored-by: silverwind <[email protected]>
2026-11-06 17:12:50 +00:00
silverwind 46b5401a81 Document the new DEFAULT_DELETE_BRANCH_AFTER_MERGE default (#608)
Documents https://github.com/go-gitea/gitea/pull/39975 for main, which changes the default of `DEFAULT_DELETE_BRANCH_AFTER_MERGE` to `true`.

Reviewed-on: https://gitea.com/gitea/docs/pulls/608
Reviewed-by: Lunny Xiao <[email protected]>
2026-11-05 23:34:03 +00:00
Gitea BotandLunny Xiao f6e17361fe Update the runner reference pages (#628)
Automated update of the generated runner reference pages from gitea/runner (main for the develop docs, the newest stable tag for every documented series), opened by the "update runner reference" scheduled workflow.

<!-- cloudflare-preview --> Preview: https://pr-628.docs-gitea-com.pages.dev

---------

Co-authored-by: Lunny Xiao <[email protected]>
Reviewed-on: https://gitea.com/gitea/docs/pulls/628
Reviewed-by: Lunny Xiao <[email protected]>
Co-authored-by: Gitea Bot <[email protected]>
2026-11-02 05:07:00 +00:00
Gitea Bot c3cff4ab08 Update the latest api documents (#627)
Automated update of static/swagger-latest.json and static/openapi3-latest.json from the gitea main branch, opened by the "update api spec files" scheduled workflow.

<!-- cloudflare-preview --> Preview: https://pr-627.docs-gitea-com.pages.dev

Reviewed-on: https://gitea.com/gitea/docs/pulls/627
Reviewed-by: Lunny Xiao <[email protected]>
Co-authored-by: Gitea Bot <[email protected]>
2026-11-02 03:39:31 +00:00
Renovate Bot aa975da532 chore(deps): update dependencies (#626)
This PR contains the following updates:

| Package | Change | [Age](https://docs.renovatebot.com/merge-confidence/) | [Confidence](https://docs.renovatebot.com/merge-confidence/) | Type | Update | Pending |
|---|---|---|---|---|---|---|
| [@astrojs/check](https://github.com/withastro/astro/tree/main/packages/language-tools/astro-check) ([source](https://github.com/withastro/astro/tree/HEAD/packages/language-tools/astro-check)) | [`0.9.11` → `0.9.12`](https://renovatebot.com/diffs/npm/@astrojs%2fcheck/0.9.11/0.9.12) | ![age](https://developer.mend.io/api/mc/badges/age/npm/@astrojs%2fcheck/0.9.12?slim=true) | ![confidence](https://developer.mend.io/api/mc/badges/confidence/npm/@astrojs%2fcheck/0.9.11/0.9.12?slim=true) | devDependencies | patch |  |
| [@astrojs/starlight](https://starlight.astro.build) ([source](https://github.com/withastro/starlight/tree/HEAD/packages/starlight)) | [`0.42.6` → `0.42.7`](https://renovatebot.com/diffs/npm/@astrojs%2fstarlight/0.42.6/0.42.7) | ![age](https://developer.mend.io/api/mc/badges/age/npm/@astrojs%2fstarlight/0.42.7?slim=true) | ![confidence](https://developer.mend.io/api/mc/badges/confidence/npm/@astrojs%2fstarlight/0.42.6/0.42.7?slim=true) | dependencies | patch | `0.42.8` |
| [astro](https://astro.build) ([source](https://github.com/withastro/astro/tree/HEAD/packages/astro)) | [`7.4.1` → `7.4.2`](https://renovatebot.com/diffs/npm/astro/7.4.1/7.4.2) | ![age](https://developer.mend.io/api/mc/badges/age/npm/astro/7.4.2?slim=true) | ![confidence](https://developer.mend.io/api/mc/badges/confidence/npm/astro/7.4.1/7.4.2?slim=true) | dependencies | patch | `7.4.4` (+1) |
| [node](https://github.com/actions/node-versions) | `24` → `26` | ![age](https://developer.mend.io/api/mc/badges/age/github-releases/actions%2fnode-versions/26.12.1?slim=true) | ![confidence](https://developer.mend.io/api/mc/badges/confidence/github-releases/actions%2fnode-versions/24.22.2/26.12.1?slim=true) | uses-with | major | `26.13.0` |
| [pnpm](https://pnpm.io) ([source](https://github.com/pnpm/pnpm/tree/HEAD/pnpm/npm/pnpm)) | [`12.15.0` → `12.16.1`](https://renovatebot.com/diffs/npm/pnpm/12.15.0/12.16.1) | ![age](https://developer.mend.io/api/mc/badges/age/npm/pnpm/12.16.1?slim=true) | ![confidence](https://developer.mend.io/api/mc/badges/confidence/npm/pnpm/12.15.0/12.16.1?slim=true) | packageManager | minor |  |

---

### Release Notes

<details>
<summary>withastro/astro (@&#8203;astrojs/check)</summary>

### [`v0.9.12`](https://github.com/withastro/astro/blob/HEAD/packages/language-tools/astro-check/CHANGELOG.md#0912)

[Compare Source](https://github.com/withastro/astro/compare/@astrojs/[email protected]...@astrojs/[email protected])

##### Patch Changes

- [#&#8203;18455](https://github.com/withastro/astro/pull/18455) [`7af66fc`](https://github.com/withastro/astro/commit/7af66fc785d85b1df1f98e7123a52b2306250985) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes the `astro-check` binary ignoring its first two command-line arguments, so flags such as `--help`, `--root`, `--watch`, and `--tsconfig` are respected again. If your scripts padded the arguments to work around this (for example, `astro-check -- -- --tsconfig ./tsconfig.app.json`), remove the padding.
- Updated dependencies \[[`044148d`](https://github.com/withastro/astro/commit/044148d5cfbc90e0277b3205a52ec73bc452bb7e)]:
  - [@&#8203;astrojs/language-server](https://github.com/astrojs/language-server)@2.17.3

</details>

<details>
<summary>withastro/starlight (@&#8203;astrojs/starlight)</summary>

### [`v0.42.7`](https://github.com/withastro/starlight/blob/HEAD/packages/starlight/CHANGELOG.md#0427)

[Compare Source](https://github.com/withastro/starlight/compare/@astrojs/[email protected]...@astrojs/[email protected])

##### Patch Changes

- [#&#8203;4264](https://github.com/withastro/starlight/pull/4264) [`94e0985`](https://github.com/withastro/starlight/commit/94e0985ddbbbd5c0f50a4cea94dc2c92de0a607c) Thanks [@&#8203;chrispezza](https://github.com/chrispezza)! - Fixes a layout shift where the table of contents could be painted at the start of the content area and then jump to the end when a page's HTML arrived in several chunks

- [#&#8203;4285](https://github.com/withastro/starlight/pull/4285) [`6f22edd`](https://github.com/withastro/starlight/commit/6f22eddf21c90aed7bd4e3c82e48615a56268a69) Thanks [@&#8203;tunetheweb](https://github.com/tunetheweb)! - Improves hero image loading by adding `fetchpriority="high"` hint for browsers

</details>

<details>
<summary>withastro/astro (astro)</summary>

### [`v7.4.2`](https://github.com/withastro/astro/blob/HEAD/packages/astro/CHANGELOG.md#742)

[Compare Source](https://github.com/withastro/astro/compare/[email protected]@7.4.2)

##### Patch Changes

- [#&#8203;18430](https://github.com/withastro/astro/pull/18430) [`dda9ec3`](https://github.com/withastro/astro/commit/dda9ec395c89a1420abb3b8f88b5c7f1f385f82e) Thanks [@&#8203;Abhirup-99](https://github.com/Abhirup-99)! - Speeds up content sync with `experimental.collectionStorage: "chunked"` by computing each character's UTF-8 width from its code point instead of encoding every character through `TextEncoder`. On a store of \~44k entries this cuts the chunking step from about 60 seconds to well under a second, with byte-identical output.

- [#&#8203;18438](https://github.com/withastro/astro/pull/18438) [`5e0eaa4`](https://github.com/withastro/astro/commit/5e0eaa4415a9081efdaeb3d9af3717ce3226ad18) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes `astro dev` with `@astrojs/cloudflare` failing with ``Calling `require` for "node-fetch"`` when a server dependency such as `cross-fetch` requires `node-fetch`

- [#&#8203;18376](https://github.com/withastro/astro/pull/18376) [`a4e201d`](https://github.com/withastro/astro/commit/a4e201d79f19caa6bf4222f42167aeb602c066e6) Thanks [@&#8203;okxint](https://github.com/okxint)! - Fixes `astro dev` treating a stale lock file containing a Linux thread ID as a running Astro server. A successful process lookup with no matching PID now marks the lock as stale, preventing `astro dev stop` and `astro dev --force` from killing the unrelated process that owns the thread.

- [#&#8203;18467](https://github.com/withastro/astro/pull/18467) [`d1fb7d3`](https://github.com/withastro/astro/commit/d1fb7d36dad440c57d62b071e752ae220cca2baa) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes the `defineConfig()` types for `i18n.defaultLocale`, `i18n.fallback`, and `i18n.domains` so they accept a custom locale's `path` instead of its `codes`, matching how Astro validates and uses these values

- [#&#8203;18475](https://github.com/withastro/astro/pull/18475) [`cf27e70`](https://github.com/withastro/astro/commit/cf27e70a9057ce29ade2a8a843bd9275a696e9ab) Thanks [@&#8203;ematipico](https://github.com/ematipico)! - Bumps the minimum supported Node.js version to 22.23.4, which includes the fixes from the [October 2026 Node.js security releases](https://nodejs.org/en/blog/vulnerability/october-2026-security-releases)

  This is a patch release because the [Node.js support and upgrade policy](https://docs.astro.build/en/upgrade-astro/#nodejs-support-and-upgrade-policies) allows the Core team to raise the minimum Maintenance LTS version in a patch release when a disclosed and fixed Node.js security flaw affects Astro.

- [#&#8203;18451](https://github.com/withastro/astro/pull/18451) [`7a0ba6f`](https://github.com/withastro/astro/commit/7a0ba6f48ebae256a1ce49de4f1c62c009ff94e2) Thanks [@&#8203;DenisCDev](https://github.com/DenisCDev)! - Fixes `astro sync`, `astro check` and `astro build` replacing the optimized dependencies of a dev server running in the same project, which broke framework islands in that dev server until it was restarted with `--force`

- [#&#8203;18336](https://github.com/withastro/astro/pull/18336) [`e943003`](https://github.com/withastro/astro/commit/e943003259c3bb4d528d3d49c8ccd3eb8f84b8b5) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes inline styles in dev so that framework-transformed CSS is used, such as scoped styles and `v-bind()` in Vue single-file components

- [#&#8203;18399](https://github.com/withastro/astro/pull/18399) [`829fc00`](https://github.com/withastro/astro/commit/829fc00629ef715fc606b89c6e684ca93f9253b9) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes a dev server error (`Could not find server component name`) for a `server:defer` island that imports `astro:actions` or `astro:config/server`, when its page was not the first island page loaded after starting the server

- [#&#8203;18330](https://github.com/withastro/astro/pull/18330) [`4db9e0d`](https://github.com/withastro/astro/commit/4db9e0d1e6a54c2300b96a0ff0cfaf5c188cecda) Thanks [@&#8203;Samuteg](https://github.com/Samuteg)! - Fixes the `astro:env/server` virtual module being generated with invalid JS in dev when any environment variable contains `$` replacement patterns (`` $` ``, `$&`, `$'`, `$1`, …). The inlined env JSON was passed as a string to `String.replace`, so e.g. the `KITTY_PUBLIC_KEY` value set by default in Kitty terminals corrupted the module and broke dev with `Failed to parse source for import analysis`

- Updated dependencies \[[`cf27e70`](https://github.com/withastro/astro/commit/cf27e70a9057ce29ade2a8a843bd9275a696e9ab)]:
  - [@&#8203;astrojs/telemetry](https://github.com/astrojs/telemetry)@3.4.1
  - [@&#8203;astrojs/markdown-satteri](https://github.com/astrojs/markdown-satteri)@0.4.5

</details>

<details>
<summary>actions/node-versions (node)</summary>

### [`v26.12.1`](https://github.com/actions/node-versions/releases/tag/26.12.1-39618969937): 26.12.1

[Compare Source](https://github.com/actions/node-versions/compare/26.12.0-38668157440...26.12.1-39618969937)

Node.js 26.12.1

### [`v26.12.0`](https://github.com/actions/node-versions/releases/tag/26.12.0-38668157440): 26.12.0

[Compare Source](https://github.com/actions/node-versions/compare/26.11.1-37718106145...26.12.0-38668157440)

Node.js 26.12.0

### [`v26.11.1`](https://github.com/actions/node-versions/releases/tag/26.11.1-37718106145): 26.11.1

[Compare Source](https://github.com/actions/node-versions/compare/26.11.0-37718124002...26.11.1-37718106145)

Node.js 26.11.1

### [`v26.11.0`](https://github.com/actions/node-versions/releases/tag/26.11.0-37718124002): 26.11.0

[Compare Source](https://github.com/actions/node-versions/compare/26.10.0-35737674515...26.11.0-37718124002)

Node.js 26.11.0

### [`v26.10.0`](https://github.com/actions/node-versions/releases/tag/26.10.0-35737674515): 26.10.0

[Compare Source](https://github.com/actions/node-versions/compare/26.9.0-35174947414...26.10.0-35737674515)

Node.js 26.10.0

### [`v26.9.0`](https://github.com/actions/node-versions/releases/tag/26.9.0-35174947414): 26.9.0

[Compare Source](https://github.com/actions/node-versions/compare/26.8.2-34429851330...26.9.0-35174947414)

Node.js 26.9.0

### [`v26.8.2`](https://github.com/actions/node-versions/releases/tag/26.8.2-34429851330): 26.8.2

[Compare Source](https://github.com/actions/node-versions/compare/26.8.1-33034053154...26.8.2-34429851330)

Node.js 26.8.2

### [`v26.8.1`](https://github.com/actions/node-versions/releases/tag/26.8.1-33034053154): 26.8.1

[Compare Source](https://github.com/actions/node-versions/compare/26.8.0-33034064325...26.8.1-33034053154)

Node.js 26.8.1

### [`v26.8.0`](https://github.com/actions/node-versions/releases/tag/26.8.0-33034064325): 26.8.0

[Compare Source](https://github.com/actions/node-versions/compare/26.7.0-31064755789...26.8.0-33034064325)

Node.js 26.8.0

### [`v26.7.0`](https://github.com/actions/node-versions/releases/tag/26.7.0-31064755789): 26.7.0

[Compare Source](https://github.com/actions/node-versions/compare/26.6.0-30872438625...26.7.0-31064755789)

Node.js 26.7.0

### [`v26.6.0`](https://github.com/actions/node-versions/releases/tag/26.6.0-30872438625): 26.6.0

[Compare Source](https://github.com/actions/node-versions/compare/26.5.1-30508404249...26.6.0-30872438625)

Node.js 26.6.0

### [`v26.5.1`](https://github.com/actions/node-versions/releases/tag/26.5.1-30508404249): 26.5.1

[Compare Source](https://github.com/actions/node-versions/compare/26.5.0-28944078721...26.5.1-30508404249)

Node.js 26.5.1

### [`v26.5.0`](https://github.com/actions/node-versions/releases/tag/26.5.0-28944078721): 26.5.0

[Compare Source](https://github.com/actions/node-versions/compare/26.4.0-28176665805...26.5.0-28944078721)

Node.js 26.5.0

### [`v26.4.0`](https://github.com/actions/node-versions/releases/tag/26.4.0-28176665805): 26.4.0

[Compare Source](https://github.com/actions/node-versions/compare/26.3.1-27765697053...26.4.0-28176665805)

Node.js 26.4.0

### [`v26.3.1`](https://github.com/actions/node-versions/releases/tag/26.3.1-27765697053): 26.3.1

[Compare Source](https://github.com/actions/node-versions/compare/26.3.0-26776574275...26.3.1-27765697053)

Node.js 26.3.1

### [`v26.3.0`](https://github.com/actions/node-versions/releases/tag/26.3.0-26776574275): 26.3.0

[Compare Source](https://github.com/actions/node-versions/compare/26.2.0-26201774761...26.3.0-26776574275)

Node.js 26.3.0

### [`v26.2.0`](https://github.com/actions/node-versions/releases/tag/26.2.0-26201774761): 26.2.0

[Compare Source](https://github.com/actions/node-versions/compare/26.1.0-25496618813...26.2.0-26201774761)

Node.js 26.2.0

### [`v26.1.0`](https://github.com/actions/node-versions/releases/tag/26.1.0-25496618813): 26.1.0

[Compare Source](https://github.com/actions/node-versions/compare/26.0.0-25413736946...26.1.0-25496618813)

Node.js 26.1.0

### [`v26.0.0`](https://github.com/actions/node-versions/releases/tag/26.0.0-25413736946): 26.0.0

[Compare Source](https://github.com/actions/node-versions/compare/24.22.2-40806817314...26.0.0-25413736946)

Node.js 26.0.0

</details>

<details>
<summary>pnpm/pnpm (pnpm)</summary>

### [`v12.16.1`](https://github.com/pnpm/pnpm/releases/tag/v12.16.1): pnpm 12.16.1

[Compare Source](https://github.com/pnpm/pnpm/compare/v12.16.0...v12.16.1)

This release fixes `pnpm install` hanging on a cold store in workspaces that install Cargo crates, and `pnpm pack` shipping a file that `files` excludes by name.

##### Patch Changes

- `pnpm install` no longer hangs on a cold store in a workspace that also installs Cargo crates or a Rust toolchain.

- `pnpm pack` and `pnpm publish` now apply a `files` entry that names a file after the glob and directory entries, as npm does. A file excluded by name, such as `!dist/index.js`, stays out even when a later `dist/**` matches it. A file named by its path, such as `lib/secret.js`, ships even when a later `!lib/*.js` matches it.

- `pnpm install` no longer leaves a broken symlink in an injected workspace dependency when the package links to a file outside its published files and pnpm imports by hardlink. Installing a git dependency now skips internal directory symlinks when importing its files into the store.

- `pnpm install` now relinks a command that a workspace project renames into the projects that depend on it when `sharedWorkspaceLockfile` is `false` [pnpm/tasks#224](https://github.com/pnpm/tasks/issues/224).

- `pnpm install` and `pnpm rebuild` now refresh privately hoisted `.bin` shims in `node_modules/.pnpm/node_modules/.bin` after a dependency build replaces a script target with a native executable [#&#8203;17402](https://github.com/pnpm/pnpm/issues/17402).

- `pnpm install` now reads a package's manifest to decide its peer dependencies when it updates an existing lockfile, as it does when it resolves from scratch.

- Commands, `pnpm --version`, `pnpm self-update`, and invocations with unknown flags now apply the same `packageManager` and `devEngines.packageManager` settings when switching to the pinned pnpm version or recording it in `pnpm-lock.yaml`. `--config.<key>` flags and `lockfileDir` now reach the version switch and lockfile sync on every entry point. Unreadable settings in `pnpm-workspace.yaml` or the global `config.yaml` that do not affect the pin decision no longer block the version switch [pnpm/tasks#222](https://github.com/pnpm/tasks/issues/222).

- pnpm now accepts the `--cache-dir <dir>` flag, as in `pnpm install --cache-dir /tmp/pnpm-cache` [#&#8203;17422](https://github.com/pnpm/pnpm/issues/17422).

- When the version or range given to `pnpm unpublish` matches every published version, the error now says so and shows the same command with `--force`. Before, the error suggested running `pnpm unpublish <pkg>@<version>`, the command that had just failed.

<!-- sponsors -->

#### Platinum Sponsors

<table>
  <tbody>
    <tr>
      <td align="center" valign="middle">
        <a href="https://bit.cloud/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer"><img src="https://pnpm.io/img/users/bit.svg" width="80" alt="Bit"></a>
      </td>
      <td align="center" valign="middle">
        <a href="https://openai.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/openai_dark.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/openai_light.svg" />
            <img src="https://pnpm.io/img/users/openai_dark.svg" width="160" alt="OpenAI" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://notion.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer"><img src="https://pnpm.io/img/users/notion.svg" width="80" alt="Notion"></a>
      </td>
    </tr>
    <tr>
      <td align="center" valign="middle">
        <a href="https://coderabbit.ai/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/coderabbit.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/coderabbit_light.svg" />
            <img src="https://pnpm.io/img/users/coderabbit.svg" width="220" alt="CodeRabbit" />
          </picture>
        </a>
      </td>
    </tr>
  </tbody>
</table>

#### Gold Sponsors

<table>
  <tbody>
    <tr>
      <td align="center" valign="middle">
        <a href="https://sanity.io/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/sanity.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/sanity_light.svg" />
            <img src="https://pnpm.io/img/users/sanity.svg" width="120" alt="Sanity" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://discord.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/discord.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/discord_light.svg" />
            <img src="https://pnpm.io/img/users/discord.svg" width="220" alt="Discord" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://vite.dev/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer"><img src="https://pnpm.io/img/users/vitejs.svg" width="42" alt="Vite"></a>
      </td>
    </tr>
    <tr>
      <td align="center" valign="middle">
        <a href="https://serpapi.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/serpapi_dark.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/serpapi_light.svg" />
            <img src="https://pnpm.io/img/users/serpapi_dark.svg" width="160" alt="SerpApi" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://stackblitz.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/stackblitz.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/stackblitz_light.svg" />
            <img src="https://pnpm.io/img/users/stackblitz.svg" width="190" alt="Stackblitz" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://workleap.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/workleap.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/workleap_light.svg" />
            <img src="https://pnpm.io/img/users/workleap.svg" width="190" alt="Workleap" />
          </picture>
        </a>
      </td>
    </tr>
    <tr>
      <td align="center" valign="middle">
        <a href="https://nx.dev/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/nx.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/nx_light.svg" />
            <img src="https://pnpm.io/img/users/nx.svg" width="50" alt="Nx" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://latitude.so/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer"><img src="https://pnpm.io/img/users/latitude.svg" width="160" alt="Latitude"></a>
      </td>
    </tr>
  </tbody>
</table>

<!-- sponsors end -->

### [`v12.16.0`](https://github.com/pnpm/pnpm/releases/tag/v12.16.0): pnpm 12.16

[Compare Source](https://github.com/pnpm/pnpm/compare/v12.15.0...v12.16.0)

This release adds a global `--env-file` flag, updates to a symlinked `pnpm-lock.yaml`, and `pnpm setup --no-modify-path`. It also fixes two security issues, in zstd decompression and in signing.

##### Minor Changes

- Added a repeatable global `--env-file <path>` flag to load environment variables from dotenv-style files before running a command. Later files override earlier files, variables already in the environment are preserved, and loaded variables are visible to user-level `.npmrc` interpolation and lifecycle scripts [#&#8203;7111](https://github.com/pnpm/pnpm/issues/7111).

- pnpm can now update a `pnpm-lock.yaml` that is a symlink. List the directories the lockfile may link into in the `symlinkedLockfileTargetDirs` setting, in the global config or with `PNPM_CONFIG_SYMLINKED_LOCKFILE_TARGET_DIRS`. pnpm writes the update to the file the symlink points to if that file is inside one of these directories. The symlink stays in place. pnpm ignores this setting in `pnpm-workspace.yaml` [#&#8203;17222](https://github.com/pnpm/pnpm/issues/17222).

- Added a `--no-modify-path` option to `pnpm setup`. It installs pnpm without adding it to `PATH`, leaving the shell config file, the Windows registry, and the GitHub Actions environment files unchanged. `pnpm setup` then prints the lines to add yourself [get.pnpm.io#37](https://github.com/pnpm/get.pnpm.io/issues/37).

##### Patch Changes

##### Security

- Fixed memory exposure and allocation handling vulnerabilities when processing zstd-compressed data [#&#8203;17388](https://github.com/pnpm/pnpm/pull/17388).

- Signing in pnpm and pnpr no longer uses arithmetic that may leak the private key through timing. This covers shared artifacts, OCI registry tokens, and OIDC login state [advisory](https://rustsec.org/advisories/RUSTSEC-2026-0387).

##### Installing packages

- A dependency symlink that pnpm cannot point at the wanted target now fails the install with an error that names the link. This happens when the filesystem still serves the old link after pnpm removed it, as a `node_modules` served by a virtual filesystem does. pnpm used to remove the link again without end and crashed with a segmentation fault once the thread ran out of stack.

- Concurrent workspace installs no longer lose store-index rows when initializing the shared SQLite index [#&#8203;17388](https://github.com/pnpm/pnpm/pull/17388).

- Agent skill links now keep the same target across installs when a package version is installed with several sets of peer dependencies. An install no longer fails with `ERR_PNPM_AGENT_SKILL_PATH_OCCUPIED` on a skill link that pnpm created for another of those copies [#&#8203;17319](https://github.com/pnpm/pnpm/issues/17319).

- pnpm now fails at once, without retrying, when a downloaded package archive contains a rejected entry path [#&#8203;17205](https://github.com/pnpm/pnpm/issues/17205).

- pnpm now builds a git-hosted dependency in every new location it links the dependency into, such as a new global virtual store slot or a fresh `node_modules`. When the side-effects cache holds the build output, pnpm restores it from there. Before, only the install that fetched the dependency built it. This also fixes dependencies that are already in the store [#&#8203;17224](https://github.com/pnpm/pnpm/issues/17224).

- Changes a `preResolution` hook makes to the lockfiles now take effect. The hook now also runs when pnpm installs from an up-to-date lockfile. An error thrown by the hook now fails the install.

- A custom fetcher in the pnpmfile can now call `fetchers.directory` to fetch a package from a local directory. The call rejects with `ERR_PNPM_TARBALL_INTEGRITY` if the lockfile pins an archive integrity for the package. Previously, calling `fetchers.directory` failed with a `TypeError`.

- `packageImportMethod: copy` now also applies to packages that have lifecycle scripts or patches. On a filesystem that supports block cloning, such as ReFS or a Dev Drive on Windows, these packages were cloned [#&#8203;17195](https://github.com/pnpm/pnpm/issues/17195).

- With `nodeLinker: hoisted` and `autoInstallPeers: false`, a package that workspace projects use with different peer versions is now installed once per peer variant, so each project's copy resolves that project's peer [#&#8203;17395](https://github.com/pnpm/pnpm/issues/17395).

- Under `nodeLinker: hoisted`, `pnpm install` now leaves a patched package that is already in place alone. The same holds for a package whose peers include a patched package, such as every package peering on a patched `react-native` [#&#8203;17188](https://github.com/pnpm/pnpm/issues/17188).

- With `nodeLinker: hoisted`, an install that stops partway no longer leaves the next install trusting the packages it was replacing. Before, reverting the change that started the stopped install, such as a patch edit, kept the half-replaced package in `node_modules`.

##### Repeat installs and changed settings

- A repeat `pnpm install` now acts on a change to these settings. Before, it reported "Already up to date".

  - `storeDir` or `virtualStoreDir`: it recreates `node_modules`.
  - `globalVirtualStoreDir`: it links the packages from the new directory.
  - `virtualStoreDirMaxLength`: it renames the virtual store directories.
  - `dangerouslyAllowAllBuilds` turned on: it runs the builds it skipped.
  - `trustLockfile` turned off: it verifies the lockfile.

- `pnpm add`, `pnpm remove`, and `pnpm update` now fail if `node_modules` does not match the current settings. Run `pnpm install` to recreate it. Previously, these commands removed and reinstalled `node_modules` without asking. They report:

  - `ERR_PNPM_UNEXPECTED_STORE` if `node_modules` was linked from a different store.
  - `ERR_PNPM_UNEXPECTED_VIRTUAL_STORE` if it was linked from a different virtual store directory.
  - `ERR_PNPM_MODULES_BREAKING_CHANGE` if it was installed by an incompatible pnpm version, or if `node_modules/.modules.yaml` cannot be read.
  - `ERR_PNPM_NODE_LINKER_DIFF` if it was installed with a different `nodeLinker`.

  `pnpm update` now also fails with `ERR_PNPM_HOIST_PATTERN_DIFF` and the other errors `pnpm add` reports for a changed hoist pattern or `virtualStoreDirMaxLength`.

- An install filtered to some workspace projects now fails if `node_modules` was installed with a different `nodeLinker`, `hoistPattern`, `publicHoistPattern`, store, or virtual store. Before, it recreated `node_modules` and left the projects it skipped without their dependencies. A `pnpm install` of the whole workspace still recreates `node_modules` [pnpm/tasks#217](https://github.com/pnpm/tasks/issues/217).

- `pnpm install` and the `verifyDepsBeforeRun` check now notice an edited patch file when `sharedWorkspaceLockfile` is `false`.

- `pnpm install` now takes its fast path in a workspace with `patchedDependencies` when the previous install ran with another major version of pnpm.

- `pnpm install` now relinks the bins of a workspace package when its `bin` field changes, including with `--frozen-lockfile` and an unchanged lockfile. A filtered install relinks them in the selected projects, and the next install that covers the remaining projects relinks them there [#&#8203;17324](https://github.com/pnpm/pnpm/issues/17324).

- `pnpm install` now removes command shims from `node_modules/.bin` when a workspace dependency renames or removes an entry from its `bin` field [pnpm/tasks#211](https://github.com/pnpm/tasks/issues/211).

##### Resolving dependencies and the lockfile

- A package that a plain range and a `<prefix>:` specifier both resolve from one registry is now recorded once in `pnpm-lock.yaml` and installed once. The lockfile key names the registry a package resolved from. When that registry declares a prefix, through `prefix` in `registries` or through `namedRegistries`, the package is keyed `<name>@<prefix>:<version>` however its dependency was written: with the prefix, as a plain range its scope routes to that registry, or through the default registry. Before, the plain range was keyed `<name>@<version>`, so one tarball was installed twice and `instanceof` checks and module singletons broke between the two copies. The same name and version served by two registries still get separate entries. When several prefixes declare one registry, its packages are keyed by the lexicographically smallest prefix.

  If a scope you route reaches a registry that also declares a prefix, your next `pnpm install` re-keys those entries, which shows up as a lockfile diff. Commit it. `pnpm install --frozen-lockfile` installs the lockfile as recorded.

- `pnpm install` now resolves a scope's packages again when the scope is routed to another registry in `registries`. Before, the lockfile kept the versions and integrity resolved from the old registry, so the install failed when the new registry did not serve a locked version or served different content. pnpm records in the workspace state which registry each scope routed to, so a fresh clone without that record installs the lockfile as recorded. Changing the default registry resolves nothing again, and `pnpm install --frozen-lockfile` is unchanged.

- When `autoDedupe` is off, a workspace project's dependencies now resolve from its own ranges, like they do with `sharedWorkspaceLockfile: false`. Previously, another project's narrower range could hold them back. For example, `ajv: "*"` now resolves to the latest Ajv even if another project depends on `ajv@^6`. Packages that a project lists in `peerDependencies` still follow the versions other projects use. `pnpm dedupe` and installs with `autoDedupe: true` still pick one version that satisfies every range. Set `autoDedupe: true` if CI runs `pnpm dedupe --check` [#&#8203;17235](https://github.com/pnpm/pnpm/issues/17235).

- An optional dependency written with a named-registry prefix, such as `work:^1.0.0`, now fails the install when it cannot be resolved but the lockfile already has a matching entry from that registry. Such a dependency was skipped, which removed its entries from the lockfile.

- With `injectWorkspacePackages: true`, a `workspace:` dependency written as a relative path, such as `workspace:../lib-a`, in a workspace package now resolves from that package's directory [#&#8203;17284](https://github.com/pnpm/pnpm/issues/17284).

- Fixed `pnpm install` failing with `ERR_PNPM_UNSUPPORTED_PROTOCOL` when a workspace package injected through a relative path, such as `workspace:../lib`, has `catalog:` dependencies. Their catalog entries now resolve the way they do for a package injected by name [#&#8203;17280](https://github.com/pnpm/pnpm/issues/17280).

- `pnpm dedupe` now refreshes cached registry metadata while re-resolving locked versions [#&#8203;17208](https://github.com/pnpm/pnpm/issues/17208).

- `pnpm dedupe --check` no longer fails when the only difference is a `deprecated` notice that the registry added or removed after the lockfile was written [#&#8203;17198](https://github.com/pnpm/pnpm/issues/17198).

- Installs delegated to a pnpr server now resolve every prefix declared for a registry URL. A dependency or lockfile entry that used the second of two prefixes for the same registry, such as `zeta:` next to `work:` in `namedRegistries`, failed on the server [pnpm/tasks#204](https://github.com/pnpm/tasks/issues/204).

- Registry revisions are now addressed at `<registry>/<name>@<version>+r<revision>` [pnpm/tasks#208](https://github.com/pnpm/tasks/issues/208).

##### Adding packages and global packages

- `pnpm add <pkg>@<tag>` and `pnpm add <pkg>@<range>` now install the version the tag or range resolves to, even when the saved range allows a newer one [#&#8203;17234](https://github.com/pnpm/pnpm/issues/17234).

- `pnpm add <pkg>` without a version now installs the version under the dist-tag set by the `tag` setting. An `npm:` alias or a `jsr:` dependency without a version resolves that tag too. The setting is read from `pnpm-workspace.yaml`, the global config, `PNPM_CONFIG_TAG`, and `--config.tag`, and defaults to `latest`.

- `pnpm add` now accepts the lowercase short options `-p`, `-d`, `-o`, and `-e` as aliases of `--save-prod`, `--save-dev`, `--save-optional`, and `--save-exact`.

- `pnpm -D install <pkg>` now saves the package to devDependencies. An `add` option such as `-D` or `-E` written before `install <pkg>` was rejected as an unexpected argument.

- `pnpm add -T` now reports that the short option is ambiguous and points to `--save-types` and `--tilde`.

- Global packages installed with `pnpm add -g` are now linked from the global virtual store, so global packages that share dependencies share one copy. Set `virtualStoreType: project` to give each global install its own virtual store.

- `pnpm add -g` and the other `--global` commands now fail with `ERR_PNPM_CONFIG_CONFLICT_VIRTUAL_STORE_DIR_WITH_GLOBAL` when `--virtual-store-dir` is passed. A custom `--hoist-pattern` fails with `ERR_PNPM_CONFIG_CONFLICT_HOIST_PATTERN_WITH_GLOBAL`. Passing `--link-workspace-packages`, `--shared-workspace-lockfile`, or `--config.lockfile-dir` with `--global` also fails, with the matching `ERR_PNPM_CONFIG_CONFLICT_*_WITH_GLOBAL` code.

##### Registries, proxies, and login

- pnpm now reads the `strictSsl` and `localAddress` settings from `pnpm-workspace.yaml`, the global `config.yaml`, `PNPM_CONFIG_*` environment variables, and `--config.*` options. This includes `pnpm self-update` and the download of the pnpm version pinned in `packageManager`. Before, pnpm read them only from `.npmrc` as `strict-ssl` and `local-address` and ignored the other sources [pnpm/tasks#201](https://github.com/pnpm/tasks/issues/201).

- When Corepack runs pnpm and the native binary has to be downloaded, the download now uses the proxy from pnpm's config. That proxy comes from `PNPM_CONFIG_HTTPS_PROXY` and the matching variables, the global `config.yaml`, and the user `.npmrc`. Previously, the download read the proxy only from `HTTPS_PROXY`, `HTTP_PROXY`, and `NO_PROXY` [pnpm/tasks#215](https://github.com/pnpm/tasks/issues/215).

- When the `pnpm` package downloads its native binary on first run, as it does under Corepack, it now trusts the CA certificates from the `ca`, `ca[]`, and `cafile` settings of `.npmrc`, including the ones scoped to the registry. A registry behind a private CA failed with `fetch failed` before, unless `NODE_EXTRA_CA_CERTS` named the CA. A project `.npmrc` is used only while the download is checked against npm's signature. Node.js versions that cannot add CA certificates after startup still need `NODE_EXTRA_CA_CERTS`.

- `pnpm login` saves the token in `<pnpm config>/auth.ini` again. Since v12.1.0, an unscoped login had made its registry the default for every project that did not name a registry. A login now also removes the token an earlier login saved for that registry or scope under `_auth` in the global `config.yaml`. `pnpm login --scope` still routes the scope through the global `registries` setting.

- pnpm no longer warns that a `registries` entry routed through the `@` scope matches no configured registry. pnpm applied such an entry and its options such as `serverType` while reporting it as ignored [pnpm/tasks#184](https://github.com/pnpm/tasks/issues/184).

##### Running scripts and other commands

- `pnpm ci --lockfile` and `pnpm ci --config.lockfile=true` no longer delete `pnpm-lock.yaml`. `pnpm ci` now always keeps the lockfile and runs a frozen install from it.

- `pnpm deploy --legacy` now checks the workspace lockfile against `minimumReleaseAge` and the other resolution policies, as `pnpm install` does, and fails with `ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION` when a locked version is too new. It used to deploy an older version that is not in the lockfile without a warning [#&#8203;17209](https://github.com/pnpm/pnpm/issues/17209).

- `pnpm deploy` now keeps a deployed symlink to a directory inside the project even if the directory is not among the deployed files, such as a link into `node_modules` [#&#8203;17288](https://github.com/pnpm/pnpm/issues/17288).

- `pnpm pack` and `pnpm publish` now keep `pnpm.config` in the published `package.json`. They also always include the file `pnpm.config` points to in the tarball [#&#8203;17210](https://github.com/pnpm/pnpm/issues/17210).

- `pnpm -r publish --batch` now sends `PUT /-/pnpr/v0/publish`, the batch publish endpoint that pnpr serves.

- `pnpm audit --ignore` and `pnpm audit --ignore-unfixable` now exit with a non-zero code when vulnerabilities at or above the audit level remain after ignoring. Before, these commands always exited with code 0.

- `pnpm audit --fix` and `pnpm audit --interactive` now fail with `ERR_PNPM_AUDIT_FIX_WITH_IGNORE` when combined with `--ignore` or `--ignore-unfixable`. Before, the fix ran and the ignore flags had no effect.

- `pnpm -r run <script>` now honors the `requiredScripts` setting from `pnpm-workspace.yaml`. If the script is listed there and a selected project does not define it, the run fails with `ERR_PNPM_RECURSIVE_RUN_NO_SCRIPT` and names the projects that lack it.

- `pnpm run` and `pnpm exec` no longer report the dependencies as out of date after a lockfile change when `dedupePeers` is `true` [#&#8203;17322](https://github.com/pnpm/pnpm/issues/17322).

- On macOS, killing pnpm while it runs scripts in several projects at once now ends every one of those scripts. Before, a script could keep running after pnpm died.

- `pnpm run`, `pnpm exec`, and `pnpm dlx` no longer dump a core file for `pnpm` itself when a command they started dies from a signal [#&#8203;17204](https://github.com/pnpm/pnpm/issues/17204).

- The `runtime` setting is now read. Setting `runtime: false` in `pnpm-workspace.yaml`, `pnpm_config_runtime=false`, or `--config.runtime=false` stops `pnpm install`, `pnpm add`, `pnpm dedupe`, and the other installing commands from installing the runtimes in `devEngines.runtime` and `engines.runtime`. `pnpm dedupe` now also accepts `--no-runtime`.

- Directory selectors with `legacyDirFiltering: true` now include the project in the named directory along with its descendants. Excluding a directory also excludes that project [pnpm/tasks#196](https://github.com/pnpm/tasks/issues/196).

- `pnpm help --all` and `pnpm help -a` now print the full list of commands. They used to fail with an "unrecognized subcommand" error.

- Reading the file-creation mask on Linux no longer sets it. pnpm had to replace the mask to learn what it was, and a file another thread created in the window between the two calls was created unmasked.

- pnpm now passes an interrupt on to the handler it replaced, with the arguments that handler expects. A handler that asked for the signal's details was called without them. Only a program that embeds pnpm and installs its own `SIGINT`, `SIGTERM` or `SIGHUP` handler was affected.

##### Store

- `pnpm store prune` now keeps the packages that a project still uses when pnpm copied or cloned them into `node_modules`. These include patched packages, built packages, and every package installed with `packageImportMethod: copy`. Before, the prune removed them, and the next install downloaded them again [#&#8203;7192](https://github.com/pnpm/pnpm/issues/7192).

- `pnpm store prune` now keeps the packages of a project when the store path reaches its directory through a symlink. Previously, prune dropped such a project from its list and removed the packages only that project used from the global virtual store.

- `pnpm store prune` now removes the package metadata cache, the `metadata*` directories in the cache directory. This clears the outdated integrity checksums that cause `ERR_PNPM_TARBALL_INTEGRITY` when a registry republishes a version.

##### Speed

- `pnpm install` resolves dependencies faster in large workspaces on Linux, macOS, and Windows on x64 and arm64.

- Sped up cold installs and `pnpm fetch` on macOS. pnpm now links downloaded packages into the virtual store on a separate thread, so a slow link pass no longer pauses the downloads that are still in flight [#&#8203;17271](https://github.com/pnpm/pnpm/issues/17271).

- Sped up installs that add new projects to a workspace with a peer-heavy lockfile. pnpm now reads the lockfile's locked peer versions once for all new projects [#&#8203;17311](https://github.com/pnpm/pnpm/issues/17311).

- Warm installs no longer read the `package.json` of every git-hosted dependency. pnpm now stores the manifest of a git-hosted package in the store index when it fetches the package.

- `pnpm update --depth <n>` with a large `n`, such as the `--depth=9999` that `update-browserslist-db` runs, now finishes as fast as `--depth Infinity`. It used memory and stack in proportion to `n` on lockfiles with dependency cycles, and could run out of memory or crash [#&#8203;17329](https://github.com/pnpm/pnpm/issues/17329).

##### Output and warnings

- Output that fills the terminal, such as `pnpm run --stream` script output, is now written once. Before, every new line also rewrote all the lines already on screen [#&#8203;17387](https://github.com/pnpm/pnpm/issues/17387).

- pnpm now warns when a pnpmfile defines the `importPackage` hook. pnpm does not run this hook. Use the `packageImportMethod` setting to choose how packages are written to `node_modules`.

- `pnpm` now warns when a project's `pnpm-workspace.yaml` sets `ci`, `globalShims`, or `tools`, and names where to set them instead. These settings were already ignored there without a warning. `pnpm config set` also refuses to write them to a project's `pnpm-workspace.yaml`.

- pnpm no longer documents the `scriptsPrependNodePath` setting, which has no effect. A `pnpm-workspace.yaml` that sets it still loads.

<!-- sponsors -->

#### Platinum Sponsors

<table>
  <tbody>
    <tr>
      <td align="center" valign="middle">
        <a href="https://bit.cloud/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer"><img src="https://pnpm.io/img/users/bit.svg" width="80" alt="Bit"></a>
      </td>
      <td align="center" valign="middle">
        <a href="https://openai.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/openai_dark.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/openai_light.svg" />
            <img src="https://pnpm.io/img/users/openai_dark.svg" width="160" alt="OpenAI" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://notion.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer"><img src="https://pnpm.io/img/users/notion.svg" width="80" alt="Notion"></a>
      </td>
    </tr>
    <tr>
      <td align="center" valign="middle">
        <a href="https://coderabbit.ai/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/coderabbit.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/coderabbit_light.svg" />
            <img src="https://pnpm.io/img/users/coderabbit.svg" width="220" alt="CodeRabbit" />
          </picture>
        </a>
      </td>
    </tr>
  </tbody>
</table>

#### Gold Sponsors

<table>
  <tbody>
    <tr>
      <td align="center" valign="middle">
        <a href="https://sanity.io/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/sanity.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/sanity_light.svg" />
            <img src="https://pnpm.io/img/users/sanity.svg" width="120" alt="Sanity" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://discord.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/discord.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/discord_light.svg" />
            <img src="https://pnpm.io/img/users/discord.svg" width="220" alt="Discord" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://vite.dev/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer"><img src="https://pnpm.io/img/users/vitejs.svg" width="42" alt="Vite"></a>
      </td>
    </tr>
    <tr>
      <td align="center" valign="middle">
        <a href="https://serpapi.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/serpapi_dark.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/serpapi_light.svg" />
            <img src="https://pnpm.io/img/users/serpapi_dark.svg" width="160" alt="SerpApi" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://stackblitz.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/stackblitz.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/stackblitz_light.svg" />
            <img src="https://pnpm.io/img/users/stackblitz.svg" width="190" alt="Stackblitz" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://workleap.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/workleap.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/workleap_light.svg" />
            <img src="https://pnpm.io/img/users/workleap.svg" width="190" alt="Workleap" />
          </picture>
        </a>
      </td>
    </tr>
    <tr>
      <td align="center" valign="middle">
        <a href="https://nx.dev/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/nx.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/nx_light.svg" />
            <img src="https://pnpm.io/img/users/nx.svg" width="50" alt="Nx" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://latitude.so/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer"><img src="https://pnpm.io/img/users/latitude.svg" width="160" alt="Latitude"></a>
      </td>
    </tr>
  </tbody>
</table>

<!-- sponsors end -->

</details>

---

### Configuration

📅 **Schedule**: (UTC)

- Branch creation
  - Between 12:00 AM and 03:59 AM, only on Monday (`* 0-3 * * 1`)
- Automerge
  - At any time (no schedule defined)

🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied.

♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox.

👻 **Immortal**: This PR will be recreated if closed unmerged. Get [config help](https://github.com/renovatebot/renovate/discussions) if that's undesired.

---

 - [ ] <!-- rebase-check -->If you want to rebase/retry this PR, check this box

---

This PR has been generated by [Mend Renovate CLI](https://github.com/renovatebot/renovate).
<!--renovate-debug:eyJjcmVhdGVkSW5WZXIiOiI0NC4xODEuNyIsInVwZGF0ZWRJblZlciI6IjQ0LjE5OS4yIiwidGFyZ2V0QnJhbmNoIjoibWFpbiIsImxhYmVscyI6W119-->

Reviewed-on: https://gitea.com/gitea/docs/pulls/626
Reviewed-by: Lunny Xiao <[email protected]>
Co-authored-by: Renovate Bot <[email protected]>
2026-11-02 00:49:41 +00:00
silverwindandLunny Xiao 6632d38fe2 Document the commitstatus token scope (#622)
Documents https://github.com/go-gitea/gitea/pull/40144 for main, which adds `read:commitstatus` and `write:commitstatus` token scopes so CI integrations can report commit statuses without full repository access. The repository scopes include them.

Adds the scope to the OAuth2 provider scope table and the API usage permission list. Draft until the Gitea PR merges.

_Written by Claude (Opus 5.5)._

---------

Co-authored-by: Lunny Xiao <[email protected]>
Reviewed-on: https://gitea.com/gitea/docs/pulls/622
Reviewed-by: Lunny Xiao <[email protected]>
Co-authored-by: silverwind <[email protected]>
2026-11-01 18:19:38 +00:00
silverwindandbircni ef57d8d2c0 Document gitea-cli OAuth2 application (#620)
Documents https://github.com/go-gitea/gitea/pull/40036 for main, which renames the built-in tea OAuth2 application to gitea-cli and keeps `tea` as an alias in `[oauth2] DEFAULT_APPLICATIONS`.

The default list and the pre-configured applications table also gain the missing gitea-app and gitea-vscode entries.

_Written by Claude (Opus 5.5)._

---------

Co-authored-by: bircni <[email protected]>
Reviewed-on: https://gitea.com/gitea/docs/pulls/620
Reviewed-by: bircni <[email protected]>
Co-authored-by: silverwind <[email protected]>
2026-11-01 12:50:48 +00:00
bircni ba4abd749d update to 28.3.0 (#623)
Bump the v28 docs to the 28.3.0 release:

- point the `28` version variables (`version`, `sourceVersion`, `dockerVersion`, `displayVersion`) at 28.3.0
- update the v28 entry in `update_api_docs.sh` to `28.3.0`
- regenerate `static/swagger-28.json` and `static/openapi3-28.json` from the `v28.3.0` tag, which picks up the updated `Deadline` and `Labels` descriptions from go-gitea/gitea#39869 and go-gitea/gitea#39873

Reviewed-on: https://gitea.com/gitea/docs/pulls/623
Reviewed-by: silverwind <[email protected]>
2026-11-01 10:11:04 +00:00
silverwind 8197192134 Document GITEA_* env aliases, missing variables and accurate examples (#618)
https://gitea.com/gitea/runner/pulls/1358 mirrors every built-in `GITHUB_*` variable as `GITEA_*`. The variables page now lists both names for each, in the same paired style as the context table.

It also adds variables that runners already set but the page left out (`*_ACTOR_ID`, `*_REF_PROTECTED`, `*_REPOSITORY_ID`, `*_REPOSITORY_OWNER_ID`, `*_TRIGGERING_ACTOR`, `*_WORKFLOW_SHA`, `ACT`, `ImageOS`, `RUNNER_DEBUG`, `RUNNER_ENVIRONMENT`, `RUNNER_NAME`, `RUNNER_WORKSPACE`, `TRACEPARENT`, `TRACESTATE`).

Examples copied from GitHub's runner (`/home/runner/work/_temp/...` paths, `__run`, `ghs_***`) are replaced with the values gitea-runner and Gitea actually produce, using placeholder users, repositories and instance URLs.

The zh-cn and zh-tw pages get the environment variable section they never had.

Reviewed-on: https://gitea.com/gitea/docs/pulls/618
Reviewed-by: Lunny Xiao <[email protected]>
Co-authored-by: silverwind <[email protected]>
2026-10-31 05:25:00 +00:00
brock0124andLunny Xiao 97fa45dabc fix(Hem Chart Registry docs): typo (#614)
Co-authored-by: Lunny Xiao <[email protected]>
Reviewed-on: https://gitea.com/gitea/docs/pulls/614
Reviewed-by: Lunny Xiao <[email protected]>
Co-authored-by: brock0124 <[email protected]>
2026-10-29 02:19:31 +00:00
ee9e91cdeb Add project workflow documentation (#308)
Documentation for https://github.com/go-gitea/gitea/pull/30205

---------

Co-authored-by: silverwind <[email protected]>
Co-authored-by: silverwind <[email protected]>
Co-authored-by: silverwind <[email protected]>
Reviewed-on: https://gitea.com/gitea/docs/pulls/308
Reviewed-by: silverwind <[email protected]>
2026-10-28 16:12:53 +00:00
Renovate BotandLunny Xiao d301461648 chore(deps): update dependencies (#611)
This PR contains the following updates:

| Package | Change | [Age](https://docs.renovatebot.com/merge-confidence/) | [Confidence](https://docs.renovatebot.com/merge-confidence/) | Type | Update | Pending |
|---|---|---|---|---|---|---|
| [@astrojs/check](https://github.com/withastro/astro/tree/main/packages/language-tools/astro-check) ([source](https://github.com/withastro/astro/tree/HEAD/packages/language-tools/astro-check)) | [`0.9.10` → `0.9.11`](https://renovatebot.com/diffs/npm/@astrojs%2fcheck/0.9.10/0.9.11) | ![age](https://developer.mend.io/api/mc/badges/age/npm/@astrojs%2fcheck/0.9.11?slim=true) | ![confidence](https://developer.mend.io/api/mc/badges/confidence/npm/@astrojs%2fcheck/0.9.10/0.9.11?slim=true) | devDependencies | patch | `0.9.12` |
| [astro](https://astro.build) ([source](https://github.com/withastro/astro/tree/HEAD/packages/astro)) | [`7.3.8` → `7.4.1`](https://renovatebot.com/diffs/npm/astro/7.3.8/7.4.1) | ![age](https://developer.mend.io/api/mc/badges/age/npm/astro/7.4.1?slim=true) | ![confidence](https://developer.mend.io/api/mc/badges/confidence/npm/astro/7.3.8/7.4.1?slim=true) | dependencies | minor | `7.4.2` |
| [pnpm](https://pnpm.io) ([source](https://github.com/pnpm/pnpm/tree/HEAD/pnpm/npm/pnpm)) | [`12.13.0` → `12.15.0`](https://renovatebot.com/diffs/npm/pnpm/12.13.0/12.15.0) | ![age](https://developer.mend.io/api/mc/badges/age/npm/pnpm/12.15.0?slim=true) | ![confidence](https://developer.mend.io/api/mc/badges/confidence/npm/pnpm/12.13.0/12.15.0?slim=true) | packageManager | minor |  |
| [ubuntu](https://github.com/actions/runner-images) | `24.04` → `26.04` | ![age](https://developer.mend.io/api/mc/badges/age/github-runners/ubuntu/26.04?slim=true) | ![confidence](https://developer.mend.io/api/mc/badges/confidence/github-runners/ubuntu/24.04/26.04?slim=true) | github-runner | major |  |

---

### Release Notes

<details>
<summary>withastro/astro (@&#8203;astrojs/check)</summary>

### [`v0.9.11`](https://github.com/withastro/astro/blob/HEAD/packages/language-tools/astro-check/CHANGELOG.md#0911)

[Compare Source](https://github.com/withastro/astro/compare/@astrojs/[email protected]...@astrojs/[email protected])

##### Patch Changes

- [#&#8203;18445](https://github.com/withastro/astro/pull/18445) [`d736df7`](https://github.com/withastro/astro/commit/d736df7a9cc03c12b22e538f058fb1f769672471) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes the `--preserveWatchOutput` help text, which described the opposite of the flag's behavior. Setting it to `true` keeps output between checks in watch mode.

- [#&#8203;18444](https://github.com/withastro/astro/pull/18444) [`c55134c`](https://github.com/withastro/astro/commit/c55134c1d3c238a43e17cfeff136375a4d9d5d35) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes `astro check --watch` exiting immediately when the project path contains `node_modules` or `.git`

</details>

<details>
<summary>withastro/astro (astro)</summary>

### [`v7.4.1`](https://github.com/withastro/astro/blob/HEAD/packages/astro/CHANGELOG.md#741)

[Compare Source](https://github.com/withastro/astro/compare/[email protected]@7.4.1)

##### Patch Changes

- [#&#8203;18425](https://github.com/withastro/astro/pull/18425) [`6fdc36e`](https://github.com/withastro/astro/commit/6fdc36ed97316d932d2e143b85739f0af37ab329) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Preserves the last modified date of cached optimized images and incrementally restored build output when copying them into the build output on all platforms

- [#&#8203;18419](https://github.com/withastro/astro/pull/18419) [`395d195`](https://github.com/withastro/astro/commit/395d19525986a276bf81af7bd365e7a35dc20ef3) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes a typo in the error message shown when a font `cssVariable` is invalid

- [#&#8203;18401](https://github.com/withastro/astro/pull/18401) [`484822f`](https://github.com/withastro/astro/commit/484822fbba652745c4f2da5ef434a350203578e2) Thanks [@&#8203;danielmlr](https://github.com/danielmlr)! - Fixes a bug where projects whose path contains an apostrophe (`'`) failed to load sessions, middleware, a cache provider, or a `src/fetch.ts` handler

- [#&#8203;18407](https://github.com/withastro/astro/pull/18407) [`a6e00be`](https://github.com/withastro/astro/commit/a6e00beae6c134d0c1b5248eb02fbf119b7d64e9) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes a `TSCONFIG_ERROR` during `astro build` when a parent directory contains a `tsconfig.json` that cannot be resolved, such as one extending `astro/tsconfigs/strict` without installed dependencies

- [#&#8203;18427](https://github.com/withastro/astro/pull/18427) [`908f167`](https://github.com/withastro/astro/commit/908f1672a9fe6c40e6b73bfb0307f0d1f3ac2057) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes an `Unterminated string` build error when application code imports from `astro/config` (for example, `fontProviders` in a shared fonts module)

- [#&#8203;18428](https://github.com/withastro/astro/pull/18428) [`40e7d54`](https://github.com/withastro/astro/commit/40e7d54c7f969b402f011d32ccd87123835d0aa1) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes missing styles in production builds for conditionally rendered framework components (e.g. Svelte components inside `{#if}` blocks) imported by a hydrated island

- [#&#8203;18424](https://github.com/withastro/astro/pull/18424) [`617ff59`](https://github.com/withastro/astro/commit/617ff59820b4a5777eb5d3765c09d29082b11acc) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes style-only HMR in `.astro` components falling back to a full page reload when a PostCSS plugin (such as `@unocss/postcss`) lists the component as a dependency of its own style

- [#&#8203;18274](https://github.com/withastro/astro/pull/18274) [`70834bb`](https://github.com/withastro/astro/commit/70834bbea43695c563358ea055d32ecb5e0a78dd) Thanks [@&#8203;Princesseuh](https://github.com/Princesseuh)! - Fixes increasing memory usage when editing the Astro configuration while the dev server is running

### [`v7.4.0`](https://github.com/withastro/astro/blob/HEAD/packages/astro/CHANGELOG.md#740)

[Compare Source](https://github.com/withastro/astro/compare/[email protected]@7.4.0)

##### Minor Changes

- [#&#8203;17894](https://github.com/withastro/astro/pull/17894) [`b7a1bd9`](https://github.com/withastro/astro/commit/b7a1bd99ac7c68cf36078058f15f1bd1fab4cbe8) Thanks [@&#8203;Princesseuh](https://github.com/Princesseuh)! - Adds a new `--timings` flag to `astro build` to help you find what slows down your builds

  When a build takes longer than expected, it can be hard to tell whether the cause is an integration, a Markdown processor plugin, image processing, or even syntax highlighting. Add the `--timings` flag to your build command to print a summary once the build finishes:

  ```sh
  astro build --timings
  ```

  This is helpful to decide what to optimize first, or to compare build times before and after a change to your project.

- [#&#8203;17830](https://github.com/withastro/astro/pull/17830) [`a937b0d`](https://github.com/withastro/astro/commit/a937b0d3ec236c8dd1c62a7a4da7c65b2fdbb7c1) Thanks [@&#8203;florian-lefebvre](https://github.com/florian-lefebvre)! - Adds a new optional `getFontProperties()` callback to font providers

  Font providers can now expose the weights, styles, subsets and formats a font family actually has. Astro uses it when resolving your font configuration to warn about values a provider cannot serve, for example a weight a font family does not offer.

  All built-in providers implement it. If you maintain a custom font provider, implementing this callback is optional for now but it will be required in Astro 8:

  ```ts
  import type { FontProvider } from 'astro';

  const provider: FontProvider = {
  	name: 'my-provider',
  	resolveFont: ({ familyName }) => {
  		// ...
  	},
  	getFontProperties: ({ familyName }) => ({
  		weights: ['400', '700'],
  		styles: ['normal', 'italic'],
  		subsets: ['latin'],
  		formats: ['woff2'],
  	}),
  };
  ```

- [#&#8203;17830](https://github.com/withastro/astro/pull/17830) [`a937b0d`](https://github.com/withastro/astro/commit/a937b0d3ec236c8dd1c62a7a4da7c65b2fdbb7c1) Thanks [@&#8203;florian-lefebvre](https://github.com/florian-lefebvre)! - Adds a `fetch()` function to the font provider `init()` context

  This function requests a provider API, retrying transient failures and more. It lets providers that wrap a 3rd-party unifont provider pass the context to it directly:

  ```ts
  import type { FontProvider } from 'astro';
  import type { InitializedProvider } from 'unifont';
  import { acmeProvider } from '@acme/unifont-provider';

  export function acmeFontProvider(): FontProvider {
  	const provider = acmeProvider();
  	let initializedProvider: InitializedProvider | undefined;
  	return {
  		name: provider._name,
  		async init(context) {
  			initializedProvider = await provider(context);
  		},
  		// ...
  	};
  }
  ```

- [#&#8203;18015](https://github.com/withastro/astro/pull/18015) [`0b30239`](https://github.com/withastro/astro/commit/0b302391059dbc4f8ece24d7b44599c7ec9fef24) Thanks [@&#8203;florian-lefebvre](https://github.com/florian-lefebvre)! - Adds `experimental.redirectPage`, letting you provide your own `src/pages/3xx.astro` in place of the redirect page Astro generates in static builds.

  A static site has no server to send an HTTP `Location` header, so Astro generates a small HTML page with a `<meta http-equiv="refresh">` tag for each redirect it builds:

  - Your [`redirects`](https://docs.astro.build/en/reference/configuration-reference/#redirects) entries
  - `Astro.redirect()` calls in prerendered pages
  - i18n redirects

  That page's markup, wording, and refresh delay were fixed, so you could not brand or translate it.

  To enable this feature, add the experimental flag to your Astro config:

  ```js
  // astro.config.mjs
  import { defineConfig } from 'astro/config';

  export default defineConfig({
    experimental: {
      redirectPage: true,
    },
  });
  ```

  Then create `src/pages/3xx.astro`. Astro renders it once per redirect, passing that redirect's details as props:

  ```astro
  ---
  // src/pages/3xx.astro
  import type { RedirectPageProps as Props } from 'astro';

  const { from, to, status, delay } = Astro.props;
  ---

  <html lang="en">
    <head>
      <meta http-equiv="refresh" content={`${delay};url=${to}`} />
      <meta name="robots" content="noindex" />
      <title>Redirecting…</title>
    </head>
    <body>
      <p>This page has moved. <a href={to}>Continue to {to}</a>.</p>
    </body>
  </html>
  ```

  Your page must render a `<meta http-equiv="refresh">` tag pointing at `to`, because in a static build that tag is the redirect. Astro logs a warning during the build if it is missing.

  See the [experimental redirect page documentation](https://docs.astro.build/en/reference/experimental-flags/redirect-page/) for more information.

- [#&#8203;18265](https://github.com/withastro/astro/pull/18265) [`910ee69`](https://github.com/withastro/astro/commit/910ee69147c4c2460f2b31a294bc70c5269f44d4) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Adds a `notFound()` handler to `astro/fetch` and `astro/hono` that renders the custom 404 page when no route matches, including a prerendered `404.astro`

  Add it before `pages()` in a custom worker or server entrypoint that does not run inside `App.render`, such as a Hono app used directly as a Cloudflare worker. Without it, `pages()` and `middleware()` return an empty 404 with an internal `X-Astro-Error` header for unmatched routes. `astro()` already includes this handling.

  ```ts
  import { Hono } from 'hono';
  import { notFound, pages } from 'astro/hono';
  import { cf } from '@astrojs/cloudflare/hono';

  const app = new Hono();
  app.use(cf());
  app.use(notFound());
  app.use(pages());
  export default app;
  ```

- [#&#8203;18177](https://github.com/withastro/astro/pull/18177) [`7d814e5`](https://github.com/withastro/astro/commit/7d814e5ac3e7c84b4e4fd4e6c7cc6820f553742c) Thanks [@&#8203;Princesseuh](https://github.com/Princesseuh)! - Adds support for separate `build` and `runtime` image services

  `image.service` now also accepts a `build` and a `runtime` service. The `build` service optimizes images on prerendered pages when you build your site, and is also used during development. The `runtime` service handles images on on-demand rendered pages and the image endpoint of your deployed site.

  The following example uses Sharp to optimize images on prerendered pages, and an image CDN for on-demand rendered pages:

  ```js
  // astro.config.mjs
  import { defineConfig } from 'astro/config';

  export default defineConfig({
    image: {
      service: {
        build: { entrypoint: 'astro/assets/services/sharp' },
        runtime: { entrypoint: 'my-image-cdn-service' },
      },
    },
  });
  ```

##### Changes for integration authors

`config.image.service` keeps the shape the user configured it with. When a project sets `build` and `runtime` services, `config.image.service.entrypoint` and `config.image.service.config` are `undefined`.

If your integration reads `image.service`, check for the `runtime` property to get the service you need:

```ts
'astro:config:done': ({ config }) => {
  const { service } = config.image;
  const runtimeService = 'runtime' in service ? service.runtime : service;

  if (runtimeService.entrypoint === 'astro/assets/services/sharp') {
    // ...
  }
},
```

Setting `image.service` with `updateConfig()` replaces the existing service instead of merging with it when the two use different shapes. For example, setting a single service in a project that uses `build` and `runtime` services replaces both.

- [#&#8203;18277](https://github.com/withastro/astro/pull/18277) [`2715958`](https://github.com/withastro/astro/commit/2715958666b0a706b069d0592da3a070b3796a9b) Thanks [@&#8203;florian-lefebvre](https://github.com/florian-lefebvre)! - Increases the minimum Node.js version to 22.22.0

  The minimum supported Node.js version is now 22.22.0, the latest Node.js 22 release supported by StackBlitz. This change is in line with Astro's [Node.js support policy](https://docs.astro.build/en/upgrade-astro/#support).

- [#&#8203;18313](https://github.com/withastro/astro/pull/18313) [`71e2b24`](https://github.com/withastro/astro/commit/71e2b24bb365e5a8809fc0432716f91ecc6d8ab5) Thanks [@&#8203;matthewp](https://github.com/matthewp)! - Allows integrations to control where Astro writes client, server, and prerender build output.

  Custom prerenderers can access the final output locations through the new `outputDirectories` context:

  ```ts
  setPrerenderer((defaultPrerenderer, { outputDirectories }) => {
    const { client, server, prerender } = outputDirectories

    return createPrerenderer({
      defaultPrerenderer,
      client,
      server,
      prerender,
    })
  })
  ```

- [#&#8203;18177](https://github.com/withastro/astro/pull/18177) [`7d814e5`](https://github.com/withastro/astro/commit/7d814e5ac3e7c84b4e4fd4e6c7cc6820f553742c) Thanks [@&#8203;Princesseuh](https://github.com/Princesseuh)! - Lets custom prerenderers report the images used on prerendered pages

  Astro now generates images on prerendered pages from the image information that a prerenderer's `getStaticPaths()` and `render()` return. If your prerenderer wraps Astro's default one, pass this information through:

  ```js
  setPrerenderer((defaultPrerenderer) => ({
    name: 'my-prerenderer',
    async setup() {
      await defaultPrerenderer.setup?.();
    },
    async getStaticPaths() {
      const result = await defaultPrerenderer.getStaticPaths();
      const { paths, metadata } = Array.isArray(result) ? { paths: result } : result;
      return { paths: paths.filter(({ pathname }) => !pathname.startsWith('/drafts')), metadata };
    },
    render(request, options) {
      return defaultPrerenderer.render(request, options);
    },
    async teardown() {
      await defaultPrerenderer.teardown?.();
    },
  }));
  ```

  Returning a plain array from `getStaticPaths()` or a plain `Response` from `render()` still works, but is deprecated: images used on those pages are not generated.

- [#&#8203;17932](https://github.com/withastro/astro/pull/17932) [`b905ff1`](https://github.com/withastro/astro/commit/b905ff1a8649b7a9a9056d9b05ca25ae7b3c07a1) Thanks [@&#8203;Princesseuh](https://github.com/Princesseuh)! - Adds support for experimental parallel prerendering

  This experimental feature makes `astro build` render your static pages in parallel, using multiple CPU cores at once instead of one. On sites with many pages, this can significantly reduce build times, at the cost of higher memory usage.

  To enable this feature, add the experimental flag in your Astro config:

  ```js
  // astro.config.mjs
  import { defineConfig } from 'astro/config';

  export default defineConfig({
    experimental: {
      parallelPrerender: true,
    },
  });
  ```

  By default, Astro uses all available CPU cores but one. Each additional worker increases the memory used by your build. If your build runs out of memory, or does not get faster, set `workers` to a lower number:

  ```js
  // astro.config.mjs
  import { defineConfig } from 'astro/config';

  export default defineConfig({
    experimental: {
      parallelPrerender: {
        workers: 4,
      },
    },
  });
  ```

  Each worker renders as many pages at once as your [`build.concurrency`](https://docs.astro.build/en/reference/configuration-reference/#buildconcurrency) setting allows.

  This feature has no effect when your adapter provides its own way of prerendering pages. Among official adapters, this only applies to `@astrojs/cloudflare`. Astro logs a warning during the build when the flag is ignored.

  For more information on enabling and using this feature in your project, see the [experimental parallel prerendering docs](https://docs.astro.build/en/reference/experimental-flags/parallel-prerender/).

##### Patch Changes

- [#&#8203;18313](https://github.com/withastro/astro/pull/18313) [`71e2b24`](https://github.com/withastro/astro/commit/71e2b24bb365e5a8809fc0432716f91ecc6d8ab5) Thanks [@&#8203;matthewp](https://github.com/matthewp)! - Fixes deployment integrations being unable to use Vite manifests when preparing build output

- [#&#8203;18270](https://github.com/withastro/astro/pull/18270) [`0c3bf11`](https://github.com/withastro/astro/commit/0c3bf116ee70aae4772313fc167a372c7d54869e) Thanks [@&#8203;ArmandPhilippot](https://github.com/ArmandPhilippot)! - Fixes the JSDoc for CSP utilities to point to the render context reference in docs.

- [#&#8203;18368](https://github.com/withastro/astro/pull/18368) [`1f04637`](https://github.com/withastro/astro/commit/1f04637a6ca23b59e8982424248ead47d6a3ec31) Thanks [@&#8203;43081j](https://github.com/43081j)! - Replaces internal use of `find-proc` with `tinyps`.

- [#&#8203;18355](https://github.com/withastro/astro/pull/18355) [`59b9cc0`](https://github.com/withastro/astro/commit/59b9cc00726495bb45f5c4b000dbbb7b5a19d662) Thanks [@&#8203;matthewp](https://github.com/matthewp)! - Fixes prerender errors being silently swallowed when using a custom `src/fetch.ts` with an adapter that prerenders in its own runtime, such as `@astrojs/cloudflare`. Previously, a page that threw during prerendering was written as an empty HTML file and the build succeeded. The build now fails with the underlying error.

- [#&#8203;18177](https://github.com/withastro/astro/pull/18177) [`7d814e5`](https://github.com/withastro/astro/commit/7d814e5ac3e7c84b4e4fd4e6c7cc6820f553742c) Thanks [@&#8203;Princesseuh](https://github.com/Princesseuh)! - Fixes original images being kept despite only `width` or `height` being read.

- [#&#8203;18353](https://github.com/withastro/astro/pull/18353) [`af54bfa`](https://github.com/withastro/astro/commit/af54bfaebff9180cb96822c0da11737b4b26e65a) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes `glob()` loader swallowing rendering errors during content sync, which allowed `astro build` to exit successfully (code 0) even when a remark/rehype plugin threw an error

- [#&#8203;18271](https://github.com/withastro/astro/pull/18271) [`23e8e28`](https://github.com/withastro/astro/commit/23e8e28c22effe006fe19abb193802e2fec8eaab) Thanks [@&#8203;ArmandPhilippot](https://github.com/ArmandPhilippot)! - Fixes the `sync` command description in `astro help`, which only mentioned content collections.

- Updated dependencies \[[`b7a1bd9`](https://github.com/withastro/astro/commit/b7a1bd99ac7c68cf36078058f15f1bd1fab4cbe8), [`2715958`](https://github.com/withastro/astro/commit/2715958666b0a706b069d0592da3a070b3796a9b)]:
  - [@&#8203;astrojs/internal-helpers](https://github.com/astrojs/internal-helpers)@0.13.0
  - [@&#8203;astrojs/markdown-satteri](https://github.com/astrojs/markdown-satteri)@0.4.4
  - [@&#8203;astrojs/telemetry](https://github.com/astrojs/telemetry)@3.4.0

</details>

<details>
<summary>pnpm/pnpm (pnpm)</summary>

### [`v12.15.0`](https://github.com/pnpm/pnpm/releases/tag/v12.15.0): pnpm 12.15

[Compare Source](https://github.com/pnpm/pnpm/compare/v12.14.0...v12.15.0)

This release lets `pnpm-workspace.yaml` delegate settings to other files and config dependencies with `include`, adds `lockfile.integrityTarget: tar` and tar-registry support, accepts zstd-compressed registry responses, and honors `SOURCE_DATE_EPOCH` in `pnpm deploy` and `pnpm install`. It also rejects registry metadata that names a different package than the one requested and speeds up workspace installs and macOS file linking.

##### Minor Changes

- `pnpm-workspace.yaml` can now delegate settings to other YAML files and to config dependencies through a new `include` field. Each source may define only the settings the root manifest delegates to it. Every setting has one owner. Commands that change settings write each one to the file that owns it. A relative path in an included file is relative to that file. See [Splitting Settings Across Files](https://pnpm.io/config-includes).

  A config dependency supplies its settings through the YAML file named in the `pnpm.config` field of its `package.json`. The new `bootConfig` setting sets the release-age and trust policy pnpm uses to install config dependencies and the pnpm version from `packageManager`.

- Added the `lockfile.integrityTarget` setting. With `integrityTarget: tar`, `pnpm-lock.yaml` pins the hash of every package's uncompressed tar, so the lockfile no longer changes when a registry recompresses its tarballs or serves them as tars. pnpm learns a version's tar hash from the store or by downloading it once. `pnpm audit signatures` ties the tar hash to the signed `.tgz` integrity.

  ```yaml title="pnpm-workspace.yaml"
  lockfile:
    integrityTarget: tar
  ```

- pnpm can now install from a registry that serves uncompressed tars with zstd or gzip content coding. `pnpm-lock.yaml` records the hash of each tar. Declare such a registry with `serverType: pnpr` in `registries` to keep tarball URLs out of the lockfile. See [Tar registries](https://pnpm.io/registries#tar-registries).

  pnpm now decodes the content coding of tarball downloads itself. It rejects a zstd response whose window is larger than 8 MiB.

  Added the `maxTarballUnpackedSize` setting. It caps the bytes the files of one package may unpack to, 4 GiB by default.

- Registry revisions now always pin the hash of the uncompressed tar, the original included. pnpm records an original selected through the revision protocol, for example with a `+r0` specifier, as `revision: 0` in the lockfile and fetches it from the registry's digest route. pnpm checks a revision's tar whether the registry sends it as a tar, gzip, or zstd. Revision metadata must list revision 0 and mark the selected revision. pnpm rejects incomplete revision metadata with `ERR_PNPM_MALFORMED_METADATA`.

- pnpm now accepts zstd-compressed responses. Registries that serve zstd send package metadata in fewer bytes than with gzip, most of all the full metadata that settings such as `minimumReleaseAge` and `trustPolicy` read.

- `pnpm deploy` and `pnpm install` now use the `SOURCE_DATE_EPOCH` environment variable as an upper bound for timestamps in `node_modules/.modules.yaml` and `node_modules/.pnpm-workspace-state-v1.json`. With an equivalently prepared deploy target and an epoch no later than the timestamps that would otherwise be recorded, deploying the same project twice produces identical files [#&#8203;17171](https://github.com/pnpm/pnpm/issues/17171).

- `pnpm update --interactive` now highlights the row under the cursor in cyan while keeping the colors of its version changes.

##### Patch Changes

##### Security

- pnpm now fails with `ERR_PNPM_REGISTRY_NAME_MISMATCH` if a registry returns metadata for a package other than the one requested. Before, pnpm installed the package under the name in the metadata, so `allowBuilds` rules for the requested package did not apply to it.

- `minimumReleaseAgeExcludePrune` and `trustPolicyExcludePrune` now keep exclusions for resolved configuration dependencies and their transitive dependencies [#&#8203;17142](https://github.com/pnpm/pnpm/issues/17142).

##### Resolving dependencies

- When `pnpm install` resolves a dependency again, it now reuses a version that the install already resolved for the same package, as a fresh install does. Before, it kept the version the lockfile pinned and added a second copy of the package. A locked version still stays when nothing else in the install prefers another version. To pin a transitive dependency on purpose, use `overrides` [#&#8203;17084](https://github.com/pnpm/pnpm/issues/17084).

- When another workspace project adds a different version of a package, a project's auto-installed peer on that package now moves to the version a fresh install picks. It used to stay on its locked version while any other project still accepted that version [#&#8203;17058](https://github.com/pnpm/pnpm/issues/17058).

- A package that lists the same dependency in `dependencies` and as an optional peer now gets the peer bound when a project adds a provider for it later. The lockfile now records every peer a package declares, including one its own dependency supplies [#&#8203;17056](https://github.com/pnpm/pnpm/issues/17056).

- `pnpm install --prod` and `pnpm deploy --prod` no longer drop a dependency that a package declares both as an optional peer and as its own dependency, when the package resolved it as its own dependency and a dev dependency provides the same package under another alias.

- `pnpm install` with an existing lockfile and a second `pnpm dedupe` now keep optional peer bindings that point into a dependency cycle or back into the dependent package. Before, the second run dropped the optional peer binding from the lockfile snapshot key.

- `pnpm install` and `pnpm dedupe` now preserve own-dependency and peer-dependency bindings when reusing a lockfile whose peer suffixes were hashed by `peersSuffixMaxLength`.

  Upgrading a direct dependency in one workspace project now refreshes matching transitive pins in sibling projects during the same `pnpm install` pass.

- With `resolvePeersFromWorkspaceRoot: false`, a workspace project no longer binds a peer to a version that only another project's dependencies provide. pnpm now auto-installs a version that satisfies the peer range for that project. Before, the project got a version outside the range, with no peer warning.

- `pnpm install`, `pnpm add`, and `pnpm update` now reuse the lockfile's resolution for dependencies that take part in a dependency cycle, such as `mlly` and `pkg-types`. They re-resolved those packages and everything that depends on them from the registry before [pnpm/tasks#130](https://github.com/pnpm/tasks/issues/130).

- pnpm now measures a `pnpm.overrides` entry written as a `workspace:` path, such as `workspace:./packages/foo`, from the directory holding `pnpm-workspace.yaml`. It used to be measured from each package the override rewrote. The install then linked a directory that does not exist, or failed if workspace packages were injected [#&#8203;17010](https://github.com/pnpm/pnpm/issues/17010).

- `pnpm install` now removes config dependencies that are no longer declared, including when the entire `configDependencies` setting is removed. Frozen installs reject a lockfile that still records removed config dependencies.

- `pnpm install --update-checksums` now re-resolves every locked package and records the integrity the registry reports now.

- `pnpm add` and `pnpm install` now accept `gist:<id>` dependencies and GitHub Gist URLs, and install them from the gist's archive. `pnpm pkg fix` normalizes a `gist:` repository the way `npm pkg fix` does, `pnpm licenses` links a gist package to its gist page, and `pnpm sbom` reports the repository of a package whose `repository` field is a `gist:` shorthand.

- `pnpm add` now reads the package name correctly from a tarball URL under a registry URL that has a path, such as `https://example.com/npm/`, and installs a registry tarball URL with a malformed percent escape as a plain tarball URL. Before, the registry path became part of the name, so a scoped package failed with `ERR_PNPM_INVALID_PACKAGE_NAME`.

- With `minimumReleaseAge` set, pnpm now revalidates a package's cached full metadata with a single ETag request so an unchanged registry answers with `304`, even when the registry does not list a publish time for every version. Previously, pnpm downloaded that metadata again whenever the cached copy was older than `minimumReleaseAge`. With `resolutionMode` set to `lowest-direct` or `time-based`, pnpm also reuses that metadata across every workspace project that depends on the package.

- When pnpm revalidates cached registry metadata, it now sends `If-Modified-Since` when the registry's modification time is a date without a time, and no longer crashes when the modification time is before 1970.

- Added protocol versioning between the pnpm client and pnpr server, verified applied resolution policies in resolution responses, and preserved structured error codes across the wire.

##### Performance

- Sped up `pnpm install` on macOS. On a 12-core Mac, installing 1352 packages from a warm store took 1.3 seconds, down from 2.2. pnpm now writes package files into `node_modules` with 4 threads on macOS, whatever the number of CPU cores. Set the `PNPM_MACOS_LINK_THREADS` environment variable to use a different number of threads, or to `0` to write files with the threads pnpm uses for the rest of the install.

- `pnpm install` is faster and uses less memory in large workspaces with `sharedWorkspaceLockfile: false`. Each project's install no longer reads the manifests of every other workspace project again. Installs that wait for their workspace dependencies now count toward `workspaceConcurrency` [#&#8203;16966](https://github.com/pnpm/pnpm/issues/16966).

- Sped up workspace project discovery, dependency resolution, lockfile up-to-date checks, and peer dependency checks in large workspaces [#&#8203;16839](https://github.com/pnpm/pnpm/issues/16839) [pnpm/tasks#9](https://github.com/pnpm/tasks/issues/9). On a workspace with 6,833 projects, the lockfile up-to-date check uses about 1 second less CPU time. The peer dependency check at the end of an install now checks linked workspace projects against the manifests already in memory, without reading each `package.json` again.

- Sped up bin linking and build planning during `pnpm install`. Package binary targets and shebang runtimes are now precalculated during tarball extraction and served in `pnpr` registry metadata alongside verified `requiresBuild`, tarball size, and file-count metadata.

- Lowered peak memory when pnpm downloads many packuments, such as during lockfile verification with `trustPolicy` on Linux. In one 1,800-entry workspace, a lockfile update now peaks at 1.8 to 2.0 GB. It peaked at 2.6 to 3.7 GB before [#&#8203;17020](https://github.com/pnpm/pnpm/issues/17020).

- `pnpm install` in a Cargo workspace skips crates that an earlier install already unpacked into the store. Before, a repeat install processed every crate in `Cargo.lock` again. `pnpm install --force` unpacks every crate again [pnpm/tasks#69](https://github.com/pnpm/tasks/issues/69).

##### Linking node_modules and workspaces

- Concurrent installs that import the same package into one project now all complete. One of them used to fail with `ENOTEMPTY` when its copy of the package collided with the copy another install had already placed [pnpm/tasks#48](https://github.com/pnpm/tasks/issues/48).

- `pnpm install` now succeeds when `node_modules` is a symlink to an existing directory. Dependency hoisting previously rejected a symlinked `node_modules` as an invalid destination [#&#8203;17157](https://github.com/pnpm/pnpm/issues/17157).

- A filtered first install under the isolated linker now links every workspace project by name into `node_modules/.pnpm/node_modules`, not only the selected ones [pnpm/tasks#155](https://github.com/pnpm/tasks/issues/155).

- With `nodeLinker: hoisted`, a filtered install such as `pnpm --filter app add <pkg>` keeps the root `node_modules` links and bins of the workspace projects it did not select. A project with no dependencies of its own lost them until the next full install.

- `pnpm install --filter` with `nodeLinker: hoisted` and `--prod` or `--dev` now preserves previously installed dependency groups for unselected workspace projects [pnpm/tasks#164](https://github.com/pnpm/tasks/issues/164). Repeat filtered installs also re-resolve when a transitive injected workspace dependency or a linked dependency's version changes.

- With `sharedWorkspaceLockfile: false`, `pnpm install` now runs the workspace root's pnpmfile for every project, after the project's own pnpmfile. Before, it ran only the pnpmfile in the project's directory.

- `pnpm install` and `pnpm peers check` now detect peer dependency issues and report linked package versions in linked projects that use `package.json5` or `package.yaml` [pnpm/tasks#172](https://github.com/pnpm/tasks/issues/172).

- `pnpm install` and `pnpm peers check` no longer report an unmet peer when a workspace package's peer is provided by a remote tarball URL. pnpm now compares the peer range with the version in the tarball's manifest [#&#8203;17037](https://github.com/pnpm/pnpm/issues/17037).

- `pnpm prune` now removes extraneous direct packages from `node_modules` when `package.json` and `pnpm-lock.yaml` are already in sync. `pnpm prune` also honors `--filter`, `--recursive`, `sharedWorkspaceLockfile: false`, and the `trustLockfile` setting and `--trust-lockfile` flag. With the lockfile trusted, `pnpm prune --prod` works offline when every package is in the store [#&#8203;16999](https://github.com/pnpm/pnpm/issues/16999).

##### Injected workspace packages

- `pnpm install --frozen-lockfile` now fails with `ERR_PNPM_OUTDATED_LOCKFILE` when a local directory dependency or injected workspace package changes a dependency to a different tarball URL or git commit [#&#8203;17129](https://github.com/pnpm/pnpm/issues/17129). It also fails when an injected workspace package changes a dependency's named-registry range, such as `work:^2.0.0`, to one the locked version no longer satisfies.

- `pnpm install --frozen-lockfile` now accepts the lockfile it wrote for a `file:` dependency on a directory without a `package.json`. It also accepts the lockfile for an injected workspace package that bundles a dependency in `bundledDependencies`, lists a dependency in both `dependencies` and `optionalDependencies`, or publishes from a `publishConfig.directory` whose `package.json` lists other dependencies than the project's own. Before, these failed with `ERR_PNPM_OUTDATED_LOCKFILE`.

- The lockfile now records a `catalog:` peer dependency of an injected workspace package as written in its `package.json`. It recorded the catalog's range before, so editing the catalog changed the consumer's lockfile entry [pnpm/tasks#153](https://github.com/pnpm/tasks/issues/153).

- `pnpm install` now resolves a git, tarball, or tag dependency of an injected workspace package again when its spec changes. Before, it kept the old version.

- Repeat installs and `verifyDepsBeforeRun` now re-check projects that inject a modified workspace package, including when `sharedWorkspaceLockfile` is `false` [#&#8203;17007](https://github.com/pnpm/pnpm/issues/17007), and accept aliased `workspace:` ranges on linked dependencies.

- An injected workspace package that was linked now becomes a copy when the project that depends on it starts providing one of its peers at a version the package's own workspace context lacks. The link used to stay until that dependency was updated, so the package could not find the peer the project provides [#&#8203;17057](https://github.com/pnpm/pnpm/issues/17057).

- An injected workspace package now keeps only the files its manifest lists after a lifecycle script or a script named in `syncInjectedDepsAfterScripts` rebuilds it. Before, these refreshes copied every file of the package directory into the injected copy, including files that `files` or `.npmignore` leave out. With `deployAllFiles: true` the copy still gets every file.

- A script listed in `syncInjectedDepsAfterScripts` now keeps a package's links to its own files as links in the injected copies, the way `pnpm install` writes them, and updates those copies when `sharedWorkspaceLockfile` is `false`. Before, a directory link the script added became a real directory or went missing with `deployAllFiles`, and with `sharedWorkspaceLockfile: false` the copies kept the files from the last install.

##### Running scripts and checking dependencies

- Pressing Ctrl+C during `pnpm -r run` or `pnpm --filter <pkg> run` no longer reports `ERR_PNPM_RECURSIVE_RUN_FIRST_FAIL`. pnpm now ends with the interrupted script's status, such as 130 for a script that SIGINT ended on Linux or macOS [#&#8203;16964](https://github.com/pnpm/pnpm/issues/16964).

- With `enableGlobalVirtualStore`, a Node.js resolve hook that a script registers now sees the importer as `context.parentURL` after pnpm's `NODE_PATH` fallback fails to find a bare specifier. Hooks that resolve tsconfig `paths` aliases from the importer failed with `ERR_MODULE_NOT_FOUND` [#&#8203;16979](https://github.com/pnpm/pnpm/issues/16979).

- `pnpm run`, `pnpm exec`, and `pnpm restart` now pass the install flags they were given, such as `--lockfile-dir`, `--modules-dir`, `--store-dir`, `--offline`, and `--ignore-scripts`, to the `pnpm install` that `verifyDepsBeforeRun: install` starts. When that install leaves the dependencies out of date, pnpm now prints a warning.

- A repeated `pnpm install --filter` now finishes without reinstalling when the selected projects are up to date, and so does `pnpm install` once filtered commands have installed every project. After a filtered install, `pnpm run` and `pnpm exec` now install a selected project whose dependencies changed in between [#&#8203;17011](https://github.com/pnpm/pnpm/issues/17011), require the workspace root when a filtered install with `pruneDirectDependencies: true` skipped it [pnpm/tasks#181](https://github.com/pnpm/tasks/issues/181), and preserve the recorded ignored build scripts of unselected projects.

- The check that runs before a script now holds the workspace projects that the selected project depends on, including with `sharedWorkspaceLockfile: false` and for workspace dependencies declared with `link:`. `--filter=<project>...` now selects `link:` dependencies as well. In a workspace that has no `package.json` at its root, `pnpm run` and `pnpm exec` no longer reinstall before every command when the dependencies are up to date.

- `verifyDepsBeforeRun` and repeat `pnpm install` runs now apply `overrides` before comparing a modified `package.json` with `pnpm-lock.yaml` [#&#8203;17127](https://github.com/pnpm/pnpm/issues/17127). `pnpm install` with `optimisticRepeatInstall` now re-runs when `configDependencies` changed, `verifyDepsBeforeRun` reports `node_modules` out of date when `useGitBranchLockfile` is enabled and the branch lockfile is missing, and in a single-project repository both checks record a successful lockfile check so later runs skip it until the lockfile changes [#&#8203;16993](https://github.com/pnpm/pnpm/issues/16993).

- `pnpm install` and `verifyDepsBeforeRun` now compare manifests, lockfiles, and patch files by content hash. They notice an edit that kept the file's modification time, as `cp -p`, `rsync -a`, or an archive extraction leave it, and a patch file that was copied or touched without changing its content no longer marks dependencies as outdated [#&#8203;16988](https://github.com/pnpm/pnpm/issues/16988).

##### Deploying, packing, and other commands

- `pnpm deploy` now deploys `file:` dependencies that live outside the workspace directory. It failed with "Refusing to deploy unsafe lockfile path" [#&#8203;16983](https://github.com/pnpm/pnpm/issues/16983).

- `pnpm deploy` now records the peer dependencies of the workspace packages it copies into the deployed lockfile. Before, pnpm rejected that lockfile with `--frozen-lockfile` when a deployed workspace package declared a peer and `injectWorkspacePackages` was off [#&#8203;17093](https://github.com/pnpm/pnpm/issues/17093).

- `pnpm install --frozen-lockfile` and `verifyDepsBeforeRun` now succeed inside a directory created by `pnpm deploy`. `pnpm deploy` writes self-contained workspace and lockfile settings, prunes unused `patchedDependencies`, and preserves workspace-level dependency resolutions on deployed directory dependencies.

- On macOS, `pnpm deploy` no longer writes a second, unused copy of every package to `node_modules/.pnpm/@` in the deploy directory [#&#8203;17116](https://github.com/pnpm/pnpm/issues/17116).

- `pnpm patch-commit` and `pnpm install` now apply a patch that renames or moves a file of the patched package. Such a patch failed with "rename/copy operations in patches are not yet supported".

- In workspaces with `sharedWorkspaceLockfile: false`, `pnpm patch`, `pnpm patch-commit`, and `pnpm patch-remove` now resolve patch files and `patchedDependencies` entries at the workspace root. `pnpm install` checks configured patches across all workspace projects before reporting unused patches.

- `pnpm pack` and `pnpm publish` no longer include editor swap files such as `.*.swp`, macOS `._*` files, `.lock-wscript`, `.wafpickle-*`, `build/config.gypi`, or `archived-packages/` in the tarball. Naming one of these files in `files` still includes it [#&#8203;16955](https://github.com/pnpm/pnpm/issues/16955).

- `pnpm pack` and `pnpm publish` now support extended glob patterns and brace ranges such as `part{1..3}.js` and `part{a..c}.js`, including descending ranges, steps, and zero padding, in `files`, `.npmignore`, and `.gitignore`. Explicitly listed internal directory symlinks are preserved below excluded directories, entry points honor nested ignore files, ignore negations can re-include default-excluded logs and backup files, and nested lockfiles follow the package's file selection rules.

- Trusted publishing with OIDC now works with registries whose URL has a path, such as `https://registry.example/npm/private/`. pnpm previously sent the token exchange request to the root of the registry host.

- `pnpm deprecate` and `pnpm unpublish` now work for packages whose registry metadata is larger than 10 MiB, such as `typescript`. They accept up to 50 MiB, the same limit as `pnpm owner`.

- `pnpm owner ls` now lists the owners of a package on the npm registry. It reported every package as not found.

- `pnpm licenses list --prod` now includes optional dependencies, including transitive ones. Pass `--no-optional` to leave them out. `pnpm licenses list` also reports no licenses for workspace projects not recorded in the lockfile, errors when `pnpm-lock.yaml` is missing, and formats empty results as the requested text or JSON [pnpm/tasks#174](https://github.com/pnpm/tasks/issues/174).

- `pnpm why` now reads each selected workspace project's lockfile and modules directory when `sharedWorkspaceLockfile` is `false` [pnpm/tasks#169](https://github.com/pnpm/tasks/issues/169).

- `pnpm pkg fix` now converts a `repository` string such as `github:pnpm/example` to the object form, as `npm pkg fix` does. It also normalizes a GitHub, GitLab, or Bitbucket repository URL the way `npm pkg fix` does [#&#8203;16980](https://github.com/pnpm/pnpm/issues/16980).

##### Configuration and setting up pnpm

- Registry credentials and TLS settings passed with `--config`, such as `--config.//registry.example.com/:_authToken=<token>`, are now applied. They take precedence over the same settings in `.npmrc` files.

- pnpm now reads only the settings it needs to decide whether to switch to the pnpm version a project pins. A setting outside them can no longer fail that decision or change its outcome. For example, `pnpm --version` no longer fails in a pinned project whose `pnpm-workspace.yaml` has a setting this pnpm cannot read. Projects that pin neither pnpm nor a runtime skip this check without reading any settings.

- When pnpm switches to the version a project pins, an option only the pinned pnpm knows now reaches that pnpm when it comes immediately before the command name, as in `pnpm --new-flag install`. When switching for `pnpm --version` or an unrecognized command line, pnpm also honors `--color`, `--no-color`, `--reporter`, and `--loglevel` wherever they appear on the command line.

- `pnpm self-update` now updates the project's pnpm pin when Homebrew installed pnpm or Corepack runs it, leaving the global pnpm alone [#&#8203;17001](https://github.com/pnpm/pnpm/issues/17001). Run inside a workspace package, `pnpm self-update` updates the pin in the workspace root's manifest, including in `package.yaml` or `package.json5`.

- `pnpm setup` now completes when Windows registry environment values cannot be read or written. It prints PowerShell commands to configure `PNPM_HOME` and `PATH` without registry access [#&#8203;17167](https://github.com/pnpm/pnpm/issues/17167).

- `pnpm setup` now succeeds when it cannot tell which shell configuration file to update, for example in a container where `SHELL` is not set. It installs pnpm and prints the `PNPM_HOME` and `PATH` lines to add yourself. Previously it failed with `ERR_PNPM_UNKNOWN_SHELL`, and so did the installer script at get.pnpm.io [#&#8203;16973](https://github.com/pnpm/pnpm/issues/16973).

- In StackBlitz WebContainers, `pnpm` no longer crashes intermittently with `Parking not supported on this platform`, and running a command that does not exist now reports that the command was not found. Previously it sometimes failed with a generic error.

<!-- sponsors -->

#### Platinum Sponsors

<table>
  <tbody>
    <tr>
      <td align="center" valign="middle">
        <a href="https://bit.cloud/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer"><img src="https://pnpm.io/img/users/bit.svg" width="80" alt="Bit"></a>
      </td>
      <td align="center" valign="middle">
        <a href="https://openai.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/openai_dark.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/openai_light.svg" />
            <img src="https://pnpm.io/img/users/openai_dark.svg" width="160" alt="OpenAI" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://notion.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer"><img src="https://pnpm.io/img/users/notion.svg" width="80" alt="Notion"></a>
      </td>
    </tr>
    <tr>
      <td align="center" valign="middle">
        <a href="https://coderabbit.ai/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/coderabbit.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/coderabbit_light.svg" />
            <img src="https://pnpm.io/img/users/coderabbit.svg" width="220" alt="CodeRabbit" />
          </picture>
        </a>
      </td>
    </tr>
  </tbody>
</table>

#### Gold Sponsors

<table>
  <tbody>
    <tr>
      <td align="center" valign="middle">
        <a href="https://sanity.io/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/sanity.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/sanity_light.svg" />
            <img src="https://pnpm.io/img/users/sanity.svg" width="120" alt="Sanity" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://discord.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/discord.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/discord_light.svg" />
            <img src="https://pnpm.io/img/users/discord.svg" width="220" alt="Discord" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://vite.dev/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer"><img src="https://pnpm.io/img/users/vitejs.svg" width="42" alt="Vite"></a>
      </td>
    </tr>
    <tr>
      <td align="center" valign="middle">
        <a href="https://serpapi.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/serpapi_dark.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/serpapi_light.svg" />
            <img src="https://pnpm.io/img/users/serpapi_dark.svg" width="160" alt="SerpApi" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://stackblitz.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/stackblitz.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/stackblitz_light.svg" />
            <img src="https://pnpm.io/img/users/stackblitz.svg" width="190" alt="Stackblitz" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://workleap.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/workleap.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/workleap_light.svg" />
            <img src="https://pnpm.io/img/users/workleap.svg" width="190" alt="Workleap" />
          </picture>
        </a>
      </td>
    </tr>
    <tr>
      <td align="center" valign="middle">
        <a href="https://nx.dev/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/nx.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/nx_light.svg" />
            <img src="https://pnpm.io/img/users/nx.svg" width="50" alt="Nx" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://latitude.so/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer"><img src="https://pnpm.io/img/users/latitude.svg" width="160" alt="Latitude"></a>
      </td>
    </tr>
  </tbody>
</table>

<!-- sponsors end -->

### [`v12.14.0`](https://github.com/pnpm/pnpm/releases/tag/v12.14.0): pnpm 12.14.0

[Compare Source](https://github.com/pnpm/pnpm/compare/v12.13.0...v12.14.0)

This release adds the `sideEffectsCache.exclude` setting, stops `pnpm install` from waiting on the daily update check, and keeps pnpm from aborting with a core dump when the reader of its output exits.

##### Minor Changes

- Added the `sideEffectsCache.exclude` setting for packages whose build depends on something pnpm cannot include in the cache key, such as the system libraries a native addon links against. pnpm builds the listed packages in every project and never restores or saves their builds through the side-effects cache, locally or on a `remoteCache` server. Under the global virtual store, each project gets its own copy of these packages and of the packages that depend on them. Entries use the same `name`, `@scope/*`, and `name@version` patterns as `minimumReleaseAgeExclude` [#&#8203;5271](https://github.com/pnpm/pnpm/issues/5271).

- `pnpm login` now prints the `npm-notice` response header during web-based login. Registries use it to show the verification code that completes the sign-in in the browser.

##### Patch Changes

##### Installing packages

- `pnpm install` and `pnpm add` no longer wait for the daily update check. If the command finishes first, pnpm skips the update notice and checks again next time. On a registry that accepted the connection but never answered, an install that had nothing to do used to take minutes [#&#8203;16839](https://github.com/pnpm/pnpm/issues/16839).

- `pnpm install`, `pnpm add` and `pnpm update` now reuse `pnpm-lock.yaml` when the workspace configures a catalog entry that no dependency references, such as an unused entry or one whose package an `overrides` entry replaces. Before, every resolution in such a workspace resolved all dependencies again from the registry [#&#8203;16923](https://github.com/pnpm/pnpm/issues/16923).

- `pnpm install` now looks up a git dependency's branch or tag once per install, even when many workspace projects depend on it. With `linkWorkspacePackages` enabled, it used to run `git ls-remote` once per project [#&#8203;16899](https://github.com/pnpm/pnpm/issues/16899).

- A filtered install, such as `pnpm install --filter <pkg>`, now keeps the `pnpm-lock.yaml` entries of workspace projects that are missing from disk, as in a sparse checkout. Their importers, packages, and catalog entries stay even when the filter matches every project on disk [#&#8203;16931](https://github.com/pnpm/pnpm/issues/16931).

- pnpm now decides whether a dependency that a package also declares as an optional peer is linked as a dependency or as a peer from the shallowest path that reaches the package. When an existing lockfile records such a dependency as a regular dependency and a newly added dependency now provides the peer, pnpm records it as a peer, as a fresh install does. The lockfile entry of such a package can change on the next install [#&#8203;16901](https://github.com/pnpm/pnpm/issues/16901).

- An install that adds nothing to the store no longer changes the modification time of the store directory. CI caches that check modification times, such as GitLab's, no longer re-upload an unchanged store [#&#8203;16929](https://github.com/pnpm/pnpm/issues/16929).

##### Running commands and scripts

- pnpm no longer aborts with a core dump when the reader of its output has exited, as in `pnpm list | head -1` or `pnpm start 2>&1 | head -1`. The command finishes with its usual exit code, and a failing script's exit code is kept. A write to stdout that fails for another reason, such as a full disk, ends the command with exit code 1 [#&#8203;16904](https://github.com/pnpm/pnpm/issues/16904) [pnpm/tasks#132](https://github.com/pnpm/tasks/issues/132).

- On Windows, `pnpm exec`, `pnpm run`, and commands such as `pnpm nx` now return when the command they run exits, even if it left a detached process running and pnpm's output is redirected or piped. Previously a shell reading that output waited until the detached process, such as the Nx daemon, exited [#&#8203;16930](https://github.com/pnpm/pnpm/issues/16930).

- Commands that do not write the project manifest now leave a missing `package.json` absent. This covers queries such as `pnpm why` and `pnpm outdated`, `pnpm fetch`, `pnpm dedupe --check`, and commands that exit with an error, such as `pnpm rt ls`. These commands used to create one from the initialization template. `pnpm sbom` run from a lockfile alone now reports the root component as `unknown` with version `0.0.0` [#&#8203;16907](https://github.com/pnpm/pnpm/issues/16907).

- `pnpm run` now reports a failed script as a JSON record under `--reporter=ndjson`. It printed a plain `[ELIFECYCLE]` line to stderr.

- `pnpm run` no longer prints `[ELIFECYCLE] Command failed with exit code N.` to stderr when a script fails under `--reporter=silent`, `--silent`, or `--loglevel=silent`.

- `pnpm pipeline --dry-run` no longer writes a run report when no projects are selected. With `--json` it prints `{"tasks": []}` [pnpm/tasks#126](https://github.com/pnpm/tasks/issues/126).

##### Packing and publishing

- `pnpm pack` and `pnpm publish` now ship the whole gitignored directory that `main`, `browser`, or `bin` points into, as npm does. Previously only the `main` and `bin` files themselves were packed, and a gitignored `browser` file was left out [#&#8203;16908](https://github.com/pnpm/pnpm/issues/16908).

- `pnpm pack` and `pnpm publish` now honor a `.npmignore` or `.gitignore` inside a subdirectory when `package.json` has a `files` field. The package root's ignore files and those inherited from the workspace are still skipped [#&#8203;16909](https://github.com/pnpm/pnpm/issues/16909).

##### Setting up pnpm and toolchains

- `--registry`, `--https-proxy`, `--http-proxy`, and `--no-proxy` now apply when pnpm resolves and downloads the pnpm version a project pins in `packageManager`. Before, these lookups went to `https://registry.npmjs.org/`, which a firewall that only allows a private registry blocks [#&#8203;16911](https://github.com/pnpm/pnpm/discussions/16911).

- On Windows, `pnpm install` now installs the Rust toolchain for rustup's default host, so a machine set up with `rustup set default-host x86_64-pc-windows-gnu` gets the MinGW toolchain. Without a default host, pnpm installs the MSVC toolchain for the machine's architecture, as rustup does. This includes a pnpm built for MinGW, such as the MSYS2 package, which has installed the MinGW toolchain since 12.13.0. An x64 pnpm on ARM64 Windows now installs the ARM64 toolchain [#&#8203;16854](https://github.com/pnpm/pnpm/issues/16854).

<!-- sponsors -->

#### Platinum Sponsors

<table>
  <tbody>
    <tr>
      <td align="center" valign="middle">
        <a href="https://bit.cloud/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer"><img src="https://pnpm.io/img/users/bit.svg" width="80" alt="Bit"></a>
      </td>
      <td align="center" valign="middle">
        <a href="https://openai.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/openai_dark.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/openai_light.svg" />
            <img src="https://pnpm.io/img/users/openai_dark.svg" width="160" alt="OpenAI" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://notion.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer"><img src="https://pnpm.io/img/users/notion.svg" width="80" alt="Notion"></a>
      </td>
    </tr>
    <tr>
      <td align="center" valign="middle">
        <a href="https://coderabbit.ai/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/coderabbit.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/coderabbit_light.svg" />
            <img src="https://pnpm.io/img/users/coderabbit.svg" width="220" alt="CodeRabbit" />
          </picture>
        </a>
      </td>
    </tr>
  </tbody>
</table>

#### Gold Sponsors

<table>
  <tbody>
    <tr>
      <td align="center" valign="middle">
        <a href="https://sanity.io/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/sanity.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/sanity_light.svg" />
            <img src="https://pnpm.io/img/users/sanity.svg" width="120" alt="Sanity" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://discord.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/discord.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/discord_light.svg" />
            <img src="https://pnpm.io/img/users/discord.svg" width="220" alt="Discord" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://vite.dev/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer"><img src="https://pnpm.io/img/users/vitejs.svg" width="42" alt="Vite"></a>
      </td>
    </tr>
    <tr>
      <td align="center" valign="middle">
        <a href="https://serpapi.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/serpapi_dark.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/serpapi_light.svg" />
            <img src="https://pnpm.io/img/users/serpapi_dark.svg" width="160" alt="SerpApi" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://stackblitz.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/stackblitz.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/stackblitz_light.svg" />
            <img src="https://pnpm.io/img/users/stackblitz.svg" width="190" alt="Stackblitz" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://workleap.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/workleap.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/workleap_light.svg" />
            <img src="https://pnpm.io/img/users/workleap.svg" width="190" alt="Workleap" />
          </picture>
        </a>
      </td>
    </tr>
    <tr>
      <td align="center" valign="middle">
        <a href="https://nx.dev/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/nx.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/nx_light.svg" />
            <img src="https://pnpm.io/img/users/nx.svg" width="50" alt="Nx" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://latitude.so/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer"><img src="https://pnpm.io/img/users/latitude.svg" width="160" alt="Latitude"></a>
      </td>
    </tr>
  </tbody>
</table>

<!-- sponsors end -->

</details>

---

### Configuration

📅 **Schedule**: (UTC)

- Branch creation
  - Between 12:00 AM and 03:59 AM, only on Monday (`* 0-3 * * 1`)
- Automerge
  - At any time (no schedule defined)

🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied.

♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox.

👻 **Immortal**: This PR will be recreated if closed unmerged. Get [config help](https://github.com/renovatebot/renovate/discussions) if that's undesired.

---

 - [ ] <!-- rebase-check -->If you want to rebase/retry this PR, check this box

---

This PR has been generated by [Mend Renovate CLI](https://github.com/renovatebot/renovate).
<!--renovate-debug:eyJjcmVhdGVkSW5WZXIiOiI0My4xOTEuMiIsInVwZGF0ZWRJblZlciI6IjQ0LjE4MS43IiwidGFyZ2V0QnJhbmNoIjoibWFpbiIsImxhYmVscyI6W119-->

<!-- cloudflare-preview --> Preview: https://pr-611.docs-gitea-com.pages.dev

---------

Co-authored-by: Lunny Xiao <[email protected]>
Reviewed-on: https://gitea.com/gitea/docs/pulls/611
Reviewed-by: Lunny Xiao <[email protected]>
Co-authored-by: Renovate Bot <[email protected]>
2026-10-26 22:30:15 +00:00
Gitea Bot 4ea46e6315 Update the latest api documents (#612)
Automated update of static/swagger-latest.json and static/openapi3-latest.json from the gitea main branch, opened by the "update api spec files" scheduled workflow.

<!-- cloudflare-preview --> Preview: https://pr-612.docs-gitea-com.pages.dev

Reviewed-on: https://gitea.com/gitea/docs/pulls/612
Co-authored-by: Gitea Bot <[email protected]>
2026-10-26 16:10:40 +00:00
silverwindandLunny Xiao cb424640a2 docs: document Forwarded header and client port for REVERSE_PROXY_LIMIT (#560)
Document https://github.com/go-gitea/gitea/pull/39190, which reads the RFC 7239 `Forwarded` header when `X-Forwarded-For` is absent and keeps the forwarded client port.

- `REVERSE_PROXY_LIMIT`: list `X-Real-IP`, `X-Forwarded-For` and `Forwarded` in the order they are read, and where the client port comes from, also in zh-cn and zh-tw
- Reverse proxies: require the proxy to set `X-Real-IP`, since Caddy, Apache and HAProxy pass a client-sent one through by default, and mention `X-Real-Port` for logging the client port

Co-authored-by: Lunny Xiao <[email protected]>
Reviewed-on: https://gitea.com/gitea/docs/pulls/560
Reviewed-by: Lunny Xiao <[email protected]>
2026-10-23 22:44:51 +00:00
bircniandsilverwind 09bb4cabcf Add documentation for gt, the Gitea CLI (#603)
Adds a CLI product for gt (https://gitea.com/gitea/cli), set up like the runner, with short guides for installation, logging in, CI and scripting. Each command's details stay in gt <command> --help. Until the first release, the docs are served at /cli/; make cut-version PRODUCT=cli VERSION=0.1 adds the release series.

Closes https://gitea.com/gitea/cli/issues/16

<!-- cloudflare-preview --> Preview: https://pr-603.docs-gitea-com.pages.dev

---------

Co-authored-by: silverwind <[email protected]>
Reviewed-on: https://gitea.com/gitea/docs/pulls/603
Reviewed-by: Lunny Xiao <[email protected]>
Reviewed-by: silverwind <[email protected]>
2026-10-23 12:16:49 +00:00
silverwind 9699ec2c87 docs: clarify that team package permissions cover the whole org (#605)
Packages belong to the owner, so a team's packages permission covers every package of the organization, regardless of the team's repositories. State that in the access restrictions section, matching the team settings change in https://github.com/go-gitea/gitea/pull/39953.

The old note announced a dedicated team permission for finer control, which has existed since the packages unit was added, so it is replaced.

Reviewed-on: https://gitea.com/gitea/docs/pulls/605
Reviewed-by: Lunny Xiao <[email protected]>
Co-authored-by: silverwind <[email protected]>
2026-10-22 23:46:15 +00:00
silverwindandbircni c00af83676 Document the artifact retention limit (#602)
Documents https://github.com/go-gitea/gitea/pull/39894 for main and 28. Workflows can request a shorter artifact retention, down to 1 day, and `github.retention_days` carries `ARTIFACT_RETENTION_DAYS`, empty when artifacts are kept forever.

---------

Co-authored-by: bircni <[email protected]>
Reviewed-on: https://gitea.com/gitea/docs/pulls/602
Reviewed-by: bircni <[email protected]>
Co-authored-by: silverwind <[email protected]>
2026-10-22 20:05:39 +00:00
silverwind c9282b96da Clarify reverse proxy authentication requirements (#604)
Document that reverse proxy authentication requires Gitea to be reachable only through the authenticating proxy, and which routes each setting covers. Companion to https://github.com/go-gitea/gitea/pull/39940.

_Written by Claude._

Reviewed-on: https://gitea.com/gitea/docs/pulls/604
Reviewed-by: bircni <[email protected]>
Co-authored-by: silverwind <[email protected]>
2026-10-22 16:33:31 +00:00
49d912f7fb docs: fix repository path in binary install restore example (#601)
Fixes the binary-install restore example in the Backup and Restore docs.

The default `[repository] ROOT` is `{APP_DATA_PATH}/gitea-repositories`, but the example restored repos to `/var/lib/gitea/data/repositories/`, so restored repositories did not show up. Changed it to `/var/lib/gitea/data/gitea-repositories/`.

The Docker and Docker-rootless examples are unchanged: their app.ini templates set `[repository] ROOT` explicitly, so their paths are already correct.

Refs go-gitea/gitea#39736

---------

Co-authored-by: silverwind <[email protected]>
Co-authored-by: silverwind <[email protected]>
Co-authored-by: souvik-biswas-dev <[email protected]>
Reviewed-on: https://gitea.com/gitea/docs/pulls/601
Reviewed-by: silverwind <[email protected]>
Co-authored-by: souvikbiswasdev <[email protected]>
2026-10-22 03:46:06 +00:00
398f418387 docs: document protected branch deletion and system users (#583)
Documents protected branch deletion and system users in push, force-push and deletion allowlists, added in https://github.com/go-gitea/gitea/pull/39243 and https://github.com/go-gitea/gitea/pull/39735 (both merged).

Updates the Actions token permissions guide and audit actor names to match.

---------

Co-authored-by: silverwind <[email protected]>
Co-authored-by: Lunny Xiao <[email protected]>
Reviewed-on: https://gitea.com/gitea/docs/pulls/583
Reviewed-by: silverwind <[email protected]>
Co-authored-by: Enoque Duarte <[email protected]>
2026-10-22 03:43:37 +00:00
silverwind be6aefc7e8 Simplify the runner docs and fix their outdated facts (#600)
The runner pages had drifted from the runner. They claimed Podman is unsupported, a registration retry limit of 10, a `container.env` proxy override that has no effect, and they used the deprecated `generate-config` command, while the actual instructions were buried under implementation details.

The develop and 5.x pages are rewritten from the current runner sources (`main` is `v5.2.0`). They are shorter and aimed at operators, with a new page covering what jobs get. The reference generator now documents the `config` command, and the quickstart pages in every language use the `gitea-runner` binary name.

Reviewed-on: https://gitea.com/gitea/docs/pulls/600
Reviewed-by: Lunny Xiao <[email protected]>
Co-authored-by: silverwind <[email protected]>
2026-10-21 05:25:45 +00:00
bircni a874918bb7 Document runner 4 and 5, regenerate the 28.2.0 api documents (#599)
The 28.2.0 bump in #594 only changed the version string of the api documents, so they still listed the 28.1.0 endpoints. They are now regenerated from v28.2.0 (mostly new `423 repoArchivedError` responses).

The runner docs stopped at 3.3.0 while the runner is at 5.1.1:

- cut the runner `4` and `5` series, `/runner/` now serves 5.1.1 and `/runner/4/` 4.1.0, the `3` series is bumped to 3.5.0
- series specific image tags and versions in the new copies, the `3` series no longer claims the `latest` tag
- 4.0 and 5.0 sections in the upgrade guide, and the Git 2.34.1 requirement of 5.0 in the requirements
- regenerated every reference page from the newest stable tag of its series

Reviewed-on: https://gitea.com/gitea/docs/pulls/599
Reviewed-by: TheFox0x7 <[email protected]>
2026-10-20 19:19:28 +00:00
Renovate Bot 5304217222 chore(deps): update dependencies (#595)
Co-authored-by: Renovate Bot <[email protected]>
2026-10-20 18:53:10 +00:00
Shudhanshu Singh 88356280ec docs: mention release reactions in the REACTIONS setting (#598)
Documents the `[ui] RELEASE_REACTIONS` setting added in https://github.com/go-gitea/gitea/pull/38415, which sets the reactions available on releases (default `+1, laugh, hooray, heart, rocket, eyes`). `REACTIONS` now only covers issues, pull requests and comments. Updated in English, 简体中文 and 繁體中文.

Reviewed-on: https://gitea.com/gitea/docs/pulls/598
Reviewed-by: silverwind <[email protected]>
Co-authored-by: Shudhanshu Singh <[email protected]>
2026-10-20 13:21:46 +00:00
Gitea BotandLunny Xiao c7dc13cf83 Update the latest api documents (#596)
Automated update of static/swagger-latest.json and static/openapi3-latest.json from the gitea main branch, opened by the "update api spec files" scheduled workflow.

<!-- cloudflare-preview --> Preview: https://pr-596.docs-gitea-com.pages.dev

---------

Co-authored-by: Lunny Xiao <[email protected]>
Reviewed-on: https://gitea.com/gitea/docs/pulls/596
Reviewed-by: Lunny Xiao <[email protected]>
Co-authored-by: Gitea Bot <[email protected]>
2026-10-19 14:05:10 +00:00
Gitea BotandLunny Xiao bed218d62d Update the runner reference pages (#597)
Automated update of the generated runner reference pages from gitea/runner (main for the develop docs, the newest stable tag for every documented series), opened by the "update runner reference" scheduled workflow.

<!-- cloudflare-preview --> Preview: https://pr-597.docs-gitea-com.pages.dev

---------

Co-authored-by: Lunny Xiao <[email protected]>
Reviewed-on: https://gitea.com/gitea/docs/pulls/597
Reviewed-by: Lunny Xiao <[email protected]>
Co-authored-by: Gitea Bot <[email protected]>
2026-10-19 09:24:38 +00:00
Lunny Xiao 08aff1bae9 update to v28.2.0 (#594)
<!-- cloudflare-preview --> Preview: https://pr-594.docs-gitea-com.pages.dev

Reviewed-on: https://gitea.com/gitea/docs/pulls/594
Reviewed-by: silverwind <[email protected]>
2026-10-19 04:58:10 +00:00
Lunny Xiao 8cf8f49a95 Remove on-cloud-provider page (#593)
Cloud providers are now listed in awesome-gitea (https://gitea.com/gitea/awesome-gitea/pulls/202). Removes the page from the current docs and its zh-cn/zh-tw translations; released versioned docs are untouched.

Reviewed-on: https://gitea.com/gitea/docs/pulls/593
Reviewed-by: silverwind <[email protected]>
2026-10-18 19:06:41 +00:00
2af7b60fd9 docs(actions): document OIDC workload identity (#526)
Document the OpenID Connect tokens that Gitea Actions jobs can request since https://github.com/go-gitea/gitea/pull/39052, so they can sign in to cloud providers without long-lived secrets.

- Add an OpenID Connect page covering how to trust Gitea, request a token and match its claims
- Document the `id-token` permission scope and its maximum
- Translate both for zh-cn and zh-tw, which still listed `id-token` as unsupported

Co-authored-by: silverwind <[email protected]>
Co-authored-by: silverwind <[email protected]>
Reviewed-on: https://gitea.com/gitea/docs/pulls/526
Reviewed-by: silverwind <[email protected]>
Co-authored-by: Max P. <[email protected]>
2026-10-18 07:12:16 +00:00
Jakub VránaandJakub Vrana db9e6f9f48 docs: document pre-filling issues and pull requests from query parameters (#592)
Describe the query parameters of the new issue and pull request pages, including those added in https://github.com/go-gitea/gitea/pull/39804.

---------

Co-authored-by: Jakub Vrana <[email protected]>
Reviewed-on: https://gitea.com/gitea/docs/pulls/592
Reviewed-by: wxiaoguang <[email protected]>
Reviewed-by: bircni <[email protected]>
Co-authored-by: Jakub Vrána <[email protected]>
2026-10-17 21:56:31 +00:00
Lunny Xiao b555a247e0 refactor: drop the remaining docusaurus names from identifiers and comments (#589)
Follow-up to #588.

- rename `DocusaurusSidebarItem` -> `SidebarSourceItem`, `fromDocusaurus` -> `fromSidebarSource`, `docusaurusSidebars` -> `sidebarSources`
- reword comments and READMEs that described behaviour by comparison with docusaurus; fix the stale note in `sites/docs/src/config/api.ts`
- drop `.docusaurus/` from `.gitignore`

No functional change. `pnpm check` has 0 errors and `pnpm build` still builds 6690 pages.

<!-- cloudflare-preview --> Preview: https://pr-589.docs-gitea-com.pages.dev

Reviewed-on: https://gitea.com/gitea/docs/pulls/589
Reviewed-by: silverwind <[email protected]>
2026-10-15 17:39:24 +00:00
Lunny Xiao 2275bef3bd refactor: rename i18n/*/docusaurus-plugin-content-docs to i18n/*/docs (#588)
Drops the leftover docusaurus name from the translated content directories.

- git mv i18n/{en-us,zh-cn,zh-tw}/docusaurus-plugin-content-docs -> i18n/{locale}/docs (pure renames, content unchanged)
- update the paths in packages/content-loader/src/products.ts, scripts/cut-version.mjs and sites/docs/README.md

current.json / version-*.json keep their names and stay beside the content.

Verified: pnpm build succeeds, 6690 pages built.

<!-- cloudflare-preview --> Preview: https://pr-588.docs-gitea-com.pages.dev
Reviewed-on: https://gitea.com/gitea/docs/pulls/588
Reviewed-by: Zettat123 <[email protected]>
2026-10-12 21:05:07 +00:00
Renovate Bot 1408e4890e chore(deps): update dependencies (#585)
This PR contains the following updates:

| Package | Change | [Age](https://docs.renovatebot.com/merge-confidence/) | [Confidence](https://docs.renovatebot.com/merge-confidence/) | Type | Update | Pending |
|---|---|---|---|---|---|---|
| [@astrojs/starlight](https://starlight.astro.build) ([source](https://github.com/withastro/starlight/tree/HEAD/packages/starlight)) | [`0.42.4` → `0.42.5`](https://renovatebot.com/diffs/npm/@astrojs%2fstarlight/0.42.4/0.42.5) | ![age](https://developer.mend.io/api/mc/badges/age/npm/@astrojs%2fstarlight/0.42.5?slim=true) | ![confidence](https://developer.mend.io/api/mc/badges/confidence/npm/@astrojs%2fstarlight/0.42.4/0.42.5?slim=true) | dependencies | patch | `0.42.6` |
| [actions/setup-node](https://github.com/actions/setup-node) ([changelog](https://github.com/actions/setup-node/compare/820762786026740c76f36085b0efc47a31fe5020..949feb2413d6458794dcd2491c4babbbce0c15c1)) | `8207627` → `949feb2` |  |  | action | digest |  |
| [astro](https://astro.build) ([source](https://github.com/withastro/astro/tree/HEAD/packages/astro)) | [`7.3.5` → `7.3.6`](https://renovatebot.com/diffs/npm/astro/7.3.5/7.3.6) | ![age](https://developer.mend.io/api/mc/badges/age/npm/astro/7.3.6?slim=true) | ![confidence](https://developer.mend.io/api/mc/badges/confidence/npm/astro/7.3.5/7.3.6?slim=true) | dependencies | patch | `7.3.8` (+1) |
| [pnpm](https://pnpm.io) ([source](https://github.com/pnpm/pnpm/tree/HEAD/pnpm/npm/pnpm)) | [`12.8.2` → `12.10.1`](https://renovatebot.com/diffs/npm/pnpm/12.8.2/12.10.1) | ![age](https://developer.mend.io/api/mc/badges/age/npm/pnpm/12.10.1?slim=true) | ![confidence](https://developer.mend.io/api/mc/badges/confidence/npm/pnpm/12.8.2/12.10.1?slim=true) | packageManager | minor | `12.11.2` (+2) |

---

### Release Notes

<details>
<summary>withastro/starlight (@&#8203;astrojs/starlight)</summary>

### [`v0.42.5`](https://github.com/withastro/starlight/blob/HEAD/packages/starlight/CHANGELOG.md#0425)

[Compare Source](https://github.com/withastro/starlight/compare/@astrojs/[email protected]...@astrojs/[email protected])

##### Patch Changes

- [#&#8203;4227](https://github.com/withastro/starlight/pull/4227) [`5ba7a70`](https://github.com/withastro/starlight/commit/5ba7a70ad491ed8b5fc7033558dcc5428112cf97) Thanks [@&#8203;I90rche](https://github.com/I90rche)! - Adds Macedonian language support

</details>

<details>
<summary>withastro/astro (astro)</summary>

### [`v7.3.6`](https://github.com/withastro/astro/blob/HEAD/packages/astro/CHANGELOG.md#736)

[Compare Source](https://github.com/withastro/astro/compare/[email protected]@7.3.6)

##### Patch Changes

- [#&#8203;18166](https://github.com/withastro/astro/pull/18166) [`5134d0f`](https://github.com/withastro/astro/commit/5134d0f9e7478f23b1a590fa2416a2469c62ee23) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes an intermittent dev server crash when using `astro:actions` inside a server island with adapters that use a pre-bundled SSR environment (e.g. `@astrojs/cloudflare`)

- [#&#8203;18076](https://github.com/withastro/astro/pull/18076) [`8a2df66`](https://github.com/withastro/astro/commit/8a2df6675aa62fea382bce1cdb30c4260e0f104b) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes stale scoped styles during HMR when both markup and `<style>` are changed in a single save

- [#&#8203;18252](https://github.com/withastro/astro/pull/18252) [`2d29e7e`](https://github.com/withastro/astro/commit/2d29e7e38db65fcca7f241c967417003e20ecf43) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes CSS from other pages leaking into a page's `<head>` in dev when the page imports a module such as `astro:config/server`.

- [#&#8203;18000](https://github.com/withastro/astro/pull/18000) [`6724575`](https://github.com/withastro/astro/commit/67245751e02fb94223266d3c55cc7d7ac65ab060) Thanks [@&#8203;barclayd](https://github.com/barclayd)! - Fixes a bug where server islands containing framework components rendered empty in the dev server when using a custom `src/fetch.ts`

- [#&#8203;18241](https://github.com/withastro/astro/pull/18241) [`7c5fd6f`](https://github.com/withastro/astro/commit/7c5fd6f1faf4d87d0c9c5836ee47cc0d6d529ca3) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes the composable `i18n()` handler from `astro/fetch` and `astro/hono` returning an empty 404 for paths without a locale prefix. It now renders the custom 404 page, matching `astro()`.

- [#&#8203;18164](https://github.com/withastro/astro/pull/18164) [`1a6997f`](https://github.com/withastro/astro/commit/1a6997f280529650e4f1dacf0388e8fe07d05a1a) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes CSS Module HMR in dev when a component is rendered both with and without hydration on the same page. Astro now uses path-based class name hashing in dev mode so that editing CSS declarations no longer changes the generated selectors, allowing Vite's CSS HMR to update styles without a full page reload.

- [#&#8203;18243](https://github.com/withastro/astro/pull/18243) [`dd29d62`](https://github.com/withastro/astro/commit/dd29d62b1e7bd071804f822e90361cf5c9784682) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes `context.props` being `null` in middleware and endpoints when the composable `astro/hono` or `astro/fetch` `actions()` handler runs before `middleware()`, or when `pages()` runs without `middleware()`

- [#&#8203;18193](https://github.com/withastro/astro/pull/18193) [`95d5d16`](https://github.com/withastro/astro/commit/95d5d16ce983612e09b588bb249f76d273c872f7) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes `astro build` failing on Windows with Node.js 25+ with `ERR_INVALID_ARG_VALUE` when clearing the output directory hits a transient `EPERM` error

- [#&#8203;18220](https://github.com/withastro/astro/pull/18220) [`d6c13a4`](https://github.com/withastro/astro/commit/d6c13a48c682bb42da1eb295d520f9667035e1fb) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes type errors reported in Astro's built-in `<Picture />` and `<Font />` components when type-checking a project with `tsc` and `@astrojs/ts-content-mapper`

- [#&#8203;18133](https://github.com/withastro/astro/pull/18133) [`faac481`](https://github.com/withastro/astro/commit/faac481dc86efdd2e4987069a7298f2aea3f1c6c) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes lost request state when Vite discovers server dependencies during a request in Cloudflare dev mode

- [#&#8203;18146](https://github.com/withastro/astro/pull/18146) [`2af4516`](https://github.com/withastro/astro/commit/2af45163fb7757a533bdf929874278e0a7483cfc) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes CSS imported from an `injectScript('page')` script being dropped during build

- [#&#8203;18159](https://github.com/withastro/astro/pull/18159) [`e5f8fe0`](https://github.com/withastro/astro/commit/e5f8fe0fcfd1c1845ae425cbf874864ce5ab5a37) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes a hang when a `server:defer` component is inside a slot of another component in an MDX content collection entry

- [#&#8203;18246](https://github.com/withastro/astro/pull/18246) [`c3b42ad`](https://github.com/withastro/astro/commit/c3b42adb50612041b2e1c59f386065be934e5259) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes the `glob()` loader skipping content files whose paths contain `#` or `?`

- [#&#8203;18248](https://github.com/withastro/astro/pull/18248) [`b97184e`](https://github.com/withastro/astro/commit/b97184e53012404990da6788be5aa30f99c4cf6e) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes a bug where page routes added with `injectRoute()` returned a 404 when `i18n.routing.prefixDefaultLocale` was `true` and the route path had no locale prefix

- [#&#8203;18251](https://github.com/withastro/astro/pull/18251) [`3415263`](https://github.com/withastro/astro/commit/34152630b0dd77c2bfae68e568e01f824a8ee603) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes content collection changes being ignored in `astro dev` after the dev server restarts because of a config change

- [#&#8203;18226](https://github.com/withastro/astro/pull/18226) [`ad54af0`](https://github.com/withastro/astro/commit/ad54af063accfa123bf36c44a126da0404c480bb) Thanks [@&#8203;imharjot](https://github.com/imharjot)! - Fixes `Astro.cookies.get()` returning `undefined` for request cookies with empty values

- [#&#8203;18155](https://github.com/withastro/astro/pull/18155) [`37ab0e4`](https://github.com/withastro/astro/commit/37ab0e47ff53a688b667b6197807717bc4454e1b) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes nondeterministic ordering of the server manifest's `assets` array, ensuring builds with identical inputs produce byte-identical output

- [#&#8203;18099](https://github.com/withastro/astro/pull/18099) [`6987261`](https://github.com/withastro/astro/commit/69872618b7b7c915b2bd51a4b41e3a3e3116f3bb) Thanks [@&#8203;renovate](https://github.com/apps/renovate)! - Adds YAML parsing with timestamp and merge key support, and formats YAML errors consistently across Astro, Markdown, MDX, and Markdoc.

- [#&#8203;15595](https://github.com/withastro/astro/pull/15595) [`64e4039`](https://github.com/withastro/astro/commit/64e40396dc7e955986fd6d7bbd195f72556933d5) Thanks [@&#8203;qzio](https://github.com/qzio)! - Improves CSRF protection by taking modern browsers headers into account

- [#&#8203;18215](https://github.com/withastro/astro/pull/18215) [`941bd5e`](https://github.com/withastro/astro/commit/941bd5ecbe0b8ffdc9cde92880d402b8edc37d7a) Thanks [@&#8203;ump45nose](https://github.com/ump45nose)! - Fixes a runtime `ReferenceError` for inlined scripts that import a URL with `/* @&#8203;vite-ignore */`.

  Astro now inlines scripts after Vite replaces its preload markers, so ignored dynamic imports can remain inline without shipping an unresolved `__VITE_PRELOAD__` reference.

- [#&#8203;18179](https://github.com/withastro/astro/pull/18179) [`6caa659`](https://github.com/withastro/astro/commit/6caa6594afb557177e885077028db37506c409b7) Thanks [@&#8203;matthewp](https://github.com/matthewp)! - Fixes custom View Transition direction names that are not valid CSS identifiers, such as names starting with a digit or containing spaces. These directions now match their animations correctly.

- [#&#8203;18250](https://github.com/withastro/astro/pull/18250) [`7eae39b`](https://github.com/withastro/astro/commit/7eae39bebbafc5a7b7763a8733a6e60ded5ead17) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes a 404 for a CSS file that a dynamic import preloads when the imported module uses a component that is also a hydrated island on the same page

- [#&#8203;18176](https://github.com/withastro/astro/pull/18176) [`7c9d00d`](https://github.com/withastro/astro/commit/7c9d00d251e42b577ed298879fe9e68a345bd776) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes duplicate CSS in production builds when a component is both server-rendered and used with `client:only` on the same page

- [#&#8203;18245](https://github.com/withastro/astro/pull/18245) [`492e95f`](https://github.com/withastro/astro/commit/492e95f8716829f1bd0ead70405ad982a0a5c105) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes the composable `astro/fetch` and `astro/hono` handlers (`trailingSlash()`, `redirects()`, `actions()`, `middleware()`, and `pages()`) so they reject over-encoded request paths with a `400 Bad Request`, matching `astro()`. For these requests, `redirects()` and `actions()` return the `400` response instead of `undefined`, so no redirect is issued and no action runs.

- [#&#8203;18078](https://github.com/withastro/astro/pull/18078) [`0a2ab10`](https://github.com/withastro/astro/commit/0a2ab102a91c141f42b6d7da9810db74f61d1fa0) Thanks [@&#8203;manuelgruber](https://github.com/manuelgruber)! - Fixes `Astro.rewrite()` and `context.rewrite()` selecting the wrong route in `astro dev` when two dynamic routes match the same path

- [#&#8203;18210](https://github.com/withastro/astro/pull/18210) [`62b13ba`](https://github.com/withastro/astro/commit/62b13ba3e0068057a47fbfc2ab8842b263c68f0d) Thanks [@&#8203;edmundhung](https://github.com/edmundhung)! - Allows Astro CLI commands to install tagged package versions

- [#&#8203;18069](https://github.com/withastro/astro/pull/18069) [`d39eb97`](https://github.com/withastro/astro/commit/d39eb97752ea6f5d02c82e6fe35fdbfb8d9f8982) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes a dev server dependency scan failure when an `.astro` file contains a literal `<script` in frontmatter or a template expression

- [#&#8203;18114](https://github.com/withastro/astro/pull/18114) [`c17d920`](https://github.com/withastro/astro/commit/c17d9209bef385ea88b6fee36e91ad4e635f4a86) Thanks [@&#8203;matthewp](https://github.com/matthewp)! - Fixes Astro on StackBlitz and other WebContainer environments

- [#&#8203;18088](https://github.com/withastro/astro/pull/18088) [`cb767f9`](https://github.com/withastro/astro/commit/cb767f974e7ef1fec9b2d496e51b09c985c93947) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes a `MODULE_LEVEL_DIRECTIVE` warning during build caused by a stale `"use astro:head-inject"` directive in content collection propagated asset modules

- [#&#8203;18247](https://github.com/withastro/astro/pull/18247) [`2b3f73d`](https://github.com/withastro/astro/commit/2b3f73db230e3bff28ed9784a3b21257a97611e0) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes actions returning 500 for malformed JSON request bodies and undecodable action names. A `SyntaxError` from invalid JSON now returns 400 (`BAD_REQUEST`), and a `URIError` from a malformed percent-encoded action name now returns 404 (`NOT_FOUND`).

- [`1d9e910`](https://github.com/withastro/astro/commit/1d9e910a0308ef9699694a2871b3d71b6f5c3383) Thanks [@&#8203;matthewp](https://github.com/matthewp)! - Validates the `Host` header against `security.allowedDomains` when using the Node adapter

- [#&#8203;18249](https://github.com/withastro/astro/pull/18249) [`c7799a4`](https://github.com/withastro/astro/commit/c7799a4b21f2f7384cf070765f0912f9ac08848b) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes the `fontsource` font provider to resolve variable fonts when using the "Variable" suffix in the font name (e.g. `"Inter Variable"`)

- [#&#8203;18163](https://github.com/withastro/astro/pull/18163) [`e48da9d`](https://github.com/withastro/astro/commit/e48da9d4f6f293d8708bd8de9ae235429272f556) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes `<video muted>` losing its muted state after a ClientRouter navigation in Chrome

- [#&#8203;18244](https://github.com/withastro/astro/pull/18244) [`f67e7f7`](https://github.com/withastro/astro/commit/f67e7f7fe13e67131bb4e4c538970af60bdbbb94) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes localized error pages such as `src/pages/pt/404.astro` returning a `200` status when rendered through the `pages()` handler from `astro/fetch` or `astro/hono`

- [#&#8203;18242](https://github.com/withastro/astro/pull/18242) [`c5275e3`](https://github.com/withastro/astro/commit/c5275e3d5a688a7d246c9576b594870675b70e37) Thanks [@&#8203;astro-factory](https://github.com/apps/astro-factory)! - Fixes `experimental_AstroContainer` output including dev toolbar `data-astro-source-file` and `data-astro-source-loc` attributes when rendering components under Vitest

- Updated dependencies \[[`6987261`](https://github.com/withastro/astro/commit/69872618b7b7c915b2bd51a4b41e3a3e3116f3bb), [`62b13ba`](https://github.com/withastro/astro/commit/62b13ba3e0068057a47fbfc2ab8842b263c68f0d)]:
  - [@&#8203;astrojs/internal-helpers](https://github.com/astrojs/internal-helpers)@&#8203;0.12.0
  - [@&#8203;astrojs/markdown-satteri](https://github.com/astrojs/markdown-satteri)@&#8203;0.4.3

</details>

<details>
<summary>pnpm/pnpm (pnpm)</summary>

### [`v12.10.1`](https://github.com/pnpm/pnpm/releases/tag/v12.10.1): pnpm 12.10.1

[Compare Source](https://github.com/pnpm/pnpm/compare/v12.10.0...v12.10.1)

This release fixes `pnpm install` failures after an `overrides` change and on a filtered frozen install with `catalogPrune`. It also fixes several bugs in the experimental `nodeLinker.type: loaded`, which now keeps its generated files in `node_modules`.

##### Patch Changes

- With `nodeLinker.type: loaded`, pnpm now writes its generated files to `node_modules`, which projects already ignore in git. The store manifest and loader are `node_modules/.pnpm/.store-manifest.json` and `node_modules/.pnpm/.store-loader.mjs`. Bin shims are in `node_modules/.bin`.

  Earlier versions wrote `.pnpm-store.json` and `.pnpm-store-loader.mjs` to the project root, and a `.pnpm` directory to the root and to each workspace package. Delete them after reinstalling.

- With `nodeLinker.type: loaded`, packages that ship their own `node_modules` directory, such as `npm` with its bundled dependencies, now load from the store. Before, one such package in the install stopped every Node.js process from starting.

- With `nodeLinker.type: loaded`, scripts can now run a Node.js runtime installed through `devEngines.runtime`. Before, every script that called `node` re-ran its own shim until it failed with "Argument list too long".

- With `nodeLinker.type: loaded`, Node.js processes start faster. In a project with 13,000 stored files, the startup overhead per process dropped from 67 ms to 18 ms.

- `pnpm install` no longer fails with `ERR_PNPM_NO_MATCHING_VERSION` after a change to `overrides` when the lockfile resolves an optional peer dependency to an npm alias of another package [#&#8203;16654](https://github.com/pnpm/pnpm/issues/16654).

- A frozen install with `catalogPrune` no longer removes catalog entries that `pnpm-lock.yaml` still records. Before, `pnpm install --frozen-lockfile --filter` failed with `ERR_PNPM_LOCKFILE_CONFIG_MISMATCH` when some workspace projects were missing from disk [#&#8203;16638](https://github.com/pnpm/pnpm/issues/16638).

- `pnpm install --fix-lockfile` no longer removes the `deprecated` and `hasBin` fields from lockfile entries [#&#8203;6600](https://github.com/pnpm/pnpm/issues/6600).

- With `enableGlobalVirtualStore`, an install that updates `node_modules` now repairs a package in the global virtual store that an interrupted install left without some of its dependency links or package files. Before, such an install kept the incomplete package if the project's `node_modules` already recorded it [#&#8203;16642](https://github.com/pnpm/pnpm/issues/16642).

- `pnpm install` now skips the Cargo and Python projects inside a nested directory that has its own `pnpm-workspace.yaml` or `.git` directory, such as a git worktree of the same workspace or a separate clone.

- The `Request took` warning for package metadata now starts timing when pnpm sends the request. Before, it also counted the time the request waited for a free request slot, so large installs printed it for requests the registry answered quickly.

<!-- sponsors -->

#### Platinum Sponsors

<table>
  <tbody>
    <tr>
      <td align="center" valign="middle">
        <a href="https://bit.cloud/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer"><img src="https://pnpm.io/img/users/bit.svg" width="80" alt="Bit"></a>
      </td>
      <td align="center" valign="middle">
        <a href="https://openai.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/openai_dark.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/openai_light.svg" />
            <img src="https://pnpm.io/img/users/openai_dark.svg" width="160" alt="OpenAI" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://notion.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer"><img src="https://pnpm.io/img/users/notion.svg" width="80" alt="Notion"></a>
      </td>
    </tr>
    <tr>
      <td align="center" valign="middle">
        <a href="https://coderabbit.ai/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/coderabbit.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/coderabbit_light.svg" />
            <img src="https://pnpm.io/img/users/coderabbit.svg" width="220" alt="CodeRabbit" />
          </picture>
        </a>
      </td>
    </tr>
  </tbody>
</table>

#### Gold Sponsors

<table>
  <tbody>
    <tr>
      <td align="center" valign="middle">
        <a href="https://sanity.io/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/sanity.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/sanity_light.svg" />
            <img src="https://pnpm.io/img/users/sanity.svg" width="120" alt="Sanity" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://discord.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/discord.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/discord_light.svg" />
            <img src="https://pnpm.io/img/users/discord.svg" width="220" alt="Discord" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://vite.dev/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer"><img src="https://pnpm.io/img/users/vitejs.svg" width="42" alt="Vite"></a>
      </td>
    </tr>
    <tr>
      <td align="center" valign="middle">
        <a href="https://serpapi.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/serpapi_dark.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/serpapi_light.svg" />
            <img src="https://pnpm.io/img/users/serpapi_dark.svg" width="160" alt="SerpApi" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://stackblitz.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/stackblitz.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/stackblitz_light.svg" />
            <img src="https://pnpm.io/img/users/stackblitz.svg" width="190" alt="Stackblitz" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://workleap.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/workleap.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/workleap_light.svg" />
            <img src="https://pnpm.io/img/users/workleap.svg" width="190" alt="Workleap" />
          </picture>
        </a>
      </td>
    </tr>
    <tr>
      <td align="center" valign="middle">
        <a href="https://nx.dev/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/nx.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/nx_light.svg" />
            <img src="https://pnpm.io/img/users/nx.svg" width="50" alt="Nx" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://latitude.so/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer"><img src="https://pnpm.io/img/users/latitude.svg" width="160" alt="Latitude"></a>
      </td>
    </tr>
  </tbody>
</table>

<!-- sponsors end -->

### [`v12.10.0`](https://github.com/pnpm/pnpm/releases/tag/v12.10.0): pnpm 12.10.0

[Compare Source](https://github.com/pnpm/pnpm/compare/v12.9.1...v12.10.0)

This release adds an experimental `loaded` node linker, lets `pnpm-lock.yaml` record resolution settings, and reads cached registry metadata faster. It also carries several security fixes, including one that stops a dependency version from writing files outside the global virtual store.

##### Minor Changes

- Added experimental `nodeLinker: { type: loaded }` installation. Compatible dependencies load directly from the content-addressable store through an automatically registered Node.js loader. `nodeLinker.excluded` selects packages and their dependency trees to install in the global virtual store.

- `lockfile.includeResolutionSettings: true` makes `pnpm-lock.yaml` record `autoDedupe`, `dedupeInjectedDeps`, `dedupePeerDependents` and `linkWorkspacePackages`. Installs then treat a lockfile that records other values as outdated. A lockfile that records `autoDedupe` is reused by later installs on any machine, so `pnpm run` after `pnpm install --frozen-lockfile` no longer starts another install [#&#8203;16583](https://github.com/pnpm/pnpm/issues/16583).

##### Patch Changes

##### Security

- `pnpm install` now prevents dependency versions with path traversal from writing files outside the global virtual store.

- pnpm now verifies locked config dependencies against their registry before installing them. Config dependencies must come from an npm registry. The lockfile can no longer replace the integrity of a config dependency pinned with `version+integrity`.

- Lockfile verification now checks the tarballs inside a `variations` resolution against the registry. A `name@version` lockfile entry with an empty `variations` resolution is now rejected.

- `pnpm audit signatures` now verifies signatures against the integrity recorded in the lockfile. Packages without a recorded integrity cannot pass signature verification.

- `pnpm install` and `pnpm publish` now reject archive metadata larger than 64 MiB before reading it into memory. Publishing a pre-built tarball also rejects manifests and README files larger than 64 MiB.

- Two URL or local path dependencies no longer share a virtual store directory when one URL has `+`, `#`, `:`, or `?` where the other has `/`. Such dependencies, including git dependencies pinned with `#`, now get a hash suffix on their directory name.

- The warning about an ignored project `.npmrc` registry setting no longer prints the username and password of a URL-scoped key such as `//user:[email protected]/${PATH}/:_authToken`.

##### Installing and resolving dependencies

- `pnpm install` now fails with `ERR_PNPM_UNSUPPORTED_PROTOCOL` when a dependency uses a specifier with a protocol pnpm does not support, such as Yarn's `patch:`. On Windows, such a specifier failed with `os error 123`. On other platforms, pnpm linked it to a directory that does not exist. Reading a `package.json` that fails now names the file [#&#8203;16590](https://github.com/pnpm/pnpm/issues/16590).

- `pnpm install` now fails with `ERR_PNPM_PACKAGE_MANIFEST_INVALID_ATTRIBUTE` when a project declares a dependency whose specifier is not a string, such as `"is-positive": 42`. Before, the dependency was silently left out of the lockfile. A `readPackage` hook can still correct the specifier.

- Fixed `pnpm install` failing with `ERR_PNPM_CMD_SHIM_RESOLVE_PATH` when an executable's parent directory contains a dangling symlink.

- `pnpm install --frozen-lockfile` no longer fails with `ERR_PNPM_RESOLUTION_SHAPE_MISMATCH` when a `name@version` lockfile entry has a resolution served by a custom fetcher [pnpm/tasks#108](https://github.com/pnpm/tasks/issues/108).

- `pnpm install --fix-lockfile` repairs a lockfile whose importer references a package that has no snapshot entry, as left by a badly merged lockfile. It failed with `ERR_PNPM_LOCKFILE_MISSING_DEPENDENCY` since 12.8.0 [#&#8203;16618](https://github.com/pnpm/pnpm/issues/16618).

- When a dependency moves an exact dependency of its own to an older version, a peer dependency that pnpm installed automatically now moves with it. Before, `pnpm install` and `pnpm dedupe` kept the newer locked version of the peer, so the lockfile held two copies of it, for example two copies of `vue` [pnpm/tasks#61](https://github.com/pnpm/tasks/issues/61).

- `pnpm dedupe` now reads registry metadata for a dependency pinned to an exact version, as `pnpm install` does. If the registry metadata disagreed with the package's `package.json`, the lockfile it wrote depended on whether `minimumReleaseAge` was set [#&#8203;16615](https://github.com/pnpm/pnpm/issues/16615).

##### Speed and size

- Dependency resolution reads cached registry metadata faster. The metadata cache moved to `<cache-dir>/v12/`, so the first install after upgrading downloads registry metadata again. A damaged cache entry is downloaded again, or reported as an error when `--offline` is set. `pnpm cache prune` also removes the metadata cache that older pnpm versions wrote under `<cache-dir>/v11/` [#&#8203;13512](https://github.com/pnpm/pnpm/pull/13512).

- Package metadata requests no longer wait behind queued tarball downloads when `maxSockets` or a proxy limits the connections to a registry. Large installs resolve faster and print fewer `Request took` warnings.

- Sped up installs in large workspaces on macOS when the dependency links already exist. pnpm now keeps a link that already points at the right package without trying to create it first. Relinking the direct dependencies of 1,000 workspace projects took 45 ms, down from 116 ms [pnpm/tasks#65](https://github.com/pnpm/tasks/issues/65).

- Commands in a project that pins a different pnpm version start about 13 ms faster on macOS. pnpm now runs the pinned version's binary directly, without the shell script in front of it [pnpm/tasks#66](https://github.com/pnpm/tasks/issues/66).

- The pnpm binary is about 0.9 MB smaller, and the arm64 Linux binary is about 1 MB smaller still.

##### Running scripts and commands

- `pnpm run` no longer prints `[ELIFECYCLE] Command failed ...` after Ctrl+C ends the script. pnpm still exits the way the script's shell did: on Windows with the shell's exit code (`cmd` reports `-1073741510`, PowerShell `1`), on Unix by re-raising `SIGINT` [#&#8203;16579](https://github.com/pnpm/pnpm/issues/16579).

- `pnpm run "/<regex>/"` now accepts JavaScript regular expression syntax such as lookahead and lookbehind. A selector like `"/^hello:(?!b).*$/"` failed with `ERR_PNPM_NO_SCRIPT` [#&#8203;16604](https://github.com/pnpm/pnpm/issues/16604).

- `pnpm run` and `pnpm exec` now forward `--config.*` command-line flags to the install started by `verifyDepsBeforeRun` [pnpm/tasks#60](https://github.com/pnpm/tasks/issues/60).

- On Windows, a process started by `pnpm run` or `pnpm exec` can again start a child with `CREATE_BREAKAWAY_FROM_JOB`. That child keeps running after pnpm exits, even if the command fails [#&#8203;16628](https://github.com/pnpm/pnpm/issues/16628).

- Empty `nodeOptions` values from command-line flags and environment variables now override lower-priority settings. Scripts retain `NODE_OPTIONS` from the parent environment or `extraEnv` when `nodeOptions` is empty.

- pnpm now reads the `failIfNoMatch` setting from `pnpm-workspace.yaml`, so a filter that matches no workspace project exits with code 1 when the setting is `true`. The new `--no-fail-if-no-match` flag turns the setting off for one command [#&#8203;16577](https://github.com/pnpm/pnpm/issues/16577).

##### Configuration, setup, and pnpm versions

- `pnpm config get --global` and `pnpm config list --global` now show only the global configuration, also when run inside a project. Settings from the project's `pnpm-workspace.yaml` and `.npmrc` were included before. The same applies to `--location=global` [#&#8203;16598](https://github.com/pnpm/pnpm/issues/16598).

- pnpm now prints config warnings, such as an unset environment variable in `.npmrc`, when loading the config fails.

- pnpm 11 releases older than 11.28.4 can run pnpm 12 again when the `packageManager` field pins it. Since 12.9.0 they failed with `SyntaxError: Invalid or unexpected token` [#&#8203;16594](https://github.com/pnpm/pnpm/issues/16594).

- On Windows, `pnpm self-update` no longer runs the update a second time when it replaces a `pnpm.cmd` linked by pnpm 12.8 or older. cmd.exe read on in the replaced `pnpm.cmd`, printed an error about a command that is not recognized, and ran the new pnpm once more [#&#8203;16573](https://github.com/pnpm/pnpm/issues/16573).

- `pnpm setup` now puts `$PNPM_HOME/bin` first on `PATH` in login shells that inherited it further down, such as the VS Code terminal on macOS. Before, another `node` took precedence over the one installed by `pnpm runtime set node -g`. Run `pnpm setup` again to update the block in your shell config [#&#8203;16635](https://github.com/pnpm/pnpm/issues/16635).

- `pnpm setup` now names the shell config file even if it is already up to date [#&#8203;16608](https://github.com/pnpm/pnpm/issues/16608).

##### Updating, auditing, and publishing

- `pnpm update --latest` now applies the `savePrefix` setting when it rewrites a dependency whose range has no operator of its own, such as `<2.0.0`.

- The interactive `pnpm audit --fix` picker now shows each patched version with the `saveExact` and `savePrefix` style that the override is written with [#&#8203;13209](https://github.com/pnpm/pnpm/issues/13209).

- `pnpm unpublish <pkg>@&#8203;<version>` now deletes the tarball under the registry's path when the registry is served under one, such as Gitea's npm registry. It used to send the delete to the host root and report success without removing the version [#&#8203;16568](https://github.com/pnpm/pnpm/issues/16568). It also no longer mistakes a sibling path such as `/npm-mirror/` for the registry path `/npm/` [pnpm/tasks#94](https://github.com/pnpm/tasks/issues/94).

##### Output and messages

- A warning about a project's `devEngines` or `packageManager` pin is now printed to stderr. A command such as `pnpm cache path` or `pnpm list --json` keeps only its own output on stdout [#&#8203;16584](https://github.com/pnpm/pnpm/issues/16584).

- `pnpm list` now reports the correct package paths when `nodeLinker` is `hoisted` [#&#8203;9593](https://github.com/pnpm/pnpm/issues/9593).

- Resolution errors now name the failing dependency and its parent packages. Fatal errors appear as structured error records with their error codes when using `--reporter=ndjson`.

- The error for an invalid git repository in the lockfile now has the code `ERR_PNPM_INVALID_GIT_REPOSITORY`. Its message now lists every rejected form of the value.

- `pnpm runtime --help` and `pnpm help runtime` now name the `set` subcommand and the runtimes it accepts [#&#8203;16580](https://github.com/pnpm/pnpm/issues/16580).

<!-- sponsors -->

#### Platinum Sponsors

<table>
  <tbody>
    <tr>
      <td align="center" valign="middle">
        <a href="https://bit.cloud/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer"><img src="https://pnpm.io/img/users/bit.svg" width="80" alt="Bit"></a>
      </td>
      <td align="center" valign="middle">
        <a href="https://openai.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/openai_dark.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/openai_light.svg" />
            <img src="https://pnpm.io/img/users/openai_dark.svg" width="160" alt="OpenAI" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://notion.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer"><img src="https://pnpm.io/img/users/notion.svg" width="80" alt="Notion"></a>
      </td>
    </tr>
    <tr>
      <td align="center" valign="middle">
        <a href="https://coderabbit.ai/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/coderabbit.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/coderabbit_light.svg" />
            <img src="https://pnpm.io/img/users/coderabbit.svg" width="220" alt="CodeRabbit" />
          </picture>
        </a>
      </td>
    </tr>
  </tbody>
</table>

#### Gold Sponsors

<table>
  <tbody>
    <tr>
      <td align="center" valign="middle">
        <a href="https://sanity.io/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/sanity.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/sanity_light.svg" />
            <img src="https://pnpm.io/img/users/sanity.svg" width="120" alt="Sanity" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://discord.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/discord.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/discord_light.svg" />
            <img src="https://pnpm.io/img/users/discord.svg" width="220" alt="Discord" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://vite.dev/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer"><img src="https://pnpm.io/img/users/vitejs.svg" width="42" alt="Vite"></a>
      </td>
    </tr>
    <tr>
      <td align="center" valign="middle">
        <a href="https://serpapi.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/serpapi_dark.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/serpapi_light.svg" />
            <img src="https://pnpm.io/img/users/serpapi_dark.svg" width="160" alt="SerpApi" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://stackblitz.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/stackblitz.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/stackblitz_light.svg" />
            <img src="https://pnpm.io/img/users/stackblitz.svg" width="190" alt="Stackblitz" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://workleap.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/workleap.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/workleap_light.svg" />
            <img src="https://pnpm.io/img/users/workleap.svg" width="190" alt="Workleap" />
          </picture>
        </a>
      </td>
    </tr>
    <tr>
      <td align="center" valign="middle">
        <a href="https://nx.dev/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/nx.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/nx_light.svg" />
            <img src="https://pnpm.io/img/users/nx.svg" width="50" alt="Nx" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://latitude.so/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer"><img src="https://pnpm.io/img/users/latitude.svg" width="160" alt="Latitude"></a>
      </td>
    </tr>
  </tbody>
</table>

<!-- sponsors end -->

### [`v12.9.1`](https://github.com/pnpm/pnpm/releases/tag/v12.9.1): pnpm 12.9.1

[Compare Source](https://github.com/pnpm/pnpm/compare/v12.9.0...v12.9.1)

This release moves the WebContainer build into a separate `@pnpm/wasm` package, shrinks the `pnpm` package back to about 4 MB, and fixes `pnpm publish` with provenance from GitLab CI.

##### Patch Changes

- The WebAssembly build for StackBlitz WebContainers now ships as a separate `@pnpm/wasm` package. The `pnpm` and `@pnpm/exe` packages no longer include it, which brings their unpacked size back from about 55 MB to about 4 MB. In a WebContainer, install `@pnpm/wasm` with npm to get the `pnpm` command.

- `pnpm publish` with provenance from GitLab CI is no longer rejected by the npm registry with a 422 error. The provenance statement now includes the GitLab CI variables in `invocation.parameters`, as npm does [#&#8203;16551](https://github.com/pnpm/pnpm/issues/16551).

- `pnpm audit signatures` now uses the TLS settings of the redirect target when a registry redirects its signing-keys request, for example to registry.npmjs.org. A `cafile` scoped to a private registry no longer makes the redirected request fail [#&#8203;16541](https://github.com/pnpm/pnpm/issues/16541).

- Fixed `pnpm install --frozen-lockfile` rejecting an up-to-date lockfile when an injected workspace package uses a catalog entry in `peerDependencies` [#&#8203;16557](https://github.com/pnpm/pnpm/issues/16557).

- The `[<since>]` filter selector works again with Git 2.24 through 2.27 [#&#8203;16561](https://github.com/pnpm/pnpm/issues/16561). With Git older than 2.24, the selector now fails with an error that names the required Git version.

  It also detects changes in projects whose directory names contain non-ASCII characters. Such a change used to be credited to the parent project. `changedFilesIgnorePattern` and `testPattern` now match changed files whose names contain non-ASCII characters.

- The `pnpm` executable is about 10% smaller. On macOS arm64 it went from 45.1 MB to 40.3 MB.

- Sped up trust downgrade checks for packages with long release histories.

- With `optimisticRepeatInstall: false`, `pnpm install` now runs the projects' own lifecycle scripts, such as `prepare`, even when `node_modules` is already up to date [#&#8203;16545](https://github.com/pnpm/pnpm/issues/16545).

- `pnpm self-update` now fails for Homebrew-installed pnpm and prints the `brew upgrade` command for the installed formula, such as `brew upgrade pnpm` or `brew upgrade pnpm@11`. It used to install a second copy of pnpm that the Homebrew one kept shadowing [#&#8203;16547](https://github.com/pnpm/pnpm/issues/16547).

<!-- sponsors -->

#### Platinum Sponsors

<table>
  <tbody>
    <tr>
      <td align="center" valign="middle">
        <a href="https://bit.cloud/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer"><img src="https://pnpm.io/img/users/bit.svg" width="80" alt="Bit"></a>
      </td>
      <td align="center" valign="middle">
        <a href="https://openai.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/openai_dark.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/openai_light.svg" />
            <img src="https://pnpm.io/img/users/openai_dark.svg" width="160" alt="OpenAI" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://notion.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer"><img src="https://pnpm.io/img/users/notion.svg" width="80" alt="Notion"></a>
      </td>
    </tr>
    <tr>
      <td align="center" valign="middle">
        <a href="https://coderabbit.ai/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/coderabbit.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/coderabbit_light.svg" />
            <img src="https://pnpm.io/img/users/coderabbit.svg" width="220" alt="CodeRabbit" />
          </picture>
        </a>
      </td>
    </tr>
  </tbody>
</table>

#### Gold Sponsors

<table>
  <tbody>
    <tr>
      <td align="center" valign="middle">
        <a href="https://sanity.io/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/sanity.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/sanity_light.svg" />
            <img src="https://pnpm.io/img/users/sanity.svg" width="120" alt="Sanity" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://discord.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/discord.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/discord_light.svg" />
            <img src="https://pnpm.io/img/users/discord.svg" width="220" alt="Discord" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://vite.dev/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer"><img src="https://pnpm.io/img/users/vitejs.svg" width="42" alt="Vite"></a>
      </td>
    </tr>
    <tr>
      <td align="center" valign="middle">
        <a href="https://serpapi.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/serpapi_dark.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/serpapi_light.svg" />
            <img src="https://pnpm.io/img/users/serpapi_dark.svg" width="160" alt="SerpApi" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://stackblitz.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/stackblitz.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/stackblitz_light.svg" />
            <img src="https://pnpm.io/img/users/stackblitz.svg" width="190" alt="Stackblitz" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://workleap.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/workleap.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/workleap_light.svg" />
            <img src="https://pnpm.io/img/users/workleap.svg" width="190" alt="Workleap" />
          </picture>
        </a>
      </td>
    </tr>
    <tr>
      <td align="center" valign="middle">
        <a href="https://nx.dev/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/nx.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/nx_light.svg" />
            <img src="https://pnpm.io/img/users/nx.svg" width="50" alt="Nx" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://latitude.so/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer"><img src="https://pnpm.io/img/users/latitude.svg" width="160" alt="Latitude"></a>
      </td>
    </tr>
  </tbody>
</table>

<!-- sponsors end -->

### [`v12.9.0`](https://github.com/pnpm/pnpm/releases/tag/v12.9.0): pnpm 12.9

[Compare Source](https://github.com/pnpm/pnpm/compare/v12.8.2...v12.9.0)

This release runs pnpm in StackBlitz WebContainers, adds a per-registry `networkConcurrency` setting, and records every installed project in the store. It also carries a security fix for `pnpm login`.

##### Minor Changes

- pnpm now automatically uses WebAssembly in StackBlitz WebContainers, including when installation scripts are disabled. Native installations continue to use the native executable when installation scripts are enabled.

- A `registries` entry can now set `networkConcurrency`, the most requests pnpm keeps in flight to that registry's origin. Requests to other registries keep the overall limit. The setting may live in `pnpm-workspace.yaml` or the global `config.yaml`.

  ```yaml
  registries:
    https://npm.corp.example.com/:
      scopes: ["@&#8203;acme"]
      networkConcurrency: 4
  ```

- `pnpm install` now records every project it installs in the store's `projects` directory, as a symlink to the project directory. A `--frozen-store` install without the global virtual store still records nothing. Only projects that used the global virtual store were recorded before [#&#8203;6929](https://github.com/pnpm/pnpm/issues/6929).

##### Patch Changes

- `pnpm login` no longer forwards credentials in its request body to another origin during redirects.

##### Installing packages

- Fixed `pnpm install` failing on Android with `ERR_PNPM_STORE_DIR_ACQUIRE_OPERATION_LOCK` [#&#8203;16508](https://github.com/pnpm/pnpm/issues/16508).

- `pnpm install --frozen-lockfile` again succeeds when a workspace project recorded in `pnpm-lock.yaml` has no directory, such as a project left out of a Docker build context. It still fails if the project's directory exists without a `package.json` [#&#8203;16453](https://github.com/pnpm/pnpm/issues/16453).

- `pnpm install --frozen-lockfile` no longer requires a `pnpm-lock.yaml` in a project that has no dependencies. It also succeeds when `pnpm-lock.yaml` records only the pinned pnpm version, as other commands write it when they run before the first install [#&#8203;16477](https://github.com/pnpm/pnpm/issues/16477).

- Fixed `pnpm install --frozen-lockfile` rejecting a fresh lockfile when an injected workspace dependency has an optional peer supplied by another workspace project [#&#8203;16428](https://github.com/pnpm/pnpm/issues/16428).

- With `nodeLinker: hoisted`, a filtered install now keeps the packages of the workspace projects an earlier install put in `node_modules`. This also covers the install that `pnpm --filter <selector> run` and `pnpm --filter <selector> exec` start before the command. Before, these installs removed every package that only the unselected projects needed [#&#8203;16483](https://github.com/pnpm/pnpm/issues/16483).

- `pnpm install` with `nodeLinker: hoisted` now refreshes directories supplied by custom fetchers when reinstalling. pnpm also keeps the symlinks inside those directories.

- With `enableGlobalVirtualStore` on, scripts can run entry points that a CommonJS require hook loads again, such as `ts-node index.ts`. They failed with `ERR_UNKNOWN_FILE_EXTENSION` on Node.js versions without built-in TypeScript support [#&#8203;16436](https://github.com/pnpm/pnpm/issues/16436).

- pnpm now keeps each project's current lockfile and hidden hoisted dependencies in its own `node_modules/.pnpm` when `virtualStoreDir` points at a shared global virtual store. `--virtual-store-dir` now sets the global virtual store's location too [pnpm/tasks#47](https://github.com/pnpm/tasks/issues/47).

- `pnpm clean` no longer deletes the project when `virtualStoreDir` or `globalVirtualStoreDir` is set to the project directory. It also leaves a directory outside the project alone when the setting reaches it through a symlink. It now removes a global virtual store that `globalVirtualStoreDir` places inside the project, as it does for `virtualStoreDir`.

##### Optional dependencies

- `pnpm install` no longer fails when a dependency of an optional dependency is missing from the registry. Like npm, pnpm now leaves out the nearest optional dependency above it, together with its subtree [#&#8203;16511](https://github.com/pnpm/pnpm/issues/16511).

- When an optional dependency fails to build, pnpm now removes its link from `node_modules`. A repeat `pnpm install` then reports "Already up to date" and no longer reruns the failing build [#&#8203;16468](https://github.com/pnpm/pnpm/issues/16468).

- `pnpm install` now prints a warning with the error when an optional dependency cannot be fetched and is skipped. The skipped package is no longer counted in the `Packages: +N` summary. The `pnpm:skipped-optional-dependency` log reports the skip with the `fetch_failure` reason [#&#8203;16514](https://github.com/pnpm/pnpm/issues/16514).

##### Resolving dependencies

- Fixed `pnpm install` changing an unchanged project's direct dependency to a sibling workspace's pinned version when its dependency tree contains a cycle [#&#8203;16417](https://github.com/pnpm/pnpm/issues/16417).

- With `autoDedupe` enabled, downgrading a dependency in one workspace project now moves the other projects to that version when it satisfies their ranges. This also applies to a filtered `pnpm --filter <project> add` [#&#8203;16432](https://github.com/pnpm/pnpm/issues/16432).

- `pnpm install` and `pnpm dedupe` now move an optional peer to the version already in the dependency graph when no other package provides its locked version anymore. After a bump such as `vue` 3.5.40 to 3.5.43, the lockfile kept a second copy of `@vue/server-renderer` for `@vue/test-utils` [#&#8203;16443](https://github.com/pnpm/pnpm/issues/16443).

- `pnpm dedupe --check` no longer fails right after `pnpm install` when a project's optional peer is satisfied by a package another workspace project installs. `pnpm dedupe` now picks the same versions for that package's dependencies as `pnpm install` [#&#8203;16447](https://github.com/pnpm/pnpm/issues/16447).

- `pnpm install` no longer re-resolves an up-to-date lockfile on every run when a patched package is a peer in a peer cycle [#&#8203;16418](https://github.com/pnpm/pnpm/issues/16418).

- With `autoDedupe` enabled, `pnpm install --lockfile-only` no longer resolves the dependency graph again when nothing changed since an earlier `--lockfile-only` install deduplicated the lockfile. Such an install keeps the lockfile even if versions were published since it was written, or if only a setting such as `resolutionMode` changed. Run `pnpm dedupe` to apply such a change [#&#8203;16458](https://github.com/pnpm/pnpm/issues/16458).

##### Speed and network

- A repeat `pnpm install` in a large workspace reports "Already up to date" faster [#&#8203;16487](https://github.com/pnpm/pnpm/issues/16487).

- Sped up dependency resolution of workspaces with many peer dependencies.

- `pnpm install` sends fewer registry metadata requests when the lockfile already decides which version a range resolves to. This now also covers ranges that several locked versions satisfy when one of them outranks the others, and direct dependencies kept at their locked version. Packages that `minimumReleaseAgeExclude` lists without a version now reuse cached registry metadata the same way they do when `minimumReleaseAge` is not set [#&#8203;16458](https://github.com/pnpm/pnpm/issues/16458).

- pnpm no longer downloads every packument again on each install from a registry whose metadata responses forbid caching, such as `Cache-Control: no-store`. pnpm revalidates the cached metadata with a conditional request, so a registry that supports conditional requests answers with a 304 when the package has not changed [#&#8203;16528](https://github.com/pnpm/pnpm/issues/16528).

- Cached metadata for a package published within `minimumReleaseAge` is now revalidated with its ETag, so the npm registry can answer `304 Not Modified`. Before, the next install that checked the cache downloaded the whole document again [#&#8203;16506](https://github.com/pnpm/pnpm/issues/16506).

- A fetch timeout while other downloads from the same host are still running now lowers concurrency for that host to one connection. Retries of that request, and later downloads from that host, use the lower concurrency. Other hosts keep the configured concurrency [#&#8203;12791](https://github.com/pnpm/pnpm/issues/12791).

- Sped up `pnpm install --offline` when the version a range picks is not in the store. While it looks for a version the store holds, pnpm now reads only the versions the range admits [#&#8203;16495](https://github.com/pnpm/pnpm/issues/16495).

- `pnpm install --offline` now reuses config dependency tarballs that are already present in the store [pnpm/tasks#46](https://github.com/pnpm/tasks/issues/46).

##### Running scripts

- `pnpm -s <script>` runs the script again, with `-s` meaning `--sequential` as it does for `pnpm run -s <script>`. pnpm rejected it with "unexpected argument '-s' found" [#&#8203;16446](https://github.com/pnpm/pnpm/issues/16446).

- `pnpm run` and `pnpm exec` now warn and run the command when the install that `verifyDepsBeforeRun` starts fails. This lets scripts run in sandboxes where pnpm cannot install, such as containers with a read-only store or no network [#&#8203;15173](https://github.com/pnpm/pnpm/issues/15173).

- A filtered `pnpm run` or `pnpm exec` now finds dependencies out of date when a workspace dependency of a selected project has no `node_modules` directory, as after a filtered install. With `verifyDepsBeforeRun: install`, pnpm installs that dependency before running the command [pnpm/tasks#45](https://github.com/pnpm/tasks/issues/45).

- Scripts run without a terminal no longer start a second `sh` each. One watchdog per pnpm command now ends every script's process group if pnpm is killed, so `pnpm -r run` across many projects starts half as many processes [#&#8203;16489](https://github.com/pnpm/pnpm/issues/16489).

- `Terminate batch job (Y/N)?` no longer appears after pressing Ctrl+C in a script started with `pnpm` from PowerShell or cmd on Windows [#&#8203;16502](https://github.com/pnpm/pnpm/issues/16502).

- `pnpm rebuild` and `pnpm approve-builds` refresh command launchers when a build changes a command's interpreter or replaces it with a native executable. Dependent packages' build scripts use the refreshed launchers.

- When `pnpm run <script>` or `pnpm <script>` finds nothing to run and `--filter` follows the script name, the error now suggests putting the filter option before the script name [#&#8203;4655](https://github.com/pnpm/pnpm/issues/4655).

- Package-name filters now support `?` to match one character [#&#8203;2817](https://github.com/pnpm/pnpm/issues/2817).

##### The pinned pnpm and `pnpm self-update`

- pnpm no longer downloads the project's pinned pnpm version again on every command when `nodeVersion` in `pnpm-workspace.yaml` names a different Node.js major than the `node` on `PATH`. Before, each of those commands took about a second longer and failed without network access [#&#8203;16497](https://github.com/pnpm/pnpm/issues/16497).

- Several `pnpm` commands started at once in a project that pins `packageManager` no longer fail with `The process cannot access the file because it is being used by another process` on Windows while the pinned pnpm is being installed.

- pnpm can now switch to a `packageManager` version below 11 on x64 musl Linux, such as Alpine [#&#8203;16467](https://github.com/pnpm/pnpm/issues/16467).

- A `devEngines.packageManager` range no longer makes pnpm replace the version recorded in `pnpm-lock.yaml` with the running pnpm while the recorded version still satisfies the range. When pnpm does record a version, it records the running pnpm only if it meets `minimumReleaseAge`. Otherwise it records the newest version in the range that meets it, or the running pnpm if none does [#&#8203;16431](https://github.com/pnpm/pnpm/issues/16431).

- On Windows, `pnpm self-update` now replaces a `pnpm.exe` left in `PNPM_HOME` or in `PNPM_HOME\bin`. Windows ran that executable in place of the updated `pnpm.cmd` shim, so `pnpm --version` kept printing the old version after a successful update. If the executable was in `PNPM_HOME`, `self-update` now asks you to run `pnpm setup` [#&#8203;9094](https://github.com/pnpm/pnpm/issues/9094).

- `pnpm self-update` now checks that a version installed as the JavaScript `pnpm` can start before making it the global `pnpm`. If Node.js is missing, the update fails and the current `pnpm` stays in place.

##### Other commands

- `pnpm deploy` now finds patches and local dependencies when the target directory sits under a symlink, such as `/tmp` on macOS. It failed with `ERR_PNPM_PATCH_NOT_FOUND` [#&#8203;16470](https://github.com/pnpm/pnpm/issues/16470).

- `pnpm deploy --legacy` now resolves the deployed project's relative `file:`, `link:`, and path dependencies from the project's own directory [#&#8203;16475](https://github.com/pnpm/pnpm/issues/16475).

- `pnpm update --global` now removes hard-linked executables from `PNPM_HOME` when migrating packages from the old global layout [#&#8203;16420](https://github.com/pnpm/pnpm/issues/16420).

- `pnpm store prune` no longer fails on store index entries that pnpm 11 wrote for git-hosted packages without a `package.json`. Entries that still cannot be read are kept and counted in the prune summary.

- `pnpm store prune` now aborts when an error other than a missing directory occurs while scanning project directories in the mark phase.

- `pnpm config get` and `pnpm config list` now report a setting given on the command line with `--config.<name>=<value>`. Before, a value such as `--config.node-linker=hoisted` reached the install but was absent from the reported configuration [#&#8203;16276](https://github.com/pnpm/pnpm/issues/16276).

- `pnpm -r pkg get` now reports every selected project when several share a package name. Projects with the same name are keyed by their directory relative to the workspace root. Before, only one of them appeared in the output.

- The install summary shows a `link:` dependency as `+ name <- path`, and the Node.js API's `hideLinkedPkgsDiff` reporter option leaves matching linked dependencies out of the summary.

- The `--force` help text of `pnpm install` and `pnpm add` now says that `--force` keeps skipping optional dependencies built for other platforms. It points to `forceIgnoresPlatform` and the `--os`, `--cpu`, and `--libc` options for installing them [#&#8203;16435](https://github.com/pnpm/pnpm/issues/16435).

- The `homepage` field of the published `pnpm` package points to <https://pnpm.io> again.

<!-- sponsors -->

#### Platinum Sponsors

<table>
  <tbody>
    <tr>
      <td align="center" valign="middle">
        <a href="https://bit.cloud/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer"><img src="https://pnpm.io/img/users/bit.svg" width="80" alt="Bit"></a>
      </td>
      <td align="center" valign="middle">
        <a href="https://openai.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/openai_dark.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/openai_light.svg" />
            <img src="https://pnpm.io/img/users/openai_dark.svg" width="160" alt="OpenAI" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://notion.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer"><img src="https://pnpm.io/img/users/notion.svg" width="80" alt="Notion"></a>
      </td>
    </tr>
    <tr>
      <td align="center" valign="middle">
        <a href="https://coderabbit.ai/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/coderabbit.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/coderabbit_light.svg" />
            <img src="https://pnpm.io/img/users/coderabbit.svg" width="220" alt="CodeRabbit" />
          </picture>
        </a>
      </td>
    </tr>
  </tbody>
</table>

#### Gold Sponsors

<table>
  <tbody>
    <tr>
      <td align="center" valign="middle">
        <a href="https://sanity.io/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/sanity.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/sanity_light.svg" />
            <img src="https://pnpm.io/img/users/sanity.svg" width="120" alt="Sanity" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://discord.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/discord.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/discord_light.svg" />
            <img src="https://pnpm.io/img/users/discord.svg" width="220" alt="Discord" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://vite.dev/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer"><img src="https://pnpm.io/img/users/vitejs.svg" width="42" alt="Vite"></a>
      </td>
    </tr>
    <tr>
      <td align="center" valign="middle">
        <a href="https://serpapi.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/serpapi_dark.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/serpapi_light.svg" />
            <img src="https://pnpm.io/img/users/serpapi_dark.svg" width="160" alt="SerpApi" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://stackblitz.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/stackblitz.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/stackblitz_light.svg" />
            <img src="https://pnpm.io/img/users/stackblitz.svg" width="190" alt="Stackblitz" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://workleap.com/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/workleap.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/workleap_light.svg" />
            <img src="https://pnpm.io/img/users/workleap.svg" width="190" alt="Workleap" />
          </picture>
        </a>
      </td>
    </tr>
    <tr>
      <td align="center" valign="middle">
        <a href="https://nx.dev/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer">
          <picture>
            <source media="(prefers-color-scheme: light)" srcset="https://pnpm.io/img/users/nx.svg" />
            <source media="(prefers-color-scheme: dark)" srcset="https://pnpm.io/img/users/nx_light.svg" />
            <img src="https://pnpm.io/img/users/nx.svg" width="50" alt="Nx" />
          </picture>
        </a>
      </td>
      <td align="center" valign="middle">
        <a href="https://latitude.so/?utm_source=pnpm&utm_medium=release_notes" target="_blank" rel="noopener noreferrer"><img src="https://pnpm.io/img/users/latitude.svg" width="160" alt="Latitude"></a>
      </td>
    </tr>
  </tbody>
</table>

<!-- sponsors end -->

</details>

---

### Configuration

📅 **Schedule**: (UTC)

- Branch creation
  - Between 12:00 AM and 03:59 AM, only on Monday (`* 0-3 * * 1`)
- Automerge
  - At any time (no schedule defined)

🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied.

♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox.

👻 **Immortal**: This PR will be recreated if closed unmerged. Get [config help](https://github.com/renovatebot/renovate/discussions) if that's undesired.

---

 - [ ] <!-- rebase-check -->If you want to rebase/retry this PR, check this box

---

This PR has been generated by [Mend Renovate](https://github.com/renovatebot/renovate).
<!--renovate-debug:eyJjcmVhdGVkSW5WZXIiOiI0My4xOTEuMiIsInVwZGF0ZWRJblZlciI6IjQzLjE5MS4yIiwidGFyZ2V0QnJhbmNoIjoibWFpbiIsImxhYmVscyI6W119-->

<!-- cloudflare-preview --> Preview: https://pr-585.docs-gitea-com.pages.dev

Reviewed-on: https://gitea.com/gitea/docs/pulls/585
Reviewed-by: Lunny Xiao <[email protected]>
Co-authored-by: Renovate Bot <[email protected]>
2026-10-12 16:24:14 +00:00
Gitea Bot adaae2f859 Update the runner reference pages (#586)
Automated update of the generated runner reference pages from gitea/runner (main for the develop docs, the newest stable tag for every documented series), opened by the "update runner reference" scheduled workflow.

<!-- cloudflare-preview --> Preview: https://pr-586.docs-gitea-com.pages.dev

Reviewed-on: https://gitea.com/gitea/docs/pulls/586
Reviewed-by: Lunny Xiao <[email protected]>
Co-authored-by: Gitea Bot <[email protected]>
2026-10-12 16:04:09 +00:00
silverwind 424c481e19 docs: drop the gc.reflogExpire default (#584)
Gitea no longer sets `gc.reflogExpire`, leaving reflog expiry to git's defaults, see https://github.com/go-gitea/gitea/pull/39703, backported in https://github.com/go-gitea/gitea/pull/39711.

Reviewed-on: https://gitea.com/gitea/docs/pulls/584
Reviewed-by: Lunny Xiao <[email protected]>
Co-authored-by: silverwind <[email protected]>
2026-10-10 16:56:06 +00:00
silverwind ad95b7776c docs: update GO_GET_CLONE_URL_PROTOCOL default (#580)
Copy the new `app.example.ini` wording from https://github.com/go-gitea/gitea/pull/39674, backported in https://github.com/go-gitea/gitea/pull/39676. `GO_GET_CLONE_URL_PROTOCOL` now defaults to ssh when `DISABLE_HTTP_GIT` is enabled.

Reviewed-on: https://gitea.com/gitea/docs/pulls/580
Reviewed-by: wxiaoguang <[email protected]>
Co-authored-by: silverwind <[email protected]>
2026-10-08 13:28:26 +00:00
Lunny Xiao f940b0bc9e ci: generate the v28 awesome page and explain skipped previews (#579)
The v28 release (#564) added the `prepare-awesome-v%` Makefile rule, but the checks and publish workflows still only prepare awesome.md up to 1.27, so version-28/awesome.md is not generated in CI. Both workflows now call `prepare-awesome-v28`.

The preview step is skipped when Cloudflare secrets are unavailable, which is the case for pull requests from forks (#557 and #565 have no preview line, while same-repo PRs like #533 and #563 do). The skip is now a visible notice. Previewing fork PRs would need a separate trusted workflow and is not part of this change.

Reviewed-on: https://gitea.com/gitea/docs/pulls/579
Reviewed-by: bircni <[email protected]>
Co-authored-by: Lunny Xiao <[email protected]>
2026-10-07 04:29:39 +00:00
1780 changed files with 12375 additions and 8868 deletions

No files matched your search

+5 -5
View File
@@ -8,7 +8,7 @@ on:
jobs: jobs:
build-docs: build-docs:
runs-on: ubuntu-24.04 runs-on: ubuntu-26.04
env: env:
NODE_OPTIONS: --max-old-space-size=8192 NODE_OPTIONS: --max-old-space-size=8192
# search only appears once the credentials are set, the build falls back # search only appears once the credentials are set, the build falls back
@@ -18,14 +18,14 @@ jobs:
PUBLIC_DOCSEARCH_INDEX_NAME: ${{ secrets.DOCSEARCH_INDEX_NAME }} PUBLIC_DOCSEARCH_INDEX_NAME: ${{ secrets.DOCSEARCH_INDEX_NAME }}
steps: steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7 - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
- uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6 - uses: pnpm/action-setup@73e46992e05b19abd31f2f3c20e0e7370d762115 # v6
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7 - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7
with: with:
node-version: 24 node-version: 26
cache: pnpm cache: pnpm
- name: prepare awesome list - name: prepare awesome list
run: | run: |
make prepare-awesome-latest prepare-awesome\#27 prepare-awesome\#26 prepare-awesome\#25 prepare-awesome\#24 prepare-awesome\#23 prepare-awesome\#22 make prepare-awesome-latest prepare-awesome\#27 prepare-awesome\#26 prepare-awesome\#25 prepare-awesome\#24 prepare-awesome\#23 prepare-awesome\#22 prepare-awesome-v28
- name: Install dependencies - name: Install dependencies
run: pnpm install --frozen-lockfile run: pnpm install --frozen-lockfile
+5 -5
View File
@@ -15,14 +15,14 @@ jobs:
NODE_OPTIONS: --max-old-space-size=8192 NODE_OPTIONS: --max-old-space-size=8192
steps: steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7 - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
- uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6 - uses: pnpm/action-setup@73e46992e05b19abd31f2f3c20e0e7370d762115 # v6
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7 - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7
with: with:
node-version: 24 node-version: 26
cache: pnpm cache: pnpm
- name: prepare awesome list - name: prepare awesome list
run: | run: |
make prepare-awesome-latest prepare-awesome\#27 prepare-awesome\#26 prepare-awesome\#25 prepare-awesome\#24 prepare-awesome\#23 prepare-awesome\#22 make prepare-awesome-latest prepare-awesome\#27 prepare-awesome\#26 prepare-awesome\#25 prepare-awesome\#24 prepare-awesome\#23 prepare-awesome\#22 prepare-awesome-v28
- name: install dependencies - name: install dependencies
run: pnpm install --frozen-lockfile run: pnpm install --frozen-lockfile
@@ -45,7 +45,7 @@ jobs:
# pull requests from forks do not get the secrets, the build above is # pull requests from forks do not get the secrets, the build above is
# then the only check and the preview is silently skipped # then the only check and the preview is silently skipped
if [ -z "${CLOUDFLARE_API_TOKEN:-}" ] || [ -z "${CLOUDFLARE_ACCOUNT_ID:-}" ]; then if [ -z "${CLOUDFLARE_API_TOKEN:-}" ] || [ -z "${CLOUDFLARE_ACCOUNT_ID:-}" ]; then
echo "no Cloudflare credentials available, skipping the preview deployment" echo "::notice::no Cloudflare credentials available (pull request from a fork?), skipping the preview deployment"
exit 0 exit 0
fi fi
-1
View File
@@ -6,7 +6,6 @@ sites/*/dist
sites/*/.astro sites/*/.astro
sites/*/.cache sites/*/.cache
build/ build/
.docusaurus/
# Misc # Misc
.DS_Store .DS_Store
+1 -1
View File
@@ -92,7 +92,7 @@ update-runner-docs:
update-runner-docs-released: update-runner-docs-released:
./update_runner_docs.sh --released ./update_runner_docs.sh --released
# freezes the current docs or runner tree as a new version, see # freezes the current docs, runner or cli tree as a new version, see
# scripts/cut-version.mjs # scripts/cut-version.mjs
.PHONY: cut-version .PHONY: cut-version
cut-version: cut-version:
+19 -6
View File
@@ -3,13 +3,14 @@
The sources of [docs.gitea.com](https://docs.gitea.com), built with The sources of [docs.gitea.com](https://docs.gitea.com), built with
[Astro](https://astro.build) and [Starlight](https://starlight.astro.build). [Astro](https://astro.build) and [Starlight](https://starlight.astro.build).
The site covers three products, all served from this repository: The site covers four products, all served from this repository:
| Product | Content | Versions | Languages | | Product | Content | Versions | Languages |
| --- | --- | --- | --- | | --- | --- | --- | --- |
| Docs | `docs/`, `versioned_docs/`, `i18n/` | next, 28, 1.27 … 1.22 | English, 简体中文, 繁體中文 | | Docs | `docs/`, `versioned_docs/`, `i18n/` | next, 28, 1.27 … 1.22 | English, 简体中文, 繁體中文 |
| API | `static/swagger-*.json`, `static/openapi3-*.json` | next, 28, 1.27 … 1.22 | English | | API | `static/swagger-*.json`, `static/openapi3-*.json` | next, 28, 1.27 … 1.22 | English |
| Runner | `runner-docs/`, `runner-docs_versioned_docs/` | develop, 3 … 0 | English | | Runner | `runner-docs/`, `runner-docs_versioned_docs/` | develop, 5 … 0 | English |
| CLI | `cli-docs/`, `cli-docs_versioned_docs/` | develop | English |
The enterprise documentation is built and deployed from its own repository and The enterprise documentation is built and deployed from its own repository and
reached through `/enterprise/`, which a Cloudflare worker maintained elsewhere reached through `/enterprise/`, which a Cloudflare worker maintained elsewhere
@@ -52,7 +53,8 @@ group from the `_category_.json` of its directory.
```shell ```shell
make cut-version PRODUCT=docs VERSION=1.28 make cut-version PRODUCT=docs VERSION=1.28
make cut-version PRODUCT=runner VERSION=4 make cut-version PRODUCT=runner VERSION=6
make cut-version PRODUCT=cli VERSION=0.1
``` ```
This freezes the current tree, its translations and its sidebar. The label of This freezes the current tree, its translations and its sidebar. The label of
@@ -88,8 +90,8 @@ documented.
| Version | Content | URL | | Version | Content | URL |
| --- | --- | --- | | --- | --- | --- |
| develop | `runner-docs/` | `/runner/develop/` | | develop | `runner-docs/` | `/runner/develop/` |
| current series | `runner-docs_versioned_docs/version-3/` | `/runner/` | | current series | `runner-docs_versioned_docs/version-5/` | `/runner/` |
| older series | `runner-docs_versioned_docs/version-2/` | `/runner/2/` | | older series | `runner-docs_versioned_docs/version-4/` | `/runner/4/` |
A version directory covers a whole release series (`version-3` documents every A version directory covers a whole release series (`version-3` documents every
`3.x` release), so a patch release only needs a content update, not a new `3.x` release), so a patch release only needs a content update, not a new
@@ -101,7 +103,8 @@ Its sidebar is written by hand: `runner-sidebars.js` for develop, and
version. version.
The pages under `reference/` are generated from the runner sources — the command The pages under `reference/` are generated from the runner sources — the command
line reference from `--help`, the example configuration from `generate-config`: line reference from `--help`, the example configuration from `config generate`
(`generate-config` before 3.1):
```shell ```shell
make update-runner-docs # develop docs, from the main branch of gitea/runner make update-runner-docs # develop docs, from the main branch of gitea/runner
@@ -114,6 +117,16 @@ workflow runs weekly and opens a pull request whenever the runner's CLI or
example configuration changed. Generating them needs Go, since the script builds example configuration changed. Generating them needs Go, since the script builds
the runner binary. the runner binary.
## CLI docs
The documentation of `gt`, the Gitea CLI from
[gitea/cli](https://gitea.com/gitea/cli), is laid out like the runner docs, with
its sidebar in `cli-sidebars.js`. No series is documented yet, so `cli-docs/` is
served at `/cli/`. Once a release exists, cut its series and list it in
`cliSeries` in `packages/content-loader/src/products.ts`, which moves the develop
docs to `/cli/develop/`. The guides leave the flags of each command to
`gt <command> --help`.
## Deployment ## Deployment
`main` is built and published by the `Build and Publish Docs site` workflow, to `main` is built and published by the `Build and Publish Docs site` workflow, to
+55
View File
@@ -0,0 +1,55 @@
---
sidebar_position: 3
---
# Logging in
On a terminal, `gt auth login` asks for the instance and how to log in. gt never asks for
your password.
## OAuth in a browser
```bash
gt auth login --host https://gitea.example.com --oauth
```
gt opens the instance's authorization page, so single sign-on and two-factor
authentication work as on the web. The browser has to run on the same machine as gt.
`--scopes` limits the token to fewer [scopes](/development/oauth2-provider#scopes); gt
refreshes OAuth tokens on its own.
## Access token
Create a token under **Settings > Applications** on the instance and pass it on stdin:
```bash
gt auth login --host https://gitea.example.com --with-token < token.txt
```
The token needs `read:user`, and the scopes of what you do with gt, such as
`write:repository` and `write:issue` for working on pull requests.
## SSH key
gt can sign its requests with an SSH key registered for your account instead of using a
token:
```bash
gt auth login --host https://gitea.example.com --ssh-key ~/.ssh/id_ed25519
```
## Accounts
Tokens go to the system keyring, or with `--credential-store file` to gt's configuration
directory on machines without one. Run `gt auth login` once per instance and account.
gt picks the instance from the repository's remote or `--host`, and the account with
`gt auth switch` or `--user`. `gt auth status` lists your accounts and `gt auth logout`
removes one.
For instances behind an access proxy, `--header` and `--client-cert` add headers and a
client certificate.
## Git over HTTPS
`gt auth setup-git` lets `git push` and `git fetch` over HTTPS use gt's login. gt's own
clone and checkout commands need no setup.
+40
View File
@@ -0,0 +1,40 @@
---
sidebar_position: 4
---
# Using gt in CI
Give gt a token and an instance through the environment, and turn prompts off:
| Variable | Description |
| --- | --- |
| `GITEA_TOKEN` | Access token; gt never stores it |
| `GITEA_CLI_HOST` or `GITEA_INSTANCE_URL` | URL of the instance |
| `GITEA_CLI_REPO` | Repository, like `--repo` |
`--no-input` makes a command fail instead of prompting, and `--yes` confirms changes in
advance.
## Gitea Actions
Gitea does not allow secret names that start with `GITEA_`, so store the token as, for
example, `GT_TOKEN`:
```yaml
on:
push:
branches: [main]
jobs:
staging:
runs-on: ubuntu-latest
env:
GITEA_TOKEN: ${{ secrets.GT_TOKEN }}
GITEA_CLI_HOST: ${{ gitea.server_url }}
GITEA_CLI_REPO: ${{ gitea.repository }}
steps:
- run: curl -fsSL https://gitea.com/gitea/cli/raw/branch/main/scripts/install.sh | sh
- run: gt workflow run deploy.yml --ref main --field env=staging --no-input
```
`gt run watch` and `gt pr checks --watch` wait for runs and checks and fail when one fails.
+38
View File
@@ -0,0 +1,38 @@
---
sidebar_position: 1
slug: /
---
# Gitea CLI
[gt](https://gitea.com/gitea/cli) is the official command line client for Gitea. It works
with repositories, issues, pull requests, releases, Actions and the other resources of a
Gitea instance, from a terminal or a script.
:::info Development version
These pages describe builds from the `main` branch, published as `nightly` binaries and images.
:::
gt needs Gitea 28 or later, and Git for the commands that clone, check out or push.
## Getting started
1. [Install gt](installation.md).
2. [Log in](authentication.md):
```bash
gt auth login
```
3. Run commands in a clone of a repository on that instance, or select one with `--repo`:
```bash
gt issue list --label bug
gt pr checkout 13
gt issue view 42 --repo gitea.com/gitea/cli
```
`gt doctor` checks your setup and suggests a fix for each problem it finds.
`gt <command> --help` lists the flags of a command, and `gt help environment` the global
flags and environment variables.
+37
View File
@@ -0,0 +1,37 @@
---
sidebar_position: 2
---
# Installation
gt is a single binary for Linux, macOS, Windows and FreeBSD.
## Install script
The install script downloads gt from [dl.gitea.com](https://dl.gitea.com/gitea-cli/),
verifies its checksum and installs it.
```bash
# Linux, macOS, FreeBSD
curl -fsSL https://gitea.com/gitea/cli/raw/branch/main/scripts/install.sh | sh
```
```powershell
# Windows
irm https://gitea.com/gitea/cli/raw/branch/main/scripts/install.ps1 | iex
```
Set `GITEA_CLI_VERSION` to install a specific version, or `nightly` for the latest build
of `main`.
## Other ways
- **Binaries:** download them from [dl.gitea.com/gitea-cli](https://dl.gitea.com/gitea-cli/).
- **Docker:** the [`gitea/gitea-cli`](https://hub.docker.com/r/gitea/gitea-cli) image runs
`gt` as its entry point.
- **Go:** `go install gitea.dev/cli/cmd/gt@latest`
## Shell completion and man pages
`gt completion <shell>` prints the completion script for bash, zsh, fish or PowerShell;
`gt completion <shell> --help` shows how to load it. `gt man` prints the manual.
+22
View File
@@ -0,0 +1,22 @@
---
sidebar_position: 5
---
# Output and scripting
Scripts should read JSON: the text output is meant for people and may change.
```bash
gt pr view 123 --json number,title,state
gt issue list --json number,title --jq '.[] | "\(.number)\t\(.title)"'
```
`--json` prints all fields or the ones you list; the **JSON FIELDS** section of a command's
`--help` names them. `--jq` filters the result without needing jq installed. Piped lists
print as tab-separated values.
gt exits with 0 on success, 1 when a command fails, 2 on a usage error and 4 when
authentication is missing or rejected; `gt help exit-codes` lists all codes.
`gt api` calls any API endpoint with gt's login, and `gt alias set` defines shortcuts for
commands you use often.
+1
View File
@@ -0,0 +1 @@
[]
+16
View File
@@ -0,0 +1,16 @@
// Sidebar of the gt (Gitea CLI) documentation (develop version).
// Released versions carry their own copy in
// cli-docs_versioned_sidebars/version-<version>-sidebars.json.
module.exports = {
cli: [
{
type: 'doc',
id: 'index',
label: 'What is gt?',
},
'installation',
'authentication',
'ci',
'scripting',
],
};
+2 -2
View File
@@ -2,8 +2,8 @@
# is copied into the build output by the publish workflow, so that it is not # is copied into the build output by the publish workflow, so that it is not
# uploaded to S3/CloudFront where it would be publicly readable at /_headers. # uploaded to S3/CloudFront where it would be publicly readable at /_headers.
# #
# Unlike the docusaurus build, astro emits a single content hashed asset # The build emits a single content hashed asset directory shared by every
# directory shared by every language, so no per locale rules are needed. # language, so no per locale rules are needed.
# Content hashed build output (js, css, fonts). The file name changes with the # Content hashed build output (js, css, fonts). The file name changes with the
# content, so these can be cached forever. # content, so these can be cached forever.
+4 -2
View File
@@ -1,11 +1,13 @@
# Redirects for legacy URLs and routes the site no longer serves directly. # Redirects for legacy URLs and routes the site no longer serves directly.
# The api reference and the runner docs are separate products, published in # The api reference, the runner and the cli docs are separate products,
# english only. Docusaurus served an empty localized copy of them. # published in english only, so they have no localized copy.
/zh-cn/api/* /api/:splat 301 /zh-cn/api/* /api/:splat 301
/zh-tw/api/* /api/:splat 301 /zh-tw/api/* /api/:splat 301
/zh-cn/runner/* /runner/:splat 301 /zh-cn/runner/* /runner/:splat 301
/zh-tw/runner/* /runner/:splat 301 /zh-tw/runner/* /runner/:splat 301
/zh-cn/cli/* /cli/:splat 301
/zh-tw/cli/* /cli/:splat 301
# The version served at the root of a product is also reachable under its # The version served at the root of a product is also reachable under its
# number, which is what the release notes and old links use. # number, which is what the release notes and old links use.
+3 -1
View File
@@ -7,6 +7,7 @@
"https://docs.gitea.com/zh-cn/", "https://docs.gitea.com/zh-cn/",
"https://docs.gitea.com/zh-tw/", "https://docs.gitea.com/zh-tw/",
"https://docs.gitea.com/runner/", "https://docs.gitea.com/runner/",
"https://docs.gitea.com/cli/",
"https://docs.gitea.com/api/", "https://docs.gitea.com/api/",
"https://docs.gitea.com/enterprise/" "https://docs.gitea.com/enterprise/"
], ],
@@ -15,7 +16,8 @@
"https://docs.gitea.com/1.2*/**", "https://docs.gitea.com/1.2*/**",
"https://docs.gitea.com/*/1.2*/**", "https://docs.gitea.com/*/1.2*/**",
"https://docs.gitea.com/api/1.2*/**", "https://docs.gitea.com/api/1.2*/**",
"https://docs.gitea.com/runner/[0-9]/**" "https://docs.gitea.com/runner/[0-9]/**",
"https://docs.gitea.com/cli/[0-9]*/**"
], ],
"selectors": { "selectors": {
"lvl0": { "selector": "//nav[contains(@aria-labelledby,'starlight__sidebar')]//a[@aria-current='page']/ancestor::details//summary//span", "type": "xpath", "global": true, "default_value": "Documentation" }, "lvl0": { "selector": "//nav[contains(@aria-labelledby,'starlight__sidebar')]//a[@aria-current='page']/ancestor::details//summary//span", "type": "xpath", "global": true, "default_value": "Documentation" },
+5 -5
View File
@@ -94,16 +94,16 @@ Most web and API requests pick up the signed-in user automatically.
Other entry points record a system actor: Other entry points record a system actor:
- `(gitea-cli)` for `gitea admin` commands and the `system:startup` and - `gitea:cli` for `gitea admin` commands and the `system:startup` and
`system:shutdown` events `system:shutdown` events
- `(gitea-auth-source)` for authentication-source syncs and for users an - `gitea:auth-source` for authentication-source syncs and for users an
authentication source creates or updates at sign-in authentication source creates or updates at sign-in
- `gitea-actions` for Gitea Actions tasks - `gitea-actions` for Gitea Actions tasks
- `(deploy-key)` for pushes with a deploy key - `gitea:deploy-key` for pushes with a deploy key
- `(Cron)` for scheduled cron tasks - `(Cron)` for scheduled cron tasks
- `Unknown` when no actor can be resolved - `Unknown` when no actor can be resolved
Events of the `(gitea-cli)` actor use origin `cli`. Cron tasks, git hooks and Events of the `gitea:cli` actor use origin `cli`. Cron tasks, git hooks and
other background work use origin `system`. other background work use origin `system`.
## What is recorded ## What is recorded
@@ -112,7 +112,7 @@ Events cover security-relevant changes, grouped by action family:
- **User**: create and delete, admin, restricted and active status, name, - **User**: create and delete, admin, restricted and active status, name,
password and password reset requests, visibility, emails, authentication password and password reset requests, visibility, emails, authentication
source, 2FA, WebAuthn, OpenID, external logins, access tokens, OAuth2 source, 2FA, WebAuthn, external logins, access tokens, OAuth2
applications and grants, SSH/GPG/principal keys, secrets, webhooks, applications and grants, SSH/GPG/principal keys, secrets, webhooks,
impersonation, failed two-factor authentication impersonation, failed two-factor authentication
- **Organization**: create and delete, name, visibility, members, teams, - **Organization**: create and delete, name, visibility, members, teams,
+10 -10
View File
@@ -18,12 +18,13 @@ Both the LDAP via BindDN and the simple auth LDAP share the following fields:
- Host **(required)** - Host **(required)**
- The address where the LDAP server can be reached. - Comma-separated LDAP servers. Each is a host using the Port and Security Protocol fields, or an `ldap://`, `ldaps://` or `ldap+starttls://` URL with an optional port. `ldap://` requires the Unencrypted Security Protocol, the other URLs require an encrypted one.
- Example: `mydomain.com` - The next server is tried when the previous one fails or takes over 250 ms to connect. Bind and search failures do not move on to it.
- Example: `ldap1.mydomain.com, ldaps://ldap2.mydomain.com:636`
- Port **(required)** - Port **(required)**
- The port to use when connecting to the server. - The port to use when connecting to hosts given without a URL.
- Example: `389` for LDAP or `636` for LDAP SSL - Example: `389` for LDAP or `636` for LDAP SSL
- Enable TLS Encryption (optional) - Enable TLS Encryption (optional)
@@ -337,9 +338,13 @@ The default login user email is `X-WEBAUTH-EMAIL`, you can change it via changin
If set `ENABLE_REVERSE_PROXY_FULL_NAME=true`, a user full name expected in `X-WEBAUTH-FULLNAME` will be assigned to the user when auto creating the user. You can also change the header name with `REVERSE_PROXY_AUTHENTICATION_FULL_NAME`. If set `ENABLE_REVERSE_PROXY_FULL_NAME=true`, a user full name expected in `X-WEBAUTH-FULLNAME` will be assigned to the user when auto creating the user. You can also change the header name with `REVERSE_PROXY_AUTHENTICATION_FULL_NAME`.
You can also limit the reverse proxy's IP address range with `REVERSE_PROXY_TRUSTED_PROXIES` which default value is `127.0.0.0/8,::1/128`. By `REVERSE_PROXY_LIMIT`, you can limit trusted proxies level. It applies to the web interface, Git over HTTP, Git LFS and the package registry.
You can enable the this authentication method for the API with :::warning
Gitea trusts these headers on every request it receives. Make sure Gitea is only reachable through your authenticating proxy, and that the proxy sets or removes these headers on every request, including on paths you exempt from authentication, for example for Git or package clients. `REVERSE_PROXY_TRUSTED_PROXIES` does not restrict them.
:::
To also accept them on the REST API under `/api/v1`, enable:
```ini ```ini
[service] [service]
@@ -427,8 +432,3 @@ USERNAME = nickname
; what to do when the username or email is already taken ; what to do when the username or email is already taken
ACCOUNT_LINKING = login ACCOUNT_LINKING = login
``` ```
:::note
This is unrelated to `ENABLE_OPENID_SIGNIN` and the `[openid]` section, which
configure the older OpenID 2.0 sign-in.
:::
+1 -1
View File
@@ -83,7 +83,7 @@ cd gitea-dump-1610949662
mv app.ini /etc/gitea/conf/app.ini mv app.ini /etc/gitea/conf/app.ini
mv data/* /var/lib/gitea/data/ mv data/* /var/lib/gitea/data/
mv log/* /var/lib/gitea/log/ mv log/* /var/lib/gitea/log/
mv repos/* /var/lib/gitea/data/repositories/ mv repos/* /var/lib/gitea/data/gitea-repositories/
chown -R gitea:gitea /etc/gitea/conf/app.ini /var/lib/gitea chown -R gitea:gitea /etc/gitea/conf/app.ini /var/lib/gitea
# mysql # mysql
-7
View File
@@ -50,13 +50,6 @@ Listing all embedded files with `openid` in their path:
```sh ```sh
$ gitea embedded list '**openid**' $ gitea embedded list '**openid**'
public/assets/img/auth/openid_connect.svg public/assets/img/auth/openid_connect.svg
public/assets/img/openid-16x16.png
templates/user/auth/finalize_openid.tmpl
templates/user/auth/signin_openid.tmpl
templates/user/auth/signup_openid_connect.tmpl
templates/user/auth/signup_openid_navbar.tmpl
templates/user/auth/signup_openid_register.tmpl
templates/user/settings/security_openid.tmpl
``` ```
## Extracting resources ## Extracting resources
+8 -8
View File
@@ -205,8 +205,8 @@ Admin operations:
- `--not-active`: Deactivate the authentication source. - `--not-active`: Deactivate the authentication source.
- `--security-protocol value`: Security protocol name. Required. - `--security-protocol value`: Security protocol name. Required.
- `--skip-tls-verify`: Disable TLS verification. - `--skip-tls-verify`: Disable TLS verification.
- `--host value`: The address where the LDAP server can be reached. Required. - `--host value`: Comma-separated LDAP hosts or `ldap://`, `ldaps://` or `ldap+starttls://` URLs, tried in order. Required.
- `--port value`: The port to use when connecting to the LDAP server. Required. - `--port value`: The port to use when connecting to hosts given without a URL. Required.
- `--user-search-base value`: The LDAP base at which user accounts will be searched for. Required. - `--user-search-base value`: The LDAP base at which user accounts will be searched for. Required.
- `--user-filter value`: An LDAP filter declaring how to find the user record that is attempting to authenticate. Required. - `--user-filter value`: An LDAP filter declaring how to find the user record that is attempting to authenticate. Required.
- `--admin-filter value`: An LDAP filter specifying if a user should be given administrator privileges. - `--admin-filter value`: An LDAP filter specifying if a user should be given administrator privileges.
@@ -231,8 +231,8 @@ Admin operations:
- `--not-active`: Deactivate the authentication source. - `--not-active`: Deactivate the authentication source.
- `--security-protocol value`: Security protocol name. - `--security-protocol value`: Security protocol name.
- `--skip-tls-verify`: Disable TLS verification. - `--skip-tls-verify`: Disable TLS verification.
- `--host value`: The address where the LDAP server can be reached. - `--host value`: Comma-separated LDAP hosts or `ldap://`, `ldaps://` or `ldap+starttls://` URLs, tried in order.
- `--port value`: The port to use when connecting to the LDAP server. - `--port value`: The port to use when connecting to hosts given without a URL.
- `--user-search-base value`: The LDAP base at which user accounts will be searched for. - `--user-search-base value`: The LDAP base at which user accounts will be searched for.
- `--user-filter value`: An LDAP filter declaring how to find the user record that is attempting to authenticate. - `--user-filter value`: An LDAP filter declaring how to find the user record that is attempting to authenticate.
- `--admin-filter value`: An LDAP filter specifying if a user should be given administrator privileges. - `--admin-filter value`: An LDAP filter specifying if a user should be given administrator privileges.
@@ -257,8 +257,8 @@ Admin operations:
- `--not-active`: Deactivate the authentication source. - `--not-active`: Deactivate the authentication source.
- `--security-protocol value`: Security protocol name. Required. - `--security-protocol value`: Security protocol name. Required.
- `--skip-tls-verify`: Disable TLS verification. - `--skip-tls-verify`: Disable TLS verification.
- `--host value`: The address where the LDAP server can be reached. Required. - `--host value`: Comma-separated LDAP hosts or `ldap://`, `ldaps://` or `ldap+starttls://` URLs, tried in order. Required.
- `--port value`: The port to use when connecting to the LDAP server. Required. - `--port value`: The port to use when connecting to hosts given without a URL. Required.
- `--user-search-base value`: The LDAP base at which user accounts will be searched for. - `--user-search-base value`: The LDAP base at which user accounts will be searched for.
- `--user-filter value`: An LDAP filter declaring how to find the user record that is attempting to authenticate. Required. - `--user-filter value`: An LDAP filter declaring how to find the user record that is attempting to authenticate. Required.
- `--admin-filter value`: An LDAP filter specifying if a user should be given administrator privileges. - `--admin-filter value`: An LDAP filter specifying if a user should be given administrator privileges.
@@ -279,8 +279,8 @@ Admin operations:
- `--not-active`: Deactivate the authentication source. - `--not-active`: Deactivate the authentication source.
- `--security-protocol value`: Security protocol name. - `--security-protocol value`: Security protocol name.
- `--skip-tls-verify`: Disable TLS verification. - `--skip-tls-verify`: Disable TLS verification.
- `--host value`: The address where the LDAP server can be reached. - `--host value`: Comma-separated LDAP hosts or `ldap://`, `ldaps://` or `ldap+starttls://` URLs, tried in order.
- `--port value`: The port to use when connecting to the LDAP server. - `--port value`: The port to use when connecting to hosts given without a URL.
- `--user-search-base value`: The LDAP base at which user accounts will be searched for. - `--user-search-base value`: The LDAP base at which user accounts will be searched for.
- `--user-filter value`: An LDAP filter declaring how to find the user record that is attempting to authenticate. - `--user-filter value`: An LDAP filter declaring how to find the user record that is attempting to authenticate.
- `--admin-filter value`: An LDAP filter specifying if a user should be given administrator privileges. - `--admin-filter value`: An LDAP filter specifying if a user should be given administrator privileges.
+16 -25
View File
@@ -130,8 +130,8 @@ In addition, there is _`StaticRootPath`_ which can be set as a built-in at build
HTTP protocol. HTTP protocol.
- `USE_COMPAT_SSH_URI`: **false**: Force ssh:// clone url instead of scp-style uri when - `USE_COMPAT_SSH_URI`: **false**: Force ssh:// clone url instead of scp-style uri when
default SSH port is used. default SSH port is used.
- `GO_GET_CLONE_URL_PROTOCOL`: **https**: Value for the "go get" request returns the repository url as https or ssh - `GO_GET_CLONE_URL_PROTOCOL`: **_empty_**: Scheme of the returned URL for the "go get" response.
default is https. Default is "https" if DISABLE_HTTP_GIT=false or SSH is disabled, otherwise "ssh".
- `ACCESS_CONTROL_ALLOW_ORIGIN`: **_empty_**: Value for Access-Control-Allow-Origin header, - `ACCESS_CONTROL_ALLOW_ORIGIN`: **_empty_**: Value for Access-Control-Allow-Origin header,
default is not to present. default is not to present.
@@ -151,8 +151,6 @@ In addition, there is _`StaticRootPath`_ which can be set as a built-in at build
- `DISABLE_MIGRATIONS`: **false**: Disable migrating feature. - `DISABLE_MIGRATIONS`: **false**: Disable migrating feature.
- `DISABLE_STARS`: **false**: Disable stars feature. - `DISABLE_STARS`: **false**: Disable stars feature.
- `DEFAULT_BRANCH`: **main**: Default branch name of all repositories. - `DEFAULT_BRANCH`: **main**: Default branch name of all repositories.
- `ALLOW_ADOPTION_OF_UNADOPTED_REPOSITORIES`: **false**: Allow non-admin users to adopt unadopted repositories
- `ALLOW_DELETION_OF_UNADOPTED_REPOSITORIES`: **false**: Allow non-admin users to delete unadopted repositories
- `DISABLE_DOWNLOAD_SOURCE_ARCHIVES`: **false**: Don't allow download source archive files from UI - `DISABLE_DOWNLOAD_SOURCE_ARCHIVES`: **false**: Don't allow download source archive files from UI
- `ALLOW_FORK_WITHOUT_MAXIMUM_LIMIT`: **true**: Allow to fork repositories without maximum number limit - `ALLOW_FORK_WITHOUT_MAXIMUM_LIMIT`: **true**: Allow to fork repositories without maximum number limit
- `ALLOW_FORK_INTO_SAME_OWNER`: **false**: Allow to fork repositories into the same owner (user or organization). - `ALLOW_FORK_INTO_SAME_OWNER`: **false**: Allow to fork repositories into the same owner (user or organization).
@@ -179,7 +177,7 @@ In addition, there is _`StaticRootPath`_ which can be set as a built-in at build
- `POPULATE_SQUASH_COMMENT_WITH_COMMIT_MESSAGES`: **false**: In default squash-merge messages include the commit message of all commits comprising the pull request. - `POPULATE_SQUASH_COMMENT_WITH_COMMIT_MESSAGES`: **false**: In default squash-merge messages include the commit message of all commits comprising the pull request.
- `ADD_CO_COMMITTER_TRAILERS`: **true**: Add co-authored-by and co-committed-by trailers to merge commit messages if committer does not match author. - `ADD_CO_COMMITTER_TRAILERS`: **true**: Add co-authored-by and co-committed-by trailers to merge commit messages if committer does not match author.
- `RETARGET_CHILDREN_ON_MERGE`: **true**: Retarget child pull requests to the parent pull request branch target on merge of parent pull request. It only works on merged PRs where the head and base branch target the same repo. - `RETARGET_CHILDREN_ON_MERGE`: **true**: Retarget child pull requests to the parent pull request branch target on merge of parent pull request. It only works on merged PRs where the head and base branch target the same repo.
- `DEFAULT_DELETE_BRANCH_AFTER_MERGE`: **false**: Set the default value for "Delete pull request branch after merge by default" for new repositories. - `DEFAULT_DELETE_BRANCH_AFTER_MERGE`: **true**: Set the default value for "Delete pull request branch after merge by default" for new repositories.
- `DEFAULT_TITLE_SOURCE`: **auto**: Default source for the pull request title when opening a new PR. Valid options: - `DEFAULT_TITLE_SOURCE`: **auto**: Default source for the pull request title when opening a new PR. Valid options:
- `first-commit`: Uses the oldest commit's summary as the title. If there are multiple commits, still uses the first commit's message. - `first-commit`: Uses the oldest commit's summary as the title. If there are multiple commits, still uses the first commit's message.
- `auto`: Uses the commit's summary when the PR contains a single commit; when there are multiple commits, converts the branch name into a human-readable title by normalizing separators and casing. - `auto`: Uses the commit's summary when the PR contains a single commit; when there are multiple commits, converts the branch name into a human-readable title by normalizing separators and casing.
@@ -270,9 +268,10 @@ The following configuration set `Content-Type: application/vnd.android.package-a
- `FOLDER_ICON_THEME`: **basic**: The icon theme for folders (basic/material). - `FOLDER_ICON_THEME`: **basic**: The icon theme for folders (basic/material).
- `MAX_DISPLAY_FILE_SIZE`: **8388608**: Max size of files to be displayed (default is 8MiB) - `MAX_DISPLAY_FILE_SIZE`: **8388608**: Max size of files to be displayed (default is 8MiB)
- `AMBIGUOUS_UNICODE_DETECTION`: **true**: Detect ambiguous unicode characters in file contents and show warnings on the UI - `AMBIGUOUS_UNICODE_DETECTION`: **true**: Detect ambiguous unicode characters in file contents and show warnings on the UI
- `REACTIONS`: All available reactions users can choose on issues/prs and comments - `REACTIONS`: All available reactions users can choose on issues, pull requests and comments.
Values can be emoji alias (:smile:) or a unicode emoji. Values can be emoji alias (:smile:) or a unicode emoji.
For custom reactions, add a tightly cropped square image to public/assets/img/emoji/reaction_name.png For custom reactions, add a tightly cropped square image to public/assets/img/emoji/reaction_name.png
- `RELEASE_REACTIONS`: **+1, laugh, hooray, heart, rocket, eyes**: Reactions available for releases, in the same format as `REACTIONS`.
- `REACTION_MAX_USER_NUM`: **10**: Change the number of users that are displayed in reactions tooltip (triggered by mouse hover). - `REACTION_MAX_USER_NUM`: **10**: Change the number of users that are displayed in reactions tooltip (triggered by mouse hover).
- `CUSTOM_EMOJIS`: **gitea, codeberg, gitlab, git, github, gogs**: Additional Emojis not defined in the utf8 standard. - `CUSTOM_EMOJIS`: **gitea, codeberg, gitlab, git, github, gogs**: Additional Emojis not defined in the utf8 standard.
By default, we support Gitea (:gitea:), to add more copy them to public/assets/img/emoji/emoji_name.png and By default, we support Gitea (:gitea:), to add more copy them to public/assets/img/emoji/emoji_name.png and
@@ -568,7 +567,7 @@ And the following unique queues:
- `manage_ssh_keys`: User cannot configure ssh keys. - `manage_ssh_keys`: User cannot configure ssh keys.
- `manage_gpg_keys`: User cannot configure gpg keys. - `manage_gpg_keys`: User cannot configure gpg keys.
- `manage_mfa`: a User cannot configure mfa devices. - `manage_mfa`: a User cannot configure mfa devices.
- `manage_credentials`: a user cannot configure emails, passwords, or openid - `manage_credentials`: a user cannot configure emails or passwords
- `change_username`: a user cannot change their username - `change_username`: a user cannot change their username
- `change_full_name`: a user cannot change their full name - `change_full_name`: a user cannot change their full name
- `EXTERNAL_USER_DISABLE_FEATURES`: **_empty_**: Comma separated list of disabled features ONLY if the user has an external login type (eg. LDAP, Oauth, etc.), could be `deletion`, `manage_ssh_keys`, `manage_gpg_keys`, `manage_mfa`, `manage_credentials`. This setting is independent from `USER_DISABLED_FEATURES` and supplements its behavior. - `EXTERNAL_USER_DISABLE_FEATURES`: **_empty_**: Comma separated list of disabled features ONLY if the user has an external login type (eg. LDAP, Oauth, etc.), could be `deletion`, `manage_ssh_keys`, `manage_gpg_keys`, `manage_mfa`, `manage_credentials`. This setting is independent from `USER_DISABLED_FEATURES` and supplements its behavior.
@@ -576,7 +575,7 @@ And the following unique queues:
- `manage_ssh_keys`: User cannot configure ssh keys. - `manage_ssh_keys`: User cannot configure ssh keys.
- `manage_gpg_keys`: User cannot configure gpg keys. - `manage_gpg_keys`: User cannot configure gpg keys.
- `manage_mfa`: a User cannot configure mfa devices. - `manage_mfa`: a User cannot configure mfa devices.
- `manage_credentials`: a user cannot configure emails, passwords, or openid - `manage_credentials`: a user cannot configure emails or passwords
- `change_username`: a user cannot change their username - `change_username`: a user cannot change their username
- `change_full_name`: a user cannot change their full name - `change_full_name`: a user cannot change their full name
@@ -594,7 +593,8 @@ And the following unique queues:
authentication provided email. authentication provided email.
- `REVERSE_PROXY_AUTHENTICATION_FULL_NAME`: **X-WEBAUTH-FULLNAME**: Header name for reverse proxy - `REVERSE_PROXY_AUTHENTICATION_FULL_NAME`: **X-WEBAUTH-FULLNAME**: Header name for reverse proxy
authentication provided full name. authentication provided full name.
- `REVERSE_PROXY_LIMIT`: **1**: Interpret X-Forwarded-For header or the X-Real-IP header and set this as the remote IP for the request. - `REVERSE_PROXY_LIMIT`: **1**: Interpret the X-Real-IP, X-Forwarded-For or Forwarded header, in that order, and set this as the remote IP for the request.
The client port is taken from the header value or, with X-Real-IP, from X-Real-Port.
Number of trusted proxy count. Set to zero to not use these headers. Number of trusted proxy count. Set to zero to not use these headers.
- `REVERSE_PROXY_TRUSTED_PROXIES`: **127.0.0.0/8,::1/128**: List of IP addresses and networks separated by comma of trusted proxy servers. Use `*` to trust all. - `REVERSE_PROXY_TRUSTED_PROXIES`: **127.0.0.0/8,::1/128**: List of IP addresses and networks separated by comma of trusted proxy servers. Use `*` to trust all.
- `X_FRAME_OPTIONS`: **SAMEORIGIN**: Set the `X-Frame-Options` header value for all HTTP responses. Set to `unset` to not send the header. Previously located in `[cors]`. - `X_FRAME_OPTIONS`: **SAMEORIGIN**: Set the `X-Frame-Options` header value for all HTTP responses. Set to `unset` to not send the header. Previously located in `[cors]`.
@@ -677,15 +677,6 @@ And the following unique queues:
- `HMAC_KEY`: **_empty_**: Provide the HMAC key for encoding URLs, it **is required** if camo is enabled. - `HMAC_KEY`: **_empty_**: Provide the HMAC key for encoding URLs, it **is required** if camo is enabled.
- `ALWAYS`: **false**: Set to true to use camo for both HTTP and HTTPS content, otherwise only non-HTTPS URLs are proxied. `ALLWAYS` is deprecated and will be removed in a future release. - `ALWAYS`: **false**: Set to true to use camo for both HTTP and HTTPS content, otherwise only non-HTTPS URLs are proxied. `ALLWAYS` is deprecated and will be removed in a future release.
## OpenID (`openid`)
- `ENABLE_OPENID_SIGNIN`: **false**: Allow authentication in via OpenID.
- `ENABLE_OPENID_SIGNUP`: **false**: Allow registering via OpenID.
- `WHITELISTED_URIS`: **_empty_**: If non-empty, list of POSIX regex patterns matching
OpenID URI's to permit.
- `BLACKLISTED_URIS`: **_empty_**: If non-empty, list of POSIX regex patterns matching
OpenID URI's to block.
## OAuth2 Client (`oauth2_client`) ## OAuth2 Client (`oauth2_client`)
- `REGISTER_EMAIL_CONFIRM`: _[service]_ **REGISTER\_EMAIL\_CONFIRM**: Set this to enable or disable email confirmation of OAuth2 auto-registration. (Overwrites the REGISTER\_EMAIL\_CONFIRM setting of the `[service]` section) - `REGISTER_EMAIL_CONFIRM`: _[service]_ **REGISTER\_EMAIL\_CONFIRM**: Set this to enable or disable email confirmation of OAuth2 auto-registration. (Overwrites the REGISTER\_EMAIL\_CONFIRM setting of the `[service]` section)
@@ -739,8 +730,8 @@ And the following unique queues:
If you set it to false, maybe it also needs to set `ENABLE_BASIC_AUTHENTICATION` to false to If you set it to false, maybe it also needs to set `ENABLE_BASIC_AUTHENTICATION` to false to
completely disable password-based authentication. completely disable password-based authentication.
- `ENABLE_PASSKEY_AUTHENTICATION`: **true**: Allow users to sign-in with a passkey - `ENABLE_PASSKEY_AUTHENTICATION`: **true**: Allow users to sign-in with a passkey
- `ENABLE_REVERSE_PROXY_AUTHENTICATION`: **false**: Enable this to allow reverse proxy authentication for web requests - `ENABLE_REVERSE_PROXY_AUTHENTICATION`: **false**: Enable reverse proxy authentication for the web interface, Git over HTTP, Git LFS and the package registry. Gitea must only be reachable through the proxy, see [Reverse Proxy](authentication.md#reverse-proxy).
- `ENABLE_REVERSE_PROXY_AUTHENTICATION_API`: **false**: Enable this to allow reverse proxy authentication for API requests, the reverse proxy is responsible for ensuring that no CSRF is possible. - `ENABLE_REVERSE_PROXY_AUTHENTICATION_API`: **false**: Enable reverse proxy authentication for the REST API under `/api/v1`.
- `ENABLE_REVERSE_PROXY_AUTO_REGISTRATION`: **false**: Enable this to allow auto-registration - `ENABLE_REVERSE_PROXY_AUTO_REGISTRATION`: **false**: Enable this to allow auto-registration
for reverse authentication. for reverse authentication.
- `ENABLE_REVERSE_PROXY_EMAIL`: **false**: Enable this to allow to auto-registration with a - `ENABLE_REVERSE_PROXY_EMAIL`: **false**: Enable this to allow to auto-registration with a
@@ -763,6 +754,7 @@ And the following unique queues:
- `CF_TURNSTILE_SECRET` **""**: Go to https://dash.cloudflare.com/?to=/:account/turnstile to get a secret for cloudflare turnstile. - `CF_TURNSTILE_SECRET` **""**: Go to https://dash.cloudflare.com/?to=/:account/turnstile to get a secret for cloudflare turnstile.
- `CF_TURNSTILE_SITEKEY` **""**: Go to https://dash.cloudflare.com/?to=/:account/turnstile to get a sitekey for cloudflare turnstile. - `CF_TURNSTILE_SITEKEY` **""**: Go to https://dash.cloudflare.com/?to=/:account/turnstile to get a sitekey for cloudflare turnstile.
- `DEFAULT_KEEP_EMAIL_PRIVATE`: **false**: By default set users to keep their email address private. - `DEFAULT_KEEP_EMAIL_PRIVATE`: **false**: By default set users to keep their email address private.
- `FORCE_USER_ACTIVITY_VISIBILITY`: **_empty_**: Force all users' activity to "public" or "private", overwriting their "Hide Activity" setting.
- `DEFAULT_ALLOW_CREATE_ORGANIZATION`: **true**: Allow new users to create organizations by default. - `DEFAULT_ALLOW_CREATE_ORGANIZATION`: **true**: Allow new users to create organizations by default.
- `DEFAULT_USER_IS_RESTRICTED`: **false**: Give new users restricted permissions by default - `DEFAULT_USER_IS_RESTRICTED`: **false**: Give new users restricted permissions by default
- `DEFAULT_ENABLE_DEPENDENCIES`: **true**: Enable this to have dependencies enabled by default. - `DEFAULT_ENABLE_DEPENDENCIES`: **true**: Enable this to have dependencies enabled by default.
@@ -809,7 +801,6 @@ Define allowed algorithms and their minimum key length (use -1 to disable a type
- `ED25519`: **256** - `ED25519`: **256**
- `ECDSA`: **256** - `ECDSA`: **256**
- `RSA`: **3071**: We set 3071 here because an otherwise valid 3072 RSA key can be reported as 3071 length. - `RSA`: **3071**: We set 3071 here because an otherwise valid 3072 RSA key can be reported as 3071 length.
- `DSA`: **-1**: DSA is now disabled by default. Set to **1024** to re-enable but ensure you may need to reconfigure your SSHD provider
## Webhook (`webhook`) ## Webhook (`webhook`)
@@ -1327,7 +1318,6 @@ These options are written into the gitconfig file under `[git] HOME_PATH` when G
- `diff.algorithm`: **histogram** - `diff.algorithm`: **histogram**
- `core.logAllRefUpdates`: **true** - `core.logAllRefUpdates`: **true**
- `gc.reflogExpire`: **90**
## Metrics (`metrics`) ## Metrics (`metrics`)
@@ -1355,7 +1345,7 @@ These options are written into the gitconfig file under `[git] HOME_PATH` when G
- `JWT_SECRET_URI`: **_empty_**: Instead of defining JWT_SECRET in the configuration, this configuration option can be used to give Gitea a path to a file that contains the secret (example value: `file:/etc/gitea/oauth2_jwt_secret`) - `JWT_SECRET_URI`: **_empty_**: Instead of defining JWT_SECRET in the configuration, this configuration option can be used to give Gitea a path to a file that contains the secret (example value: `file:/etc/gitea/oauth2_jwt_secret`)
- `JWT_SIGNING_PRIVATE_KEY_FILE`: **jwt/private.pem**: Private key file path used to sign OAuth2 tokens. The path is relative to `APP_DATA_PATH`. This setting is only needed if `JWT_SIGNING_ALGORITHM` is set to `RS256`, `RS384`, `RS512`, `ES256`, `ES384` or `ES512`. The file must contain a RSA or ECDSA private key in the PKCS8 format. If no key exists a 4096 bit key will be created for you. - `JWT_SIGNING_PRIVATE_KEY_FILE`: **jwt/private.pem**: Private key file path used to sign OAuth2 tokens. The path is relative to `APP_DATA_PATH`. This setting is only needed if `JWT_SIGNING_ALGORITHM` is set to `RS256`, `RS384`, `RS512`, `ES256`, `ES384` or `ES512`. The file must contain a RSA or ECDSA private key in the PKCS8 format. If no key exists a 4096 bit key will be created for you.
- `MAX_TOKEN_LENGTH`: **32767**: Maximum length of token/cookie to accept from OAuth2 provider - `MAX_TOKEN_LENGTH`: **32767**: Maximum length of token/cookie to accept from OAuth2 provider
- `DEFAULT_APPLICATIONS`: **git-credential-oauth, git-credential-manager, tea, gitea-app**: Pre-register OAuth applications for some services on startup. See the [OAuth2 documentation](/development/oauth2-provider.md) for the list of available options. - `DEFAULT_APPLICATIONS`: **git-credential-oauth, git-credential-manager, gitea-cli, gitea-app, gitea-vscode**: Pre-register OAuth applications for some services on startup. See the [OAuth2 documentation](/development/oauth2-provider.md) for the list of available options. `tea` is accepted as an alias of `gitea-cli`.
- `CUSTOM_SCHEMES`: **_empty_**: By default, OAuth2 applications can only use "http" and "https" as their redirect URI schemes. - `CUSTOM_SCHEMES`: **_empty_**: By default, OAuth2 applications can only use "http" and "https" as their redirect URI schemes.
If you need to use other schemes (e.g. for desktop applications), you can specify them here as a comma-separated list. If you need to use other schemes (e.g. for desktop applications), you can specify them here as a comma-separated list.
For example: set "my-scheme, com.example.app" to support "my-scheme://..." and "com.example.app://..." redirect URIs. For example: set "my-scheme, com.example.app" to support "my-scheme://..." and "com.example.app://..." redirect URIs.
@@ -1487,8 +1477,9 @@ These lists are enforced on direct connections only. When a proxy is configured
- `LIMIT_SIZE_RPM`: **-1**: Maximum size of a RPM upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`) - `LIMIT_SIZE_RPM`: **-1**: Maximum size of a RPM upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
- `LIMIT_SIZE_RUBYGEMS`: **-1**: Maximum size of a RubyGems upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`) - `LIMIT_SIZE_RUBYGEMS`: **-1**: Maximum size of a RubyGems upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
- `LIMIT_SIZE_SWIFT`: **-1**: Maximum size of a Swift upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`) - `LIMIT_SIZE_SWIFT`: **-1**: Maximum size of a Swift upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
- `LIMIT_SIZE_TERRAFORM_MODULE`: **-1**: Maximum size of a Terraform module archive upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`). Archives are additionally capped at 32 MiB decompressed.
- `LIMIT_SIZE_TERRAFORM_STATE`: **-1**: Maximum size of a Terraform state upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
- `LIMIT_SIZE_VAGRANT`: **-1**: Maximum size of a Vagrant upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`) - `LIMIT_SIZE_VAGRANT`: **-1**: Maximum size of a Vagrant upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
- `LIMIT_SIZE_TERRAFORM_STATE``: **-1**: Maximum size of a Terraform state upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
## Mirror (`mirror`) ## Mirror (`mirror`)
@@ -1707,7 +1698,7 @@ PROXY_HOSTS = *.github.com
But it will save storage space and network bandwidth, so it's still recommended to use compression. But it will save storage space and network bandwidth, so it's still recommended to use compression.
- `ARTIFACT_RETENTION_DAYS`: **90**: Days to keep artifacts. Old artifacts will be deleted after this period. 0 means keep forever. - `ARTIFACT_RETENTION_DAYS`: **90**: Days to keep artifacts. Old artifacts will be deleted after this period. 0 means keep forever.
Changes only apply to newly uploaded artifacts, existing ones keep the expiry stored when they were uploaded. Changes only apply to newly uploaded artifacts, existing ones keep the expiry stored when they were uploaded.
Artifacts could have their own retention periods by setting the `retention-days` option in `actions/upload-artifact` step. Workflows can request a shorter retention period, down to 1 day.
- `ARTIFACT_PREVIEW_MAX_SIZE`: **10485760**: Maximum total artifact size in bytes that can be browsed or previewed in the web UI. Set to `0` to disable artifact previews or `-1` for no limit. Individual files are also limited by [`MAX_DISPLAY_FILE_SIZE`](#ui-ui). - `ARTIFACT_PREVIEW_MAX_SIZE`: **10485760**: Maximum total artifact size in bytes that can be browsed or previewed in the web UI. Set to `0` to disable artifact previews or `-1` for no limit. Individual files are also limited by [`MAX_DISPLAY_FILE_SIZE`](#ui-ui).
- `RUN_RETENTION_DAYS`: **400**: Days to keep completed runs. Old runs and everything under them will be deleted after this period. 0 means keep forever. - `RUN_RETENTION_DAYS`: **400**: Days to keep completed runs. Old runs and everything under them will be deleted after this period. 0 means keep forever.
- `ZOMBIE_TASK_TIMEOUT`: **10m**: Timeout to stop the task which have running status, but haven't been updated for a long time - `ZOMBIE_TASK_TIMEOUT`: **10m**: Timeout to stop the task which have running status, but haven't been updated for a long time
+4 -3
View File
@@ -10,9 +10,10 @@ aliases:
## Builtin repository code search without indexer ## Builtin repository code search without indexer
Users could do repository-level code search without setting up a repository indexer. Users can search the code of a single repository without setting up a repository indexer.
The builtin code search is based on the `git grep` command, which is fast and efficient for small repositories. This search uses `git grep`, which is fast for small repositories and requires Git built with PCRE support, as most distributions provide.
Better code search support could be achieved by setting up the repository indexer. Searching across repositories requires the repository indexer.
See [Code Search](../usage/code-search.md) for the query syntax.
## Setting up the repository indexer ## Setting up the repository indexer
+1
View File
@@ -16,6 +16,7 @@ aliases:
4. Make sure `Host` and `X-Forwarded-Proto` headers are correctly passed to Gitea to make Gitea see the real URL being visited. 4. Make sure `Host` and `X-Forwarded-Proto` headers are correctly passed to Gitea to make Gitea see the real URL being visited.
5. Make sure your webserver has a certificate, including all intermediate and RootCA certificates, for `git clone` and `git pull` to work. 5. Make sure your webserver has a certificate, including all intermediate and RootCA certificates, for `git clone` and `git pull` to work.
6. Gitea uses a WebSocket connection at `/-/ws` for real-time updates like the notification counter. Make sure the reverse-proxy talks HTTP/1.1 and forwards the `Upgrade` and `Connection` headers, see the examples below. Without it, Gitea falls back to periodic polling. 6. Gitea uses a WebSocket connection at `/-/ws` for real-time updates like the notification counter. Make sure the reverse-proxy talks HTTP/1.1 and forwards the `Upgrade` and `Connection` headers, see the examples below. Without it, Gitea falls back to periodic polling.
7. Make sure the reverse-proxy sets the `X-Real-IP` header, otherwise Gitea uses a client-sent value. For example `header_up X-Real-IP {remote_host}` in Caddy's `reverse_proxy`, `RequestHeader set X-Real-IP "expr=%{REMOTE_ADDR}"` in Apache or `http-request set-header X-Real-IP %[src]` in HAProxy. To log the client port, also set `X-Real-Port`, for example `proxy_set_header X-Real-Port $remote_port;` in nginx.
### Use a sub-path ### Use a sub-path
+1
View File
@@ -73,6 +73,7 @@ By default, this creates a token with very limited permissions. To complete your
- `activitypub` - `activitypub`
- `admin` - `admin`
- `commitstatus` (included in `repository`)
- `issue` - `issue`
- `misc` - `misc`
- `notification` - `notification`
+6 -1
View File
@@ -111,6 +111,9 @@ Gitea token scopes are as follows:
| **admin** | `/admin/*` API routes: Site-wide administrative operations (hidden for non-admin accounts). | | **admin** | `/admin/*` API routes: Site-wide administrative operations (hidden for non-admin accounts). |
| &nbsp;&nbsp;&nbsp; **read:admin** | Grants read access for admin operations, such as getting cron jobs or registered user emails. | | &nbsp;&nbsp;&nbsp; **read:admin** | Grants read access for admin operations, such as getting cron jobs or registered user emails. |
| &nbsp;&nbsp;&nbsp; **write:admin** | Grants read/write/delete access for admin operations, such as running cron jobs or updating user accounts. | | &nbsp;&nbsp;&nbsp; **write:admin** | Grants read/write/delete access for admin operations, such as running cron jobs or updating user accounts. |
| **commitstatus** | `/repos/{owner}/{repo}/statuses/{sha}` and `/repos/{owner}/{repo}/commits/{ref}/status(es)` API routes: Commit status operations. |
| &nbsp;&nbsp;&nbsp; **read:commitstatus** | Grants read access to commit statuses. Included in `read:repository`. |
| &nbsp;&nbsp;&nbsp; **write:commitstatus** | Grants read/write access to commit statuses, such as reporting CI results. Included in `write:repository`. |
| **issue** | `issues/*`, `labels/*`, `milestones/*` API routes: Issue-related operations. | | **issue** | `issues/*`, `labels/*`, `milestones/*` API routes: Issue-related operations. |
| &nbsp;&nbsp;&nbsp; **read:issue** | Grants read access for issues operations, such as getting issue comments, issue attachments, and milestones. | | &nbsp;&nbsp;&nbsp; **read:issue** | Grants read access for issues operations, such as getting issue comments, issue attachments, and milestones. |
| &nbsp;&nbsp;&nbsp; **write:issue** | Grants read/write/delete access for issues operations, such as posting or editing an issue comment or attachment, and updating milestones. | | &nbsp;&nbsp;&nbsp; **write:issue** | Grants read/write/delete access for issues operations, such as posting or editing an issue comment or attachment, and updating milestones. |
@@ -141,7 +144,9 @@ Gitea creates OAuth applications for the following services by default on startu
|-----------|-----------|---------| |-----------|-----------|---------|
|[git-credential-oauth](https://github.com/hickford/git-credential-oauth)|Git credential helper|`a4792ccc-144e-407e-86c9-5e7d8d9c3269`| |[git-credential-oauth](https://github.com/hickford/git-credential-oauth)|Git credential helper|`a4792ccc-144e-407e-86c9-5e7d8d9c3269`|
|[Git Credential Manager](https://github.com/git-ecosystem/git-credential-manager)|Git credential helper|`e90ee53c-94e2-48ac-9358-a874fb9e0662`| |[Git Credential Manager](https://github.com/git-ecosystem/git-credential-manager)|Git credential helper|`e90ee53c-94e2-48ac-9358-a874fb9e0662`|
|[tea](https://gitea.com/gitea/tea)|tea|`d57cb8c4-630c-4168-8324-ec79935e18d4`| |[Gitea CLI](https://gitea.com/gitea/cli)|Gitea CLI|`d57cb8c4-630c-4168-8324-ec79935e18d4`|
|Gitea App|Official Gitea mobile app|`b757811a-05c8-4c76-8d74-a5ee3d2073f2`|
|[gitea-vscode](https://gitea.com/gitea/gitea-vscode)|VS Code extension|`75a9ec3e-42b5-40cb-9144-9ea96ecd56a6`|
To prevent unexpected behavior, they are being displayed as locked in the UI and their creation can instead be controlled by the `DEFAULT_APPLICATIONS` parameter in `app.ini`. To prevent unexpected behavior, they are being displayed as locked in the UI and their creation can instead be controlled by the `DEFAULT_APPLICATIONS` parameter in `app.ini`.
+4 -19
View File
@@ -134,22 +134,13 @@ You can also see an example of the `swagger.json` file at https://gitea.com/swag
There are multiple things you can combine to prevent spammers. There are multiple things you can combine to prevent spammers.
1. By whitelisting or blocklisting certain email domains 1. By whitelisting or blocklisting certain email domains
2. By only whitelisting certain domains with OpenID (see below) 2. Setting `ENABLE_CAPTCHA` to `true` in your `app.ini` and properly configuring `RECAPTCHA_SECRET` and `RECAPTCHA_SITEKEY`
3. Setting `ENABLE_CAPTCHA` to `true` in your `app.ini` and properly configuring `RECAPTCHA_SECRET` and `RECAPTCHA_SITEKEY` 3. Settings `DISABLE_REGISTRATION` to `true` and creating new users via the [CLI](../administration/command-line.md), [API](development/api-usage.md), or Gitea's Admin UI
4. Settings `DISABLE_REGISTRATION` to `true` and creating new users via the [CLI](../administration/command-line.md), [API](development/api-usage.md), or Gitea's Admin UI
### Only allow/block certain email domains ### Only allow/block certain email domains
You can configure `EMAIL_DOMAIN_WHITELIST` or `EMAIL_DOMAIN_BLOCKLIST` in your app.ini under `[service]` You can configure `EMAIL_DOMAIN_WHITELIST` or `EMAIL_DOMAIN_BLOCKLIST` in your app.ini under `[service]`
### Only allow/block certain OpenID providers
You can configure `WHITELISTED_URIS` or `BLACKLISTED_URIS` under `[openid]` in your `app.ini`
:::note
Whitelisted takes precedence, so if it is non-blank then blacklisted is ignored.
:::
### Issue only users ### Issue only users
The current way to achieve this is to create/modify a user with a max repo creation limit of 0. The current way to achieve this is to create/modify a user with a max repo creation limit of 0.
@@ -328,14 +319,8 @@ It is highly recommended to back-up your database before running these commands.
## How to adopt repositories from disk ## How to adopt repositories from disk
- Add your (bare) repositories to the correct spot for your configuration (`repository.ROOT`), ensuring they are in the correct layout `<REPO_ROOT>/[user]/[repo].git`. To import repositories from disk, use the [Gitea importer](https://gitea.com/gitea/importer) with `--source-type local`.
- **Note:** the directory names must be lowercase. If the repositories are already under Gitea's repository root, move them outside it before importing to avoid conflicts with destination paths.
- You can also check `<ROOT_URL>/-/admin/config` for the repository root path.
- Ensure that the user/org exists that you want to adopt repositories for.
- As an admin, go to `<ROOT_URL>/-/admin/repos/unadopted` and search.
- Users can also be given similar permissions via config [`ALLOW_ADOPTION_OF_UNADOPTED_REPOSITORIES`](../administration/config-cheat-sheet.md#repository-repository).
- If the above steps are done correctly, you should be able to select repositories to adopt.
- If no repositories are found, enable [debug logging](../administration/config-cheat-sheet.md#repository-repository) to check for any specific errors.
## Gitea can't start on NFS ## Gitea can't start on NFS
+23 -1
View File
@@ -8,7 +8,7 @@ aliases:
# Database Preparation # Database Preparation
You need a database to use Gitea. Gitea supports PostgreSQL (>= 12), MySQL (>= 8.0), MariaDB (>= 10.4), SQLite (builtin), and MSSQL (>= 2012 SP4). This page will guide into preparing database. Only PostgreSQL and MySQL will be covered here since those database engines are widely-used in production. If you plan to use SQLite, you can ignore this chapter. You need a database to use Gitea. Gitea supports PostgreSQL (>= 12), MySQL (>= 8.0), MariaDB (>= 10.4), SQLite (builtin), and MSSQL (>= 2012 SP4). This page will guide into preparing database. PostgreSQL, MySQL and MSSQL are covered here. If you plan to use SQLite, you can ignore this chapter.
:::warning :::warning
Converting one database type to another is not a well-tested process and you may experience issues. It is better to choose the final database type at the type of the first installation. Be aware that SQLite does not scale; if you expect your instance to grow at a later time, you should choose another database type. Converting one database type to another is not a well-tested process and you may experience issues. It is better to choose the final database type at the type of the first installation. Be aware that SQLite does not scale; if you expect your instance to grow at a later time, you should choose another database type.
@@ -177,6 +177,28 @@ All steps below requires that the database engine of your choice is installed on
You should be prompted to enter password for the database user, and connected to the database. You should be prompted to enter password for the database user, and connected to the database.
## MSSQL
1. As an administrator, create the login, a database with case-sensitive collation, and its user. Replace the password `'gitea'` with a secure one:
```sql
CREATE LOGIN gitea WITH PASSWORD = 'gitea';
CREATE DATABASE giteadb COLLATE Latin1_General_CS_AS;
GO
USE giteadb;
CREATE USER gitea FOR LOGIN gitea;
ALTER ROLE db_owner ADD MEMBER gitea;
GO
```
Upgrades change the database schema, so the user needs `db_owner`, or `db_ddladmin`, `db_datareader` and `db_datawriter`. With the latter, also run `ALTER DATABASE giteadb SET READ_COMMITTED_SNAPSHOT ON;` as administrator.
2. On your Gitea server, test the connection to the database:
```sh
sqlcmd -S 203.0.113.3 -U gitea -d giteadb
```
## Database Connection over TLS ## Database Connection over TLS
If the communication between Gitea and your database instance is performed through a private network, or if Gitea and the database are running on the same server, this section can be omitted since the security between Gitea and the database instance is not critically exposed. If instead the database instance is on a public network, use TLS to encrypt the connection to the database, as it is possible for third-parties to intercept the traffic data. If the communication between Gitea and your database instance is performed through a private network, or if Gitea and the database are running on the same server, this section can be omitted since the security between Gitea and the database instance is not critically exposed. If instead the database instance is on a public network, use TLS to encrypt the connection to the database, as it is possible for third-parties to intercept the traffic data.
-49
View File
@@ -1,49 +0,0 @@
---
date: "2016-12-01T16:00:00+02:00"
slug: "install-on-cloud-provider"
sidebar_position: 90
aliases:
- /en-us/install-on-cloud-provider
---
# Installation on Cloud Provider
## Cloudron
Gitea is available as a 1-click install on [Cloudron](https://cloudron.io).
Cloudron makes it easy to run apps like Gitea on your server and keep them up-to-date and secure.
[![Install](/cloudron.svg)](https://cloudron.io/button.html?app=io.gitea.cloudronapp)
The Gitea package is maintained [here](https://git.cloudron.io/cloudron/gitea-app).
There is a [demo instance](https://my.demo.cloudron.io) (username: cloudron password: cloudron) where
you can experiment with running Gitea.
## Linode
[Linode](https://www.linode.com/) has Gitea as an app in their marketplace.
To deploy Gitea to Linode, have a look at the [Linode Marketplace](https://www.linode.com/marketplace/apps/linode/gitea/).
## alwaysdata
[alwaysdata](https://www.alwaysdata.com/) has Gitea as an app in their marketplace.
To deploy Gitea to alwaysdata, have a look at the [alwaysdata Marketplace](https://www.alwaysdata.com/en/marketplace/gitea/).
## Exoscale
[Exoscale](https://www.exoscale.com/) provides Gitea managed by [Glasskube](https://glasskube.eu/) in their marketplace.
Exoscale is a European cloud service provider.
The package is maintained and update via the open source [Glasskube Kubernetes Operator](https://github.com/glasskube/operator).
To deploy Gitea to Exoscale, have a look at the [Exoscale Marketplace](https://www.exoscale.com/marketplace/listing/glasskube-gitea/).
## Sealos
Gitea is available as a one-click deployment on [Sealos](https://sealos.io/products/app-store/gitea).
The community-maintained template source is available [here](https://github.com/labring-actions/templates/tree/kb-0.9/template/gitea).
@@ -10,13 +10,13 @@ aliases:
# Protected branches # Protected branches
Protected branches prevent unwanted changes by enforcing push and merge policies on selected branches. The rules are enforced for every Git protocol (HTTP(S), SSH), the web editor, the API, and background jobs such as auto-merge. Only repository owners and administrators can manage the rules, and the Branches page is read-only while a repository is archived. Protected branches prevent unwanted changes by enforcing push, deletion, and merge policies on selected branches. The rules are enforced for every Git protocol (HTTP(S), SSH), the web editor, the API, and background jobs such as auto-merge. Only repository owners and administrators can manage the rules, and the Branches page is read-only while a repository is archived.
## Creating or editing a rule ## Creating or editing a rule
1. Open the repository and select **Settings → Branches** (repository admin permission required). 1. Open the repository and select **Settings → Branches** (repository admin permission required).
2. Select **Add new rule** or **Edit** next to an existing rule. 2. Select **Add new rule** or **Edit** next to an existing rule.
3. Fill in the **Protected branch name pattern** and optional file patterns, then configure the push, merge, and review options described below. 3. Fill in the **Protected branch name pattern** and optional file patterns, then configure the push, deletion, merge, and review options described below.
4. Select **Save rule**. 4. Select **Save rule**.
The rule immediately applies to all matching branches, even if the branches are created in the future. The rule immediately applies to all matching branches, even if the branches are created in the future.
@@ -48,7 +48,9 @@ The **Push** section controls direct pushes (including the web editor and API).
- **Disable push** makes the branch read-only. Any attempt to push directly fails, and changes must be merged through pull requests. - **Disable push** makes the branch read-only. Any attempt to push directly fails, and changes must be merged through pull requests.
- **Enable push** allows anyone with [write access](./permissions.md) to push (force pushes are still blocked unless explicitly allowed). - **Enable push** allows anyone with [write access](./permissions.md) to push (force pushes are still blocked unless explicitly allowed).
- **Allowlist restricted push** requires being on the allowlist. Choose users and, for organization-owned repositories, teams. Deploy keys that already have write access can also be allowlisted. - **Allowlist restricted push** requires being on the allowlist. Choose users and, for organization-owned repositories, teams.
The user allowlists for push, force-push and deletion can include the **Gitea Actions** and **Deploy Key** system users. They still require write access; **Deploy Key** also covers deploy tokens.
When a push is blocked, the server-side hook rejects the update with an explanation. When a push is blocked, the server-side hook rejects the update with an explanation.
@@ -58,7 +60,17 @@ Force pushes have their own set of options:
- **Disable force push** completely forbids rewriting history on the branch. - **Disable force push** completely forbids rewriting history on the branch.
- **Enable force push** allows anyone who can push to also force push. - **Enable force push** allows anyone who can push to also force push.
- **Allowlist restricted force push** limits force pushes to a separate allowlist (users, teams, and optionally deploy keys) **and** requires the person to already have regular push access. - **Allowlist restricted force push** limits force pushes to a separate allowlist of users or teams **and** requires regular push access.
## Branch deletion
The **Branch Deletion** section controls whether matching protected branches can be deleted:
- **Disable branch deletion** prevents deletion. This is the default.
- **Enable branch deletion** allows anyone who can push to delete the branch.
- **Allowlist restricted branch deletion** limits deletion to a separate allowlist of users or teams **and** requires regular push access.
These rules apply to Git (`git push --delete`), the API, the web interface and post-merge cleanup. The default branch and configured default pull request target branch cannot be deleted.
## Pull request merges and approvals ## Pull request merges and approvals
+3 -13
View File
@@ -16,17 +16,7 @@ Gitea Actions is designed to be compatible with GitHub Actions, with the differe
### Action prefixes ### Action prefixes
`uses:` accepts these prefixes: `uses:` accepts the `self:` prefix to reference your own Gitea instance, e.g. `uses: self:owner/repo@v1` or `uses: self:owner/repo/.gitea/workflows/build.yml@v1`.
- `self:` references your own Gitea instance, e.g. `uses: self:owner/repo@v1` or `uses: self:owner/repo/.gitea/workflows/build.yml@v1`
- `builtin:` runs an action built into Gitea Runner, which needs no download and no Node in the job image, e.g. `uses: builtin:checkout`
`builtin:checkout` accepts the `repository`, `ref`, `token`, `path` and `fetch-depth` inputs of `actions/checkout` with the same defaults, and fails on any other input.
### Workflow-relative actions
`$/` references the repository and commit of the workflow, or of the enclosing composite action, e.g. `uses: $/.gitea/actions/build`.
Unlike `./`, it needs no checkout first.
### Actions written in Go ### Actions written in Go
@@ -85,14 +75,14 @@ Service steps have no section of their own in the job log.
### Job token permissions (`permissions`) ### Job token permissions (`permissions`)
`permissions` and `jobs.<job_id>.permissions` control the `GITEA_TOKEN` permissions, clamped by the repository and owner settings and further restricted for fork pull requests and cross-repository access. `permissions` and `jobs.<job_id>.permissions` control the `GITEA_TOKEN` permissions, clamped by the repository and owner settings and further restricted for fork pull requests and cross-repository access.
GitHub-only scopes like `statuses`, `checks`, `deployments`, `id-token`, `security-events` and `pages` are not supported, while Gitea adds `code`, `releases`, `wiki` and `projects`. GitHub-only scopes like `statuses`, `checks`, `deployments`, `security-events` and `pages` are not supported, while Gitea adds `code`, `releases`, `wiki` and `projects`. `id-token` works like on GitHub, see [OpenID Connect](openid-connect.md).
See [Actions job token permissions](token-permissions.md). See [Actions job token permissions](token-permissions.md).
### Downloading actions ### Downloading actions
Actions without a host, like `uses: actions/checkout@v4`, are downloaded from `https://github.com`, or from your own instance when `[actions].DEFAULT_ACTIONS_URL` is `self`. Actions without a host, like `uses: actions/checkout@v4`, are downloaded from `https://github.com`, or from your own instance when `[actions].DEFAULT_ACTIONS_URL` is `self`.
See the [Configuration Cheat Sheet](../../administration/config-cheat-sheet.md#actions-actions). See the [Configuration Cheat Sheet](../../administration/config-cheat-sheet.md#actions-actions).
For other sources, see [Absolute action URLs](#absolute-action-urls), [Action prefixes](#action-prefixes) and [Workflow-relative actions](#workflow-relative-actions). For other sources, see [Absolute action URLs](#absolute-action-urls) and [Action prefixes](#action-prefixes).
### Context availability ### Context availability
+60
View File
@@ -0,0 +1,60 @@
---
date: "2026-08-23T00:00:00+00:00"
slug: "openid-connect"
sidebar_position: 40
---
# OpenID Connect
Jobs can request short-lived OpenID Connect (OIDC) tokens to sign in to cloud providers and other services without storing long-lived secrets. The tokens use the GitHub Actions format, so actions like `aws-actions/configure-aws-credentials`, `google-github-actions/auth` and `azure/login` work unchanged.
## Trusting Gitea
Add Gitea as an OIDC identity provider in the service:
- Issuer: `<ROOT_URL>/api/actions/oidc`
- Audience: `<ROOT_URL>/<owner>`, unless the workflow requests another one
Then limit which workflows can sign in with a condition on the [`sub` claim](#claims).
Gitea signs the tokens with a key it creates at `<APP_DATA_PATH>/jwt/actions_oidc.pem`. Instances behind a load balancer must share this file.
## Requesting a token
Grant the `id-token` permission to the workflow or job:
```yaml
permissions:
id-token: write
```
Default permissions never include it, and jobs from fork pull requests never get it. Owners and repositories can disable it with their [maximum token permissions](token-permissions.md#maximum-token-permissions-clamping).
Actions like the ones above request the token themselves. In a script, use `ACTIONS_ID_TOKEN_REQUEST_URL` and `ACTIONS_ID_TOKEN_REQUEST_TOKEN`:
```shell
curl --fail --silent --show-error \
--header "Authorization: Bearer ${ACTIONS_ID_TOKEN_REQUEST_TOKEN}" \
"${ACTIONS_ID_TOKEN_REQUEST_URL}&audience=my-service"
```
The token is in the `value` field of the response and expires after five minutes.
## Claims
The `sub` claim names the owner and repository with their IDs, so a renamed or recreated repository cannot match an existing trust policy:
```text
repo:<owner>@<owner-id>/<repo>@<repo-id>:ref:<ref>
repo:<owner>@<owner-id>/<repo>@<repo-id>:pull_request
```
The `pull_request` event uses the second form, all other events use the first, including `pull_request_target`.
The other claims match GitHub's, like `repository`, `ref`, `sha`, `workflow_ref` and `job_workflow_ref`. The discovery document at `<ROOT_URL>/api/actions/oidc/.well-known/openid-configuration` lists them all.
Differences from GitHub Actions:
- There is no `environment` claim.
- Pull request runs use `refs/pull/<index>/head` and its commit, not the merge ref and merge commit.
- `run_number` counts runs per repository, not per workflow.
+2 -2
View File
@@ -40,7 +40,7 @@ However, it is recommended to use Docker to run the jobs, because it is more sec
Before running a runner, you should first register it to your Gitea instance using the following command: Before running a runner, you should first register it to your Gitea instance using the following command:
```bash ```bash
./runner register --no-interactive --instance <instance> --token <token> gitea-runner register --no-interactive --instance <instance> --token <token>
``` ```
There are two arguments required, `instance` and `token`. There are two arguments required, `instance` and `token`.
@@ -69,7 +69,7 @@ If this file is missing or corrupted, you can simply remove it and register agai
Finally, it's time to start the runner: Finally, it's time to start the runner:
```bash ```bash
./runner daemon gitea-runner daemon
``` ```
And you can see the new runner in the management page: And you can see the new runner in the management page:
+11 -3
View File
@@ -53,13 +53,14 @@ Valid access mode values for each scope are `read`, `write`, and `none`.
- `wiki` - `wiki`
- `projects` - `projects`
- `packages` (if supported by the target feature) - `packages` (if supported by the target feature)
- `id-token` (`write` allows requesting [OpenID Connect tokens](openid-connect.md), `read` grants nothing)
If you specify both `contents` and a more granular scope (like `code` or `releases`), the granular scope wins for that unit. If you specify both `contents` and a more granular scope (like `code` or `releases`), the granular scope wins for that unit.
### Compatibility notes ### Compatibility notes
Gitea supports a subset of GitHub Actions permission scopes. Gitea supports a subset of GitHub Actions permission scopes.
GitHub-only scopes such as `statuses`, `checks`, `deployments`, `id-token`, `security-events`, and `pages` are not currently supported by Gitea Actions. GitHub-only scopes such as `statuses`, `checks`, `deployments`, `security-events`, and `pages` are not currently supported by Gitea Actions.
Gitea also exposes repository-unit scopes that do not exist as separate scopes in GitHub Actions: Gitea also exposes repository-unit scopes that do not exist as separate scopes in GitHub Actions:
@@ -75,15 +76,18 @@ If neither the workflow nor the job defines `permissions:`, Gitea uses the confi
- **Permissive**: read and write permissions for most units in the job's repository (backwards-compatible default). - **Permissive**: read and write permissions for most units in the job's repository (backwards-compatible default).
- **Restricted**: read-only permissions for `code`, `releases`, and `packages` in the job's repository, and no access to other units by default. - **Restricted**: read-only permissions for `code`, `releases`, and `packages` in the job's repository, and no access to other units by default.
Neither mode includes `id-token`.
## Maximum token permissions (clamping) ## Maximum token permissions (clamping)
You can configure a maximum permission per repository unit. You can configure a maximum permission per repository unit and for `id-token`.
The job's effective permissions are computed as: The job's effective permissions are computed as:
`effective = min(requested, maximum)` `effective = min(requested, maximum)`
This means workflows can reduce permissions for a job, but cannot exceed your configured maximum. This means workflows can reduce permissions for a job, but cannot exceed your configured maximum.
If you don't configure a maximum, the maximum defaults to `write` for all scopes. If you don't configure a maximum, the maximum defaults to `write` for all scopes.
Maximums saved before Gitea supported `id-token` deny it until you set it to `write`.
## Where to configure ## Where to configure
@@ -95,9 +99,13 @@ You can configure defaults and maximums at:
Note: Repository-level token permission settings are only shown once **Repository Actions** are enabled. Note: Repository-level token permission settings are only shown once **Repository Actions** are enabled.
## Protected branches
Actions job tokens must have code write permission and satisfy [branch protection rules](../access-control/protected-branches.md), including any **Gitea Actions** allowlist requirements.
## Fork pull requests ## Fork pull requests
For security reasons, workflows triggered by pull requests from forks are always restricted to read-only permissions for repository contents, regardless of workflow `permissions:` or settings. For security reasons, workflows triggered by pull requests from forks are always restricted to read-only permissions for repository contents, regardless of workflow `permissions:` or settings. They also get no OpenID Connect tokens.
## Cross-repository access ## Cross-repository access
+74 -60
View File
@@ -9,53 +9,67 @@ sidebar_position: 25
## Environment variables ## Environment variables
These environment variables are set automatically in every workflow run and can be accessed directly (e.g. `$CI` in shell scripts). These environment variables are set automatically in every workflow run and can be accessed directly (e.g. `$CI` in shell scripts).
A `GITEA_*` name listed with a `GITHUB_*` name holds the same value.
| Name | Description | Example | | Name | Description | Example |
|---|---|---| |---|---|---|
| `ACT` | Always set to `true`, unless the runner is configured with `runner.set_act_env: false`. | `true` |
| `CI` | Always set to `true`. | `true` | | `CI` | Always set to `true`. | `true` |
| `GITEA_ACTIONS` | Always set to `true`. Useful to distinguish Gitea Actions from other CI systems. | `true` | | `GITEA_ACTION`<br/>`GITHUB_ACTION` | The `id` of the current step, or its index when it has none. | `0` |
| `GITEA_ACTIONS_RUNNER_VERSION` | The version of the runner executing the workflow. | `1.0.8` | | `GITEA_ACTION_PATH`<br/>`GITHUB_ACTION_PATH` | The path where the action is located. Only set in composite actions. | `/var/run/act/actions/***` |
| `GITEA_DOCKER_WORKSPACE` | The workspace path as the Docker daemon sees it, for bind mounts into containers a job starts, e.g. `${GITEA_DOCKER_WORKSPACE:-.}/data:/app/data` in a compose file. Only set for jobs running in a container. | `/var/lib/docker/volumes/GITEA-ACTIONS-TASK-42_***/_data` | | `GITEA_ACTION_REF`<br/>`GITHUB_ACTION_REF` | The ref of the action being executed. | `v4` |
| `GITEA_ENV`<br/>`GITHUB_ENV` | Path to the file that sets environment variables for subsequent steps. | `/home/runner/work/_temp/_runner_file_commands/set_env_***` | | `GITEA_ACTION_REPOSITORY`<br/>`GITHUB_ACTION_REPOSITORY` | The owner and repository of the action. | `actions/checkout` |
| `GITEA_OUTPUT`<br/>`GITHUB_OUTPUT` | Path to the file that sets step output parameters. | `/home/runner/work/_temp/_runner_file_commands/set_output_***` | | `GITEA_ACTIONS`<br/>`GITHUB_ACTIONS` | Always set to `true`. `GITEA_ACTIONS` is useful to distinguish Gitea Actions from other CI systems. | `true` |
| `GITEA_PATH`<br/>`GITHUB_PATH` | Path to the file that adds system `PATH` entries for subsequent steps. | `/home/runner/work/_temp/_runner_file_commands/add_path_***` | | `GITEA_ACTIONS_RUNNER_VERSION` | The version of the runner executing the workflow. | `v5.2.4` |
| `GITEA_STATE`<br/>`GITHUB_STATE` | Path to the file that sets step state variables. | `/home/runner/work/_temp/_runner_file_commands/save_state_***` | | `GITEA_ACTOR`<br/>`GITHUB_ACTOR` | The username of the user that triggered the workflow. | `alice` |
| `GITEA_STEP_SUMMARY`<br/>`GITHUB_STEP_SUMMARY` | Path to the file for writing job summaries. | `/home/runner/work/_temp/_runner_file_commands/step_summary_***` | | `GITEA_ACTOR_ID`<br/>`GITHUB_ACTOR_ID` | The ID of the user that triggered the workflow. | `1` |
| `GITHUB_ACTIONS` | Always set to `true`. | `true` | | `GITEA_API_URL`<br/>`GITHUB_API_URL` | The URL of the REST API. | `https://gitea.example.com/api/v1` |
| `GITHUB_ACTION` | The name of the action currently running, or the step `id`. | `__run` | | `GITEA_BASE_REF`<br/>`GITHUB_BASE_REF` | The target branch of a pull request. | `main` |
| `GITHUB_ACTION_PATH` | The path where the action is located. | `/home/runner/work/_actions/actions/checkout/v4` | | `GITEA_DOCKER_WORKSPACE` | The workspace path as the Docker daemon sees it, for bind mounts into containers a job starts, e.g. `${GITEA_DOCKER_WORKSPACE:-.}/data:/app/data` in a compose file. Only set for jobs running in a container. | `/var/lib/docker/volumes/GITEA-ACTIONS-TASK-42-***/_data` |
| `GITHUB_ACTION_REF` | The ref of the action being executed. | `v4` | | `GITEA_ENV`<br/>`GITHUB_ENV` | Path to the file that sets environment variables for subsequent steps. | `/var/run/act/workflow/envs.txt` |
| `GITHUB_ACTION_REPOSITORY` | The owner and repository of the action. | `actions/checkout` | | `GITEA_EVENT_NAME`<br/>`GITHUB_EVENT_NAME` | The name of the event that triggered the workflow. | `push` |
| `GITHUB_ACTOR` | The username of the user that triggered the workflow. | `silverwind` | | `GITEA_EVENT_PATH`<br/>`GITHUB_EVENT_PATH` | Path to the file containing the event webhook payload. | `/var/run/act/workflow/event.json` |
| `GITHUB_API_URL` | The URL of the REST API. | `https://gitea.com/api/v1` | | `GITEA_GRAPHQL_URL`<br/>`GITHUB_GRAPHQL_URL` | Empty in Gitea (GraphQL is not supported). | _(empty)_ |
| `GITHUB_BASE_REF` | The target branch of a pull request. | `main` | | `GITEA_HEAD_REF`<br/>`GITHUB_HEAD_REF` | The source branch of a pull request. | `feature-branch` |
| `GITHUB_EVENT_NAME` | The name of the event that triggered the workflow. | `push` | | `GITEA_JOB`<br/>`GITHUB_JOB` | The `job_id` of the current job. | `build` |
| `GITHUB_EVENT_PATH` | Path to the file containing the event webhook payload. | `/home/runner/work/_temp/_github_workflow/event.json` | | `GITEA_OUTPUT`<br/>`GITHUB_OUTPUT` | Path to the file that sets step output parameters. | `/var/run/act/workflow/outputcmd.txt` |
| `GITHUB_GRAPHQL_URL` | Empty in Gitea (GraphQL is not supported). | _(empty)_ | | `GITEA_PATH`<br/>`GITHUB_PATH` | Path to the file that adds system `PATH` entries for subsequent steps. | `/var/run/act/workflow/pathcmd.txt` |
| `GITHUB_HEAD_REF` | The source branch of a pull request. | `feature-branch` | | `GITEA_REF`<br/>`GITHUB_REF` | The fully-formed ref that triggered the workflow. | `refs/heads/main` |
| `GITHUB_JOB` | The `job_id` of the current job. | `build` | | `GITEA_REF_NAME`<br/>`GITHUB_REF_NAME` | The short ref name. | `main` |
| `GITHUB_REF` | The fully-formed ref that triggered the workflow. | `refs/heads/main` | | `GITEA_REF_PROTECTED`<br/>`GITHUB_REF_PROTECTED` | `true` if branch protections are configured for the ref that triggered the workflow. | `true` |
| `GITHUB_REF_NAME` | The short ref name. | `main` | | `GITEA_REF_TYPE`<br/>`GITHUB_REF_TYPE` | The type of ref: `branch` or `tag`. | `branch` |
| `GITHUB_REF_TYPE` | The type of ref: `branch` or `tag`. | `branch` | | `GITEA_REPOSITORY`<br/>`GITHUB_REPOSITORY` | The owner and repository name. | `owner/repo` |
| `GITHUB_REPOSITORY` | The owner and repository name. | `gitea/docs` | | `GITEA_REPOSITORY_ID`<br/>`GITHUB_REPOSITORY_ID` | The ID of the repository. | `123` |
| `GITHUB_REPOSITORY_OWNER` | The repository owner's username. | `gitea` | | `GITEA_REPOSITORY_OWNER`<br/>`GITHUB_REPOSITORY_OWNER` | The repository owner's username. | `owner` |
| `GITHUB_RETENTION_DAYS` | The number of days that workflow run logs and artifacts are kept. | `90` | | `GITEA_REPOSITORY_OWNER_ID`<br/>`GITHUB_REPOSITORY_OWNER_ID` | The ID of the repository owner. | `45` |
| `GITHUB_RUN_ATTEMPT` | The attempt number of the workflow run. | `1` | | `GITEA_RETENTION_DAYS`<br/>`GITHUB_RETENTION_DAYS` | The number of days that artifacts are kept, empty when kept forever. | `90` |
| `GITHUB_RUN_ID` | A unique number for each workflow run. | `1234` | | `GITEA_RUN_ATTEMPT`<br/>`GITHUB_RUN_ATTEMPT` | The attempt number of the workflow run. | `1` |
| `GITHUB_RUN_NUMBER` | A unique number for each run of a particular workflow. | `42` | | `GITEA_RUN_ID`<br/>`GITHUB_RUN_ID` | A unique number for each workflow run. | `1234` |
| `GITHUB_SERVER_URL` | The URL of the Gitea instance. | `https://gitea.com` | | `GITEA_RUN_NUMBER`<br/>`GITHUB_RUN_NUMBER` | A unique number for each run of a particular workflow. | `42` |
| `GITHUB_SHA` | The commit SHA that triggered the workflow. | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` | | `GITEA_SERVER_URL`<br/>`GITHUB_SERVER_URL` | The URL of the Gitea instance. | `https://gitea.example.com` |
| `GITHUB_WORKFLOW` | The name of the workflow. | `CI` | | `GITEA_SHA`<br/>`GITHUB_SHA` | The commit SHA that triggered the workflow. | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` |
| `GITHUB_WORKSPACE` | The default working directory on the runner. | `/workspace/gitea/docs` | | `GITEA_STATE`<br/>`GITHUB_STATE` | Path to the file that sets step state variables. | `/var/run/act/workflow/statecmd.txt` |
| `GITEA_STEP_SUMMARY`<br/>`GITHUB_STEP_SUMMARY` | Path to the file for writing job summaries. | `/var/run/act/workflow/step-summary-0.md` |
| `GITEA_TRIGGERING_ACTOR`<br/>`GITHUB_TRIGGERING_ACTOR` | The username of the user that initiated the workflow run. May differ from `GITEA_ACTOR` on re-runs. | `alice` |
| `GITEA_WORKFLOW`<br/>`GITHUB_WORKFLOW` | The name of the workflow. | `CI` |
| `GITEA_WORKFLOW_SHA`<br/>`GITHUB_WORKFLOW_SHA` | The commit SHA of the workflow file. | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` |
| `GITEA_WORKSPACE`<br/>`GITHUB_WORKSPACE` | The default working directory on the runner. | `/workspace/owner/repo` |
| `TRACEPARENT` | The W3C trace context of the job's span, so instrumented tools can add spans to the job's trace. Only set when the runner exports traces, see [Monitoring](/runner/monitoring/#opentelemetry). | `00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01` |
| `TRACESTATE` | Vendor-specific trace data that accompanies `TRACEPARENT`. Only set when the trace carries any. | `rojo=00f067aa0ba902b7` |
### Runner environment variables ### Runner environment variables
| Name | Description | Example | | Name | Description | Example |
|---|---|---| |---|---|---|
| `ImageOS` | The OS and release of the job's image, read by `setup-*` actions. | `ubuntu24` |
| `RUNNER_ARCH` | The architecture of the runner. | `X64` | | `RUNNER_ARCH` | The architecture of the runner. | `X64` |
| `RUNNER_DEBUG` | Set to `1` when the `ACTIONS_STEP_DEBUG` secret is `true`, unset otherwise. | `1` |
| `RUNNER_ENVIRONMENT` | Always set to `self-hosted`. | `self-hosted` |
| `RUNNER_NAME` | The name of the runner executing the job. | `my-runner` |
| `RUNNER_OS` | The operating system of the runner. | `Linux` | | `RUNNER_OS` | The operating system of the runner. | `Linux` |
| `RUNNER_TEMP` | Path to a temporary directory on the runner. | `/tmp` | | `RUNNER_TEMP` | Path to a temporary directory on the runner. | `/tmp` |
| `RUNNER_TOOL_CACHE` | Path to the tool cache directory on the runner. | `/opt/hostedtoolcache` | | `RUNNER_TOOL_CACHE` | Path to the tool cache directory on the runner. | `/opt/hostedtoolcache` |
| `RUNNER_WORKSPACE` | The parent directory of `GITEA_WORKSPACE`. | `/workspace/owner` |
### Internal environment variables ### Internal environment variables
@@ -64,11 +78,11 @@ These are used internally by the runner and actions. They are typically not need
| Name | Description | Example | | Name | Description | Example |
|---|---|---| |---|---|---|
| `ACTIONS_CACHE_URL` | URL for the actions cache service. | `http://192.168.1.10:8088/` | | `ACTIONS_CACHE_URL` | URL for the actions cache service. | `http://192.168.1.10:8088/` |
| `ACTIONS_ID_TOKEN_REQUEST_TOKEN` | Token for OIDC requests. Only set when configured. | `***` | | `ACTIONS_ID_TOKEN_REQUEST_TOKEN` | Token for OIDC requests. Only set when `id-token: write` is granted. | `***` |
| `ACTIONS_ID_TOKEN_REQUEST_URL` | URL to request OIDC tokens. Only set when configured. | `https://gitea.com/login/oauth/access_token` | | `ACTIONS_ID_TOKEN_REQUEST_URL` | URL to request OIDC tokens. Only set when `id-token: write` is granted. | `https://gitea.example.com/api/actions/oidc/token?` |
| `ACTIONS_RESULTS_URL` | URL for storing artifacts. | `https://gitea.com` | | `ACTIONS_RESULTS_URL` | URL for storing artifacts. | `https://gitea.example.com` |
| `ACTIONS_RUNTIME_TOKEN` | Authentication token for the Actions pipeline API. | `***` | | `ACTIONS_RUNTIME_TOKEN` | Authentication token for the Actions pipeline API. | `***` |
| `ACTIONS_RUNTIME_URL` | URL for the Gitea Actions pipeline API. | `https://gitea.com/api/actions_pipeline/` | | `ACTIONS_RUNTIME_URL` | URL for the Gitea Actions pipeline API. | `https://gitea.example.com/api/actions_pipeline/` |
## Context variables ## Context variables
@@ -76,39 +90,39 @@ These variables are available in workflow expressions via `${{ gitea.<name> }}`.
| Name | Description | Example | | Name | Description | Example |
|---|---|---| |---|---|---|
| `gitea.action`<br/>`github.action` | The name of the action currently running, or the `id` of a step. | `__run` | | `gitea.action`<br/>`github.action` | The `id` of the current step, or its index when it has none. | `0` |
| `gitea.action_path`<br/>`github.action_path` | The path where an action is located. Only supported in composite actions. | `/home/runner/work/_actions/actions/checkout/v4` | | `gitea.action_path`<br/>`github.action_path` | The path where an action is located. Only supported in composite actions. | `/var/run/act/actions/***` |
| `gitea.action_ref`<br/>`github.action_ref` | The ref of the action being executed. | `v4` | | `gitea.action_ref`<br/>`github.action_ref` | The ref of the action being executed. | `v4` |
| `gitea.action_repository`<br/>`github.action_repository` | The owner and repository name of the action. | `actions/checkout` | | `gitea.action_repository`<br/>`github.action_repository` | The owner and repository name of the action. | `actions/checkout` |
| `gitea.action_status`<br/>`github.action_status` | The current result of a composite action. | `success` | | `gitea.action_status`<br/>`github.action_status` | The current result of a composite action. | `success` |
| `gitea.actor`<br/>`github.actor` | The username of the user that triggered the initial workflow run. | `silverwind` | | `gitea.actor`<br/>`github.actor` | The username of the user that triggered the initial workflow run. | `alice` |
| `gitea.api_url`<br/>`github.api_url` | The URL of the REST API. | `https://gitea.com/api/v1` | | `gitea.api_url`<br/>`github.api_url` | The URL of the REST API. | `https://gitea.example.com/api/v1` |
| `gitea.base_ref`<br/>`github.base_ref` | The target branch of a pull request. Only set for `pull_request` and `pull_request_target` events. | `main` | | `gitea.base_ref`<br/>`github.base_ref` | The target branch of a pull request. Only set for `pull_request` and `pull_request_target` events. | `main` |
| `gitea.env`<br/>`github.env` | Path on the runner to the file that sets environment variables from workflow commands. Unique to each step. | `/home/runner/work/_temp/_runner_file_commands/set_env_***` | | `gitea.env`<br/>`github.env` | Path on the runner to the file that sets environment variables from workflow commands. | `/var/run/act/workflow/envs.txt` |
| `gitea.event`<br/>`github.event` | The full event webhook payload as an object. See [Event payload](#event-payload). | `{...}` | | `gitea.event`<br/>`github.event` | The full event webhook payload as an object. See [Event payload](#event-payload). | `{...}` |
| `gitea.event_name`<br/>`github.event_name` | The name of the event that triggered the workflow run. | `push` | | `gitea.event_name`<br/>`github.event_name` | The name of the event that triggered the workflow run. | `push` |
| `gitea.event_path`<br/>`github.event_path` | Path on the runner to the file containing the full event webhook payload. | `/home/runner/work/_temp/_github_workflow/event.json` | | `gitea.event_path`<br/>`github.event_path` | Path on the runner to the file containing the full event webhook payload. | `/var/run/act/workflow/event.json` |
| `gitea.head_ref`<br/>`github.head_ref` | The source branch of a pull request. Only set for `pull_request` and `pull_request_target` events. | `feature-branch` | | `gitea.head_ref`<br/>`github.head_ref` | The source branch of a pull request. Only set for `pull_request` and `pull_request_target` events. | `feature-branch` |
| `gitea.job`<br/>`github.job` | The `job_id` of the current job. | `build` | | `gitea.job`<br/>`github.job` | The `job_id` of the current job. | `build` |
| `gitea.ref`<br/>`github.ref` | The fully-formed ref that triggered the workflow. | `refs/heads/main` | | `gitea.ref`<br/>`github.ref` | The fully-formed ref that triggered the workflow. | `refs/heads/main` |
| `gitea.ref_name`<br/>`github.ref_name` | The short ref name. | `main` | | `gitea.ref_name`<br/>`github.ref_name` | The short ref name. | `main` |
| `gitea.ref_protected`<br/>`github.ref_protected` | `true` if branch protections are configured for the ref that triggered the workflow run. | `true` | | `gitea.ref_protected`<br/>`github.ref_protected` | `true` if branch protections are configured for the ref that triggered the workflow run. | `true` |
| `gitea.ref_type`<br/>`github.ref_type` | The type of ref: `branch` or `tag`. | `branch` | | `gitea.ref_type`<br/>`github.ref_type` | The type of ref: `branch` or `tag`. | `branch` |
| `gitea.path`<br/>`github.path` | Path on the runner to the file that sets system `PATH` variables from workflow commands. Unique to each step. | `/home/runner/work/_temp/_runner_file_commands/add_path_***` | | `gitea.path`<br/>`github.path` | Path on the runner to the file that sets system `PATH` variables from workflow commands. | `/var/run/act/workflow/pathcmd.txt` |
| `gitea.repository`<br/>`github.repository` | The owner and repository name. | `gitea/docs` | | `gitea.repository`<br/>`github.repository` | The owner and repository name. | `owner/repo` |
| `gitea.repository_owner`<br/>`github.repository_owner` | The repository owner's username. | `gitea` | | `gitea.repository_owner`<br/>`github.repository_owner` | The repository owner's username. | `owner` |
| `gitea.repositoryUrl`<br/>`github.repositoryUrl` | The HTML URL to the repository. | `https://gitea.com/gitea/docs` | | `gitea.repositoryUrl`<br/>`github.repositoryUrl` | The HTML URL to the repository. | `https://gitea.example.com/owner/repo` |
| `gitea.retention_days`<br/>`github.retention_days` | The number of days that workflow run logs and artifacts are kept. | `90` | | `gitea.retention_days`<br/>`github.retention_days` | The number of days that artifacts are kept, empty when kept forever. | `90` |
| `gitea.run_id`<br/>`github.run_id` | A unique number for each workflow run within a repository. Does not change on re-run. | `1234` | | `gitea.run_id`<br/>`github.run_id` | A unique number for each workflow run within a repository. Does not change on re-run. | `1234` |
| `gitea.run_number`<br/>`github.run_number` | A unique number for each run of a particular workflow. Starts at 1 and increments with each new run. | `42` | | `gitea.run_number`<br/>`github.run_number` | A unique number for each run of a particular workflow. Starts at 1 and increments with each new run. | `42` |
| `gitea.run_attempt`<br/>`github.run_attempt` | A unique number for each re-run attempt. Starts at 1 and increments with each re-run. | `1` | | `gitea.run_attempt`<br/>`github.run_attempt` | A unique number for each re-run attempt. Starts at 1 and increments with each re-run. | `1` |
| `gitea.secret_source`<br/>`github.secret_source` | The source of a secret used in a workflow. Always `Actions` in Gitea. | `Actions` | | `gitea.secret_source`<br/>`github.secret_source` | The source of a secret used in a workflow. Always `Actions` in Gitea. | `Actions` |
| `gitea.server_url`<br/>`github.server_url` | The URL of the Gitea instance. | `https://gitea.com` | | `gitea.server_url`<br/>`github.server_url` | The URL of the Gitea instance. | `https://gitea.example.com` |
| `gitea.sha`<br/>`github.sha` | The commit SHA that triggered the workflow. | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` | | `gitea.sha`<br/>`github.sha` | The commit SHA that triggered the workflow. | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` |
| `gitea.token`<br/>`github.token` | A token to authenticate on behalf of the Gitea App installed on the repository. See [Token permissions](token-permissions.md). | `ghs_***` | | `gitea.token`<br/>`github.token` | A token to authenticate on behalf of the Gitea App installed on the repository. See [Token permissions](token-permissions.md). | `***` |
| `gitea.triggering_actor`<br/>`github.triggering_actor` | The username of the user that initiated the workflow run. May differ from `actor` on re-runs. | `silverwind` | | `gitea.triggering_actor`<br/>`github.triggering_actor` | The username of the user that initiated the workflow run. May differ from `actor` on re-runs. | `alice` |
| `gitea.workflow`<br/>`github.workflow` | The name of the workflow. If unnamed, the full path of the workflow file. | `CI` | | `gitea.workflow`<br/>`github.workflow` | The name of the workflow. If unnamed, the full path of the workflow file. | `CI` |
| `gitea.workspace`<br/>`github.workspace` | The default working directory on the runner and the default location of your repository when using the `checkout` action. | `/workspace/gitea/docs` | | `gitea.workspace`<br/>`github.workspace` | The default working directory on the runner and the default location of your repository when using the `checkout` action. | `/workspace/owner/repo` |
| `gitea.gitea_default_actions_url` | The default URL for downloading actions. Gitea-specific. | `https://github.com` | | `gitea.gitea_default_actions_url` | The default URL for downloading actions. Gitea-specific. | `https://github.com` |
### Event payload ### Event payload
@@ -124,11 +138,11 @@ These fields exist in almost every payload:
| Name | Description | Example | | Name | Description | Example |
|---|---|---| |---|---|---|
| `gitea.event.action` | The activity type. Only set for events that have activity types, see [supported events](faq.md#what-workflow-trigger-events-does-gitea-support). | `opened` | | `gitea.event.action` | The activity type. Only set for events that have activity types, see [supported events](faq.md#what-workflow-trigger-events-does-gitea-support). | `opened` |
| `gitea.event.repository.full_name` | The owner and name of the repository. | `gitea/docs` | | `gitea.event.repository.full_name` | The owner and name of the repository. | `owner/repo` |
| `gitea.event.repository.default_branch` | The default branch of the repository. | `main` | | `gitea.event.repository.default_branch` | The default branch of the repository. | `main` |
| `gitea.event.repository.private` | Whether the repository is private. | `false` | | `gitea.event.repository.private` | Whether the repository is private. | `false` |
| `gitea.event.repository.html_url` | The HTML URL of the repository. | `https://gitea.com/gitea/docs` | | `gitea.event.repository.html_url` | The HTML URL of the repository. | `https://gitea.example.com/owner/repo` |
| `gitea.event.sender.login` | The username of the user that triggered the event. Also available as `sender.username`. | `silverwind` | | `gitea.event.sender.login` | The username of the user that triggered the event. Also available as `sender.username`. | `alice` |
The remaining fields are specific to one or a few events: The remaining fields are specific to one or a few events:
@@ -143,12 +157,12 @@ The remaining fields are specific to one or a few events:
| `gitea.event.commits` | `push` | The commits contained in the push, each with `id`, `message`, `url`, `author`, `added`, `removed` and `modified`. | `[{...}]` | | `gitea.event.commits` | `push` | The commits contained in the push, each with `id`, `message`, `url`, `author`, `added`, `removed` and `modified`. | `[{...}]` |
| `gitea.event.head_commit.message` | `push` | The message of the most recent commit of the push. | `fix: broken link` | | `gitea.event.head_commit.message` | `push` | The message of the most recent commit of the push. | `fix: broken link` |
| `gitea.event.total_commits` | `push` | The number of commits in the push. Gitea-specific. | `3` | | `gitea.event.total_commits` | `push` | The number of commits in the push. Gitea-specific. | `3` |
| `gitea.event.compare_url` | `push` | The URL comparing `before` with `after`. GitHub names this field `compare`. | `https://gitea.com/gitea/docs/compare/a1b2c3d...e5f6a1b` | | `gitea.event.compare_url` | `push` | The URL comparing `before` with `after`. GitHub names this field `compare`. | `https://gitea.example.com/owner/repo/compare/a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2...f6e5d4c3b2a1f6e5d4c3b2a1f6e5d4c3b2a1f6e5` |
| `gitea.event.pusher.login` | `push` | The username of the user that pushed. | `silverwind` | | `gitea.event.pusher.login` | `push` | The username of the user that pushed. | `alice` |
| `gitea.event.forkee.full_name` | `fork` | The owner and name of the new fork. | `silverwind/docs` | | `gitea.event.forkee.full_name` | `fork` | The owner and name of the new fork. | `alice/repo` |
| `gitea.event.page` | `gollum` | The name of the wiki page. | `Home` | | `gitea.event.page` | `gollum` | The name of the wiki page. | `Home` |
| `gitea.event.number` | `issues`, `pull_request`, `pull_request_target`, `pull_request_review`, `pull_request_review_comment` | The index of the issue or pull request. Not set for `issue_comment`, use `gitea.event.issue.number` there. | `386` | | `gitea.event.number` | `issues`, `pull_request`, `pull_request_target`, `pull_request_review`, `pull_request_review_comment` | The index of the issue or pull request. Not set for `issue_comment`, use `gitea.event.issue.number` there. | `386` |
| `gitea.event.issue.number`<br/>`gitea.event.issue.title`<br/>`gitea.event.issue.body`<br/>`gitea.event.issue.state`<br/>`gitea.event.issue.labels`<br/>`gitea.event.issue.user.login` | `issues`, `issue_comment` | The issue the event happened on. | `Expand gitea.event in actions docs` | | `gitea.event.issue.number`<br/>`gitea.event.issue.title`<br/>`gitea.event.issue.body`<br/>`gitea.event.issue.state`<br/>`gitea.event.issue.labels`<br/>`gitea.event.issue.user.login` | `issues`, `issue_comment` | The issue the event happened on. | `Fix typo in README` |
| `gitea.event.comment.body` | `issue_comment` | The body of the comment. | `LGTM` | | `gitea.event.comment.body` | `issue_comment` | The body of the comment. | `LGTM` |
| `gitea.event.is_pull` | `issue_comment` | Whether the comment was made on a pull request. Gitea-specific, GitHub sets `issue.pull_request` on the issue object instead. | `true` | | `gitea.event.is_pull` | `issue_comment` | Whether the comment was made on a pull request. Gitea-specific, GitHub sets `issue.pull_request` on the issue object instead. | `true` |
| `gitea.event.pull_request.number`<br/>`gitea.event.pull_request.title`<br/>`gitea.event.pull_request.body`<br/>`gitea.event.pull_request.draft`<br/>`gitea.event.pull_request.merged`<br/>`gitea.event.pull_request.state`<br/>`gitea.event.pull_request.labels`<br/>`gitea.event.pull_request.user.login` | `pull_request`, `pull_request_target`, `pull_request_review`, `pull_request_review_comment` | The pull request the event happened on. | `Add caching to CI` | | `gitea.event.pull_request.number`<br/>`gitea.event.pull_request.title`<br/>`gitea.event.pull_request.body`<br/>`gitea.event.pull_request.draft`<br/>`gitea.event.pull_request.merged`<br/>`gitea.event.pull_request.state`<br/>`gitea.event.pull_request.labels`<br/>`gitea.event.pull_request.user.login` | `pull_request`, `pull_request_target`, `pull_request_review`, `pull_request_review_comment` | The pull request the event happened on. | `Add caching to CI` |
+42
View File
@@ -0,0 +1,42 @@
---
date: "2026-10-29T00:00:00+00:00"
slug: "code-search"
sidebar_position: 50
---
# Code Search
Search code in a single repository with the search box on the repository's code tab. To search across repositories, use the **Code** tab on the explore page or on a user or organization profile. Searching across repositories requires the [repository indexer](../administration/repo-indexer.md).
## Query syntax
A file is found when every term matches its content or its path. Matching ignores case and also finds terms inside longer words, so `port` matches `import`.
| Syntax | Example | Finds files that |
| --- | --- | --- |
| `term` | `getUser` | contain `getUser` |
| `term term` | `user cache` | contain both `user` and `cache` |
| `"phrase"` | `"func main()"` | contain the exact text, including spaces |
| `/regexp/` | `/get\w+User/` | have a line matching the regular expression |
| `path:DIR` | `path:src/utils` | are inside the `src/utils` directory |
| `language:NAME` | `language:go` | are written in Go |
| `repo:OWNER/NAME` | `repo:gitea/tea` | are in the `gitea/tea` repository |
| `user:NAME`, `org:NAME` | `org:gitea` | are in a repository owned by `gitea` |
- `repo:`, `user:` and `org:` only work when searching across repositories. Repeat them to search several, for example `repo:gitea/tea repo:gitea/act`.
- Regular expressions only work when the repository indexer is not enabled. They match one line at a time, so use `\s` for spaces, as a space separates terms.
- `language:` only works with the repository indexer.
- `AND`, `OR`, `NOT`, negated qualifiers like `-path:`, and qualifiers like `content:` or `extension:` are not supported and show an error.
## Results
Each file shows up to 10 snippets with the matches highlighted. Binary files are only found by their path.
Without the repository indexer, a search stops after 50 files and shows a notice. Narrow the query with more terms or `path:` to see the rest.
## API
- `GET /api/v1/repos/{owner}/{repo}/code/search?q=...` searches one repository. Set `ref` to search a branch, tag or commit other than the default branch. It always supports regular expressions, but not `language:`.
- `GET /api/v1/search/code?q=...` searches the default branches of all repositories you can read. It requires the repository indexer and does not support regular expressions.
Both return results in GitHub's format, including `text_matches` with the match positions. Results can be paged up to the 1000th file.
@@ -15,7 +15,7 @@ creating issues and pull requests. This will cut down on the initial back and fo
of getting some clarifying details. of getting some clarifying details.
It is currently not possible to provide generic issue/pull-request templates globally. It is currently not possible to provide generic issue/pull-request templates globally.
Additionally, the New Issue page URL can be suffixed with `?title=Issue+Title&body=Issue+Text` and the form will be populated with those strings. Those strings will be used instead of the template if there is one. Additionally, the New Issue page URL can be suffixed with `?title=Issue+Title&body=Issue+Text` and the form will be populated with those strings. Those strings will be used instead of the template if there is one. See [Pre-filling Issues and Pull Requests](prefill-issues-pull-requests.md) for all parameters.
## File names ## File names
@@ -0,0 +1,42 @@
---
date: "2026-10-17T00:00:00+00:00"
slug: "prefill-issues-pull-requests"
sidebar_position: 14
---
# Pre-filling Issues and Pull Requests
Links to the pages for creating issues and pull requests can pre-fill the form with query parameters.
This lets you link users from another app, a README or a project board to a form that is already categorized.
- New issue: `/{owner}/{repo}/issues/new?…`
- New pull request: `/{owner}/{repo}/compare/{base}...{head}?…`
For example, this link opens a new issue with a title, two labels and an assignee:
```
https://gitea.example.com/owner/repo/issues/new?title=Dashboard+crashes&label=kind/bug,area/dashboard&assignee=alice
```
## Parameters
| Parameter | Value |
| ------------- | --------------------------------------------------------------------------- |
| `title` | Title |
| `body` | Description |
| `label` | Comma-separated label IDs or names |
| `labels` | Alias of `label` |
| `milestone` | Milestone ID or name |
| `project` | Comma-separated project IDs or titles |
| `assignee` | Comma-separated user IDs or usernames |
| `template` | File name of the [template](issue-pull-request-templates.md) to use |
| `field:<id>` | Value of the field with this `id` in a YAML template |
IDs and names can be mixed and names are matched case-insensitively. Values that don't match anything in the repository are ignored.
Labels include the organization's labels, and closed milestones and projects can be selected too.
Milestones and projects are only offered to users who can write to issues or pull requests, so for other users these parameters have no effect.
The values from the link take precedence over the title, description, labels and assignees of the template.
When there are several issue templates to choose from, the parameters are passed through to the chosen one.
On the compare page, any of these parameters also opens the pull request form directly, as `expand=1` does.
+3 -2
View File
@@ -36,6 +36,7 @@ The following package managers are currently supported:
| [RubyGems](usage/packages/rubygems.md) | Ruby | `gem`, `Bundler` | | [RubyGems](usage/packages/rubygems.md) | Ruby | `gem`, `Bundler` |
| [Swift](usage/packages/swift.md) | Swift | `swift` | | [Swift](usage/packages/swift.md) | Swift | `swift` |
| [Terraform](usage/packages/terraform.md) | - | `terraform` | | [Terraform](usage/packages/terraform.md) | - | `terraform` |
| [Terraform Module](usage/packages/terraform-module.md) | - | `terraform`, `terragrunt` |
| [Vagrant](usage/packages/vagrant.md) | - | `vagrant` | | [Vagrant](usage/packages/vagrant.md) | - | `vagrant` |
**The following paragraphs only apply if Packages are not globally disabled!** **The following paragraphs only apply if Packages are not globally disabled!**
@@ -55,11 +56,11 @@ and shows a link to the repository on the package site (as well as a link to the
| Package owner type | User | Organization | | Package owner type | User | Organization |
|--------------------|------|--------------| |--------------------|------|--------------|
| **read** access | public, if user is public too; otherwise for this user only | public, if org is public, otherwise for org members only | | **read** access | public, if user is public too; otherwise for this user only | public, if org is public, otherwise for org members only |
| **write** access | owner only | org members with admin or write access to the org | | **write** access | owner only | members of a team with write access to packages |
Please note, that your respective package manager needs to have a [personal access token](development/api-usage.md#authentication) with the permissions `package` set to either Read or Read & Write to download and publish packages respectively. Please note, that your respective package manager needs to have a [personal access token](development/api-usage.md#authentication) with the permissions `package` set to either Read or Read & Write to download and publish packages respectively.
N.B.: These access restrictions are [subject to change](https://github.com/go-gitea/gitea/issues/19270), where more finegrained control will be added via a dedicated organization team permission. The packages permission of an organization team applies to all packages of the organization, regardless of the repositories assigned to the team.
## Create or upload a package ## Create or upload a package
+170
View File
@@ -0,0 +1,170 @@
---
date: "2026-06-09T00:00:00+00:00"
slug: "terraform-module"
sidebar_position: 119
---
# Terraform Module Registry
Publish [Terraform](https://www.terraform.io/) modules for your user or organization and use them
from Terraform or Terragrunt. The registry implements the
[HashiCorp module registry protocol](https://developer.hashicorp.com/terraform/internals/module-registry-protocol),
so modules are referenced with the usual `HOST/NAMESPACE/NAME/PROVIDER` address.
## Requirements
- The [Terraform CLI](https://developer.hashicorp.com/terraform/install) or
[Terragrunt](https://terragrunt.gruntwork.io/).
- **Your Gitea instance must be served over HTTPS with a valid certificate.**
Terraform and Terragrunt only perform module registry discovery over HTTPS and reject
plain HTTP — including `http://localhost`. This is a requirement of the protocol, not of Gitea.
A module is addressed by three segments:
| Segment | Meaning |
| ----------- | ------------------------------------------------------------- |
| `namespace` | The owner of the module: a Gitea user or organization name. It must follow the same rules as `name`, so owners with a `.` in their name cannot publish modules. |
| `name` | The module name. Letters, digits, `-` and `_`, starting and ending with a letter or digit, up to 64 characters. |
| `provider` | The main provider the module targets, e.g. `aws`. Lowercase letters and digits, up to 64 characters. |
Versions follow [semantic versioning](https://semver.org/) and are stored in canonical form: a
leading `v` is dropped and missing segments are padded, so `v1.2.3` and `1.2.3` address the same
version, and `1.2` becomes `1.2.0`.
## Packaging a module
A module is published as a single `.tar.gz` archive, stored and served exactly as uploaded. The
module's `.tf` files must therefore be at the **archive root**. A source tarball downloaded from a Git
host wraps everything in a `repository-version/` directory and is rejected — repackage the module
directory's contents instead:
```shell
tar -czf vpc-1.0.0.tar.gz -C path/to/module .
```
The root module's inputs, outputs, providers and `README` are shown on the package page. Each
submodule found under `modules/<name>` is listed with its source address and links to its own page,
which shows the install snippet for that submodule along with its inputs, outputs, providers and
`README`. Only one level is indexed, so `modules/<name>/<nested>` is not listed. Anything else,
including `examples/`, is kept in the archive but is not indexed. A module that is only a collection of
submodules, with no root module, is also accepted. Files in JSON syntax (`.tf.json`) are accepted too,
but only `.tf` files are indexed.
## Authentication
Create a [personal access token](development/api-usage.md#authentication) with the `read:package` scope to download
private modules, and `write:package` to publish or delete them. Add it to your Terraform CLI
configuration file (`~/.terraformrc` or `%APPDATA%/terraform.rc`):
```hcl
credentials "gitea.example.com" {
token = "<your token>"
}
```
Modules owned by a public user or organization can be downloaded without a token.
## Publishing a module
Upload an archive with a `PUT` request, sending the file as the raw request body. Use
`curl --upload-file` rather than `--data-binary`: the latter sends a form content type that
the registry will not accept as an archive.
```shell
curl --user "your_username:your_token" \
--upload-file vpc-1.0.0.tar.gz \
https://gitea.example.com/api/packages/-/terraform/modules/{namespace}/{name}/{provider}/{version}
```
| Parameter | Description |
| ----------- | -------------------------------------- |
| `namespace` | The owner (user or organization). |
| `name` | The module name. |
| `provider` | The provider the module targets. |
| `version` | The module version (semver). |
For example, to publish version `1.0.0` of the `vpc` module for the `aws` provider under the `acme`
organization:
```shell
curl --user "your_username:your_token" \
--upload-file vpc-1.0.0.tar.gz \
https://gitea.example.com/api/packages/-/terraform/modules/acme/vpc/aws/1.0.0
```
A successful upload returns `201 Created`. Published versions are immutable: uploading a version that
already exists returns `409 Conflict`. To replace a version, delete it first.
## Linking a module to a repository
A module always lives in a user or organization's package space — its namespace is that user or
organization, never a repository, because the registry address (`HOST/NAMESPACE/NAME/PROVIDER`) has no
repository segment. You cannot publish "into" a repository. Instead, a repository link is a display
association that surfaces the module on a repository's **Packages** tab. The workflow is:
1. **Publish** the module to the user or organization namespace, exactly as shown in
[Publishing a module](#publishing-a-module).
2. **Link** the package to a repository owned by that same user or organization: open the package,
go to its **Settings**, and select the repository (or use the
`POST /api/v1/packages/{owner}/terraform-module/{name}%2F{provider}/-/link/{repo}` API).
The link applies to the whole module — all of its versions, including ones published later — and can
be changed or removed at any time. It only affects where the module is listed in the UI; the address
used to consume it is unchanged (still `HOST/NAMESPACE/NAME/PROVIDER`, with no repository in it).
## Consuming a module
Reference the module by its registry address. With Terraform:
```hcl
module "vpc" {
source = "gitea.example.com/acme/vpc/aws"
version = "~> 1.0"
}
```
To use a submodule, append its path with the standard `//` separator:
```hcl
module "network" {
source = "gitea.example.com/acme/infra/google//modules/network"
version = "~> 1.0"
}
```
With Terragrunt, use the `tfr://` scheme and pass the version as a query parameter:
```hcl
terraform {
source = "tfr://gitea.example.com/acme/vpc/aws?version=1.0.0"
}
```
`terraform init` (or `terragrunt init`) resolves the address through the service discovery document
at `https://gitea.example.com/.well-known/terraform.json` and downloads the matching version.
## Deleting a version
```shell
curl --user "your_username:your_token" \
--request DELETE \
https://gitea.example.com/api/packages/-/terraform/modules/acme/vpc/aws/1.0.0
```
A successful delete returns `204 No Content`. This requires the `write:package` scope. There is no
separate deprecation flow — deleting a version removes it from the registry.
## Limits
The stored archive is bounded by the instance-wide package limits (`LIMIT_SIZE_TERRAFORM_MODULE` and
`LIMIT_TOTAL_OWNER_SIZE`) set by your Gitea administrator; see the
[configuration cheat sheet](../../administration/config-cheat-sheet.md#packages-packages).
Independently of those settings, an archive may not exceed **32 MiB decompressed**. The registry
reads the whole archive to index it, and stops with `413 Request Entity Too Large` past that ceiling,
so raising `LIMIT_SIZE_TERRAFORM_MODULE` above 32 MiB does not allow larger modules. Real modules are
kilobyte-scale, so this only affects archives carrying unrelated payloads.
A `README` larger than **1 MiB**, of the root module or of a submodule, is not shown on the package
page. The module is still accepted and the file stays in the archive.
+9
View File
@@ -0,0 +1,9 @@
{
"label": "Projects",
"position": 60,
"link": {
"type": "generated-index",
"slug": "/usage/projects",
"description": "Plan and track work with project boards"
}
}
+82
View File
@@ -0,0 +1,82 @@
---
date: "2025-11-25T18:58:22Z"
slug: "project-workflows"
sidebar_position: 1
description: "Automate project boards with event-driven filters and actions."
---
# Project Workflows
Project workflows automate a project board. When an issue or pull request in the project triggers an event, each enabled workflow for that event checks its filters and applies its actions. Workflows run in Gitea and need no runner.
## Edit workflows
1. Open a project and select **Workflows**.
2. Select an event in the sidebar.
3. Set filters and actions, then select **Save**. To change an existing workflow, select **Edit** first.
An event can have several workflows. **Clone** copies the selected workflow so you can adapt it to other items. **Disable** pauses a workflow and keeps its configuration. **Remove** deletes it.
## Events
| Event | Runs when | Filters | Actions |
| --- | --- | --- | --- |
| Item added to project | An item is added to the project or created in it | Apply to, labels | Move to column, labels, issue state |
| Item removed from project | An item is removed from the project | Apply to, labels | Labels, issue state |
| Item reopened | An item is reopened | Apply to, labels | Move to column, labels |
| Item closed | An item is closed | Apply to, labels | Move to column, labels |
| Item column changed | An item moves to another column | Apply to, columns, labels | Labels, issue state |
| Code changes requested | An official reviewer requests changes on a pull request | Labels | Move to column, labels |
| Code review approved | An official reviewer approves a pull request | Labels | Move to column, labels |
| Pull request merged | A pull request is merged | Labels | Move to column, labels |
## Filters
A workflow without filters runs for every item.
- **Apply to**: issues, pull requests, or both.
- **When moved from column**, **When moved to column**: the column the item left or entered.
- **Only if it has labels**: the item must have all selected labels.
## Actions
A workflow needs at least one action. Actions run in this order:
1. **Move to column**: moves the item to a column.
2. **Add labels**, **Remove labels**: changes the item's labels.
3. **Issue state**: closes or reopens the item. Workflows never reopen pull requests.
Workflow changes appear in the timeline as "Project workflow" followed by the event, and don't trigger other workflows. Workflows don't run in closed projects or for items in archived repositories.
## Permissions
Anyone who can read a project can view its workflows. Managing them requires write access to the project and:
- Repository project: write access to the repository's issues and pull requests.
- Organization project: organization owner or site administrator.
- User project: the project's owner.
Access tokens limited to public repositories can't manage workflows for organization or user projects. Workflows apply their actions regardless of who triggered the event.
## API
Manage workflows under the project routes of a repository (`/repos/{owner}/{repo}/projects/{id}`), an organization (`/orgs/{org}/projects/{id}`) or the authenticated user (`/user/projects/{id}`):
| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `.../workflows` | List workflows |
| `GET` | `.../workflows/{workflow_id}` | Get a workflow |
| `POST` | `.../workflows` | Create a workflow |
| `PATCH` | `.../workflows/{workflow_id}` | Edit a workflow, omitted fields stay unchanged |
| `DELETE` | `.../workflows/{workflow_id}` | Delete a workflow |
A workflow has an `event` (`item_added_to_project`, `item_removed_from_project`, `item_reopened`, `item_closed`, `item_column_changed`, `code_changes_requested`, `code_review_approved` or `pull_request_merged`), an `enabled` flag, `filters` (`issue_type`, `source_column_id`, `target_column_id`, `label_ids`) and `actions` (`column_id`, `add_label_ids`, `remove_label_ids`, `issue_state`). Each event accepts only the filters and actions listed in [Events](#events).
## Example
To route new bug reports to triage, create a workflow for **Item added to project**:
- **Apply to**: Issues only
- **Only if it has labels**: `bug`
- **Move to column**: Triage
- **Add labels**: `needs-triage`
+69 -13
View File
@@ -9,25 +9,36 @@ aliases:
# Code Owners # Code Owners
Gitea maintains code owner files. It looks for it in the following locations in this order: Gitea reads the first CODEOWNERS file found at these locations, in order:
- `./CODEOWNERS` - `./CODEOWNERS`
- `./docs/CODEOWNERS` - `./docs/CODEOWNERS`
- `./.gitea/CODEOWNERS` - `./.gitea/CODEOWNERS`
And stops at the first found file. Pull requests use the base branch's rules. File views show owners from the commit
being viewed, including when browsing a branch, tag, or historical commit.
File format: `<regexp rule> <@user or @org/team> [@user or @org/team]...` ## Patterns and owners
Regexp specified in golang Regex format. Each rule contains a pattern followed by users or organization teams.
Regexp can start with `!` for negative rules - match all files except specified.
Patterns starting with `*` or containing `/*` are parsed as glob expressions.
General patterns are parsed as regular expressions.
A leading `!` inverts a match.
Special rule characters like space, backslash and `#` must be escaped with a backslash.
When using regexp, since backslash needs to be escaped in rule level, literal dot should be written as `\\.`
Example file: Example file:
```bash ```text
.*\\.go @user1 @user2 # This is comment *.js @alice @bob # This is an inline comment
doc/*.md @charles # Patterns starting with "*" or containing "/*" are parsed as glob
src/**/db*.py @david # Use "**" to match any-level sub directories
.*\\.go @user1 @user2 # General patterns are parsed as regexp
test\\..*\\.js @user3 # !!! Do remeber: NOT "test.*.js", only regexp can be used for such cases
# Comment too
# You can assigning code owning for users or teams # You can assigning code owning for users or teams
frontend/src/.*\\.js @org1/team1 @org1/team2 @user3 frontend/src/.*\\.js @org1/team1 @org1/team2 @user3
@@ -42,24 +53,69 @@ docs/(aws|google|azure)/[^/]*\\.(md|txt) @user8 @org1/team4
Code owners listed in this file will automatically be requested to review pull requests Code owners listed in this file will automatically be requested to review pull requests
that modify files matching at least one corresponding rule. that modify files matching at least one corresponding rule.
### Escaping ## Sections
You can escape characters `#`, ` ` (space) and `\` with `\`, like: A section heading can supply default owners for the rules that follow it:
```text
[Documentation] @org1/team-doc
*.md
README.md @alice
[Frontend] @bob
*.js
``` ```
Owners on a rule replace the section's default owners. Section names are
case-insensitive; repeated headings belong to the same section. For each file, the
last matching rule in each named section applies. Matching rules outside named
sections retain Gitea's existing behavior: they all apply.
## Review request annotations
Use `## review-request=true` or `## review-request=false` to control automatic
review requests. A line annotation overrides a section annotation, which overrides
the global value. When none is set, individual code owners receive automatic review
requests only if they watch the repository and include pull requests in their watch
preferences. Team-level requests are enabled by default. An explicit `true` requests
a review regardless of the individual owner's watch preferences; `false` disables
automatic requests for the rule.
```text
## review-request=false # global default for following rules
*.js @alice ## review-request=true # only this rule
[Documentation] @org1/team-doc ## review-request=true
*.md
private/* @bob ## review-request=false
```
A standalone annotation changes the global default for subsequent rules.
Annotations on section headings apply until the next heading. Ordinary comments
start with `#`, including comments after annotations.
Disabling review requests keeps code owners visible when viewing a file and
does not waive approvals required by branch protection.
## Escaping
You need to escape characters `#`, ` ` (space) and `\` with backslash `\`, e.g.:
```text
dir/with\#hashtag @user1 dir/with\#hashtag @user1
path\ with\ space @user2 path\ with\ space @user2
path/with\\backslash @user3 path/with\\backslash @user3
``` ```
Some character (`.+*?()|[]{}^$\`) should be escaped with `\\` inside regexp, like: Some regexp characters (`.+*?()|[]{}^$\`) should be escaped with `\\`, e.g.:
``` ```
path/\\.with\\.dots path/\\.with\\.dots
path/with\\+plus path/with\\+plus
``` ```
### Branch Protection Rules ## Branch Protection Rules
When setting up branch protection rules, you may choose to enforce code owner approval of When setting up branch protection rules, you may choose to enforce code owner approval of
modified files. This will block a PR from being merged until at least one code owner modified files. This will block a PR from being merged until at least one code owner
@@ -67,7 +123,7 @@ has given approval for every applicable rule listed in the `CODEOWNERS` file.
For example, say you have the following `CODEOWNERS` file: For example, say you have the following `CODEOWNERS` file:
```bash ```text
.*\\.go @Bob .*\\.go @Bob
.*\\.md @Sally @Chris .*\\.md @Sally @Chris
migrations/.* @Alice migrations/.* @Alice
Loaded 50 of 1780 files, more files were not shown because too many files have changed in this diff. Show more