# ActioConfig (/docs/api/interfaces/ActioConfig)



Defined in: [packages/core/src/config.ts:62](https://github.com/austenstone/actio/blob/2b01e694a0f76521d8c073f3c6a2e48917d2c9d9/packages/core/src/config.ts#L62)

Shape of an `actio.config.{ts,js,mjs,cjs,json}` file. Every field is optional;
a missing field falls back to the built-in default (and any explicit CLI flag
overrides the value here). See `defineConfig` for type-safe authoring.

## Properties [#properties]

### annotate? [#annotate]

```ts
optional annotate?: boolean;
```

Defined in: [packages/core/src/config.ts:84](https://github.com/austenstone/actio/blob/2b01e694a0f76521d8c073f3c6a2e48917d2c9d9/packages/core/src/config.ts#L84)

Append an `actio-annotate` job that, on failure, maps the failed step back
to its `.actio.yml` source line and emits workflow annotations. Requires the
source map. Default true.

***

### artifacts? [#artifacts]

```ts
optional artifacts?: object;
```

Defined in: [packages/core/src/config.ts:139](https://github.com/austenstone/actio/blob/2b01e694a0f76521d8c073f3c6a2e48917d2c9d9/packages/core/src/config.ts#L139)

Inline step-level `artifacts:` macro config. `uploader` is the action ref
emitted for the trailing upload step (then pinned like any other ref under
pin policy). Default "actions/upload-artifact\@v4".

#### uploader? [#uploader]

```ts
optional uploader?: string;
```

***

### coercion? [#coercion]

```ts
optional coercion?: CoercionMode;
```

Defined in: [packages/core/src/config.ts:127](https://github.com/austenstone/actio/blob/2b01e694a0f76521d8c073f3c6a2e48917d2c9d9/packages/core/src/config.ts#L127)

Global default mode for the YAML type-coercion guard that defends emitted
string scalars against YAML-1.1 coercion on the Actions runner (`no`→false,
`1:30`→90, `2024-01-01`→Date). `fix` single-quotes them, `warn` reports a
`yaml-coercion-trap` diagnostic, `off` disables it. An in-source root
`coercion:` key overrides this. Default "fix".

***

### files? [#files]

```ts
optional files?: string[];
```

Defined in: [packages/core/src/config.ts:86](https://github.com/austenstone/actio/blob/2b01e694a0f76521d8c073f3c6a2e48917d2c9d9/packages/core/src/config.ts#L86)

Glob patterns of `.actio.yml` files to compile when none are passed on the CLI.

***

### header? [#header]

```ts
optional header?: boolean;
```

Defined in: [packages/core/src/config.ts:76](https://github.com/austenstone/actio/blob/2b01e694a0f76521d8c073f3c6a2e48917d2c9d9/packages/core/src/config.ts#L76)

Prepend the "generated by Actio" banner. Default true.

***

### include? [#include]

```ts
optional include?: string[];
```

Defined in: [packages/core/src/config.ts:88](https://github.com/austenstone/actio/blob/2b01e694a0f76521d8c073f3c6a2e48917d2c9d9/packages/core/src/config.ts#L88)

Alias for `files`.

***

### injectionHoist? [#injectionhoist]

```ts
optional injectionHoist?: "off" | "warn" | "error" | "fix";
```

Defined in: [packages/core/src/config.ts:102](https://github.com/austenstone/actio/blob/2b01e694a0f76521d8c073f3c6a2e48917d2c9d9/packages/core/src/config.ts#L102)

Global default mode for the injection-hoist security pass that defuses
`${{ }}` script-injection in `run:` blocks. Per-block `injection-hoist:`
knobs override this. Default "fix".

***

### lint? [#lint]

```ts
optional lint?: "off" | "warn" | "error";
```

Defined in: [packages/core/src/config.ts:74](https://github.com/austenstone/actio/blob/2b01e694a0f76521d8c073f3c6a2e48917d2c9d9/packages/core/src/config.ts#L74)

Lint generated workflows with `actionlint`, mapping any finding back to its
`.actio.yml` source. `off` disables it (default); `warn` reports warnings
(exit 0); `error` fails the build (pairs well with `actio check` in CI).
This is output linting and is independent of the schema-gating `validate`
boolean. A missing `actionlint` binary is skipped gracefully.

***

### outDir? [#outdir]

```ts
optional outDir?: string;
```

Defined in: [packages/core/src/config.ts:64](https://github.com/austenstone/actio/blob/2b01e694a0f76521d8c073f3c6a2e48917d2c9d9/packages/core/src/config.ts#L64)

Directory generated workflows are written to. Default ".github/workflows".

***

### passes? [#passes]

```ts
optional passes?: Pass[];
```

Defined in: [packages/core/src/config.ts:90](https://github.com/austenstone/actio/blob/2b01e694a0f76521d8c073f3c6a2e48917d2c9d9/packages/core/src/config.ts#L90)

Extra transform passes merged into the built-in pipeline (ordered by `runsAfter`).

***

### permissions? [#permissions]

```ts
optional permissions?: 
  | PermissionsMode
  | PermissionsConfig;
```

Defined in: [packages/core/src/config.ts:147](https://github.com/austenstone/actio/blob/2b01e694a0f76521d8c073f3c6a2e48917d2c9d9/packages/core/src/config.ts#L147)

Least-privilege `permissions:` policy. `off` (default) is a no-op; `infer`
emits each job's computed minimal block (plus a top-level deny-all baseline);
`check` audits declared blocks and warns on over-grant (errors under
`actio check`). The object form adds an action -> scopes override table and
an opt-in `inferRunScopes` heuristic for `run:` steps.

***

### pin? [#pin]

```ts
optional pin?: "off" | PinConfig | "all";
```

Defined in: [packages/core/src/config.ts:133](https://github.com/austenstone/actio/blob/2b01e694a0f76521d8c073f3c6a2e48917d2c9d9/packages/core/src/config.ts#L133)

Pin-on-compile policy. An object configures it granularly; the sugar `"all"`
pins everything (including first-party) and `"off"` disables pinning entirely.
Default: third-party + docker pinned, first-party left on-tag.

***

### sourceMap? [#sourcemap]

```ts
optional sourceMap?: boolean;
```

Defined in: [packages/core/src/config.ts:78](https://github.com/austenstone/actio/blob/2b01e694a0f76521d8c073f3c6a2e48917d2c9d9/packages/core/src/config.ts#L78)

Emit a sidecar `<name>.yml.map` source map next to each workflow. Default true.

***

### strict? [#strict]

```ts
optional strict?: boolean;
```

Defined in: [packages/core/src/config.ts:119](https://github.com/austenstone/actio/blob/2b01e694a0f76521d8c073f3c6a2e48917d2c9d9/packages/core/src/config.ts#L119)

Opt-in strict YAML 1.2.2 source lint. When `true`, every YAML 1.1 merge key
(`<<`) in `.actio.yml` source is reported as a `yaml-merge-key` warning so a
repo can keep its source to a pure 1.2.2 style. Default `false` (permissive).
Lint-only: `<<` is still resolved and erased at parse, so emitted YAML is
identical with or without strict mode. Anchors and aliases (`&`/`*`) are
valid 1.2.2 and never flagged. The `--strict` CLI flag overrides this.

***

### target? [#target]

```ts
optional target?: ActioTarget;
```

Defined in: [packages/core/src/config.ts:96](https://github.com/austenstone/actio/blob/2b01e694a0f76521d8c073f3c6a2e48917d2c9d9/packages/core/src/config.ts#L96)

Output target capability profile.

* `legacy`: emits standard workflows with no native dependency lock block.
* `github-actions-native-dependencies-preview`: emits a native `dependencies:` block.

***

### unusedSymbols? [#unusedsymbols]

```ts
optional unusedSymbols?: "off" | "warn" | "error";
```

Defined in: [packages/core/src/config.ts:110](https://github.com/austenstone/actio/blob/2b01e694a0f76521d8c073f3c6a2e48917d2c9d9/packages/core/src/config.ts#L110)

Severity for dead-code diagnostics on declared-but-unreferenced `params`,
`fragments`, and `executors`. `off` disables the check; `warn` reports
warnings (default); `error` escalates them to build failures (pairs well
with `actio check` in CI). Suppress a single symbol with a `# actio-keep`
comment on its declaration.

***

### validate? [#validate]

```ts
optional validate?: boolean;
```

Defined in: [packages/core/src/config.ts:66](https://github.com/austenstone/actio/blob/2b01e694a0f76521d8c073f3c6a2e48917d2c9d9/packages/core/src/config.ts#L66)

Validate generated YAML against GitHub's workflow schema. Default true.


## Sitemap

Browse the full documentation: [Markdown sitemap](https://austenstone.github.io/actio/sitemap.md) · [XML sitemap](https://austenstone.github.io/actio/sitemap.xml)