skip to content

A SwiftPM command plugin that reformats sources works on a laptop but fails in CI with a permission error; why, and how do you fix it?

level: seniorimportance: should knowfreq 30%

answer

  1. the sandbox asks first
  2. a terminal can answer, CI cannot
  3. the reason string is shown
  4. --allow-writing-to-package-directory

basics

~20 s

The plugin declares .writeToPackageDirectory(reason:), and SwiftPM grants that only after approval: at a terminal it asks yes or no, but without one it fails with an error. Grant it in CI by passing --allow-writing-to-package-directory to swift package.

solid answer

~40 s

On platforms that support it, SwiftPM runs plugins in a sandbox that blocks network access and writes outside a few allowed directories. A formatting plugin declares `.command(intent: .sourceCodeFormatting(), permissions: [.writeToPackageDirectory(reason:)])`. On a laptop, `swift package format-source-code` prints the plugin's stated reason and asks *Allow this plugin to write to the package directory? (yes/no)*. In CI there is no terminal, so SwiftPM cannot ask and stops with an error that names the remedy: `Use --allow-writing-to-package-directory to allow this.` Add that flag to the CI command. `--allow-writing-to-directory <path>` grants one extra directory and `--allow-network-connections <scope>` pre-approves a network permission declared with `.allowNetworkConnections(scope:reason:)`, tools version 5.9 and later. `--disable-sandbox` also skips the prompts, but it removes the sandbox altogether, which is more than the plugin asked for.

code

plaintext · 3 lines
plaintext
error: Plugin ‘FormatSources’ wants permission to write to the package directory.
Stated reason: “Rewrites Swift files in place”.
Use `--allow-writing-to-package-directory` to allow this.

go deeper

for a junior

Recall that a command plugin which writes to the package needs approval, and that --allow-writing-to-package-directory gives it without a prompt.

for a middle

Explain the sandbox, how a command plugin declares writeToPackageDirectory with a reason, and why a terminal can approve while CI cannot.

for a senior

Fix the CI job with the narrowest flag, scope network permissions properly, and reject --disable-sandbox as a shortcut.

for a principal

Set the team rule for plugins in CI: which permissions a pipeline may grant, and which plugins are trusted to receive them.

## The sandbox around plugins Swift Package Manager (SwiftPM) runs every plugin as a separate process. On platforms that support sandboxing, it wraps that process in a sandbox that prevents network access and writes to arbitrary locations; every plugin can still write to a temporary directory and to its own work directory. A **command plugin**, the kind run with `swift package <verb>`, can ask for more by declaring **permissions** in its capability. **Build tool plugins** cannot declare any, so a plugin that must rewrite checked-in files is always a command plugin. ## Declaring the permission ```swift .plugin( name: "FormatSources", capability: .command( intent: .sourceCodeFormatting(), permissions: [ .writeToPackageDirectory(reason: "Rewrites Swift files in place") ] ) ) ``` The `reason` string is shown to whoever is asked to approve, so it should say exactly what the plugin will change. The `.sourceCodeFormatting()` intent gives the plugin the verb `format-source-code`. ## What SwiftPM does when the plugin is invoked When `swift package format-source-code` runs, SwiftPM checks each declared permission: 1. If a flag on the command line already grants it, SwiftPM proceeds without asking. 2. If standard output is a terminal, SwiftPM prints the plugin's name and stated reason and asks `Allow this plugin to write to the package directory? (yes/no)`. Any answer other than `yes` stops it with `Plugin was denied permission to write to the package directory.` 3. If there is no terminal, as in a CI job, SwiftPM cannot ask, so it fails with the problem, the stated reason and the remedy. That is the whole laptop-versus-CI difference: the same plugin, the same permission, but only one environment can answer the question. ## The CI fix Pass the grant explicitly in the job: - `--allow-writing-to-package-directory` approves `writeToPackageDirectory` without a prompt, which is what SwiftPM's own error suggests. - `--allow-writing-to-directory <path>` adds one more writable directory, for a plugin that writes a report outside the package. - `--allow-network-connections <scope>` pre-approves a declared network permission; the scope is `none`, `local`, `all`, `docker` or `unixDomainSocket`, and `local` and `all` can list ports, as in `all:443`. The flags are options of `swift package`, so both `swift package --allow-writing-to-package-directory format-source-code` and the explicit form `swift package plugin --allow-writing-to-package-directory format-source-code` work. Arguments after the verb, such as `--target AppModels`, go to the plugin. ## Network permissions Tools version 5.9 added `.allowNetworkConnections(scope:reason:)` for command plugins. The scope narrows what is allowed: | Scope | Allows | |---|---| | `.none` | nothing; SwiftPM does not prompt | | `.local(ports:)` | local network connections, optionally on listed ports | | `.all(ports:)` | local and outgoing connections, optionally on listed ports | | `.docker` | connections to Docker through Unix domain sockets | | `.unixDomainSocket` | connections to any Unix domain socket | The same approval flow applies: a prompt at a terminal, an error naming `--allow-network-connections` without one. ## What not to do - Do not pass `--disable-sandbox` to silence the prompt. SwiftPM skips permission prompts when the sandbox is disabled, but the plugin then runs with no sandbox at all. - Do not move the formatter into a build tool plugin to avoid the question; build tool plugins cannot modify package sources. - Do not pipe `yes` into the command in CI; without a terminal SwiftPM never asks, so the answer is never read. ## A CI job that uses the plugin well A formatting step in CI usually wants to fail the build when code is not formatted, not to commit fixes. A workable sequence: 1. Run `swift package --allow-writing-to-package-directory format-source-code`, so the plugin rewrites files in the job's checkout. 2. Ask version control whether any file changed; if so, print the diff and fail the job. 3. Leave committing to developers, who run the same verb locally and approve the prompt once per run. This keeps the grant as narrow as the plugin's declaration: write access to the package directory, for this one invocation, with no network and no disabled sandbox. If a later version of the plugin adds a network permission, the job fails again with a new error naming `--allow-network-connections`, which is the point: a new permission is a change the team reviews before CI grants it.

  • Why does the same command work on a developer's machine without any flag?
    At a terminal SwiftPM can ask. It prints the plugin's stated reason and waits for `yes`; the developer approves, and SwiftPM adds the package directory to the sandbox's writable locations for that run. CI has no terminal, so the same check turns into an error that names the flag.
  • How does a command plugin limit itself to the targets someone asked for?
    SwiftPM passes every argument after the verb to `performCommand(context:arguments:)`. The plugin reads `--target` values with `ArgumentExtractor.extractOption(named:)` and looks them up with `context.package.targets(named:)`, falling back to all targets when none were given. Xcode passes the targets selected in its interface the same way.

  • A reason string in the manifest is enough for SwiftPM to grant the permission silently.
  • Piping yes into swift package in CI answers the permission prompt.
  • Passing --disable-sandbox is the normal way to run a formatting plugin in CI.
  • Turning the formatter into a build tool plugin avoids the permission entirely.

Assumes SwiftPM 6.4; writeToPackageDirectory has existed since tools version 5.6, while allowNetworkConnections(scope:reason:) needs tools version 5.9 or later.