Workflows — Operational Playbooks¶

TL;DR — Step-by-step procedures for common infrastructure operations. Each workflow is self-contained and links to the wiki for facts.

How to use¶

Served by MCP: get_workflow_file(path="<verb-object>/index.md").
Each playbook is self-contained for its procedure — follow the steps in order.
Workflows link to the wiki for facts (accounts, layouts, URLs, Jenkins job identities); they do not restate them.
Use the **Trigger when**: ... hint on each entry below to pick the right playbook.

Resolving cross-references¶

A index.md may contain links to wiki pages using the filesystem-relative form ../../wiki/<category>/<file>.md#<anchor> (e.g. ../../wiki/security/secrets.md). These are NOT navigated automatically when the workflow is served over MCP — translate them as follows:

Link in the workflow	How to fetch
`../../wiki/<category>/<file>.md`	`get_wiki_file(path="<category>/<file>.md")`
`../../wiki/<category>/<file>.md#<anchor>`	`get_wiki_file(path="<category>/<file>.md")`, then look up the `<anchor>` section in the returned content
`scripts/<helper>`, `references/<doc>.md`, `assets/<file>` (paths relative to the workflow folder)	Fetch via `get_workflow_file(path="<verb-object>/<the relative path>")`

The ../../wiki/ prefix is a filesystem hint for editors (VS Code, Bitbucket web). Over MCP, strip it and route to the correct tool. <category> is one of organization, infrastructure, ci-cd, repositories, frontend, security, engineering-practices, observability, ai-tooling (see wiki/index.md).

Index¶

Kubernetes & Config¶

Configure service ConfigMap — Edit the K8s config files for a backend K8s service in ops-scripts (under k8s/<service>/), open a PR, and trigger the post-merge ConfigMap apply per detected environment. Trigger when: changing non-secret env vars for a backend K8s microservice (one deployed via ops-scripts/k8s/<service>/), updating its per-env ConfigMap, or reviewing which envs need a restart after a config merge. NOT for frontends — frontend env vars follow a different flow; see wiki/frontend/frontend-architecture.md → Changing configs per environment.
Configure service DNS / ingress — Add a Kubernetes ingress rule for a backend microservice in ops-k8s-infra for dev, rc, and/or sandbox, then open a PR. Trigger when: a backend service needs to be reachable from outside the cluster — exposing it as internal (VPN only), public, or gateway (CloudFront BFF). Also use when verifying whether a service already has an ingress rule in a given environment. NOT for production — prod DNS/ingress requires a DevOps ticket via the Service Desk. NOT for frontends — frontend routing is handled via CloudFront + S3, not K8s ingress.

Git & Pull Requests¶

Create Bitbucket Pull Request — Propose a ticket-prefixed branch name when needed, commit the current working-tree changes with the [TICKET] description format, push, and open a Bitbucket PR against dev (default) using the standard Securitize PR template, preserving default reviewers and excluding the author. Trigger when: the developer has local changes in a securitize_dev/* Bitbucket repo and phrases the ask as any of — "create a PR", "open a PR", "make a PR", "push and open a PR", "push these changes (and open the PR)", "commit and push this", "create a pull request for {TICKET}" — or their Spanish equivalents: "crear un PR", "abrir un PR", "armá el PR", "hacé el PR", "pushea(me) estos cambios", "quiero que crees un PR con estos cambios", "subí estos cambios y abrí el PR", "hacé commit y push". The workflow covers branch naming, commit format, push, and PR creation end-to-end — use it whenever any of those sub-steps are mentioned. NOT for ops-scripts ConfigMap changes — use configure-service-configmap instead; that workflow already handles branch, PR, and post-merge Jenkins apply as a single procedure.

Jira & Tickets¶

Create Jira Ticket — Conversational wizard that routes a new ticket to the right Securitize team / Jira project (using the wiki SSOT), picks an issue type from the project's real list, structures Acceptance Criteria in BDD (Given/When/Then), supports three states for optional sections (fill / TBD placeholder / skip), forces a preview with an adjustment loop, and only then creates the issue via the Atlassian MCP. Trigger when: anyone (engineering, product, QA, support, operations, PM) wants to open a new Jira ticket and phrases the ask as any of — "create a ticket", "open a Jira", "new issue for X", "file a bug", "open a bug report" — or their Spanish equivalents: "creá un ticket", "abrí un Jira", "armemos un ticket de X", "abrime un bug", "necesito un ticket nuevo". Also triggers when the user mentions a Securitize Jira project key (ON, ISR2, TA, BC, AO, OPS, CTD) with intent to create. NOT for commenting on existing tickets — call the Atlassian MCP comment tool (addCommentToJiraIssue) directly. NOT for transitioning ticket states (To Do → In Progress → Done) — call transitionJiraIssue directly. NOT for editing existing tickets — call editJiraIssue directly. NOT for JQL searches or queries — call searchJiraIssuesUsingJql directly. NOT for linking a PR to an existing ticket — that is the caller's responsibility (mention the ticket key in the PR title; see create-bitbucket-pr).

Cerebro Knowledge Base¶

Update cerebro-knowledge — Single contribution procedure for any change to securitize_dev/cerebro-knowledge: clone, branch from master with a flat (no-slash) name, edit per AGENTS.md, optionally test live by swapping the cerebro MCP's SEC_MCP_BITBUCKET_BRANCH env var, then open a PR. Trigger when: the developer wants to add or modify a skill, workflow, wiki page, or any artifact under securitize_dev/cerebro-knowledge. Common phrasings: "update cerebro", "add a skill", "add a workflow", "fix a wiki page", "contribute to cerebro-knowledge", "actualizar cerebro", "agregar una skill", "editar la wiki de cerebro". NOT for editing the service catalog under services/ — those files are auto-generated; do not commit hand-edits. NOT for changes to a microservice repo — this workflow only covers cerebro-knowledge itself; for service-code changes use create-bitbucket-pr (or the dedicated workflow for that area, where one exists).