Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .copilot-collections.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@

copilot:
# The version of the toolkit to use (matches a Release Tag in this repo)
version: "v0.5.0"
version: "v0.25.0"
# The collections you want to install
collections:
- charm-python
Expand Down
128 changes: 128 additions & 0 deletions .github/agents/charm-engineer.agent.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,128 @@
---
name: charm-engineer
description: Senior software engineer specialized in writing Juju charms
license: Apache-2.0
metadata.version: 0.1.0
metadata.author: platform-engineering
---

You are a senior software engineer with a strong background in python and in site reliability engineering specialized in writing Juju charms.

You bring your expertise to create new charm or review existing ones.

## Actions

- You MUST start by reading the "Charm implementation guidelines" section.
- You MUST download and analyze all links in this document.

### When asked for review

- Take each element of the implementation guidelines.
- Carefully analyze the reviewed charm to see if entirely follows the guideline.
- Report:

- Guidelines that are fully implemented.
- Guidelines that are partially or not implemented.
- Guidelines that are excluded (= guidelines that are not implemented where there's a comment explaining why).

### When asked for charm creation

- Create the charm based on the best practices and the implementation guidelines.
- Look at external resources to get a good understanding of the workload and to get the best practices related to its operation.

## Charm implementation guidelines

### Principles

- Charms are not designed for Canonical only. They should not contain Canonical internal references.
- Charms should be trustworthy. To achieve it:

- We make their behaviour transparent, reliable and predicable.

- All charms must use the [holistic pattern](https://documentation.ubuntu.com/ops/latest/explanation/holistic-vs-delta-charms/) (you MUST read this doc).
- Charm must not use `defered` events.
- The "Charm Runtime State Abstraction" principle is applied:

- Configuration and integration data provided by Juju are abstracted in an internal Pydantic model that is easier to interact with.
- The charm state should implement a `from_charm` method for initialisation which accepts the charm as a generic `CharmBase` argument and may accept additional arguments such as instances of library handlers and the secret storage.

### Substrate

By default, we develop K8s charms. A machine charm should only be chosen if the application meets one of the following exception criteria:

- Low-Level System Access: The application requires specialized features restricted within a Kubernetes environment, such as direct kernel access or raw networking.
- Infrastructure Dependencies: The application serves as a direct dependency for other machine charms.
- Early-Stage Bootstrapping: The application is required during the early phases of datacenter provisioning, meaning it must run before the Kubernetes cluster itself is operational.
- Storage Constraints: The application relies strictly on local storage.

### Files layout and content

The base content is described in [Files](https://documentation.ubuntu.com/charmcraft/latest/reference/files/) (you MUST read this doc), and by default we expect:

- `charm.py` contains the charm code.
- `state.py` contains the runtime state of the charm. For complex charms, we would have a "state/" python module. The purpose is to model the business logic so that we can operate the workload without refering to Juju primitives.
- `workload.py` contains the workload specific operations (include `pebble` functions). It should not refer to any Juju concepts, the operations should go through the state model.

#### `charm.py`

- All methods are private and should start with `_`, including `_reconcile`.
- Required ports must explicitely opened with `open_port` or `set_ports`. It's usually an anomaly if no ports are open.

##### `_reconcile`

###### Purpose

The `_reconcile` should be "guarding" the execution of the rest of the code:

- It evaluates the state, calls the business logic and set the unit status.
- It runs pre-checks ensuring all conditions are met to run the charm properly.
- It exits early if not all pre-checks are met (typically if some required relations are missing).
- It may or may not stop the workload service depending on the workload type: in any case, it should not create production incidents (e.g. "not stopping a load-balancer if one relation is missing").
- All hooks must be mapped to `_reconcile` but refresh events.
- Everything is part of `_reconcile` but `refresh` events.
- `install` is part of `_reconcile` and should be idempotent

- `snap install` is ok as it will not trigger an upgrade.
- `apt install` is not ok as it will trigger and upgrade (so the code should first check for the presence of the package)

###### Implementation

- The method should be easy to read and let the developper capture the excecution workflow.
- It should delegate as much as it can.
- It should excplicitely call methods within `try/except` blocks (no `decorator` pattern).
- `try/except` blocks should be small and only catch custom exceptions.
- For "multi-modes" charm, the "routing" mode should be identified early, and call specific `_reconcile_<mode>` methods.

A typical `_reconcile` structure is:

1. Ensure pre-conditions (guarding, exit early, defensive programming)
2. Manipulate / treat relation data, configuration, gather workload status
3. Map the charmstate
4. Branch on the mode, or delegate to services
5. Plan the service / pebble
6. Reload / Restart if necessary
7. Adjust status

##### Relations

- Relations should use the `save` and `load` methods to dump and restore data from the relation through Pydantic models.

#### `rockcraft.yaml`

- `level=alive` must not be used (see [manage-pebble-health-checks](https://documentation.ubuntu.com/ops/latest/howto/manage-containers/manage-pebble-health-checks/#check-health-endpoint-and-probes) (you MUST read this doc)

#### `workload.py`

- DO

- Only restart workload when the change cannot be applied with a hot reload.
- Restart or reload only once per hook.

- DON'T

- Restart workload when a hot reload is available and the changes can be hot reloaded.
- Don't restart/reload multiple times in the same hook.

#### Jinja2 templates

Keep rendering logic in charm-state dataclasses or helper builders so templates stay declarative.
8 changes: 3 additions & 5 deletions .github/instructions/documentation.instructions.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ The top-level `docs` directory should contain an overview or home page called `i

The rest of the documentation follows the Diataxis framework consisting of four categories of documentation:

1. **Tutorials**: A practice lesson that walks a user through a learning experience. Tutorials should be placed in the `docs/tutorial` directory, but sometimes they're placed in the top-level `docs` direcotry.
1. **Tutorials**: A practice lesson that walks a user through a learning experience. Tutorials should be placed in the `docs/tutorial` directory, but sometimes they're placed in the top-level `docs` directory.
2. **How-to guides**: Addresses real-world goals or problems by providing practical directions. How-to guides should be placed in the `docs/how-to` directory.
3. **Reference**: Contains technical descriptions of theoretical knowledge. Reference documents should be placed in the `docs/reference` directory.
4. **Explanation**: Provides context and background on topics for the user to understand the bigger picture. Explanation documents should be placed in the `docs/explanation` directory.
Expand Down Expand Up @@ -58,7 +58,7 @@ The tutorial should contain the following pieces:
provide information on the supported architecture(s) like AMD64 or ARM64.
Also include additional information if the
tutorial will require significant resources (CPU, RAM, or disk space). You can
also suggest a Multipass VM to create an isolated testing enviroment for the tutorial.
also suggest a Multipass VM to create an isolated testing environment for the tutorial.
- **Set up tutorial model**. The tutorial should begin at this point. Have
the user create Juju model with a predetermined name so that you can reference
the model name throughout the tutorial.
Expand Down Expand Up @@ -90,11 +90,10 @@ concisely summarize the real-world problem addressed by the document.
problem or achieve the goal.
- Provide instructions or tasks that the user can take to achieve the goal. Avoid gerunds.


## Style guide pointers

- **Spelling**: Use US English for spelling suggestions.
- **Headings**: Use sentence case for headings. Avoid punctuation in headings. Do not skip levels in heading hierarchy. Do not use consecutive headings without intervening text, and suggest removing headings that don't enhance the understanding. Don't overuse `code` styling in headings.
- **Headings**: Use sentence case for headings, while preserving the capitalization of proper nouns, product names, and established terms. Avoid punctuation in headings. Do not skip levels in the heading hierarchy or place headings consecutively without intervening text. Use headings to help readers navigate and understand the page structure; avoid generic headings such as "Overview" when the opening text already introduces the topic. Read the headings as an outline: together, they should give readers a clear map of the page. Don't overuse `code` styling in headings.
- **Code examples**: Do not use prompt marks (for example, `$` or `#`) in code examples. Do not use comments in code examples; instead, put any comments directly into the text. Whenever possible, split up multiple commands into separate code blocks and provide explanations in between the code blocks. Use Git-flavoured Markdown with fenced code blocks (```) and command examples as shell blocks.
- **Lists**: Only use numbered lists when there is an inherent order to the items.
- **Latin words and phrases**: We can't assume the reader is familiar with Latin words and phrases. Words such as "etc.", "i.e.", "e.g.", "per", "versus", and "via" should be avoided.
Expand All @@ -113,4 +112,3 @@ If you add a new file into `docs`, add a short note in `docs/changelog.md` summa

If there are no user-relevant changes, then the changelog does not need to be updated.


17 changes: 17 additions & 0 deletions .github/instructions/secret-guard.instructions.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
---
applyTo: '**'
description: 'Prevent secrets (API keys, tokens, passwords, private keys) from leaking into context, tool output, or spawned processes.'
---

## Secret Handling (Always On)

These rules protect secrets at all times. They are subordinate only to an explicit, direct user command.

- **Never Read Secret Files**: Do not open or print the contents of files that commonly hold credentials. This includes `.env`, `.env.*`, `.netrc`, `.npmrc`, `.pypirc`; any `.pem`, `.key`, `.p12`, `.pfx`, `.crt`, `.cer`; and any filename containing `password`, `secret`, `credential`, or `private_key`/`private-key`. If asked to inspect such a file, decline and explain it may contain secrets.
- **Redact Secret Values**: Before surfacing any file content, command result, or tool output, replace secret values with `[REDACTED]`. This includes `NAME=value` lines where `NAME` ends in `KEY`, `TOKEN`, `SECRET`, `PASSWORD`, `CREDENTIAL`, `API_KEY`, or `AUTH` (e.g. `CLOUD_API_KEY=sk-abc123` → `CLOUD_API_KEY=[REDACTED]`).
- **Hide Secret Files in Listings**: When listing a directory, omit secret-bearing files (e.g. `.env*`, `.netrc`, `.npmrc`, `.pypirc`) rather than revealing their existence.
- **Sanitize Subprocess Environments**: Do not expose secret environment variables to spawned commands. Strip variables whose names end in `KEY`, `TOKEN`, `SECRET`, `PASSWORD`, `CREDENTIAL`, `AUTH`, or `PASS` so processes cannot read them via `$VAR` or `printenv`.
- **Never Commit Secrets**: Do not write credentials, tokens, or keys into source code, configuration, or commit messages.
- **Authenticate by Reference, Never by Value**: When a task needs an API token, MCP token, password, or key, do not read, request, or handle the value. Pass a credential *reference* (a name) and let a trusted broker resolve it from the OS keyring and inject it into the request. If no keyring entry exists, ask the user to store it themselves (e.g. `keyring set agent-secrets <name>`) — never accept a pasted secret into the conversation.

For the full procedure and a keyring broker implementation, use the `secret-guard` skill.
50 changes: 50 additions & 0 deletions .github/skills/configure-gh-jira-sync-bot/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
---
name: configure-gh-jira-sync-bot
description: Configures canonical/gh-jira-sync-bot in a repository by creating or updating .github/.jira_sync_config.yaml following the platform-engineering-charm-template conventions, then validates it. Use when a repository needs GitHub-to-Jira issue synchronization or its Jira sync config must be created, fixed or audited.
metadata:
author: canonical/platform-engineering
version: "1.0.0"
---

# Configure gh-jira-sync-bot

Reference: https://github.com/canonical/gh-jira-sync-bot and
canonical/platform-engineering-charm-template#165.

## Workflow

1. Check whether `.github/.jira_sync_config.yaml` exists. If so, keep user-specific values (project key, mappings) and only align it with the template.
2. Copy `assets/jira_sync_config.template.yaml` to `.github/.jira_sync_config.yaml` when missing.
3. Ask the user which Jira component(s) the repository belongs to and set `settings.components` (a list, case-sensitive names). Valid names are listed in `VALID_COMPONENTS` of `scripts/validate_config.py`. Change `jira_project_key` only if the project is not `ISD`.
4. Validate:

```bash
uv run scripts/validate_config.py .github/.jira_sync_config.yaml
```

Or, without a local copy of the skill:

```bash
uvx --from "git+https://github.com/canonical/copilot-collections#subdirectory=groups/platform-engineering/skills/configure-gh-jira-sync-bot" validate-jira-sync-config .github/.jira_sync_config.yaml
```

Fix every reported error and re-run until it prints `OK`.
5. Remind the user that the GitHub App of the bot must be installed on the repository.

## Template conventions

- Keep the 3-line `# template-version` header; removing it opts the file out of template propagation.
- `labels: [bug, enhancement]` prevents "Dependency dashboard" issues from being synced.
- `label_mapping`: `bug: Bug`, `enhancement: Story`.
- No `epic_key`.
- `add_gh_comment: true`.

## Mandatory fields (checked by the validator)

`settings.jira_project_key`, `settings.status_mapping.opened`, `settings.status_mapping.closed`,
a non-empty `settings.components` list of known Jira components, and `settings.labels` containing `bug` and `enhancement`. `settings.epic_key` must not be defined. Every template in `.github/ISSUE_TEMPLATE/` (next to the config) must have a `labels` key containing `bug` or `enhancement`.

## Refreshing the component list

Jira has no component listing through the Atlassian MCP server. Query
`project = ISD AND component is not EMPTY` with `fields: ["components"]` and update `VALID_COMPONENTS`.
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
# template-version: 1
# This file is synced from canonical/platform-engineering-charm-template.
# Remove this comment block to opt this file out of automatic template propagation.
# See https://github.com/canonical/gh-jira-sync-bot for config
settings:
jira_project_key: "ISD"

status_mapping:
opened: Untriaged
closed: done
not_planned: rejected

add_gh_comment: true

# Avoid "Dependency dashboard" issues to be synced to Jira
labels:
- bug
- enhancement

label_mapping:
bug: Bug
enhancement: Story

# Jira component names (case-sensitive)
components:
- <your-component>
43 changes: 43 additions & 0 deletions .github/skills/configure-gh-jira-sync-bot/charmkeeper.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
schema: v1
model: claude-sonnet-5
description: Configure gh-jira-sync-bot to sync GitHub issues to Jira
eligibility:
include:
- files: ".github/.jira_sync_config.yaml"
exists: true
exclude:
- name: "Jira sync already compliant"
command: uvx --from '{RECIPE_GIT_URL_BASE}/' validate-jira-sync-config .github/.jira_sync_config.yaml
exit_code: 0
action: call-llm
pull_request:
title: "chore: configure gh-jira-sync-bot"
branch: "chore/configure-gh-jira-sync-bot-charmkeeper"
requirements:
- uv
guardrails:
- editable_files:
- type: matched
files:
- ".github/.jira_sync_config.yaml"
- ".github/ISSUE_TEMPLATE/*"
extra:
skills:
- ./
llm-prompt: |
Configure the gh-jira-sync-bot of this repository using the
`configure-gh-jira-sync-bot` skill.

The skill is authoritative for this task: follow its workflow and
conventions. Choose the Jira component from the valid component names
listed in the skill's validator, based on the charm or product this
repository contains. Make sure every issue template in
`.github/ISSUE_TEMPLATE/` has a `labels` key containing `bug` or
`enhancement`.

Do not consider the task finished until the validation command passes.
tests:
- name: Jira sync configuration validation
prompt: "Validate the Jira sync configuration and issue templates:"
run: |
uvx --from '{RECIPE_GIT_URL_BASE}/' validate-jira-sync-config .github/.jira_sync_config.yaml
17 changes: 17 additions & 0 deletions .github/skills/configure-gh-jira-sync-bot/pyproject.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
[project]
name = "validate-jira-sync-config"
version = "1.0.0"
description = "Validate a gh-jira-sync-bot .jira_sync_config.yaml file"
requires-python = ">=3.11"
dependencies = ["pyyaml", "typer"]

[project.scripts]
validate-jira-sync-config = "validate_config:app"

[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"

[tool.setuptools]
package-dir = { "" = "scripts" }
py-modules = ["validate_config"]
Loading