Kargo Promotion Steps Reference

Kargo Promotion Steps Reference

Complete reference for all 34 Kargo promotion steps.

Git Operations

git-clone

Clones a remote Git repository and checks out specified revisions.

- uses: git-clone
  as: clone
  config:
    repoURL: https://github.com/example/repo.git
    insecureSkipTLSVerify: false
    author:
      - name: "Kargo Bot"
        email: "kargo@example.com"
        signingKey: "..."  # Optional GPG key
    checkout:
      - as: freight
        commit: ${{ commitFrom(vars.repo).ID }}
        path: /workspace/source
      - as: stage-config
        branch: ${{ vars.targetBranch }}
        path: /workspace/target
        create: true  # Create orphaned branch if missing

Parameters:

Output: commits map containing checkout keys mapped to HEAD commit hashes.

git-commit

Commits working tree changes to the checked out branch.

- uses: git-commit
  as: commit
  config:
    path: ./out
    message: |
      Update image to ${{ imageFrom(vars.imageRepo).Tag }}

      Freight: ${{ ctx.freight.displayID }}
    author:
      name: "Kargo Automation"
      email: "kargo@example.com"
      signingKey: "..."

Parameters:

Output: commit - SHA of created commit (or existing HEAD if no changes).

git-push

Pushes committed changes to remote repository.

- uses: git-push
  as: push
  config:
    path: ./out
    targetBranch: ${{ vars.targetBranch }}
    maxAttempts: 50
    # OR for PR workflow:
    generateTargetBranch: true
    provider: github  # azure, bitbucket, gitea, github, gitlab

Parameters:

Output:

• branch - Remote branch name
• commit - Commit SHA pushed
• commitURL - URL to pushed commit

git-open-pr

Opens a pull request.

- uses: git-open-pr
  as: open-pr
  config:
    repoURL: https://github.com/example/repo.git
    provider: github
    sourceBranch: ${{ outputs['push'].branch }}
    targetBranch: main
    createTargetBranch: false
    title: "Promote to ${{ ctx.stage }}"
    description: "Auto-generated promotion PR"
    labels:
      - kargo
      - automated

Output:

• pr.id - PR number
• pr.url - PR URL

git-wait-for-pr

Waits for a PR to be merged or closed.

- uses: git-wait-for-pr
  config:
    repoURL: https://github.com/example/repo.git
    prNumber: ${{ outputs['open-pr'].pr.id }}
    provider: github
    timeout: 48h

Output: commit - Merge commit SHA

git-merge-pr

Merges an open pull request.

- uses: git-merge-pr
  config:
    repoURL: https://github.com/example/repo.git
    prNumber: ${{ outputs['open-pr'].pr.id }}
    provider: github
    wait: true  # Retry if not mergeable

git-clear

Deletes entire contents of Git working tree.

- uses: git-clear
  config:
    path: ./out

Configuration Management

kustomize-set-image

Updates container image references in kustomization.yaml.

- uses: kustomize-set-image
  config:
    path: ./out/overlays/test
    images:
    - image: ghcr.io/example/app
      tag: ${{ imageFrom(vars.imageRepo).Tag }}
    - image: ghcr.io/example/other
      newName: registry.example.com/other
      digest: ${{ imageFrom('ghcr.io/example/other').Digest }}

Parameters:

Output: commitMessage - Description of changes

kustomize-build

Renders manifests from kustomization.yaml.

- uses: kustomize-build
  config:
    path: ./src/overlays/test
    outPath: ./out/manifests.yaml
    plugin.helm.kubeVersion: "1.28.0"
    plugin.helm.apiVersions:
      - apps/v1

helm-template

Renders Helm charts.

- uses: helm-template
  config:
    path: ./charts/my-chart
    outPath: ./out/manifests.yaml
    releaseName: my-release
    namespace: default
    outLayout: helm  # or 'flat'
    valuesFiles:
      - ./values-prod.yaml
    buildDependencies: true
    includeCRDs: true
    disableHooks: false
    skipTests: false
    kubeVersion: "1.28.0"
    apiVersions:
      - apps/v1
    setValues:
      - key: image.tag
        value: ${{ imageFrom(vars.imageRepo).Tag }}

helm-update-chart

Updates Helm chart dependencies in Chart.yaml.

- uses: helm-update-chart
  config:
    path: ./src/my-chart
    charts:
      - repository: https://charts.example.com
        name: dependency-chart
        version: 2.0.0
      - repository: oci://registry.example.com
        name: oci-dependency
        version: 1.5.0

Output: commitMessage

yaml-update

Updates YAML file values.

- uses: yaml-update
  config:
    path: ./src/values.yaml
    updates:
      - key: image.tag
        value: ${{ imageFrom(vars.imageRepo).Tag }}
      - key: replicas
        value: "3"
      - key: config.nested.value
        value: updated-value

Output: commitMessage

yaml-parse

Extracts values from YAML files.

- uses: yaml-parse
  as: get-version
  config:
    filePath: ./src/source.yaml
    expression: version

Output: value - Extracted value

json-update

Updates JSON file values.

- uses: json-update
  config:
    path: ./src/config.json
    updates:
      - key: version
        value: ${{ imageFrom(vars.imageRepo).Tag }}
      - key: enabled
        value: true

json-parse

Extracts values from JSON files.

- uses: json-parse
  as: get-config
  config:
    filePath: ./src/config.json
    expression: settings.version

ArgoCD Integration

argocd-update

Updates ArgoCD Application resources.

- uses: argocd-update
  config:
    apps:
    - name: my-app
      namespace: argocd
      sources:
      - repoURL: https://github.com/example/repo.git
        desiredRevision: ${{ outputs.push.commit }}
        updateTargetRevision: true
      - repoURL: ghcr.io/example/app
        tag: v1.2.3
        newName: registry.example.com/app
        updateTargetRevision: true
      # Helm parameters
      - repoURL: https://github.com/example/repo.git
        helm:
          parameters:
          - key: image.tag
            value: v1.2.3
        updateTargetRevision: true

Kustomize Images:

sources:
- repoURL: ghcr.io/example/app
  tag: v1.2.3
  newName: registry.example.com/app

Helm Parameters:

sources:
- repoURL: https://github.com/example/repo.git
  helm:
    parameters:
    - key: image.tag
      value: v1.2.3

Required Application Annotation:

annotations:
  kargo.akuity.io/authorized-stage: "project:stage"

File Operations

copy

Copies files or directories.

- uses: copy
  config:
    inPath: ./overlay/kustomization.yaml
    outPath: ./src/kustomization.yaml

delete

Removes files or directories.

- uses: delete
  config:
    path: ./temp

untar

Extracts tar/gzipped archives.

- uses: untar
  config:
    inPath: ./archive.tar.gz
    outPath: ./extracted

External Integrations

http

Makes HTTP/S requests.

- uses: http
  config:
    method: POST
    url: https://api.example.com/deploy
    headers:
      - name: Authorization
        value: "Bearer ${{ secrets.apiToken }}"
      - name: Content-Type
        value: application/json
    queryParams:
      - name: stage
        value: ${{ ctx.stage }}
    body: '{"version":"${{ ctx.freight.displayID }}"}'
    timeout: 5m
    successExpression: response.status >= 200 && response.status < 300
    failureExpression: response.status >= 500

Response Object (in expressions):

• response.status - HTTP status code
• response.headers - Header map
• response.header("name") - Header accessor
• response.body - Unmarshaled JSON

http-download

Downloads files from HTTP/S URLs.

- uses: http-download
  config:
    url: https://example.com/file.tar.gz
    outPath: ./downloads/file.tar.gz
    headers:
      - name: Authorization
        value: "Bearer ${{ secrets.token }}"

oci-download

Downloads OCI artifacts.

- uses: oci-download
  config:
    repoURL: ghcr.io/example/artifact
    tag: latest
    outPath: ./artifacts

gha-dispatch-workflow

Dispatches GitHub Actions workflows.

- uses: gha-dispatch-workflow
  as: dispatch
  config:
    repoURL: https://github.com/example/repo
    workflowFileName: deploy.yaml
    ref: main
    inputs:
      environment: production
      version: ${{ imageFrom(vars.imageRepo).Tag }}

gha-wait-for-workflow

Waits for GitHub Actions workflow completion.

- uses: gha-wait-for-workflow
  config:
    repoURL: https://github.com/example/repo
    runID: ${{ outputs['dispatch'].runID }}
    timeout: 30m

jira

Manages Jira issues.

- uses: jira
  config:
    url: https://example.atlassian.net
    projectKey: DEPLOY
    issueType: Task
    summary: "Deployment to ${{ ctx.stage }}"
    description: "Deploying ${{ ctx.freight.displayID }}"

send-message

Sends notifications to Slack, email, etc.

- uses: send-message
  config:
    channel: slack-notifications
    message: |
      Deployed ${{ ctx.freight.displayID }} to ${{ ctx.stage }}

Workflow Utilities

compose-output

Combines outputs from multiple steps.

- uses: compose-output
  config:
    pr_url: "${{ vars.repoURL }}/pull/${{ outputs['open-pr'].pr.id }}"
    commit_sha: "${{ outputs['commit'].commit }}"
    summary: "Deployed ${{ ctx.freight.displayID }}"

set-metadata

Updates Stage or Freight resource metadata.

- uses: set-metadata
  config:
    stage:
      labels:
        last-promoted: ${{ ctx.freight.displayID }}
    freight:
      annotations:
        deployed-at: ${{ now() }}

Conditional Execution & Error Handling

Conditional Steps

steps:
  - uses: some-step
    as: my-step

  - uses: another-step
    if: ${{ success() }}  # Only if all previous succeeded

  - uses: error-handler
    if: ${{ failure() }}  # Only if any previous failed

  - uses: cleanup
    if: ${{ always() }}   # Always execute

  - uses: conditional
    if: ${{ status('my-step') == 'Errored' }}

Error Handling

steps:
  - uses: git-wait-for-pr
    continueOnError: true
    retry:
      errorThreshold: 3
      timeout: 48h

Step Aliasing & Output References

steps:
  - uses: git-clone
    as: clone
    config:
      repoURL: ${{ vars.repo }}

  - uses: git-commit
    as: commit
    config:
      path: ./out
      message: "Update"

  - uses: git-push
    as: push
    config:
      path: ./out

  - uses: argocd-update
    config:
      apps:
      - name: my-app
        sources:
        - repoURL: ${{ vars.repo }}
          desiredRevision: ${{ outputs.push.commit }}