You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/meshstack.github.pipeline-automation.md
+45-21Lines changed: 45 additions & 21 deletions
Original file line number
Diff line number
Diff line change
@@ -1,17 +1,17 @@
1
1
---
2
2
id: meshstack.github.pipeline-automation
3
-
title: Pipeline Automation
3
+
title: GitHub Actions Building Blocks
4
4
---
5
5
6
-
With meshStack, you can publish automation workflows in other platforms 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.
6
+
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.
7
7
8
-
Platform engineers can offer "Pipeline Building Blocks" to trigger GitHub Action Workflows directly when added to a tenant. These building blocks can be published to the marketplace, creating a seamless experience for teams to use existing automations.
8
+
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.
9
9
10
10
## Getting Started
11
11
12
12
> Prerequisites: Your organization should be using GitHub SaaS, GitHub Enterprise, or GitHub Enterprise Server.
13
13
> Furthermore in order to integrate the GitHub Platform and execute this guide you need organization owner rights within GitHub.
14
-
> Additionally, to add individual GitHub Action workflows, you need Read and Write access for Actions and Workflows under the repository permissions.
14
+
> Additionally, to add individual GitHub Action Workflows, you need Read and Write access for Actions under the repository permissions.
15
15
16
16
**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.
17
17
@@ -21,31 +21,40 @@ To set up GitHub as a platform, go to the Admin area in meshStack, select **Plat
21
21
22
22
## Step 2: Configure Pipeline Automation
23
23
24
-
Once GitHub is set up as a platform, you can configure pipeline automations to streamline the process under Settings → Configuration.
24
+
Once your GitHub platform is created you will need to configure it. Do so by going to **Settings → Configuration → Pipeline Automation**.
25
25
26
-
meshStack will utilize the GitHub API to [authenticate as an APP installation](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation).
26
+
First of all you will need a so-called GitHub App. This is what meshStack uses to [authenticate to GitHub](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation) to talk to the GitHub API.
27
27
28
-
In order to do so meshStack needs to know
28
+
[Click here](https://github.com/settings/apps/new?name=meshStack-action-trigger&description=Provide%20meshStack%20with%20the%20ability%20to%20trigger%20GitHub%20Action%20Workflows&public=false&actions=write&url=https%3A%2F%2Fmeshcloud.io&webhook_active=false) to create a new GitHub App with the right permissions.
29
29
30
-
- the owner of the GitHub organization,
31
-
- the id of the GitHub App and
32
-
- the app’s private key to generate authentication tokens (JWT).
30
+
Once you have your GitHub App, meshStack needs to know the following to be integrated with GitHub:
33
31
34
-
Those values are available to you once you [registered a GitHub app](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app) and [installed it to a repository](https://docs.github.com/en/apps/using-github-apps/installing-your-own-github-app).\
35
-
In case you are using an enterprise version you will need to change the base URL to GitHub’s API from [https://api.github.com](https://api.github.com/) to whatever is the URL you use.
32
+
- the owner of the GitHub organization
33
+
- the ID of the GitHub App
34
+
- the app’s private key (this is a .pem file)
36
35
37
-
On the platform control plane you can select **Settings → Configuration** and the enter your data within the section for **Pipeline Automation.** You will find a button to test your configuration. 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.
36
+
Those values are available to you once you [installed the GitHub App to a repository](https://docs.github.com/en/apps/using-github-apps/installing-your-own-github-app) and [generated a private key](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps#generating-private-keys).
37
+
38
+
> 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.
39
+
40
+
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.
41
+
42
+
Once you saved your configuration it can be enabled by clicking the **Turn On** button on the bottom of this page.
38
43
39
44
## Step 3: Create a Workflow Trigger
40
45
41
46
To make a GitHub Action Workflow trigger available in the marketplace, create a building block definition that references the specific workflow. Follow these steps:
42
47
43
-
1. In the Admin area, navigate to **Building Block Definitions** and click **Create New Definition** in the top right.
44
-
2. Provide the required configuration details for the trigger.
45
-
3. On the Implementation page:
46
-
- Select the platform associated with the trigger (e.g., choose **AWS** if you are triggering an S3 bucket creation within AWS).
47
-
- Choose **Pipeline Automation** in the **Implementation Type** dropdown.
48
-
- Ensure you configure any necessary input fields to support the automation.
48
+
1. In the Admin Area or Platform Builder, navigate to **Building Block Definitions** and click **Create New Definition** on the top right.
49
+
2. Choose **GitHub Actions** as the implementation type.
50
+
3. Provide all required configuration details for the trigger.
51
+
4. On the Implementation page enter:
52
+
- The name of the repository where the workflow file lives
53
+
- The Git reference (branch or commit hash) that contains the workflow file
54
+
- The name of the workflow file within the repository (you don't have to enter the .github/workflows/ prefix, just the file name)
55
+
- If desired you can also have a specific workflow triggered when the building block gets deleted.
56
+
If you want to do so, set "Deletion Mode" to "Delete Resources" and enter the name of the destroy workflow file below.
57
+
5. Continue with the rest of the building block definition creation process.
49
58
50
59
The dispatch event meshStack sends to GitHub in order to trigger the workflow will look like this:
51
60
@@ -58,8 +67,8 @@ The dispatch event meshStack sends to GitHub in order to trigger the workflow wi
58
67
}
59
68
```
60
69
61
-
The value for `<ref>` is the Git reference specified in the configuration, e.g. the branch name or a commit hash.\
62
-
The value for `<encodedRun>` is a Base64 encoded version of a building block run object.\
70
+
The value for `<ref>` is the Git reference specified in the configuration, e.g. the branch name or a commit hash.
71
+
The value for `<encodedRun>` is a Base64 encoded version of a building block run object.
63
72
Please consider the following example for a run:
64
73
65
74
```json
@@ -128,3 +137,18 @@ on:
128
137
```
129
138
130
139
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.
140
+
141
+
### Status Updates
142
+
143
+
meshStack does not monitor the status of the GitHub Action Workflow. This means by default the pipeline will stay "In Progress" indefinitely after triggering the workflow. This is because meshStack does not have a built-in mechanism to track the completion or failure of GitHub Actions workflows.
144
+
145
+
However, you can use the meshStack API to update the status during and after the execution of the workflow. We highly recommend using our pre-built GitHub Actions workflow steps to do so.
146
+
147
+
You will need an [API Key](meshstack.how-to-API-keys.md) to authenticate with the meshStack API.
148
+
149
+
You should do two things within the pipeline to update the status of the run:
150
+
151
+
- Register Sources. This is something you do at the beginning of a run. It lets meshStack know what step(s) can be expected by the pipeline
152
+
- Update Status. This updates the status of a single step in the process.
153
+
154
+
We highly recommend having a look at [this example](https://github.com/likvid-bank/likvid-cloudfoundation/blob/main/.github/workflows/ionos-cp-workflow.yml) where you can see all of these steps being done.
0 commit comments