GitHub Actions Building Blocks

With meshStack, you can publish your GitHub Action Workflows directly to the marketplace, allowing application teams to easily access and initiate automation in a user-friendly, structured format in a central place. By providing triggers for automation in the marketplace, you enable teams to leverage these workflows without needing in-depth Git expertise.

Platform engineers can offer "GitHub Actions Building Blocks" that trigger a GitHub Action Workflow. These building blocks can be published to the marketplace, creating a seamless experience for teams to use existing automations.

Getting Started

Prerequisites: Your organization should be using GitHub SaaS, GitHub Enterprise, or GitHub Enterprise Server. Furthermore in order to integrate the GitHub Platform and execute this guide you need organization owner rights within GitHub. Additionally, to add individual GitHub Action Workflows, you need Read and Write access for Actions under the repository permissions.

Note: Follow Steps 1 and 2 only the first time you set up a GitHub Action Workflow integration. After the initial setup, you can go directly to Step 3 for additional triggers.

Step 1: Set Up the GitHub Platform in meshStack

To set up GitHub as a platform, go to the Admin area in meshStack, select Platforms, and click on Create New Platform at the top right. Complete the required fields and select GitHub as the platform type.

Step 2: Configure Pipeline Automation

Once your GitHub platform is created you will need to configure it. Do so by going to Settings → Configuration → Pipeline Automation.

First of all you will need a so-called GitHub App. This is what meshStack uses to authenticate to GitHub to talk to the GitHub API.

Click here to create a new GitHub App with the right permissions.

Once you have your GitHub App, meshStack needs to know the following to be integrated with GitHub:

the owner of the GitHub organization
the ID of the GitHub App
the app’s private key (this is a .pem file)

Those values are available to you once you installed the GitHub App to a repository and generated a private key.

If you are using an enterprise version you will need to change the base URL to GitHub’s API from https://api.github.com to whatever is the URL you use.

Once you entered the above configuration you can test your configuration by clicking the "Test Configuration" button. Please note that testing the configuration is only possible at the time you upload the private key. Coming back later to the form will require you to re-upload the key to meshStack in order to test the integration again.

Once you saved your configuration it can be enabled by clicking the Turn On button on the bottom of this page.

Step 3: Create a Workflow Trigger

To make a GitHub Action Workflow trigger available in the marketplace, create a building block definition that references the specific workflow. Follow these steps:

In the Admin Area or Platform Builder, navigate to Building Block Definitions and click Create New Definition on the top right.
Choose GitHub Actions as the implementation type.
Provide all required configuration details for the trigger.
On the Implementation page enter:
- The name of the repository where the workflow file lives
- The Git reference (branch or commit hash) that contains the workflow file
- The name of the workflow file within the repository (you don't have to enter the .github/workflows/ prefix, just the file name)
- If desired you can also have a specific workflow triggered when the building block gets deleted. If you want to do so, set "Deletion Mode" to "Delete Resources" and enter the name of the destroy workflow file below.
Continue with the rest of the building block definition creation process.

The dispatch event meshStack sends to GitHub in order to trigger the workflow will look like this:

{
   "ref": "<ref>",
   "inputs": {
      "buildingBlockRun": "<encodedRun>"
   }
}

The value for <ref> is the Git reference specified in the configuration, e.g. the branch name or a commit hash. The value for <encodedRun> is a Base64 encoded version of a building block run object. Please consider the following example for a run:

{
  "kind": "meshBuildingBlockRun",
  "apiVersion": "v1",
  "metadata": {
    "uuid": "19fe93f0-36d0-4019-9453-7f6f4ce490b4"
  },
  "spec": {
    "runNumber": 7,
    "buildingBlock": {
      "uuid": "3f7ee35a-a1d0-43d1-8ca7-dedbf9fd44b6",
      "spec": {
        "displayName": "name-of-buildingBlock",
        "workspaceIdentifier": "workspace-identifier",
        "projectIdentifier": "project-identifier",
        "fullPlatformIdentifier": "full-tenant-identifier",
        "inputs": [
          {
            "key": "input-key",
            "value": "test",
            "type": "STRING",
            "isSensitive": false,
            "isEnvironment": false
          }
        ],
        "parentBuildingBlocks": []
      }
    },
    "buildingBlockDefinition": {
      "uuid": "4334947b-f48f-4cf2-bb75-0f24b2ada6e0",
      "spec": {
        "version": 6,
        "implementation": {
          "type": "GITHUB_WORKFLOW"
        }
      }
    },
    "behavior": "APPLY"
  },
  "status": "IN_PROGRESS",
  "_links": {
    "registerSource": {
      "href": "https://federation.dev.meshcloud.io/api/meshobjects/meshbuildingblockruns/19fe93f0-36d0-4019-9453-7f6f4ce490b4/status/source"
    },
    "updateSource": {
      "href": "https://federation.dev.meshcloud.io/api/meshobjects/meshbuildingblockruns/19fe93f0-36d0-4019-9453-7f6f4ce490b4/status/source/{sourceId}"
    },
    "meshstackBaseUrl": {
      "href": "https://federation.dev.meshcloud.io"
    }
  }
}

The GitHub workflow needs to specify exactly one input like this:

on:
  workflow_dispatch:
    inputs:
      buildingBlockRun:
        description: "Building Block Run Object"
        required: true

This setup allows application teams to quickly and efficiently access automation workflows from the marketplace, enhancing their productivity and reducing the need for Git expertise.

Status Updates

GitHub Workflow Building Blocks support automatic status polling. You can choose between two execution modes when configuring your Building Block Definition:

Synchronous (Automatic Status Polling): meshStack automatically polls GitHub for workflow and job status updates after triggering the workflow. This provides real-time status updates in meshStack without requiring any custom integration or manual API calls. To enable this, set the "Execution Mode" to Synchronous in the Building Block Definition's implementation settings.
Asynchronous (Manual Status Updates): meshStack does not monitor the status of the GitHub Action Workflow. The pipeline remains "In Progress" until you update the status manually via the meshStack API. Use this mode if you prefer to manage status updates yourself or need custom integration steps.

How to Enable Automatic Status Polling

In the Building Block Definition's implementation settings, set Execution Mode to Synchronous.
meshStack triggers the GitHub workflow and automatically tracks its progress by polling GitHub's API for workflow and job statuses.
No additional integration code is required. Status updates are reflected in meshStack in real time.

If you use Asynchronous mode, you can update the status during and after the execution of the workflow using the meshStack API. It is recommended to use the pre-built GitHub Actions workflow steps for this purpose.

An API Key is required to authenticate with the meshStack API.

Two actions should be performed within the pipeline to update the status of the run:

Register Sources: Performed at the beginning of a run. This lets meshStack know what step(s) can be expected by the pipeline.
Update Status: Updates the status of a single step in the process.

Refer to this example to see all of these steps in practice.

Getting Started​

Step 1: Set Up the GitHub Platform in meshStack​

Step 2: Configure Pipeline Automation​

Step 3: Create a Workflow Trigger​

Status Updates​

How to Enable Automatic Status Polling​