Available actions

Humanitec Pipelines support many different kinds of actions that can be executed in the Steps of a Pipeline.

When used in the Pipeline, the action is specified as class://name@version, or simply name when using the latest version of a Humanitec native action.

jobs:
  job-1:
    steps:
      # Fully qualified action notation
      - uses: native://actions/humanitec/log@v1
        ...
      # Simplified action notation
      - uses: actions/humanitec/log
        ...

Each action is defined by a class, a name, and a version. The only supported action class today is native:// which defines built-in actions provided by Humanitec Pipelines. Native actions execute securely within Humanitec’s infrastructure and do not support any kind of custom code execution, process environment, or command interpolation. The version of an action is assumed to be latest if not provided which maps to the latest available version of the Action.

APIs and Callbacks #

actions/humanitec/api@v1 #

Executes a limited set of supported Humanitec Platform Orchestrator API operations as the current run-as user. The API operation returns a status code, headers, and optional body data. This action is used to retrieve data from Environments, Deltas, Sets, or Deployments.

This action returns the following outputs:

This step fails if the request is not successful.

Example use:

jobs:
  job-1:
    steps:
      - uses: native://actions/humanitec/api@v1
        id: getEnv
        with:
          action: getEnvironment
          env_id: "development"
      - uses: native://actions/humanitec/log@v1
        with:
          # Pick up the "data" output provided by the api action
          message: "Environment data:\n ${{ toJson(steps.getEnv.outputs.data) }}"

getEnvironment(env_id) #

Returns the API response for an Environment of the current Application. This includes details of the current deployments and their status. Requires an input for the env_id.

getDeployment(env_id, deployment_id) #

Returns the API response for a Deployment within an Environment of the current Application. Requires inputs for both environment_id and deployment_id id.

getDelta(delta_id) #

Returns the API response for a Delta within the current Application. Requires an input for the delta_id.

getDeploymentSet(set_id) #

Returns the API response for a Deployment Set within the current Application. Requires an input for the set_id.

getActiveResource(env_id, type, class, res_id?) #

Returns the Active Resource state for a resource within an Environment that matches the type, class, and optional resource identifier.

actions/humanitec/http@v1 #

Executes a remote HTTP or HTTPS request. This can be used to issue notifications externally or trigger additional external deployment actions.

The step fails if the response status code is >= 300 or if no response was received within the configured timeout.

This action returns the following outputs:

Example use:

jobs:
  job-1:
    steps:
      - uses: native://actions/humanitec/http@v1
        id: httpPost
        with:
          url: "https://my.external.service.com/path/to/endpoint"
          method: "POST"
          headers:
            Content-Type: "application/json"
            Authorization: "Bearer ${{ inputs.token }}"
          data:
            some: "data"
            passed: "in"
      - uses: native://actions/humanitec/log@v1
        with:
          # Pick up the "data" output provided by the http action
          message: "Response data:\n ${{ steps.httpPost.outputs.data }}"

actions/humanitec/github-workflow@v1 #

This action triggers a GitHub Workflow execution and waits until it completes or the Humanitec Pipeline Job times out. The inputs define which repo, branch, and workflow file to execute as well as the inputs to provide.

This action requires a GitHub access token to be present in the Application secrets.

This action returns the following outputs:

Example use:

jobs:
  job-1:
    steps:
      - uses: native://actions/humanitec/github-workflow@v1
         id: gitHubWorkflow
        with:
          repo: myGitHubOrg/myGitHubRepo
          ref: main
          workflow: "push.yml"
          # Read access token from a secret Application value
          access_token: "${{ app.values.github-token }}"
      - uses: native://actions/humanitec/log@v1
        with:
          # Pick up the "conclusion" output provided by the github-workflow action
          message: "Conclusion: ${{ steps.gitHubWorkflow.outputs.conclusion }}"

actions/humanitec/gitlab-pipeline@v1 #

This action triggers a GitLab Pipeline execution and waits until it completes or the Humanitec Pipeline Job times out. The inputs define which GitLab project and branch to trigger the Pipeline in, the variables, and the token to run with.

This action executes the GitLab Pipeline until it reaches a terminal state.

This action returns the following outputs:

Example use:

jobs:
  job-1:
    steps:
      - uses: native://actions/humanitec/gitlab-pipeline@v1
        id: gitLabPipeline
        with:
          project_id: "my-project/my-pipeline"
          ref: main
          # Read access token from a secret Application value
          private_token: "${{ app.values.gitlab-token }}"
          vars:
            - key: MY_VAR_1
              value: true
              variable_type: file
            - key: MY_VAR_2
              value: "test"
              variable_type: env_var
      - uses: native://actions/humanitec/log@v1
        with:
          # Pick up the "pipeline_id" output provided by the github-workflow action
          message: "Pipeline execution ID: ${{ steps.gitLabPipeline.outputs.pipeline_id }}"

Deltas and Deployments #

actions/humanitec/apply@v1 #

This action produces a new Deployment Set by applying a Delta to the current state of an Environment. This Deployment Set can then be deployed or cloned to another Environment.

This action will provide a Deployment Set as an output.

Example use:

on:
  pipeline_call:
    inputs:
      delta_id:
        type: string
        required: true
jobs:
  job-1:
    steps:
      - uses: native://actions/humanitec/apply@v1
        id: applyDelta
        with:
          env_id: development
          delta_id: ${{ inputs.delta_id }}
      - uses: native://actions/humanitec/log@v1
        with:
          # Pick up the "set_id" output provided by the github-workflow action
          message: "Deployment Set ID: ${{ steps.applyDelta.outputs.set_id }}"

actions/humanitec/approve@v1 #

This action blocks the Pipeline execution until a user with deployment permissions on the target Environment has approved or denied the approval resource through the UI or API. The timeout is that of the surrounding Job or entire Pipeline.

Example use:

on:
  pipeline_call:
    inputs:
      target_env_id:
        type: string
        required: true
jobs:
  job-1:
    steps:
      - uses: native://actions/humanitec/approve@v1
        id: approve
        with:
          env_id: development
          message: "Please approve deployment to ${{ inputs.target_env_id }} environment"

actions/humanitec/clone@v1 #

This action clones a Deployment Set from one Environment to another, producing both a new Deployment Set and a Delta. The Deployment Set can then be deployed into the target Environment.

This action returns the following outputs:

Example use:

on:
  pipeline_call:
    inputs:
      from_env_id:
        type: string
        required: true
      to_env_id:
        type: string
        required: true
jobs:
  job-1:
    steps:
      - uses: native://actions/humanitec/clone@v1
        id: clone
        with:
          from_env_id: ${{ inputs.from_env_id }}
          to_env_id: ${{ inputs.to_env_id }}
          # Exclude all Workloads containg the term "demo" from the resulting Delta
          exclude: "demo"

actions/humanitec/create-delta@v1 #

The create-delta action can construct a new Delta from a list of Platform Orchestrator workload artefacts or container images. The workload artefacts will all be converted into new or updated Workloads within a Humanitec Delta. The container images will be matched against existing Workloads and be processed as updated if the image repository matches.

This step is best used together with an “artefact” trigger event which can produce workload_artefacts and images in the correct format.

This action provides a Deployment Delta as an output.

Example use showing the chaining of the create-delta action with the subsequent use of apply (to create a Set from the Delta) and deploy (to deploy the Set):

name: Example Artefact Pipeline
on:
  artefact:
    type: container
    run-as: "s-12345678-abcd-1234-efab-0987654321ba"
    include:
      - "myimage"
jobs:
  job-1:
    steps:
    - uses: native://actions/humanitec/log@v1
      with:
        message: "Image versions: ${{ toJson(inputs.container_artefacts) }}"
    - uses: native://actions/humanitec/create-delta@v1
      id: create-delta
      with:
        env_id: development
        images: ${{ inputs.container_artefacts }}
    - uses: native://actions/humanitec/apply@v1
      id: apply
      with:
        env_id: development
        delta_id: ${{ steps.create-delta.outputs.delta_id }}
    - uses: native://actions/humanitec/deploy@v1
      with:
        env_id: development
        set_id: ${{ steps.apply.outputs.set_id }}

This Pipeline would be triggered by a notification using the humctl CLI:

humctl create artefact-version --type container \
  --name "myimage" \
  --version "latest" \
  --commit "0b41a3f4b17fc84ec2ba045ebac9796ad07dc123" \
  --ref "refs/head/main"

actions/humanitec/deploy@v1 #

The deploy action is one of the most used Steps in Pipelines. This action deploys a Deployment Set to a target Environment. The Deployment Set can be produced from an apply action, a Pipeline input, or may be a Set id that was already deployed in the past. The value set version can also be specified and will default to the latest value set in the Environment if not specified.

This action returns the following outputs:

Example use for an Artefact Automation Pipeline: see the create-delta action.

Example use for an API-triggered Pipeline:

name: Example API-triggered deploy Pipeline
on:
  pipeline_call:
    inputs:
      set_id:
        type: string
        required: true
        description: The Deployment Set id to deploy
      env_id:
        type: string
        required: true
        description: The Environment id to deploy into 
jobs:
  job-1:
    steps:
    - uses: native://actions/humanitec/deploy@v1
      id: deploy
      with:
        set_id: ${{ inputs.set_id }}
        env_id: ${{ inputs.env_id }}
    - uses: native://actions/humanitec/log@v1
      with:
        message: "The resulting Deployment id is ${{ steps.deploy.outputs.deployment_id }}"

Other #

actions/humanitec/log@v1 #

Writes a log message to the Pipeline logs. This can be useful for debugging or auditing Pipeline execution.

This action returns no outputs.

Most examples for the other actions on this page show the usage of the “log” action. Use this snippet as quick guidance:

name: My logging Pipeline
on:
  pipeline_call:
    inputs:
      my_input:
        type: string
        required: true
jobs:
  job-1:
    steps:
      - uses: native://actions/humanitec/log@v1
        with:
          message: "I received: ${{ inputs.my_input }}"
          level: DEBUG

actions/humanitec/fail@v1 #

Fails the Pipeline Step and writes a log message. This is similar to the log action but will always write the message at ERROR level.

This action returns no outputs.

Example use:

name: Deployment with Notifications
on:
  deployment_request: {}
  ...
jobs:
  deploy:
    ...
  notify:
    needs: ["deploy"]
    steps:
    # Fail the pipeline if the initial deployment failed
    - name: Fail if deploy failed
      if: ${{ needs.deploy.status == 'failed' }}
      uses: native://actions/humanitec/fail@v1
      with:
        message: Deployment failed.

actions/humanitec/wait-for-readiness@v1 #

Waits until all Workloads in an Environment are in a “ready” state, otherwise fails the Pipeline Step after a timeout.

This action returns no outputs.

Example use:

name: Deployment with waiting
on:
  deployment_request: {}
  ...
jobs:
  deploy:
    ...
  wait:
    needs: ["deploy"]
    steps:
      - name: "Wait for Workload readiness"
        id: wait-for-workload-readiness
        uses: native://actions/humanitec/wait-for-readiness@v1
        with:
          env_id: ${{ inputs.environment }}