This is one of several GitHub Actions provided on an "as-is" basis by CloudBees that enable users to write GitHub Action Workflows that send work to an external CloudBees CD/RO instance. This Action enables workflows to send DSL (Domain Specific Language) to a CloudBees CD/RO server for evaluation. The DSL can be used to create entities in the server, such as procedure and release models. In addition, the DSL has full access to the CloudBees CD/RO API; for example, getProjects() will return a list of all projects in the system. This GitHub Action can be used in a workflow or called in a composite GitHub Action definition. The latter approach implements the other CloudBees CD/RO actions such as run-procedure and start-release.

For teams utilizing GitHub Actions for build and continuous integration, the CloudBees CD/RO Actions provide a mechanism for releasing software in a secure, governed, and auditable manner with deep visibility, as is required in regulated industries, for example. Platform or shared services teams can build reusable content in the CloudBees CD/RO platform that conforms to company standards and removes the burden of release automation from the application teams.

CloudBees CD/RO is an enterprise "on-premise" product that automates software delivery processes, including production deployments and releases. To use utilize this GitHub Action, it is necessary to have access to a CloudBees CD/RO instance, in particular,

• A CloudBees CD/RO instance that GitHub Actions can access through REST calls (TCP port 443)
• A valid API token for the CloudBees CD/RO instance. A token can be generated from the Access Token link on the user profile page of the CloudBees CD/RO user interface; see Manage access tokens via the UI documentation for details. These values should be stored as GitHub Action secrets to be referenced securely in a GitHub Actions workflow.

The CloudBees CD/RO GitHub Actions are called from steps in a GitHub Actions workflow. The following workflow extract illustrates how the DSL in a file can be evaluated along with DSL substitution arguments, including actual parameters. DSL can be supplied inline through the dsl input field.

steps:
  - name: Run EvalDSL Action
    uses: cloudbees-github-actions/eval-dsl@v1
    env:
      CDRO_URL: ${{ secrets.CDRO_URL }}
      CDRO_TOKEN: ${{ secrets.CDRO_TOKEN }}
    with:
      dsl-file: ./example-dsl.groovy
      dsl-args: |
        projectName: My project
        projectDescription: My project description
        procedureName: My procedure
      dsl-actual-parameter: |
        procedureInput1: 123
        procedureInput2: abc

Note: One of the two parameters, dsl or dsl-file, must be specified.

The following GitHub secrets are needed to run the Action. These can be set in the Secrets and variable section of the workflow repository Settings tab.

1. Set up secrets in the repository settings for Actions. In the GitHub repository, select the Settings tab, Secrets, Variables, and Actions. Use the New Repository button to create the CDRO_URL and CDRO_TOKEN secrets.
2. Create a DSL file in the root directory of your repository, for example, simple-project-dsl.groovy:

project "My simple project 1", {
	description = "My simple project 1 description"
}

3. Create a new workflow file in the .github/workflows directory, for example, simple-project.yml:

name: Create Simple Project

on:
  workflow_dispatch:

env:
  CDRO_URL: ${{ secrets.CDRO_URL }}
  CDRO_TOKEN: ${{ secrets.CDRO_TOKEN }}

jobs:
  create-simple-project-with-dsl-file:
    runs-on: ubuntu-latest

  steps:
    - name: Checkout repository
      uses: actions/checkout@v3

      - name: Execute DSL file to create a project
        uses: cloudbees-github-actions/eval-dsl@v1
        with:
          dsl-file: ./simple-project-dsl.groovy

  create-simple-project-using-dsl-as-input:
    runs-on: ubuntu-latest

    steps:
    - name: Execute DSL input to create project
      uses: cloudbees-github-actions/eval-dsl@v1
      with:
        dsl: |
          project "My simple project 2", {
            description = "My simple project 2 description"
          }

4. Go to the GitHub Actions tab and run the workflow Create Simple Project

The CloudBees CD/RO GitHub Actions Demonstration Repository illustrates how to implement a build and release workflow with the CloudBees CD/RO GitHub Actions.

The eval-dsl action is the basis of the other CloudBees-provided Actions such as run-procedure and start-release. It is implemented as a JavaScript GitHub Action. The others are implemented as Composite type Actions. Using this Composite model, you can easily create your own CD/RO Actions. The action.yaml file in run-procedure provides a useful template for doing this. Note that the args map is used to pass both DSL and Actual Parameters to the DSL. So, for example, the following workflow yaml,

with:
  projectName: GHA Test
  procedureName: GHA Procedure
  actualParameter: |
    Input1: xyz
    Input2: abc

will create the args map

def args=[
	projectName: "GHA Test",
	procedureName: "GHA Procedure",
	actualParameter: [
		Input1: "xyz",
		Input2: "abc"
	]
]

Which can be referenced from within the DSL in multiple ways:

println "Procedure name: ${args.procedureName}"
runProcedure(args)

The CloudBees CD/RO GitHub Actions Demonstration Repository illustrates how to implement a build and release workflow with the CloudBees CD/RO GitHub Actions.

The scripts and documentation in this project are released under the MIT License.

For more details about the CloudBees CD/RO product, view the online documentation.