Skip to content

App Servers CI/CD

A push or a tag on your git repository can update your servers without anyone opening Muppy. Two pipelines do it. Both are configured on the Application Definition (Muppy › Applications › Applications › Application Definitions).

LXC CI/CD K8s Tag Mapper
Runs App Servers on LXC containers or VMs — the Odizy servers Releases on a Kubernetes cluster
Reacts to a push on a branch a successful GitLab pipeline on a tag
Builds the code the App Server itself, at each deployment your GitLab CI, as a container image
Acts on Test Servers: creates, deploys and destroys them creates a Package Profile per tag, upgrades the Releases you select
Git providers GitLab, GitHub GitLab
Turned on by Activate LXC CI/CD Activate K8s CD

Staging and Production App Servers are deployed by hand, with the same deployment the pipeline runs. See Deploying Staging and Production.

Both pipelines start from the same place: a webhook your git provider sends to Muppy.

Connect your git provider

The token and the Incoming Webhook are created once per Muppy instance: one Incoming Webhook serves every repository of a provider. The webhook at the provider is declared once per repository.

1. Create an API token

Open Inouk › API › API Auth › API Auth Tokens (administrators only) and create a token:

  • Type: Header-Based Token.
  • Service Preset: GitLab Webhook. The same token serves GitHub.
  • User: the user the webhook acts as. Every message the webhook creates runs as this user.
  • Leave Enforce Integrity checked. A token received over plain http is then expired at once; Regenerate Credentials gives a new one.

2. Create an Incoming Webhook

Open Muppy › Tasks › Incoming Webhooks and create one per git provider:

Field Value
Name A slug, e.g. gitlab-cicd. It becomes the code parameter of the URL.
API Auth Token The token above.
Host The host the task is attached to.
Task muppysh_incoming_hook
Payload Decoder Gitlab Webhook Decoder or Github Webhook Decoder
Pass Token in header Checked for GitLab. Unchecked for GitHub: the token then travels in the URL.
Dump Payload Leave it unchecked. It writes the whole request into the message journal, token included.

Copy the Hook URL:

https://<your Muppy>/mpy/api/v1/incoming_webhooks?code=gitlab-cicd

With Pass Token in header unchecked, it ends with &access_token=<token>.

3. Declare the webhook at your git provider

Muppy does not create it. Declare it in the repository settings.

GitLab — Settings › Webhooks:

  • URL: the Hook URL.
  • Secret token: the token's value. GitLab sends it in the X-Gitlab-Token header.
  • Trigger: Push events for the LXC CI/CD, Pipeline events for the K8s Tag Mapper, Merge request events for the merge request mode of the LXC CI/CD, in beta.

GitHub — Settings › Webhooks › Add webhook:

  • Payload URL: the Hook URL of the GitHub Incoming Webhook. It carries the token.
  • Content type: application/json. GitHub's default, application/x-www-form-urlencoded, is refused.
  • Which events: Just the push event.

Muppy answers HTTP 200 even when it refuses a call. The reason is in the response body, which the provider's delivery log shows. See Troubleshooting.

4. Point the Application Definition at the repository

Muppy finds the Application Definition of a webhook by its Git Project ID, in the form's header. It is the numeric ID of the repository:

  • GitLab shows it on the project's home page.
  • For GitHub, it is the id that https://api.github.com/repos/<owner>/<repository> returns.

Activate LXC CI/CD and Activate K8s CD stay read-only until it is set.

Several Application Definitions can share one Git Project ID — a duplicate keeps it. Set Ref. selection Regex on each, so that only one matches a given branch or tag. A regex that matches nothing, such as ^__no_cicd__$, keeps an Application Definition out of the CI/CD.

Follow what a webhook did

Each accepted webhook becomes one message, processed in the background. Open Muppy › Qs › Messages. The message name says what arrived:

Gitlab Webhook:'push' project='acme-erp' ref='PUSH on branch refs/heads/feature-invoice' by jdoe.

Its journal lists every decision Muppy made. The work it starts — a deployment, a new server, a new Package Profile — runs in messages of its own, listed beside it.

Next