Introduction
Understanding organizationsUnderstanding componentsManage organizationsManage componentsManage component Jira integrations
Set up your first organizationUnderstanding users and teamsUnderstanding role-based access controlManage usersManage teamsConfigure role-based access controlRBAC permissions reference
Understanding authentication in CloudBees UnifySet up multifactor authenticationConfigure SAML single sign-onConfigure OIDC authenticationConfigure network security policiesNetwork security reference
Understanding platform configurationUnderstanding environmentsManage properties and secretsManage environmentsTrack environment inventoryConfigure containersSet up preconfigured actionsConfigure notificationsSet up Slack webhook notifications
Accessibility policy referenceShared responsibility model referenceSubscription and services agreementSupport policiesSupported browsers and external tools
Introduction
Understanding feature managementUnderstanding Configuration as CodeGet started with feature managementCreate and manage feature flagsConfigure feature flag targetingOrganize feature flagsImplement feature flag governanceConfiguration as Code reference
Understanding flag impressions and activity statusUnderstanding flag healthUnderstanding code referencesReview and clean up feature flagsSet up code references
Understanding Jira integration for feature flagsSet up the Jira integrationLink Jira tickets to feature flags
Understanding multiple SDK keysBuild your first mobile app with feature flagsBuild your first feature-flagged web applicationBuild your first feature-flagged backend serviceInstall client-side SDKsInstall server-side SDKsConfigure multiple SDK keysMobile SDK referenceWeb SDK referenceBackend SDK referenceClient SDK referenceFlag implementation reference
Introduction
Understanding CI workflowsUnderstanding custom actionsCreate a build workflowCreate a custom actionCreate and manage workflowsCreate reusable workflowsTest and validate containers in workflowsCheck out source codeTrigger workflows remotelyWorkflow syntax referenceJobs syntax referenceSteps syntax referenceServices syntax reference
Monitor workflow runsView test results in runsView evidence in runsView deployments in runsManage workflow artifactsPublish test resultsPublish evidence itemsGenerate a software bill of materialsManage ServiceNow change requests
Configure workflow credentialsConfigure AWS credentialsConfigure container registry credentialsConfigure Git credentialsIntegrate CyberArk Conjur secrets
Understanding GitHub Actions integrationSet up GitHub Actions integrationDisplay GitHub Actions workflows and runsRegister GHA build artifactsPublish GHA deployed artifactsPublish GHA test resultsPublish GHA evidence itemsTrigger CloudBees workflows from GitHub ActionsScan with GitHub Actions
Understanding CloudBees CI and Jenkins® integrationConnect CI and Jenkins controllersMonitor CI and Jenkins buildsRegister CI build artifactsRegister CI deployed artifactsPublish CI test resultsConfigure CI security scanningCI and Jenkins integration reference
Build and publish container imagesUnderstanding external CI/CD integrationsRun external CI/CD jobsExternal CI/CD action reference
Introduction
Understanding release orchestrationManage applicationsCreate deployer workflowsCreate staged workflowsCreate and manage releasesOrchestrate multi-workflow releasesRelease management reference
Understanding artifact managementRegister and track artifactsStore and retrieve artifactsPromote artifactsGenerate a software bill of materialsArtifact management reference
Deploy with HelmDeploy to KubernetesContainer deployment reference
Deploy to AWSAWS deployment reference
Deploy with enterprise platformsExecute remote deployment commandsEnterprise deployment reference
Verify deployments with New RelicDeployment verification reference

Create a custom action

4 minute read

In this tutorial, you create a custom CloudBees Unify action, reusable automation packaged in a Git repository, and invoke it from a workflow job. You start with an empty repository and an action.yml file, and finish with a working action running as a step in your pipeline.

By the end, you’ll know how to:

  • Write a valid action.yml with inputs and container-based steps.

  • Commit the action to a source code repository.

  • Invoke your action from a workflow using org/repo@ref syntax.

  • Verify the action ran by inspecting step logs.

If you’re already familiar with GitHub Actions, the CloudBees Unify DSL uses the same syntax and semantics. CloudBees Unify requires all steps to run inside Docker containers unless you use Edge Runners for native runner execution.

Before you begin

Ensure you have completed the following before you start. This tutorial uses a minimal shell example so you can focus on the action structure, not on language-specific tooling.

Prerequisite Details

CloudBees Unify access

You can sign in and have at least one organization with a connected component.

A working workflow

You have completed Create a build workflow and have a CI workflow to add steps to.

A new Git repository for your action

An empty repository in any Git source control provider that CloudBees Unify supports: GitHub, GitLab, Bitbucket, or Gerrit. If you need help creating one, refer to GitHub’s documentation or your provider’s equivalent.

Step 1: Create the action.yml file

The action.yml file at the root of your repository is all that is required to define a custom action.

  1. In your action repository, create a file named action.yml at the root level.

  2. Add the following content:

    apiVersion: automation.cloudbees.io/v1alpha1(1)
kind: action(2)
name: Print greeting(3)
description: Prints a greeting to the log
inputs:
  recipient:(4)
    description: The name to greet
    required: true
    default: World
runs:(5)
  steps:
    - name: Print greeting
      uses: docker://alpine:latest(6)
      run: |
        echo "🎉 Hello, ${{ inputs.recipient }}! Your custom action is working."(7)
    ▼
    1 Required. The API version must be automation.cloudbees.io/v1alpha1.
    2 Required. Must be action.
    3 The display name shown in the CloudBees Unify UI. Maximum 63 characters.
    4 An input the calling workflow provides using with. Inputs can be required: true or optional with a default value.
    5 The execution block. Contains the list of steps to run.
    6 Every step must specify a Docker container image. All action steps run inside containers.
    7 Reference any declared input using ${{ inputs.<name> }}. The full range of CloudBees Unify context variables is available in Workflow syntax reference, including ${{ action.scm.sha }}, which resolves to the commit SHA of the action repository at the ref specified in uses.

  3. Commit the file to your repository:

    git add action.yml
git commit -m "Add action.yml"
git push
    ▼

Your repository root contains action.yml and the action is ready to be invoked from any CloudBees Unify workflow that can access this repository.

If your action repository is private, configure Git credentials in CloudBees Unify to grant access before proceeding.

Step 2: Invoke the action from a workflow

Now you add a step to your existing workflow that calls the action you just created.

  1. Select Components, then locate the component you created in Create a build workflow. You can identify it by the repository name listed beneath the component name. Select the component name link, not the repository link below it.

  2. Select Workflows in the left pane.

    If two workflows are listed, select the one named CI with custom action.

  3. Select the icon on the workflow row to open the editor.

  4. Replace the workflow content with the following:

    apiVersion: automation.cloudbees.io/v1alpha1
kind: workflow
name: CI with custom action
on:
  push:
    branches:
      - main
jobs:
  ci-job:
    steps:
      - name: checkout
        uses: https://github.com/cloudbees-io/checkout@v2
      - name: Run my custom action(1)
        uses: <your-github-org>/<your-action-repo>@main(2)
        with:
          recipient: CloudBees(3)
    ▼
    1 The step name appears in the run log.
    2 Replace <your-github-org>/<your-action-repo> with your actual values. For example: my-org/print-greeting-action@main. For GitLab, Bitbucket, or Gerrit, use the full URL: https://gitlab.com/<project>/<repo>@<ref>;. If you omit the ref, it defaults to the main branch.
    3 This value is passed to the recipient input defined in action.yml.

  5. Select Commit.

  6. Enter a Commit message, for example, Add custom action step.

  7. Select Commit to current branch.

  8. Select FINISH.

Your workflow file is updated and a new run starts automatically. The run appears in the Runs view with your commit message as the link.

If the step fails with a repository-not-found error, verify the repository is publicly accessible, or confirm your SCM integration grants CloudBees Unify access to it.

Step 3: Verify the action output

Now you confirm the action ran correctly by inspecting the step logs.

  1. Select Components, then select the component name you created in Create a build workflow.

  2. Select Runs from the left pane.

  3. Select your run.

  4. Select your job to display the steps.

  5. Select Expand all in the upper right.

  6. Locate and expand the Run my custom action step.

The step log shows 🎉 Hello, CloudBees! Your custom action is working. and a green success indicator appears next to every step.

If the log shows an input error, verify that the input name in action.yml matches the name specified in the with block in the workflow.

What you learned

In this tutorial you created a CloudBees Unify custom action with inputs and a container-based step, committed it to a Git repository, and invoked it from a workflow. You confirmed the full loop: action defined, action called, output verified. You now have a working custom action and a starting point to build on.

Next steps

Create a build workflow
Create and manage workflows