--- sidebar_label: Set up runners toc_max_heading_level: 3 doc_id: fb178956-f740-4783-bd22-51ac5fdaf6dd description: >- Guide to configure runners and IaC tools for automated service provisioning on nullplatform with security focus. keywords: - runners - service provisioning - GitHub Actions - IaC - automation --- import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; # 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: ```yaml 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](/docs/api/notification-channel-create) to create your notifications channel. Make sure you: - set `"type": "github"`. - fill in the `configuration` object with GitHub parameters. Here’s an example request: ```bash 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: ```yaml 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](/docs/api/notification-channel-create) to create your notifications channel. Make sure you: - set `"type": "gitlab"`. - fill in the `configuration` object with GitLab parameters. ```bash 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: ```yaml 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](/docs/api/notification-channel-create) 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: ```bash 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](/docs/api/notification-channel-create) to create your notifications channel. Make sure you: - set `"type": "http"`. - fill in the `configuration` object with webhooks parameters. ```bash 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](/docs/authorization/roles) for more info. ::: Use the nullplatform API to update the webhook execution results of the [service action](https://docs.nullplatform.com/api/update-a-service-action) or [link action](https://docs.nullplatform.com/api/update-a-link-action), and provide detailed outcomes and messages for the developer.