### Local Kubernetes Cluster Setup

Source: https://github.com/akuity/kargo/blob/main/AGENTS.md

Create a local Kubernetes cluster for development using either kind or k3d. These commands automatically install the necessary tools if not already present.

```bash
make hack-kind-up          # Create local K8s cluster (or hack-k3d-up)
```

--------------------------------

### v1.8 Configuration Example

Source: https://github.com/akuity/kargo/blob/main/docs/docs/50-user-guide/60-reference-docs/30-promotion-steps/gha-dispatch-workflow.md

Example of the configuration structure for Kargo v1.8, including credentials, owner, and repository.

```yaml
config:
  credentials:
    secretName: github-credentials
  owner: myorg
  repo: my-app
  workflowFile: deploy.yml
  ref: main
```

--------------------------------

### Copy File Example

Source: https://github.com/akuity/kargo/blob/main/docs/docs/50-user-guide/60-reference-docs/30-promotion-steps/copy.md

This example demonstrates copying a specific Kustomization file from an overlay directory to the main source directory. This is often used to apply stage-specific configurations.

```yaml
steps:
- uses: copy
  config:
    inPath: ./overlay/stages/${{ ctx.stage }}/kustomization.yaml
    outPath: ./src/stages/${{ ctx.stage }}/kustomization.yaml
```

--------------------------------

### v1.9 Configuration Example

Source: https://github.com/akuity/kargo/blob/main/docs/docs/50-user-guide/60-reference-docs/30-promotion-steps/gha-dispatch-workflow.md

Example of the configuration structure for Kargo v1.9 and above, using repoURL instead of owner and repo.

```yaml
config:
  repoURL: https://github.com/myorg/my-app
  workflowFile: deploy.yml
  ref: main
```

--------------------------------

### Start Promo-Gater for Manual Intervention

Source: https://github.com/akuity/kargo/blob/main/hack/testing/promo-gater/README.md

Start the promo-gater server before triggering a promotion that includes an HTTP gate step. This allows you to manually inspect the state and press Enter to continue the promotion.

```bash
go run ./hack/testing/promo-gater/
# ... promotion reaches the http step and blocks ...
# Inspect state, force-push a branch, etc.
# Press Enter to continue
```

--------------------------------

### Promotion Process Example with Expressions

Source: https://github.com/akuity/kargo/blob/main/docs/docs/50-user-guide/60-reference-docs/40-expressions.md

This example demonstrates a promotion process that clones a repository, checks out branches, uses Kustomize for manifest rendering, and commits/pushes changes. It extensively uses pre-defined variables like `ctx`, `outputs`, and `vars` to parameterize the steps.

```yaml
promotionTemplate:
  spec:
    vars:
    - name: gitRepo
      value: https://github.com/example/repo.git
    - name: srcPath
      value: ./src
    - name: outPath
      value: ./out
    - name: targetBranch
      value: stage/${{ ctx.stage }}
    steps:
    - uses: git-clone
      config:
        repoURL: ${{ vars.gitRepo }}
        checkout:
        - fromFreight: true
          path: ${{ vars.srcPath }}
        - branch: ${{ vars.targetBranch }}
          create: true
          path: ${{ vars.outPath }}
    - uses: git-clear
      config:
        path: ${{ vars.outPath }}
    - uses: kustomize-set-image
      as: update-image
      config:
        path: ${{ vars.srcPath }}/base
        images:
        - image: public.ecr.aws/nginx/nginx
    - uses: kustomize-build
      config:
        path: ${{ vars.srcPath }}/stages/${{ ctx.stage }}
        outPath: ${{ vars.outPath }}
    - uses: git-commit
      as: commit
      config:
        path: ${{ vars.outPath }}
        message: ${{ outputs['update-image'].commitMessage }}
    - uses: git-push
      config:
        path: ${{ vars.outPath }}
        targetBranch: ${{ vars.targetBranch }}
    - uses: argocd-update
      config:
        apps:
        - name: example-${{ ctx.stage }}
          sources:
          - repoURL: ${{ vars.gitRepo }}
            desiredRevision: ${{ outputs.commit.commit }}
```

--------------------------------

### Install Kargo with kind

Source: https://github.com/akuity/kargo/blob/main/docs/docs/20-quickstart/index.md

Use this command to install Kargo, cert-manager, and Argo CD on a kind cluster. Ensure Helm v3.13.1+ is installed.

```shell
curl -L https://raw.githubusercontent.com/akuity/kargo/main/hack/quickstart/kind.sh | sh
```

--------------------------------

### Install Kargo with Custom Helm Values

Source: https://github.com/akuity/kargo/blob/main/docs/docs/40-operator-guide/20-advanced-installation/10-advanced-with-helm.md

Install Kargo using Helm, applying your customized values from a local file. Ensure the namespace is created and wait for the installation to complete.

```shell
helm install kargo \
  oci://ghcr.io/akuity/kargo-charts/kargo \
  --namespace kargo \
  --create-namespace \
  --values kargo-values.yaml \
  --wait
```

--------------------------------

### Full ServiceNow Integration Workflow Example

Source: https://github.com/akuity/kargo/blob/main/docs/docs/50-user-guide/60-reference-docs/30-promotion-steps/snow-update.md

This comprehensive example illustrates a typical workflow involving creating, querying, updating, and waiting for conditions on a ServiceNow Change Request, demonstrating the integration of multiple ServiceNow steps.

```yaml
steps:
  - as: snowcreate
    config:
      credentials:
        secretName: snow-creds
        type: api-token
      parameters:
        impact: "3"
        short_description: Deploy to ${{ ctx.stage }} complete for ${{ vars.imageRepo
          }}:${{ imageFrom(vars.imageRepo).Tag }}
        urgency: "3"
      tableName: change_request
      template:
        templateId: ed89b72c83c172104517e470ceaad30a
        type: standard
    uses: snow-create
  - as: snowquery
    config:
      credentials:
        namespace: kargo-demo
        secretName: snow-creds
        type: api-token
      query:
        number: ${{ task.outputs.snowcreate.number }}
      tableName: change_request
    uses: snow-query-records
  - as: snowupdate
    config:
      credentials:
        secretName: snow-creds
        type: api-token
      parameters:
        short_description: Update deployment for ${{ vars.imageRepo }}:${{
          imageFrom(vars.imageRepo).Tag }} to resolved
      tableName: change_request
      template:
        type: standard
      ticketId: ${{ task.outputs.snowquery.sys_id }}
    uses: snow-update
  - as: snow-wait-for-condition
    config:
      condition: state=-2
      credentials:
        namespace: kargo-demo
        secretName: snow-creds
        type: api-token
      tableName: change_request
      ticketId: ${{ task.outputs.snowquery.sys_id }}
    uses: snow-wait-for-condition
  - as: snowdelete
    config:
      credentials:
        secretName: snow-creds
        type: api-token
      tableName: change_request
      template:
        type: standard
      ticketId: ${{ task.outputs.snowquery.sys_id }}
    uses: snow-delete
```

--------------------------------

### Install Kargo with Docker Desktop

Source: https://github.com/akuity/kargo/blob/main/docs/docs/20-quickstart/index.md

Use this command to install Kargo, cert-manager, and Argo CD on Docker Desktop. Ensure Helm v3.13.1+ is installed.

```shell
curl -L https://raw.githubusercontent.com/akuity/kargo/main/hack/quickstart/install.sh | sh
```

--------------------------------

### Install Kargo with Helm

Source: https://github.com/akuity/kargo/blob/main/docs/docs/40-operator-guide/10-basic-installation.md

Install Kargo using the Helm chart with default configurations. Ensure you replace the placeholder values with the generated password hash and signing key.

```shell
helm install kargo \
  oci://ghcr.io/akuity/kargo-charts/kargo \
  --namespace kargo \
  --create-namespace \
  --set api.adminAccount.passwordHash=$hashed_pass \
  --set api.adminAccount.tokenSigningKey=$signing_key \
  --wait
```

--------------------------------

### Define a Promotion Task with Variables and Steps

Source: https://github.com/akuity/kargo/blob/main/docs/docs/50-user-guide/60-reference-docs/20-promotion-tasks.md

Example of a `PromotionTask` definition including task-wide input variables and a sequence of promotion steps.

```yaml
apiVersion: kargo.akuity.io/v1alpha1
kind: PromotionTask
metadata:
  name: open-pr-and-wait
  namespace: kargo-demo
spec:
  # Task-wide input variables
  vars:
  - name: repoURL
  - name: sourceBranch
  - name: targetBranch
    value: main

  # Sequence of promotion steps
  steps:
  - uses: git-open-pr
    as: open-pr
    config:
      repoURL: ${{ vars.repoURL }}
      createTargetBranch: true
      sourceBranch: ${{ vars.sourceBranch }}
      targetBranch: ${{ vars.targetBranch }}
```

--------------------------------

### Install Kargo with k3d

Source: https://github.com/akuity/kargo/blob/main/docs/docs/20-quickstart/index.md

Use this command to install Kargo, cert-manager, and Argo CD on a k3d cluster. Ensure Helm v3.13.1+ is installed.

```shell
curl -L https://raw.githubusercontent.com/akuity/kargo/main/hack/quickstart/k3d.sh | sh
```

--------------------------------

### Kargo Promotion Configuration Before v1.9

Source: https://github.com/akuity/kargo/blob/main/docs/docs/50-user-guide/60-reference-docs/30-promotion-steps/gha-wait-for-workflow.md

Example of a Kargo promotion configuration in v1.8, including the 'credentials', 'owner', and 'repo' fields.

```yaml
config:
  credentials:
    secretName: github-credentials
  owner: example
  repo: test
  runID: 12345
  expectedConclusion: success
```

--------------------------------

### Kargo Promotion Configuration After v1.9

Source: https://github.com/akuity/kargo/blob/main/docs/docs/50-user-guide/60-reference-docs/30-promotion-steps/gha-wait-for-workflow.md

Example of a Kargo promotion configuration in v1.9, demonstrating the use of 'repoURL' and the removal of the 'credentials' field.

```yaml
config:
  repoURL: https://github.com/example/test
  runID: 12345
  expectedConclusion: success
```

--------------------------------

### Use Built-in Promotion Step in a Task

Source: https://github.com/akuity/kargo/blob/main/docs/docs/50-user-guide/60-reference-docs/20-promotion-tasks.md

Example of a task step referencing a built-in promotion step like `git-clone` with its configuration.

```yaml
steps:
- uses: git-clone
  as: clone
  config:
    repoURL: ${{ vars.repoURL }}
    checkout:
    - branch: ${{ vars.targetBranch }}
      path: ./target
```

--------------------------------

### Start ngrok Tunnel for External Webhooks

Source: https://github.com/akuity/kargo/blob/main/docs/docs/60-contributor-guide/10-hacking-on-kargo.md

Use this command to configure and start a tunnel for the external webhooks server. This is useful for testing or working on the external webhooks server, allowing external traffic to reach it.

```shell
make hack-ngrok
```

--------------------------------

### Doc Tree Structure Example

Source: https://github.com/akuity/kargo/blob/main/docs/STYLE_GUIDE.md

Illustrates the recommended file and folder naming convention using numerical prefixes for ordering documents and sections.

```tree
.\n├── 10-akuity-platform\n│├── 10-portal.md\n│├── 20-architecture.md\n│├── 30-agent.md\n│└── index.md\n├── 20-getting-started\n│├── 10-create-argo-cd-instance.md\n│├── 20-connect-kubernetes-cluster.md\n│├── 30-configure-admin-user.md\n│├── 40-access-argo-cd-instance.md\n│└── _category_.json\n├── 30-how-to-guides\n│├── 10-changing-contexts.md\n│├── 20-upgrading-argo-cd.md\n│├── 30-enabling-notifications.md\n│├── 40-using-webhooks.md\n│├── 50-enabling-external-access.md\n│├── 60-managing-system-accounts.md\n│└── _category_.json\n├── 40-changelog.md\n└── 50-faq.md
```

--------------------------------

### Conditional Step Execution Example

Source: https://github.com/akuity/kargo/blob/main/docs/docs/80-release-notes/96-v1.3.0.md

Demonstrates how to conditionally execute a promotion step using an 'if' expression. The step is skipped if the expression evaluates to false.

```yaml
apiVersion: kargo.akuity.io/v1alpha1
kind: Stage
metadata:
  name: test
  namespace: kargo-demo
spec:
  # ...
  promotionTemplate:
    spec:
      steps:
      - uses: fake-step
        if: ${{ outputs.step1.someOutput == 'value' }}
```

--------------------------------

### Use Built-in Promotion Step

Source: https://github.com/akuity/kargo/blob/main/docs/docs/50-user-guide/60-reference-docs/15-promotion-templates.md

Example of defining a promotion step that utilizes a built-in Kargo step by referencing its name with the 'uses' key.

```yaml
steps:
- uses: step-name
```

--------------------------------

### Kustomize Repository Layout Example

Source: https://github.com/akuity/kargo/blob/main/docs/docs/50-user-guide/30-patterns/index.md

A common directory structure for a Git repository managed with Kustomize, featuring a base configuration and stage-specific overlays.

```console
.
├── base
│   ├── deploy.yaml
│   ├── kustomization.yaml
│   └── service.yaml
├── charts
│   └── kargo-demo
└── stages
    ├── prod
    │   └── kustomization.yaml
    ├── test
    │   └── kustomization.yaml
    └── uat
        └── kustomization.yaml
```

--------------------------------

### ProjectConfig Status with Webhook Receiver URLs

Source: https://github.com/akuity/kargo/blob/main/docs/docs/50-user-guide/20-how-to-guides/30-working-with-warehouses.md

Example status of a ProjectConfig resource showing the generated URLs for configured webhook receivers.

```yaml
apiVersion: kargo.akuity.io/v1alpha1
kind: ProjectConfig
metadata:
  name: kargo-demo
  namespace: kargo-demo
spec:
  # ... omitted for brevity ...
status:
  conditions:
  - lastTransitionTime: "2025-06-11T22:53:21Z"
    message: ProjectConfig is synced and ready for use
    observedGeneration: 1
    reason: Synced
    status: "True"
    type: Ready
  webhookReceivers:
  - name: my-first-receiver
    path: /webhook/github/804b6f6bb40eb1f0e371f971d71dd95549be4bc9cbf868046941115f44073c67
    url: https://kargo.example.com/webhook/github/804b6f6bb40eb1f0e371f971d71dd95549be4bc9cbf868046941115f44073c67
  - name: my-second-receiver
```

--------------------------------

### Configure Global ServiceAccount Namespaces

Source: https://github.com/akuity/kargo/blob/main/docs/docs/40-operator-guide/40-security/30-access-controls.md

Example configuration to enable Kargo to recognize ServiceAccounts in designated global namespaces for system-wide permissions.

```yaml
api:
 oidc:
   globalServiceAccounts:
     namespaces:
     - kargo-global-service-accounts
```

--------------------------------

### Build Static Documentation Site

Source: https://github.com/akuity/kargo/blob/main/AGENTS.md

Commands to build the static version of the Kargo documentation site. This involves installing dependencies and running the Docusaurus build process.

```bash
cd docs && pnpm install && pnpm build-gtag-plugin && docusaurus build
```

--------------------------------

### Create and Close GitHub Tracking Issue

Source: https://github.com/akuity/kargo/blob/main/docs/docs/50-user-guide/60-reference-docs/30-promotion-steps/gh-create-issue.md

This example demonstrates creating a GitHub issue at the start of a promotion and closing it when the promotion completes. It utilizes `gh-create-issue` to open the issue and `gh-update-issue` to close it, referencing the created issue number.

```yaml
steps:
- as: create-tracking-issue
  uses: gh-create-issue
  config:
    repoURL: https://github.com/myorg/myrepo
    title: "Promote ${{ imageFrom(vars.imageRepo).Tag }} to ${{ ctx.stage }}"
    body: |
      Automated promotion triggered by Kargo.

      - **Stage:** ${{ ctx.stage }}
      - **Image:** ${{ imageFrom(vars.imageRepo).RepoURL }}:${{ imageFrom(vars.imageRepo).Tag }}
      - **Promotion:** ${{ ctx.promotion }}
    labels:
    - promotion
    - "${{ ctx.stage }}"

# ... your promotion steps (git-clone, argocd-update, etc.) ...

- uses: gh-update-issue
  config:
    repoURL: https://github.com/myorg/myrepo
    issueNumber: ${{ outputs['create-tracking-issue'].number }}
    state: closed
```

--------------------------------

### Build and Serve Docs Natively

Source: https://github.com/akuity/kargo/blob/main/docs/docs/60-contributor-guide/10-hacking-on-kargo.md

Use this command to build and serve the documentation natively on your system. This method requires a variety of tools to be installed locally and is not recommended if a container can be used.

```shell
make serve-docs
```

--------------------------------

### Multi-Source Argo CD Application for Kargo

Source: https://github.com/akuity/kargo/blob/main/docs/docs/40-operator-guide/20-advanced-installation/20-advanced-with-argocd.md

Configure an Argo CD Application to use multiple sources for Kargo installation. The first source points to the Kargo Helm chart, and the second source references a Git repository containing a custom values.yaml file and additional manifests. This setup allows for customization and inclusion of other Kubernetes resources.

```yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: kargo
  namespace: argocd
spec:
  project: default
  destination:
    namespace: kargo
    server: https://kubernetes.default.svc
  sources:
    - repoURL: ghcr.io/akuity/kargo-charts
      chart: kargo
      targetRevision: <desired version of Kargo>
      helm:
        valueFiles:
          - $values/kargo/values.yaml
    - repoURL: https://github.com/example/repo.git
      targetRevision: main
      ref: values
      path: kargo/additional-manifests
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
    - CreateNamespace=true
```

--------------------------------

### Build and Serve Docs in Container

Source: https://github.com/akuity/kargo/blob/main/docs/docs/60-contributor-guide/10-hacking-on-kargo.md

Use this command to build and serve the documentation locally within a container. This is the recommended method for previewing doc changes.

```shell
make hack-serve-docs
```

--------------------------------

### Run Promo-Gater with Command Execution

Source: https://github.com/akuity/kargo/blob/main/hack/testing/promo-gater/README.md

Execute a command when the promotion step hits the gate. The command's output is returned as the response body. Use this to perform actions like rebasing or creating files.

```bash
go run ./hack/testing/promo-gater/ -- bash -c "cd /tmp/repo && git rebase main"
```

```bash
go run ./hack/testing/promo-gater/ -- sleep 30
```

```bash
go run ./hack/testing/promo-gater/ -- touch /tmp/gate-reached
```

--------------------------------

### Define Promotion Template with Variables and Steps

Source: https://github.com/akuity/kargo/blob/main/docs/docs/50-user-guide/60-reference-docs/15-promotion-templates.md

Example of a promotion template within a Stage configuration, showing global variables and a sequence of steps including git-clone and a custom task.

```yaml
apiVersion: kargo.akuity.io/v1alpha1
kind: Stage
metadata:
  name: test
  namespace: kargo-demo
spec:
  # ...
  promotionTemplate:
    spec:
      # Template-wide variables
      vars:
        - name: gitRepo
          value: https://github.com/example/repo.git

      # Sequence of promotion steps
      steps:
        - uses: git-clone
          config:
            repoURL: ${{ vars.gitRepo }}
            checkout:
            - branch: main
              path: ./src
        - task:
            name: update-manifests
            kind: PromotionTask
```

--------------------------------

### Update GitHub Issue Example

Source: https://github.com/akuity/kargo/blob/main/docs/docs/50-user-guide/60-reference-docs/30-promotion-steps/gh-update-issue.md

This example demonstrates closing an issue and applying new labels while removing an old one. It uses dynamic values for the issue number from freight metadata.

```yaml
steps:
# ... your promotion steps ...

- uses: gh-update-issue
  config:
    repoURL: https://github.com/myorg/myrepo
    issueNumber: ${{ freightMetadata(ctx.targetFreight.name)['github-issue-number'] }}
    state: closed
    addLabels:
    - released
    - "env-prod"
    removeLabels:
    - "env-staging"
```

--------------------------------

### ProjectConfig with Advanced Stage Selectors

Source: https://github.com/akuity/kargo/blob/main/docs/docs/50-user-guide/20-how-to-guides/20-working-with-projects.md

Demonstrates advanced promotion policies using exact names, regex patterns, and glob patterns for stage selection. Use exact names for the most secure option.

```yaml
---
apiVersion: kargo.akuity.io/v1alpha1
kind: Project
metadata:
  name: example
---
apiVersion: kargo.akuity.io/v1alpha1
kind: ProjectConfig
metadata:
  name: example
  namespace: example
spec:
  promotionPolicies:
  - stageSelector:
      # Apply to a specific stage by exact name
      name: prod-east
    autoPromotionEnabled: false
  - stageSelector:
      # Apply to all stages matching a regex pattern
      name: "regex:test-.*"
    autoPromotionEnabled: true
  - stageSelector:
      # Apply to all stages matching a glob pattern
      name: "glob:dev-*"
    autoPromotionEnabled: true
```

--------------------------------

### Basic HTTP GET Request

Source: https://github.com/akuity/kargo/blob/main/docs/docs/50-user-guide/60-reference-docs/30-promotion-steps/http.md

Make a GET request to an API and extract specific fields from the JSON response body. This is useful for fetching data and making it available to subsequent steps.

```yaml
steps:
# ...
- uses: http
  as: cat-facts
  config:
    method: GET
    url: https://www.catfacts.net/api/
    outputs:
    - name: status
      fromExpression: response.status
    - name: fact1
      fromExpression: response.body.facts[0]
    - name: fact2
      fromExpression: response.body.facts[1]
```

--------------------------------

### Registering a Promotion Step Runner in Go

Source: https://github.com/akuity/kargo/blob/main/AGENTS.md

Demonstrates self-registration of a promotion step runner using `init()`. This pattern is used with name-based component registries to make implementations available at runtime.

```go
// pkg/promotion/runner/builtin/file_copier.go
func init() {
    promotion.DefaultStepRunnerRegistry.MustRegister(
        promotion.StepRunnerRegistration{
            Name:  stepKindCopy,
            Value: newFileCopier,
        },
    )
}
```

--------------------------------

### Declarative Role Management Example

Source: https://github.com/akuity/kargo/blob/main/docs/docs/50-user-guide/50-security/20-access-controls/index.md

Example of creating a custom role declaratively using Kubernetes RBAC resources. This role grants permissions to promote into specific stages for users in a given group.

```yaml
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: promoter
  namespace: guestbook
  annotations:
    kargo.akuity.io/description: Permissions to promote into pre-prod Stages
    rbac.kargo.akuity.io/claims: '{"groups":["devops"]}'
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: promoter
  namespace: guestbook
rules:
- apiGroups:
  - kargo.akuity.io
  resources:
  - promotions
  verbs:
  - create
  - patch
  - update
- apiGroups:
  - kargo.akuity.io
  resources:
  - stages
  verbs:
  - promote
  resourceNames:
  - dev
  - staging
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: promoter
  namespace: guestbook
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: promoter
subjects:
- kind: ServiceAccount
  name: promoter
  namespace: guestbook
---
# This RoleBinding allows the promoter ServiceAccount to view project
# resources (without redefining read rules), by binding it to the

```

--------------------------------

### Build Kargo CLI from Source

Source: https://github.com/akuity/kargo/blob/main/docs/docs/60-contributor-guide/10-hacking-on-kargo.md

Execute this command to build the Kargo CLI executable. The resulting binary will be located at `bin/kargo-<os>-<arch>`.

```shell
make hack-build-cli
```

--------------------------------

### Example ClusterConfig Referencing a Secret

Source: https://github.com/akuity/kargo/blob/main/docs/docs/40-operator-guide/40-security/40-managing-secrets.md

This example demonstrates a Kubernetes Secret and a Kargo ClusterConfig resource. The ClusterConfig references the Secret by name, and Kargo implicitly understands it resides in the system resources namespace.

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: gh-wh-secret
  namespace: kargo-system-resources
  labels:
    kargo.akuity.io/cred-type: generic
data:
  secret: <base64-encoded secret>
---
apiVersion: kargo.akuity.io/v1alpha1
kind: ClusterConfig
metadata:
  # Note this resource is not namespaced
  name: cluster
spec:
  webhookReceivers: 
    - name: gh-wh-receiver
      github:
        # Referenced Secrets are implicitly known to be in
        # the system resources namespace (kargo-system-resources)
        secretRef:
          name: gh-wh-secret
```

--------------------------------

### Repository Layout for Writing Back to Main

Source: https://github.com/akuity/kargo/blob/main/docs/docs/50-user-guide/30-patterns/index.md

Illustrates a repository structure that separates input and output paths for promotion processes. This is crucial when writing promotion output back to the main branch to avoid feedback loops.

```console
.\n├── builds\n│   ├── guestbook\n│   │   ├── prod\n│   │   ├── test\n│   │   └── uat\n│   └── portal\n│       ├── prod\n│       ├── test\n│       └── uat\n└── src\n   ├── guestbook\n   │   ├── base\n   │   │   ├── deploy.yaml\n   │   │   ├── kustomization.yaml\n   │   │   └── service.yaml\n   │   └── stages\n│       ├── prod\n│       │   └── kustomization.yaml\n│       ├── test\n│       │   └── kustomization.yaml\n│       └── uat\n│           └── kustomization.yaml\n└── portal\n   ├── base\n   │   ├── deploy.yaml\n   │   ├── kustomization.yaml\n   │   └── service.yaml\n   └── stages\n         ├── prod\n│   └── kustomization.yaml\n│   ├── test\n│   └── kustomization.yaml\n│   └── uat\n│       └── kustomization.yaml\n    
```

--------------------------------

### Update GitHub Issue Comment Example

Source: https://github.com/akuity/kargo/blob/main/docs/docs/50-user-guide/60-reference-docs/30-promotion-steps/gh-issue-update-comment.md

This example demonstrates how to post an initial comment using `gh-issue-add-comment` and then update its content with `gh-issue-update-comment` after other promotion steps have completed. The `commentID` is sourced from the output of the previous step.

```yaml
steps:
- as: post-comment
  uses: gh-issue-add-comment
  config:
    repoURL: https://github.com/myorg/myrepo
    issueNumber: ${{ freightMetadata(ctx.targetFreight.name)['github-issue-number'] }}
    body: "Promotion to **${{ ctx.stage }}** is in progress..."

# ... your promotion steps ...

- uses: gh-issue-update-comment
  config:
    repoURL: https://github.com/myorg/myrepo
    commentID: ${{ outputs['post-comment'].commentID }}
    body: "Promotion to **${{ ctx.stage }}** completed successfully."
```

--------------------------------

### Adopt Pre-configured Namespace

Source: https://github.com/akuity/kargo/blob/main/docs/docs/50-user-guide/20-how-to-guides/20-working-with-projects.md

Example demonstrating adoption of a Namespace that's been pre-configured with a label unrelated to Kargo. The Namespace must be labeled with `kargo.akuity.io/project: "true"` to be eligible for adoption.

```yaml
apiVersion: v1
kind: Namespace
metadata:
  name: example
labels:
  kargo.akuity.io/project: "true"
  example.com/org: platform-eng
---
apiVersion: kargo.akuity.io/v1alpha1
kind: Project
metadata:
  name: example
spec:
  # ...
```

--------------------------------

### Example ClusterMessageChannel for Slack

Source: https://github.com/akuity/kargo/blob/main/docs/docs/40-operator-guide/35-cluster-configuration.md

This example demonstrates the structure of a ClusterMessageChannel resource configured to send notifications to a Slack channel. It requires a reference to a Kubernetes Secret containing the Slack API key and specifies the target channel ID.

```yaml
apiVersion: ee.kargo.akuity.io/v1alpha1
kind: ClusterMessageChannel
metadata:
  name: devops-team-slack
spec:
  # A reference to a Secret containing the Slack token. This is required for Slack. The Secret must
  # contain the following key:
  # - `apiKey`: The Slack token with permissions to post messages to the desired channel
  secretRef:
    # The name of the Secret in the cluster resources namespace
    name: slack-token
  # Configuration specific to Slack
  slack:
    # The Slack-specific channel ID to send messages to. This field is required
    channelID: C1234567890
```

--------------------------------

### Verify Project Creation using CLI

Source: https://github.com/akuity/kargo/blob/main/docs/docs/50-user-guide/20-how-to-guides/20-working-with-projects.md

Run this command to confirm that a project has been successfully created.

```shell
kargo get project <project>
```

--------------------------------

### Sample Input: Base values.yaml

Source: https://github.com/akuity/kargo/blob/main/docs/docs/50-user-guide/60-reference-docs/30-promotion-steps/yaml-merge.md

This is a sample base YAML file for the `yaml-merge` step.

```yaml
service:
  enabled: false
```

--------------------------------

### GetConfigMapRequest

Source: https://github.com/akuity/kargo/blob/main/docs/docs/90-api-documentation.md

Request for getting a specific project-level, system-level, or shared ConfigMap.

```APIDOC
## GetConfigMapRequest

### Description
Request for getting a specific project-level, system-level, or shared ConfigMap.

### Request Body
- **system_level** (bool) - Indicates whether the request is to get a system-level ConfigMap.
- **project** (string) - The name of the project in which to get the ConfigMap. Ignored if system_level is true.
- **name** (string) - The name of the ConfigMap to retrieve.
- **format** (RawFormat) - Specifies the desired response format (structured object or raw YAML).
```

--------------------------------

### Comment Template Example

Source: https://github.com/akuity/kargo/blob/main/pkg/governance/README.md

Illustrates a comment action using Go's text/template syntax, demonstrating how to include variables like issue numbers and repository details in bot comments.

```yaml
comment: |
  Closing as a duplicate of #{{.Arg}}. See
  https://github.com/{{.RepoFullName}}/issues/{{.Arg}}.
```

--------------------------------

### Example Warehouse Subscription

Source: https://github.com/akuity/kargo/blob/main/docs/docs/50-user-guide/20-how-to-guides/30-working-with-warehouses.md

A Warehouse subscribing to both a container image repository and a Git repository.

```yaml
apiVersion: kargo.akuity.io/v1alpha1
kind: Warehouse
metadata:
  name: my-warehouse
  namespace: kargo-demo
spec:
  subscriptions:
  - image:
      repoURL: public.ecr.aws/nginx/nginx
      constraint: ^1.26.0
  - git:
      repoURL: https://github.com/example/kargo-demo.git

```

--------------------------------

### Delete k3d Cluster

Source: https://github.com/akuity/kargo/blob/main/docs/docs/20-quickstart/index.md

Command to delete a Kubernetes cluster created with k3d for the Kargo quickstart.

```shell
k3d cluster delete kargo-quickstart
```

--------------------------------

### Delete kind Cluster

Source: https://github.com/akuity/kargo/blob/main/docs/docs/20-quickstart/index.md

Command to destroy a Kubernetes cluster created with kind for the Kargo quickstart.

```shell
kind delete cluster --name kargo-quickstart
```

--------------------------------

### Retrieve token details

Source: https://github.com/akuity/kargo/blob/main/docs/docs/50-user-guide/50-security/25-api-tokens.md

Get detailed information about a specific token. The token value itself will be redacted in the output.

```shell
kargo get token --project my-project my-role-token -o yaml
```

--------------------------------

### Create and Update Jira Issue in Promotion

Source: https://github.com/akuity/kargo/blob/main/docs/docs/50-user-guide/60-reference-docs/30-promotion-steps/jira.md

This example demonstrates creating a new Jira issue for a promotion and then updating its status using the issue key from the creation step. It shows how to configure credentials, project details, issue type, assignee, and labels for creation, and how to reference the created issue's key for subsequent updates.

```yaml
apiVersion: kargo.akuity.io/v1alpha1
kind: Stage
# ...
spec:
  # ...
  promotionTemplate:
    spec:
      steps:
      - uses: jira
        as: create-promotion-issue
        config:
          credentials:
            secretName: jira-credentials
          createIssue:
            projectKey: PROMOTE
            summary: "Promote ${{ imageFrom(vars.imageRepo).Tag }} to ${{ ctx.stage }}"
            description: "Promoting ${{ imageFrom(vars.imageRepo).RepoURL }}:${{ imageFrom(vars.imageRepo).Tag }} to ${{ ctx.stage }} environment. Promotion ID: ${{ ctx.promotion }}. Freight: ${{ ctx.targetFreight.name }}".
            issueType: Task
            assigneeEmail: devops@company.com
            labels:
            - promotion
            - "${{ ctx.stage }}"
            - "release-${{ imageFrom(vars.imageRepo).Tag }}"
      # Use the created issue key in subsequent steps
      - uses: jira
        config:
          credentials:
            secretName: jira-credentials
          updateIssue:
            issueKey: "${{ outputs['create-promotion-issue'].key }}" # Or task.outputs in a (Cluster)PromotionTask
            status: "IN PROGRESS"
```

--------------------------------

### Create Project using CLI

Source: https://github.com/akuity/kargo/blob/main/docs/docs/50-user-guide/20-how-to-guides/20-working-with-projects.md

Use this command to create a new project via the command line. Alternatively, define the project in a YAML file and apply it.

```bash
kargo create project <project>
```

```yaml
apiVersion: kargo.akuity.io/v1alpha1
kind: Project
metadata:
  name: <project>
```

```shell
kargo create -f <filename>
```

--------------------------------

### Configure Git for DCO Sign-off

Source: https://github.com/akuity/kargo/blob/main/docs/docs/60-contributor-guide/30-signing-commits.md

Set your Git username and email for DCO sign-offs. This is a one-time setup.

```shell
git config user.name <legal name>
git config user.email <email address you use for GitHub>
```

```shell
git config --global user.name <legal name>
git config --global user.email <email address you use for GitHub>
```

--------------------------------

### Warehouse with Git includePaths

Source: https://github.com/akuity/kargo/blob/main/docs/docs/50-user-guide/20-how-to-guides/30-working-with-warehouses.md

This example shows a Warehouse that only produces new Freight when changes occur within the `apps/guestbook` directory.

```yaml
apiVersion: kargo.akuity.io/v1alpha1
kind: Warehouse
metadata:
  name: my-warehouse
  namespace: kargo-demo
spec:
  subscriptions:
  - git:
      repoURL: https://github.com/example/kargo-demo.git
      includePaths:
      - apps/guestbook
```

--------------------------------

### AnalysisTemplate Declaring Arguments

Source: https://github.com/akuity/kargo/blob/main/docs/docs/50-user-guide/20-how-to-guides/60-verification.md

This AnalysisTemplate example complements a Stage configuration by declaring the 'commit' argument, which is required for AnalysisRuns to succeed.

```yaml
apiVersion: argoproj.io/v1alpha1
kind: AnalysisTemplate
metadata:
  name: integration-test
  namespace: guestbook
spec:
  args:
  - name: commit
  metrics:
    # ...
```

--------------------------------

### Start Local Development Environment with Tilt

Source: https://github.com/akuity/kargo/blob/main/AGENTS.md

Launch the local development environment using Tilt. Tilt manages the build process, hot-reloading, and deployment to the local Kubernetes cluster.

```bash
make hack-tilt-up          # Start local dev environment
```

--------------------------------

### Pushing Tag After Creation with git-tag and git-push

Source: https://github.com/akuity/kargo/blob/main/docs/docs/50-user-guide/60-reference-docs/30-promotion-steps/git-tag.md

This example shows creating a tag with `git-tag` and then pushing it to the remote repository using `git-push`.

```yaml
steps:
- uses: git-tag
  config:
    path: ./out
    tag: v1.0.0
- uses: git-push
  config:
    path: ./out
    tag: v1.0.0
```

--------------------------------

### Logging with pkg/logging

Source: https://github.com/akuity/kargo/blob/main/AGENTS.md

Shows how to retrieve, enrich, and log messages using the `pkg/logging` package, which wraps `zap`. Loggers are context-aware and support various levels from Trace to Error. Use this for structured and contextualized logging.

```go
// Retrieve from context (falls back to global logger if absent)
logger := logging.LoggerFromContext(ctx)

// Enrich with request-scoped values, store back in context
logger = logger.WithValues("namespace", ns, "name", name)
ctx = logging.ContextWithLogger(ctx, logger)

// Log at various levels
logger.Trace("discovered commit", "tag", tag.Tag)   // very verbose
logger.Debug("routing webhook request")              // debugging detail
logger.Info("promotion completed", "stage", s.Name)  // normal operations
logger.Error(err, "error refreshing object")         // error takes err first
```

--------------------------------

### ProjectConfig with Stage Selectors by Labels

Source: https://github.com/akuity/kargo/blob/main/docs/docs/50-user-guide/20-how-to-guides/20-working-with-projects.md

Use label selectors to apply promotion policies to Stages with specific labels. This example promotes stages with the 'development' label.

```yaml
---
apiVersion: kargo.akuity.io/v1alpha1
kind: Project
metadata:
  name: example
---
apiVersion: kargo.akuity.io/v1alpha1
kind: ProjectConfig
metadata:
  name: example
  namespace: example
spec:
  promotionPolicies:
  - stageSelector:
      matchLabels:
        environment: development
    autoPromotionEnabled: true
  - stageSelector:
      matchExpressions:
      - key: environment
        operator: In
        values: ["development", "staging"]
    autoPromotionEnabled: true

```

--------------------------------

### Common Go Development Commands

Source: https://github.com/akuity/kargo/blob/main/AGENTS.md

Run these commands for linting, formatting, testing, and building Go code. They leverage tools like golangci-lint and Go's built-in testing framework.

```bash
make lint-go              # Lint Go code (golangci-lint)
make lint                 # Lint everything (Go, proto, charts, UI)
make format-go            # Auto-format Go code
make test-unit            # Run unit tests (with -race)
make build-cli            # Build CLI binary
make codegen              # Run all code generation
make hack-build-dev-tools # Build dev container with all tools
```

--------------------------------

### Filter Commits by Message Patterns

Source: https://github.com/akuity/kargo/blob/main/docs/docs/50-user-guide/20-how-to-guides/30-working-with-warehouses.md

This example filters commits to include only those with subjects containing 'feat:' or 'fix:', using the NewestFromBranch strategy.

```yaml
spec:
  subscriptions:
  - git:
      repoURL: https://github.com/example/repo.git
      commitSelectionStrategy: NewestFromBranch
      expressionFilter: subject contains 'feat:' || subject contains 'fix:'

```

--------------------------------

### Example AnalysisRun Resource

Source: https://github.com/akuity/kargo/blob/main/docs/docs/50-user-guide/20-how-to-guides/60-verification.md

This YAML defines an AnalysisRun resource, showing its metadata, spec (including metrics and job configuration), and status.

```yaml
apiVersion: argoproj.io/v1alpha1
kind: AnalysisRun
metadata:
  creationTimestamp: 2025-01-28T20:47:50Z
  generation: 3
  labels:
    kargo.akuity.io/freight-collection: 55d452301040a73e9fd05289b1f8ddbec1791222
    kargo.akuity.io/stage: dev
  annotations:
    kargo.akuity.io/promotion: dev.01jjpfgfwkzk18k7cyq61jehf4.319ddec
  name: dev.01jjqaq7qacfn766tcp1nqz2zv.55d4523
  namespace: guestbook
  ownerReferences:
    - apiVersion: kargo.akuity.io/v1alpha1
      blockOwnerDeletion: false
      kind: Freight
      name: 319ddec6bbfbd808d499a0357b027e773aa3707f
      uid: fb0db653-92af-420b-9092-0c7bf9be290e
  resourceVersion: "54013326"
  uid: 8cb745cb-554b-4141-80ee-e0df181cd56e
spec:
  metrics:
  - name: integration-test
    provider:
      job:
        spec:
          template:
            spec:
              containers:
              - name: sleep
                image: alpine:latest
                command: [sleep, "10"]
              restartPolicy: Never
          backoffLimit: 1
status:
  dryRunSummary: {}
  message: Metric "integration-test" assessed Failed due to failed (1) > failureLimit (0)
  metricResults:
    - count: 1
      failed: 1
      measurements:
        - finishedAt: 2025-01-28T20:50:31Z
          metadata:
            job-name: 8cb745cb-554b-4141-80ee-e0df181cd56e.integration-test.1
            job-namespace: guestbook
          phase: Failed
          startedAt: 2025-01-28T20:47:50Z
      name: integration-test
      phase: Failed
  phase: Failed
  runSummary:
    count: 1
    failed: 1
  startedAt: 2025-01-28T20:47:50Z
```

--------------------------------

### Define Promotion Steps with Promotion Template

Source: https://github.com/akuity/kargo/blob/main/docs/docs/50-user-guide/20-how-to-guides/40-working-with-stages.md

Use `spec.promotionTemplate` to define discrete steps for promoting Freight to a Stage. This example clones a Git repository, updates an image reference in Kustomize, builds manifests, commits changes, and updates an Argo CD application.

```yaml
promotionTemplate:
  spec:
    vars:
    - name: gitopsRepo
      value: https://github.com/example/repo.git
    - name: imageRepo
      value: public.ecr.aws/nginx/nginx
    - name: srcPath
      value: ./src
    - name: outPath
      value: ./out
    - name: targetBranch
      value: stage/${{ ctx.stage }}
    steps:
    - uses: git-clone
      config:
        repoURL: ${{ vars.gitopsRepo }}
        checkout:
        - branch: main
          path: ${{ vars.srcPath }}
        - branch: stage/${{ ctx.stage }}
          create: true
          path: ${{ vars.outPath }}
    - uses: git-clear
      config:
        path: ${{ vars.outPath }}
    - uses: kustomize-set-image
      as: update-image
      config:
        path: ${{ vars.srcPath }}/base
        images:
        - image: ${{ vars.imageRepo }}
    - uses: kustomize-build
      config:
        path: ${{ vars.srcPath }}/stages/${{ ctx.stage }}
        outPath: ${{ vars.outPath }}/manifests.yaml
    - uses: git-commit
      as: commit
      config:
        path: ${{ vars.outPath }}
        message: ${{ outputs['update-image'].commitMessage }}
    - uses: git-push
      config:
        path: ${{ vars.outPath }}
        branch: ${{ vars.targetBranch }}
    - uses: argocd-update
      config:
        apps:
        - name: kargo-demo-${{ ctx.stage }}
          sources:
          - repoURL: ${{ vars.gitopsRepo }}
            desiredRevision: ${{ outputs.commit.commit }}
```

--------------------------------

### Create Stage using CLI

Source: https://github.com/akuity/kargo/blob/main/docs/docs/50-user-guide/20-how-to-guides/40-working-with-stages.md

Use the `kargo create` command with a YAML file to create a new Stage. Verify the creation by listing stages with `kargo get stage`.

```shell
kargo create -f <filename>
```

```shell
kargo get stage <stage> --project <project>
```