Skip to main content

Set up runners to provision services

Runners and IaC tools handle the actual provisioning tasks. While nullplatform triggers the workflow, you manage the process directly, which keeps it flexible and aligned with your security standards.

note

We strongly recommend using your own runners to enhance security and optimize cost management.

GitHub Actions​

To set up and use GitHub Actions to provision services on nullplatform:

Configure the runner​

  1. Create a new repository on GitHub to host your service provisioning workflows.
  2. Set up a GitHub Action workflow that can be triggered manually to automate the provisioning tasks.

The workflow runs actions based on the inputs it receives.

Example configuration for a service provisioning workflow:

name: Service Provisioning
on:
  workflow_dispatch:
  inputs:
    context:
      type: string
      description: "nullplatform service lifecycle webhook context"
      required: true
permissions:
  id-token: write
  contents: read
  packages: read
jobs:
  provisioning:
  runs-on: ubuntu-latest
  env:
    CONTEXT: ${{ inputs.context }}
  steps:
    - name: Provisioning
    - run: echo "Insert your provisioning code here"

Create a notifications channel​

Create a notification channel to integrate the GitHub workflow with your service provisioning process.

Send a POST request to create your notifications channel. Make sure you:

  • set "type": "github".
  • fill in the configuration object with GitHub parameters.

Here’s an example request:

curl -L 'https://api.nullplatform.com/notification/channel' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
   "nrn": "organization=1:account=2",
   "source": [
      "service"
   ],
   "type": "github",
   "configuration": {
      "installation_id": "my-installation-id",
      "account": "my-github-org",
      "repository": "services-opentofu",
      "reference": "main",
      "workflow_id": "provisioning.yml"
      }
   }'
  • After you create the channel in nullplatform, this workflow triggers automatically each time a service or link is created.

Workflow execution​

The payload example provided earlier will be available as the context input in your workflow.

GitLab Pipelines​

To set up and use GitLab Pipelines to provision services on nullplatform:

Configure the runner​

  1. Create a new repository on GitLab to host your service provisioning workflows.
  2. Set up a GitLab pipeline workflow to automate the provisioning tasks.

The workflow will execute actions based on the inputs it receives.

Example configuration for a service provisioning workflow:

default:
tags:
  - $RUNNER_TAG
provisioning:
stage: provisioning
script:
  - echo $CONTEXT
  - echo "Insert your provisioning code here"

Create a notifications channel​

Create a notification channel to integrate the GitLab pipeline workflow with your service provisioning process.

Send a POST request to create your notifications channel. Make sure you:

  • set "type": "gitlab".

  • fill in the configuration object with GitLab parameters.

    curl -L 'https://api.nullplatform.com/notification/channel' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
       "nrn": "organization=1:account=2",
       "source": [
          "service"
       ],
       "type": "gitlab",
       "configuration": {
          "reference": "main",
          "project_id": "1"
       }   
    }'

  • After you create the channel in nullplatform, this pipeline triggers automatically each time a service or link is created.

Workflow execution​

The payload example provided earlier will be available as the CONTEXT environment variable in your pipeline.

Azure DevOps Pipelines​

To set up and use Azure DevOps Pipelines to provision services on nullplatform:

Configure the runner​

  1. Create a new repository on Azure DevOps to host your service provisioning workflows.
  2. Set up an Azure DevOps Pipeline workflow to automate the provisioning tasks.

The workflow will execute actions based on the inputs it receives.

  • Make sure you set up the variable CONTEXT in the pipeline configuration with the option "Let users override this value when running this pipeline" enabled.

Example configuration:

trigger:
  - main

pool:
vmImage: ubuntu-latest

steps:
  - script: |
      echo $(CONTEXT)
      echo "Insert your provisioning code here"
displayName: "Run Provisioning Scripts"

Create a notifications channel​

Create a notification channel to integrate the Azure pipeline with your service provisioning process.

Send a POST request to create your notifications channel. Make sure you:

  • set "type": "azure".
  • fill in the configuration object with Azure DevOps parameters.

Here’s a request example:

curl -L 'https://api.nullplatform.com/notification/channel' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
   "nrn": "organization=1:account=2",
   "source": [
      "service"
   ],
   "type": "azure",
   "configuration": {
   "organization": "my-org",
   "project": "my-devops-project",
   "pipeline_id": 1,
   "reference": "main"
   }
}'
  • After you create the channel in nullplatform, this pipeline triggers automatically each time a service or link is created.

Workflow execution​

The payload example provided earlier will be available as the CONTEXT environment variable in your pipeline.

Webhook notifications​

To set up and use Webhooks to provision services on nullplatform:

Configure the runner​

1. Create a web server​

  • Set up a web server with a POST endpoint to receive webhooks from nullplatform. The endpoint should parse the payload and trigger the provisioning tasks based on the inputs it receives.

  • Respond to nullplatform with an HTTP 2XX status code (e.g., 200 OK or 201 Created) to confirm receipt of the webhook. Process it asynchronously to avoid timeouts.

Create a notifications channel​

Create an HTTP notification channel to integrate this workflow with your service provisioning process.

Send a POST request to create your notifications channel. Make sure you:

  • set "type": "http".

  • fill in the configuration object with webhooks parameters.

    curl -L 'https://api.nullplatform.com/notification/channel' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
       "nrn": "organization=1:account=2",
       "source": [
          "service"
       ],
       "type": "http",
       "configuration": {
          "url": "https://yourdomain.com/url-you-configured",
          "headers": {
             "Authorization": "Bearer the-token"
       }
    }'

  • After you create the channel in nullplatform, this endpoint is called automatically each time a service or link is created.

3. Webhook invocation​

  • The payload, as shown earlier, is included in the request body.
  • Make sure you handle edge cases and failures during task execution.

Workflow execution​

Notify nullplatform of the result of the webhook execution.

info

You need an ops role to interact with the API. See the Roles docs for more info.

Use the nullplatform API to update the webhook execution results of the service action or link action, and provide detailed outcomes and messages for the developer.