# Configuring Guardener

URL: https://chainguard-docs-preview-git-fix-learning-lab-jsonld.chainguard.app/chainguard/guardener/github/configuration.md
Last Modified: October 13, 2026
Tags: GitHub, Configuration

Understand Guardener's .chainguard/ configuration model and how to enable features per repository.


Guardener is configured entirely through files committed to a `.chainguard/` directory — either in each repository, or once at the organization level in your `.github` repository. This page explains the configuration model that all Guardener features share. For the specific options of each feature, refer to its dedicated page.

## The `.chainguard/` directory

Guardener reads its configuration from the `.chainguard/` directory at the root of each repository. Every feature has its own file:

```text
.chainguard/
├── actions.yaml   # Hardened Actions
├── images.yaml    # Container Image Suggestions and Container Image Migration
└── source.yaml    # Commit Verification
```

Because these files live in your repository, your configuration is reviewed through pull requests, versioned in git history, and audited like any other code change.

## Features are opt-in per repository

Installing the Chainguard App does not change any repository on its own. Each feature stays disabled until you add its configuration file and enable it. This means you can:

- Roll a feature out to one repository at a time.
- Try a feature in report-only or non-blocking mode before enforcing it.
- Keep different repositories on different configurations.

A repository with no `.chainguard/` files is unaffected by Guardener even when the app is installed and the organization is linked.

## Available features

| Feature                                                           | Config file                | What it does                                                                |
| ----------------------------------------------------------------- | -------------------------- | --------------------------------------------------------------------------- |
| [Hardened Actions](/chainguard/guardener/github/actions-security/)       | `.chainguard/actions.yaml` | Recommends and migrates GitHub Actions to hardened, SHA-pinned equivalents. |
| [Container Image Suggestions](/chainguard/guardener/github/image-suggestions/) | `.chainguard/images.yaml` | Recommends Chainguard container images for the images a pull request adds or changes. |
| [Container Image Migration](/chainguard/guardener/github/image-migration/) | `.chainguard/images.yaml` | Opens a pull request that replaces the images a repository already uses with Chainguard container images. |
| [Commit Verification](/chainguard/guardener/github/commit-verification/) | `.chainguard/source.yaml`  | Verifies that commits in a pull request are signed by an authorized signer. |

The `.chainguard/` directory also holds configuration for two other products that use the Chainguard App: a `ci.yaml` file or `ci/` directory for [Chainguard Checks](/chainguard/checks/configuration/), and a `develop.yaml` file for [Chainguard Workspaces](/chainguard/workspaces/session-environment/#use-a-chainguarddevelopyaml-file).

Additional features will be added over time, each with its own `.chainguard/` file and opt-in configuration.

## Organization-level configuration with the `.github` repository

Rather than committing `.chainguard/` files to every repository, you can define configuration once at the organization level. Guardener reads a `.chainguard/` directory from your organization's `.github` repository and applies it as the default for every repository in the organization.

The `.github` repository is a special repository that GitHub already uses for organization-wide defaults (such as community health files and default workflows). Guardener follows the same convention:

```text
.github/                # your organization's .github repository
└── .chainguard/
    ├── actions.yaml     # org-wide default for Hardened Actions
    ├── images.yaml      # org-wide default for Container Image Suggestions and Container Image Migration
    └── source.yaml      # org-wide default for Commit Verification
```

To use org-level configuration:

1. Create a repository named `.github` in your organization if you don't already have one.
2. Add the Chainguard App to the `.github` repository (or install it on **All repositories**).
3. Commit your `.chainguard/` configuration files to the default branch of the `.github` repository.

Once in place, every repository Guardener can access inherits this configuration without needing its own `.chainguard/` files.

### How repository and organization configuration combine

Configuration committed directly to a repository takes precedence over the organization-level configuration from the `.github` repository:

- A repository with its own `.chainguard/<feature>.yaml` file uses that file for the feature, ignoring the org-level default for it.
- A repository without a given feature file falls back to the org-level default in the `.github` repository.
- A feature that is configured in neither place stays disabled for the repository.

This lets you set a baseline for the whole organization and override it only where a specific repository needs different behavior.

> **Note:** Guardener reads the org-level configuration from the default branch (that is, `main`) of the `.github` repository, just as it does for per-repository configuration.

## Applying configuration changes

To add or update the Guardener configuration:

1. Create or edit the relevant file in `.chainguard/` on a branch.
2. Open a pull request with your change.
3. Merge the pull request. Guardener picks up the new configuration for subsequent events.

> **Note:** Guardener uses the repo's default branch (that is, `main`) for its configuration.

## Next steps

- **[Hardened Actions](/chainguard/guardener/github/actions-security/)** — Configure `.chainguard/actions.yaml`.
- **[Container Image Suggestions](/chainguard/guardener/github/image-suggestions/)** — Configure `.chainguard/images.yaml`.
- **[Container Image Migration](/chainguard/guardener/github/image-migration/)** — Add a `migrate` block to `.chainguard/images.yaml`.
- **[Commit Verification](/chainguard/guardener/github/commit-verification/)** — Configure `.chainguard/source.yaml`.