Scaffold a new service

This guide walks you through setting up a workflow that allows developers to scaffold a new service.
A service in Port is a flexible concept, allowing you to represent a piece of software and its related components in a way that makes sense for you.

The workflow we will create in this guide will:

• Create a new Git repository.
• Create a new service in Port, and relate it to the new repository, giving it its context.

Open Beta

Port workflows are currently in open beta and available to all users. Workflows may undergo changes without prior notice.

Common use cases

• Enable developers to independently spin up new microservices with boilerplate code.
• Reduce friction for developers and prevent implementation differences by defining the logic of scaffolding a service and providing developers with a workflow they can simply execute.
• Track created services using a wide array of visualizations.

Prerequisites

• A Port account with permissions to build workflows.
• The Git Integration that is relevant for you needs to be installed.
• A repository in your Git provider in which you can create a workflow/pipeline (the backend that creates the repositories).

How it works

The workflow has two parts:

1. The workflow - A self-service trigger node collects the service name from the developer, then an action node triggers your Git provider's backend pipeline to create the repository.
2. The backend - A CI pipeline (GitHub Actions, GitLab CI, Jenkins, or Azure Pipelines) that creates the repository and scaffolds it from a cookiecutter template.

For GitHub, the workflow uses a native integration action to dispatch the GitHub Actions workflow.
For GitLab, Bitbucket (Jenkins), and Azure DevOps, the workflow uses a webhook node to trigger the pipeline, since native integration actions for these providers are not yet available.

Set up the backend

Now we will write the logic that the workflow will trigger.

GitHub

If the GitHub organization which will house your workflow is not the same as the one you'll create the new repository in, install GitHub ocean in the other organization as well.

1. First, let's create the necessary token and secrets:

   • Go to your GitHub tokens page, create a personal access token (classic) with repo, admin:repo_hook and admin:org scope, and copy it (this token is needed to create a repo from our workflow).

     
     SAML SSO

     If your organization uses SAML SSO, you will need to authorize your token. Follow these instructions and then continue this guide.

   • Go to your Port application, click on your profile picture , then click Credentials. Copy your Client ID and Client secret.

2. In the repository where your backend workflow will reside, create 3 new secrets under Settings->Secrets and variables->Actions:

   • ORG_ADMIN_TOKEN - the personal access token you created in the previous step.
   • PORT_CLIENT_ID - the client ID you copied from your Port app.
   • PORT_CLIENT_SECRET - the client secret you copied from your Port app.
   
   
   

3. Now let's create the backend workflow file that creates the repository.
   First, ensure that you have a .github/workflows directory, then create a new file named port-create-service.yml and use the following snippet as its content (remember to change <YOUR-ORG-NAME> to your GitHub organization name):

   Github workflow (click to expand)

   port-create-service.yml

   name: Scaffold a new service
   
   on:
     workflow_dispatch:
       inputs:
         service_name:
           required: true
           description: The name of the new service
           type: string
   
   jobs:
     scaffold-service:
       runs-on: ubuntu-latest
       env:
         ORG_NAME: <YOUR-ORG-NAME>
   
       steps:
         - uses: actions/checkout@v6
   
         - name: Create GitHub Repository
           uses: port-labs/cookiecutter-gha@v1.1.1
           with:
             portClientId: ${{ secrets.PORT_CLIENT_ID }}
             portClientSecret: ${{ secrets.PORT_CLIENT_SECRET }}
             token: ${{ secrets.ORG_ADMIN_TOKEN }}
             repositoryName: ${{ inputs.service_name }}
             portUserInputs: '{"cookiecutter_app_name": "${{ inputs.service_name }}" }'
             cookiecutterTemplate: https://github.com/lacion/cookiecutter-golang
             blueprintIdentifier: "githubRepository"
             organizationName: ${{ env.ORG_NAME }}
             createPortEntity: true

   This backend workflow only creates the repository and its githubRepository entity in Port. The Port workflow itself creates the service entity and relates it to the repository, so there is no need to report status from the backend workflow - the integration action monitors the GitHub Actions run for you via reportWorkflowStatus.

GitLab

First, let's create a GitLab project that will store our new scaffolder pipeline - Go to your GitLab account and create a new project.

Next, let's create the necessary token and secrets:

• Go to your Port application, click on your profile picture , then click Credentials. Copy your Client ID and Client secret.

• Go to your root group, and follow the steps here to create a new group access token with the following permission scopes: api, read_api, read_repository, write_repository, then save its value as it will be required in the next step.

  

• Go to the new GitLab project you created, from the Settings menu in the sidebar on the left, select CI/CD.

• Expand the Variables section and save the following secrets:

  • PORT_CLIENT_ID - Your Port client ID.
  • PORT_CLIENT_SECRET - Your Port client secret.
  • GITLAB_ACCESS_TOKEN - The GitLab group access token you created in the previous step.
    

• Expand the Pipeline trigger tokens section and add a new token, give it a meaningful description such as Scaffolder token and save its value.

  • You will store this token as a Port secret named GITLAB_TRIGGER_TOKEN in the Build the workflow section.

    
    
    

Project ID

You will also need your GitLab project ID for the Build the workflow section. To find it, browse to the GitLab page of the project you created, click the vertical 3 dots button at the top right corner (next to Fork) and select Copy project ID.

Now let's create the pipeline file that contains our logic.
In the root of your new GitLab project, create a new file named .gitlab-ci.yml and use the following snippet as its content:

GitLab pipeline (click to expand)

.gitlab-ci.yml

image: python:3.10.0-alpine

variables:
  # This is an example, you can replace it with any other cookiecutter template
  COOKIECUTTER_TEMPLATE_URL: "https://gitlab.com/AdriaanRol/cookiecutter-pypackage-gitlab"

stages:
  - fetch-port-access-token
  - scaffold-repo
  - create-repo-entity
  - create-service

# 1) Fetch a Port access token (used to create entities in the catalog)
fetch-port-access-token:
  stage: fetch-port-access-token
  except:
    - pushes
  before_script:
    - apk update
    - apk add jq curl -q
  script:
    - |
      echo "Getting access token from Port API"
      accessToken=$(curl -X POST \
        -H 'Content-Type: application/json' \
        -d '{"clientId": "'"$PORT_CLIENT_ID"'", "clientSecret": "'"$PORT_CLIENT_SECRET"'"}' \
        -s 'https://api.port.io/v1/auth/access_token' | jq -r '.accessToken')
      echo "ACCESS_TOKEN=$accessToken" >> data.env
  artifacts:
    reports:
      dotenv: data.env

# 2) Scaffold the repository (cookiecutter, push code, etc.)
scaffold-repo:
  stage: scaffold-repo
  needs: [fetch-port-access-token]
  except:
    - pushes
  before_script: |
    apk update
    apk add jq curl git -q
    pip3 install cookiecutter==2.3.0 -q
  script:
    - |
      echo "Creating new GitLab repository"
      service_name=$(cat $TRIGGER_PAYLOAD | jq -r '.service_name')
      CREATE_REPO_RESPONSE=$(curl -X POST -s "$CI_API_V4_URL/projects" --header "Private-Token: $GITLAB_ACCESS_TOKEN" --form "name=$service_name" --form "namespace_id=$CI_PROJECT_NAMESPACE_ID")
      PROJECT_URL=$(echo $CREATE_REPO_RESPONSE | jq -r .http_url_to_repo)

      echo "Checking if the repository creation was successful"
      if [[ -z "$PROJECT_URL" ]]; then
          echo "Failed to create GitLab repository."
          exit 1
      fi
      echo "Repository created"

      echo "PROJECT_URL=$PROJECT_URL" >> data.env
      echo "SERVICE_NAME=$service_name" >> data.env

      # Generate cookiecutter.yaml file
      cat <<EOF > cookiecutter.yaml
      default_context:
        full_name: "Mighty Scaffolder"
        email: "scaffolder@email.com"
        project_short_description: "Project scaffolded by Port"
        project_name: "${service_name}"
      EOF
      cookiecutter $COOKIECUTTER_TEMPLATE_URL --no-input --config-file cookiecutter.yaml --output-dir scaffold_out

      echo "Initializing new repository..."
      git config --global user.email "scaffolder@email.com"
      git config --global user.name "Mighty Scaffolder"
      git config --global init.defaultBranch "main"

      modified_service_name=$(echo "$service_name" | sed 's/[[:space:]-]/_/g')
      cd scaffold_out/$modified_service_name
      git init
      git add .
      git commit -m "Initial commit"
      GITLAB_HOSTNAME=$(echo "$CI_API_V4_URL" | cut -d'/' -f3)
      git remote add origin https://:$GITLAB_ACCESS_TOKEN@$GITLAB_HOSTNAME/${CI_PROJECT_NAMESPACE}/${service_name}.git
      git push -u origin main
  artifacts:
    reports:
      dotenv: data.env

# 3) Create a repository entity in Port
create-repo-entity:
  stage: create-repo-entity
  needs: [scaffold-repo]
  except:
    - pushes
  before_script:
    - apk update
    - apk add jq curl -q
  script:
    - |
      echo "Creating Port entity to match new repository"
      curl --location --request POST "https://api.port.io/v1/blueprints/gitlabRepository/entities?upsert=true&create_missing_related_entities=true" \
        --header "Authorization: Bearer $ACCESS_TOKEN" \
        --header "Content-Type: application/json" \
        -d '{"identifier": "'"$SERVICE_NAME"'","title": "'"$SERVICE_NAME"'","properties": {"url": "'"$PROJECT_URL"'"}, "relations": {}}'

# 4) Create the Service entity in Port, linking to the repo
create-service:
  stage: create-service
  needs: [create-repo-entity]
  except:
    - pushes
  before_script:
    - apk update
    - apk add jq curl -q
  script:
    - |
      echo "Creating Port entity to match new service"
      curl --location --request POST "https://api.port.io/v1/blueprints/service/entities?upsert=true&create_missing_related_entities=true" \
        --header "Authorization: Bearer $ACCESS_TOKEN" \
        --header "Content-Type: application/json" \
        -d '{"identifier": "'"$SERVICE_NAME"'_service","title": "'"$SERVICE_NAME"' Service","properties": {},"relations": {"git_lab_repositry": "'"$SERVICE_NAME"'"}}'

Bitbucket (Jenkins)

First, let's create the necessary tokens and secrets:

• Go to your Port application, click on your profile picture , then click Credentials. Copy your Client ID and Client secret.

• Configure the following as Jenkins credentials:

  • BITBUCKET_USERNAME - a user with access to the Bitbucket workspace and project.

  • BITBUCKET_APP_PASSWORD - an App Password with the Repositories:Read and Repositories:Write permissions.

  • PORT_CLIENT_ID - Your Port client ID.

  • PORT_CLIENT_SECRET - Your Port client secret.

    
    
    

Next, create a Jenkins pipeline with the following configuration:

• Enable the webhook trigger for the pipeline.

• Define the value of the token field, the token you specify will be used to trigger the scaffold pipeline specifically. For example, you can use scaffolder-token. You will reference this token in the webhook URL in the Build the workflow section.

• Define variables for the pipeline: define the SERVICE_NAME, BITBUCKET_WORKSPACE_NAME, and BITBUCKET_PROJECT_KEY variables. Scroll down to the Post content parameters and for each variable add configuration like so (look at the table below for the full variable list):

  

Create the following variables and their related JSONPath expression:

Variable Name	JSONPath Expression
SERVICE_NAME	$.service_name
BITBUCKET_WORKSPACE_NAME	$.bitbucket_workspace_name
BITBUCKET_PROJECT_KEY	$.bitbucket_project_key

Add the following content to the new Jenkins pipeline:

Jenkins pipeline (click to expand)

import groovy.json.JsonSlurper

pipeline {
    agent any

    environment {
        COOKIECUTTER_TEMPLATE = 'https://github.com/lacion/cookiecutter-golang'
        SERVICE_NAME = "${SERVICE_NAME}"
        BITBUCKET_WORKSPACE_NAME = "${BITBUCKET_WORKSPACE_NAME}"
        BITBUCKET_PROJECT_KEY = "${BITBUCKET_PROJECT_KEY}"
        SCAFFOLD_DIR = "scaffold_${SERVICE_NAME}"
        PORT_ACCESS_TOKEN = ""
    }

    stages {
        stage('Get access token') {
            steps {
                script {
                    withCredentials([
                        string(credentialsId: 'PORT_CLIENT_ID', variable: 'PORT_CLIENT_ID'),
                        string(credentialsId: 'PORT_CLIENT_SECRET', variable: 'PORT_CLIENT_SECRET')
                    ]) {
                        def result = sh(returnStdout: true, script: """
                            accessTokenPayload=\$(curl -X POST \
                                -H "Content-Type: application/json" \
                                -d '{"clientId": "${PORT_CLIENT_ID}", "clientSecret": "${PORT_CLIENT_SECRET}"}' \
                                -s "https://api.port.io/v1/auth/access_token")
                            echo \$accessTokenPayload
                        """)

                        def jsonSlurper = new JsonSlurper()
                        def payloadJson = jsonSlurper.parseText(result.trim())

                        PORT_ACCESS_TOKEN = payloadJson.accessToken
                    }
                }
            }
        } // end of stage Get access token

        stage('Create BitBucket Repository') {
            steps {
                script {
                    withCredentials([
                        string(credentialsId: 'BITBUCKET_USERNAME', variable: 'BITBUCKET_USERNAME'),
                        string(credentialsId: 'BITBUCKET_APP_PASSWORD', variable: 'BITBUCKET_APP_PASSWORD')
                    ]) {
                        sh """
                            curl -i -u ${BITBUCKET_USERNAME}:${BITBUCKET_APP_PASSWORD} \\
                            -d '{"is_private": true, "scm": "git", "project": {"key": "${BITBUCKET_PROJECT_KEY}"}}' \\
                            https://api.bitbucket.org/2.0/repositories/${BITBUCKET_WORKSPACE_NAME}/${SERVICE_NAME}
                        """
                    }
                }
            }
        } // end of stage Create BitBucket Repository

        stage('Scaffold Cookiecutter Template') {
            steps {
                script {
                    withCredentials([
                        string(credentialsId: 'BITBUCKET_USERNAME', variable: 'BITBUCKET_USERNAME'),
                        string(credentialsId: 'BITBUCKET_APP_PASSWORD', variable: 'BITBUCKET_APP_PASSWORD')
                    ]) {
                        def yamlContent = """
default_context:
  full_name: "Full Name"
  github_username: "bitbucketuser"
  app_name: "${SERVICE_NAME}"
  project_short_description": "A Golang project."
  docker_hub_username: "dockerhubuser"
  docker_image: "dockerhubuser/alpine-base-image:latest"
  docker_build_image: "dockerhubuser/alpine-golang-buildimage"
"""
                    writeFile(file: 'cookiecutter.yaml', text: yamlContent)

                        sh("""
                            rm -rf ${SCAFFOLD_DIR} ${SERVICE_NAME}
                            git clone https://${BITBUCKET_USERNAME}:${BITBUCKET_APP_PASSWORD}@bitbucket.org/${BITBUCKET_WORKSPACE_NAME}/${SERVICE_NAME}.git

                            cookiecutter ${COOKIECUTTER_TEMPLATE} --output-dir ${SCAFFOLD_DIR} --no-input --config-file cookiecutter.yaml -f

                            rm -rf ${SCAFFOLD_DIR}/${SERVICE_NAME}/.git*
                            cp -r ${SCAFFOLD_DIR}/${SERVICE_NAME}/* "${SERVICE_NAME}/"

                            cd ${SERVICE_NAME}
                            git config user.name "Jenkins Pipeline Bot"
                            git config user.email "jenkins-pipeline[bot]@users.noreply.jenkins.com"
                            git add .
                            git commit -m "Scaffolded project ${SERVICE_NAME}"
                            git push -u origin master
                            cd ..

                            rm -rf ${SCAFFOLD_DIR} ${SERVICE_NAME}
                        """)
                    }
                }
            }
        } // end of stage Scaffold Cookiecutter Template

        stage('CREATE repository entity') {
            steps {
                script {
                    def status_report_response = sh(script: """
                        curl --location --request POST "https://api.port.io/v1/blueprints/bitbucketRepository/entities?upsert=true&create_missing_related_entities=true" \
        --header "Authorization: Bearer $PORT_ACCESS_TOKEN" \
        --header "Content-Type: application/json" \
        --data-raw '{
                "identifier": "${SERVICE_NAME}",
                "title": "${SERVICE_NAME}",
                "properties": {"description":"${SERVICE_NAME} golang project","url":"https://bitbucket.org/${BITBUCKET_WORKSPACE_NAME}/${SERVICE_NAME}/src"},
                "relations": {}
            }'
                    """, returnStdout: true)

                    println(status_report_response)
                }
            }
        } // end of stage CREATE repository entity

        stage('CREATE Microservice entity') {
            steps {
                script {
                    def status_report_response = sh(script: """
                        curl --location --request POST "https://api.port.io/v1/blueprints/service/entities?upsert=true&create_missing_related_entities=true" \
        --header "Authorization: Bearer $PORT_ACCESS_TOKEN" \
        --header "Content-Type: application/json" \
        --data-raw '{
                "identifier": "${SERVICE_NAME}_service",
                "title": "${SERVICE_NAME} Service",
                "properties": {},
                "relations": {"bitbucketRepository": "${SERVICE_NAME}"}
            }'
                    """, returnStdout: true)

                    println(status_report_response)
                }
            }
        } // end of stage CREATE Microservice entity
    }

    post {
        always {
            cleanWs(cleanWhenNotBuilt: false,
                    deleteDirs: true,
                    disableDeferredWipeout: false,
                    notFailBuild: true,
                    patterns: [[pattern: '.gitignore', type: 'INCLUDE'],
                               [pattern: '.propsfile', type: 'EXCLUDE']])
        }
    }
}

Azure DevOps

• Create an Azure DevOps repository called Port-actions in your Azure DevOps Organization/Project.

• Configure Service Connection and Webhook:

  • Go to your Azure DevOps project.
  • Navigate to Project Settings > Service connections.
  • Click on New service connection.
  • Select Incoming Webhook.
  • Use the same name for both Webhook Name and Service connection name. You will reference this webhook name in the webhook URL in the Build the workflow section.

• Create Azure Pipeline in Port-actions Repository.

In your Port-actions Azure DevOps repository, create an Azure Pipeline file named azure-pipelines.yml in the root of the repo's main branch with the following content:

Azure DevOps Pipeline Script

azure-pipelines.yml

trigger: none

pool:
  vmImage: "ubuntu-latest"

variables:
  SERVICE_NAME: "${{ parameters.SERVICE_CONNECTION_NAME.properties.service_name }}"
  DESCRIPTION: "${{ parameters.SERVICE_CONNECTION_NAME.properties.description }}"
  AZURE_ORGANIZATION: "${{ parameters.SERVICE_CONNECTION_NAME.properties.azure_organization }}"
  PROJECT_ID: "${{ parameters.SERVICE_CONNECTION_NAME.properties.azure_project }}"
  # Ensure that PERSONAL_ACCESS_TOKEN, PORT_CLIENT_ID and PORT_CLIENT_SECRET are set as secret variables in your pipeline settings

resources:
  webhooks:
    - webhook: WEBHOOK_NAME
      connection: SERVICE_CONNECTION_NAME

stages:
  - stage: fetch_port_access_token
    jobs:
      - job: fetch_port_access_token
        steps:
          - script: |
              sudo apt-get update
              sudo apt-get install -y jq
          - script: |
              accessToken=$(curl -X POST \
                    -H 'Content-Type: application/json' \
                    -d '{"clientId": "$(PORT_CLIENT_ID)", "clientSecret": "$(PORT_CLIENT_SECRET)"}' \
                    -s 'https://api.port.io/v1/auth/access_token' | jq -r '.accessToken')
              echo "##vso[task.setvariable variable=accessToken;isOutput=true]$accessToken"
            displayName: Fetch Access Token
            name: getToken

  - stage: scaffold
    dependsOn:
      - fetch_port_access_token
    jobs:
      - job: scaffold
        variables:
          COOKIECUTTER_TEMPLATE_URL: "https://github.com/brettcannon/python-azure-web-app-cookiecutter"
        steps:
          - script: |
              sudo apt-get update
              sudo apt-get install -y jq
              sudo pip install cookiecutter -q
          - script: |
              PAYLOAD="{\"name\":\"$SERVICE_NAME\",\"project\":{\"id\":\"$PROJECT_ID\"}}"

              echo "SERVICE_NAME: $SERVICE_NAME"
              echo "AZURE_ORGANIZATION: $AZURE_ORGANIZATION"
              echo "PROJECT_ID: $PROJECT_ID"

              if [[ -z \"$PERSONAL_ACCESS_TOKEN\" ]]; then
                echo "PERSONAL_ACCESS_TOKEN is not set or is empty."
                exit 1
              fi

              # Create the repository
              CREATE_REPO_RESPONSE=$(curl -s -u :$PERSONAL_ACCESS_TOKEN \
                -X POST "https://dev.azure.com/$AZURE_ORGANIZATION/$PROJECT_ID/_apis/git/repositories?api-version=7.0" \
                -H "Content-Type: application/json" \
                -d "$PAYLOAD")

              echo "CREATE_REPO_RESPONSE: $CREATE_REPO_RESPONSE"

              PROJECT_URL=$(echo $CREATE_REPO_RESPONSE | jq -r .webUrl)

              if [[ -z "$PROJECT_URL" ]] || [[ "$PROJECT_URL" == "null" ]]; then
                echo "Failed to create Azure DevOps repository."
                exit 1
              fi

              echo "##vso[task.setvariable variable=PROJECT_URL;isOutput=true]$PROJECT_URL"

              cat <<EOF > cookiecutter.yaml
              default_context:
                site_name: "$SERVICE_NAME"
                python_version: "3.6.0"
              EOF
              cookiecutter $COOKIECUTTER_TEMPLATE_URL --no-input --config-file cookiecutter.yaml --output-dir scaffold_out

              echo "Initializing new repository..."
              git config --global user.email "scaffolder@email.com"
              git config --global user.name "Mighty Scaffolder"
              git config --global init.defaultBranch "main"

              cd "scaffold_out/$SERVICE_NAME"
              git init
              git add .
              git commit -m "Initial commit"

              GIT_REPO_URL=$(echo $CREATE_REPO_RESPONSE | jq -r .remoteUrl)

              if [[ -z "$GIT_REPO_URL" ]] || [[ "$GIT_REPO_URL" == "null" ]]; then
                echo "Failed to retrieve the remote URL from the repository creation response."
                exit 1
              fi

              git remote add origin "$GIT_REPO_URL"
              git config http.https://dev.azure.com/.extraheader "AUTHORIZATION: Basic $(echo -n :$PERSONAL_ACCESS_TOKEN | base64)"

              git push -u origin --all

            env:
              PERSONAL_ACCESS_TOKEN: $(PERSONAL_ACCESS_TOKEN)
            displayName: "Create Repository in Azure DevOps"
            name: scaffold

  - stage: upsert_repository
    dependsOn:
      - fetch_port_access_token
      - scaffold
    jobs:
      - job: upsert_repository
        variables:
          accessToken: $[ stageDependencies.fetch_port_access_token.fetch_port_access_token.outputs['getToken.accessToken'] ]
          PROJECT_URL: $[ stageDependencies.scaffold.scaffold.outputs['scaffold.PROJECT_URL'] ]
        steps:
          - script: |
              sudo apt-get update
              sudo apt-get install -y jq
          - script: |
              curl -X POST \
                -H 'Content-Type: application/json' \
                -H 'Authorization: Bearer $(accessToken)' \
                -d '{
                    "identifier": "${{ variables.SERVICE_NAME }}",
                    "title": "${{ variables.SERVICE_NAME }}",
                    "properties": {"description":"${{ variables.DESCRIPTION }}","url":"$(PROJECT_URL)" },
                    "relations": {
                      "project":"${{ variables.PROJECT_ID }}"
                    }
                  }' \
                "https://api.port.io/v1/blueprints/service/entities?upsert=true&create_missing_related_entities=true"

  - stage: upsert_service
    dependsOn:
      - upsert_repository
      - fetch_port_access_token
    jobs:
      - job: upsert_service
        variables:
          accessToken: $[ stageDependencies.fetch_port_access_token.fetch_port_access_token.outputs['getToken.accessToken'] ]
        steps:
          - script: |
              sudo apt-get update
              sudo apt-get install -y jq
          - script: |
              echo "Upserting service entity in Port"
              curl -X POST \
                -H 'Content-Type: application/json' \
                -H 'Authorization: Bearer $(accessToken)' \
                -d '{
                    "identifier": "${{ variables.SERVICE_NAME }}_service",
                    "title": "${{ variables.SERVICE_NAME }} Service",
                    "properties": {
                      "description":"${{ variables.DESCRIPTION }}"
                    },
                    "relations": {
                      "service": "${{ variables.SERVICE_NAME }}"
                    }
                  }' \
                "https://api.port.io/v1/blueprints/service/entities?upsert=true&create_missing_related_entities=true"

Placeholder values

Replace SERVICE_CONNECTION_NAME with the name of the service connection you created in Azure DevOps and WEBHOOK_NAME with the name of the webhook you created in Azure DevOps which should be the same as the service connection name.

• Configure the Pipeline:

  • In your Azure DevOps project, navigate to Pipelines > Create Pipeline.
  • Select Azure Repos Git and choose the Port-actions repository.
  • Click Save (in the "Run" dropdown menu).

• Create the necessary tokens and secrets:

  • Go to your Port application, click on your profile picture , then click Credentials. Copy your Client ID and Client secret.

• Configure the following as Variables for the azure-pipelines.yml:

  • Go to pipelines and select the Port-actions pipeline.
  • Click on Edit and then Variables.
  • Add the following variables:
    • PORT_CLIENT_ID - Your Port client ID.
    • PORT_CLIENT_SECRET - Your Port client secret.
    • PERSONAL_ACCESS_TOKEN - Your Azure DevOps personal access token.
      

Need help?

Having issues with Azure DevOps integration or pipelines? See the Azure DevOps Troubleshooting Guide for step-by-step help.

Cookiecutter template

The cookiecutter templates provided in the pipelines are just examples, you can replace them with any other cookiecutter template you want to use, by changing the value of the relevant template variable in the pipeline.

Build the workflow

Now we will create the workflow that triggers the backend and registers the service in Port.

1. Go to the Workflows page of your portal.

2. Click on the + Workflow button in the top-right corner.

3. Fill and submit the form for creating the new workflow.

4. Copy and paste the workflow JSON below into the editor to replace the example workflow:

   GitHub

   For this example, the workflow sends one detail that our backend needs to know - the service name. Note that the service name will be the same as the repository name.

   Scaffold service workflow JSON (click to expand)

   {
     "identifier": "scaffold_new_service",
     "title": "Scaffold a new service",
     "icon": "Microservice",
     "description": "Create a new repository and register a service in Port",
     "nodes": [
       {
         "identifier": "trigger",
         "config": {
           "type": "SELF_SERVE_TRIGGER",
           "userInputs": {
             "properties": {
               "service_name": {
                 "type": "string",
                 "title": "Service name",
                 "description": "The name of the new service"
               }
             },
             "required": ["service_name"]
           },
           "published": true
         }
       },
       {
         "identifier": "create_repo",
         "title": "Create repository",
         "icon": "Github",
         "config": {
           "type": "INTEGRATION_ACTION",
           "installationId": "YOUR_GITHUB_OCEAN_INSTALLATION_ID",
           "integrationProvider": "github-ocean",
           "integrationInvocationType": "dispatch_workflow",
           "integrationActionExecutionProperties": {
             "org": "YOUR_GITHUB_ORGANIZATION",
             "repo": "YOUR_BACKEND_REPO",
             "workflow": "port-create-service.yml",
             "workflowInputs": {
               "service_name": "{{ .outputs.trigger.service_name }}"
             },
             "reportWorkflowStatus": true
           }
         }
       },
       {
         "identifier": "create_service",
         "title": "Register service in Port",
         "config": {
           "type": "UPSERT_ENTITY",
           "blueprintIdentifier": "service",
           "mapping": {
             "identifier": "{{ .outputs.trigger.service_name }}_service",
             "title": "{{ .outputs.trigger.service_name }} Service",
             "relations": {
               "github_repository": "{{ .outputs.trigger.service_name }}"
             }
           }
         }
       }
     ],
     "connections": [
       { "sourceIdentifier": "trigger", "targetIdentifier": "create_repo" },
       {
         "sourceIdentifier": "create_repo",
         "targetIdentifier": "create_service"
       }
     ]
   }

   Replace YOUR_GITHUB_OCEAN_INSTALLATION_ID with your integration's installation ID (found in the Data sources page), YOUR_GITHUB_ORGANIZATION with your GitHub organization name, and YOUR_BACKEND_REPO with the repository that holds the port-create-service.yml workflow.

   GitLab

   The workflow triggers your GitLab pipeline using a webhook node. The pipeline reads the request body as $TRIGGER_PAYLOAD and creates the repository and entities.

   Scaffold service workflow JSON (click to expand)

   {
     "identifier": "scaffold_new_service",
     "title": "Scaffold a new service",
     "icon": "Microservice",
     "description": "Create a new GitLab repository and register a service in Port",
     "nodes": [
       {
         "identifier": "trigger",
         "config": {
           "type": "SELF_SERVE_TRIGGER",
           "userInputs": {
             "properties": {
               "service_name": {
                 "type": "string",
                 "title": "Service name",
                 "description": "The name of the new service"
               }
             },
             "required": ["service_name"]
           },
           "published": true
         }
       },
       {
         "identifier": "trigger_pipeline",
         "title": "Trigger GitLab pipeline",
         "icon": "Gitlab",
         "config": {
           "type": "WEBHOOK",
           "url": "https://gitlab.com/api/v4/projects/YOUR_GITLAB_PROJECT_ID/ref/main/trigger/pipeline?token={{ .secrets[\"GITLAB_TRIGGER_TOKEN\"] }}",
           "method": "POST",
           "body": {
             "service_name": "{{ .outputs.trigger.service_name }}"
           }
         }
       }
     ],
     "connections": [
       { "sourceIdentifier": "trigger", "targetIdentifier": "trigger_pipeline" }
     ]
   }

   Replace YOUR_GITLAB_PROJECT_ID with the ID of the GitLab project that stores your .gitlab-ci.yml pipeline.
   Before publishing, add a Port secret named GITLAB_TRIGGER_TOKEN with the trigger token you created in the Set up the backend section (see Add secrets to Port below).

   Bitbucket (Jenkins)

   When executing this workflow, developers provide the service name and two additional Bitbucket inputs. The workflow triggers your Jenkins pipeline using a webhook node.

   Scaffold service workflow JSON (click to expand)

   {
     "identifier": "scaffold_new_service",
     "title": "Scaffold a new service",
     "icon": "Microservice",
     "description": "Create a new Bitbucket repository and register a service in Port",
     "nodes": [
       {
         "identifier": "trigger",
         "config": {
           "type": "SELF_SERVE_TRIGGER",
           "userInputs": {
             "properties": {
               "service_name": {
                 "type": "string",
                 "title": "Service name",
                 "description": "The name of the new service"
               },
               "bitbucket_workspace_name": {
                 "type": "string",
                 "title": "Bitbucket Workspace Name",
                 "description": "The name of the workspace in which to create the new repository"
               },
               "bitbucket_project_key": {
                 "type": "string",
                 "title": "Bitbucket Project Key",
                 "description": "The key of the Bitbucket project in which to create the new repository"
               }
             },
             "required": [
               "service_name",
               "bitbucket_workspace_name",
               "bitbucket_project_key"
             ]
           },
           "published": true
         }
       },
       {
         "identifier": "trigger_pipeline",
         "title": "Trigger Jenkins pipeline",
         "icon": "Jenkins",
         "config": {
           "type": "WEBHOOK",
           "url": "https://YOUR_JENKINS_URL/generic-webhook-trigger/invoke?token=scaffolder-token",
           "method": "POST",
           "headers": {
             "Content-Type": "application/json"
           },
           "body": {
             "service_name": "{{ .outputs.trigger.service_name }}",
             "bitbucket_workspace_name": "{{ .outputs.trigger.bitbucket_workspace_name }}",
             "bitbucket_project_key": "{{ .outputs.trigger.bitbucket_project_key }}"
           }
         }
       }
     ],
     "connections": [
       { "sourceIdentifier": "trigger", "targetIdentifier": "trigger_pipeline" }
     ]
   }

   Replace YOUR_JENKINS_URL with your Jenkins instance URL, and make sure the token query parameter matches the token you defined for the pipeline.

   Azure DevOps

   When executing this workflow, developers provide the service name and additional Azure DevOps inputs. The workflow triggers your Azure pipeline using a webhook node that posts to your Azure DevOps incoming webhook.

   Scaffold service workflow JSON (click to expand)

   {
     "identifier": "scaffold_new_service",
     "title": "Scaffold a new service",
     "icon": "Microservice",
     "description": "Create a new Azure DevOps repository and register a service in Port",
     "nodes": [
       {
         "identifier": "trigger",
         "config": {
           "type": "SELF_SERVE_TRIGGER",
           "userInputs": {
             "properties": {
               "service_name": {
                 "type": "string",
                 "title": "Service Name",
                 "description": "The name of the new service"
               },
               "azure_organization": {
                 "type": "string",
                 "title": "Azure Organization"
               },
               "azure_project": {
                 "type": "string",
                 "format": "entity",
                 "blueprint": "project",
                 "title": "Azure Project"
               },
               "description": {
                 "type": "string",
                 "title": "Description"
               }
             },
             "required": ["service_name", "azure_organization", "azure_project"]
           },
           "published": true
         }
       },
       {
         "identifier": "trigger_pipeline",
         "title": "Trigger Azure pipeline",
         "icon": "AzureDevops",
         "config": {
           "type": "WEBHOOK",
           "url": "https://dev.azure.com/YOUR_AZURE_ORGANIZATION/_apis/public/distributedtask/webhooks/YOUR_WEBHOOK_NAME?api-version=6.0-preview",
           "method": "POST",
           "headers": {
             "Content-Type": "application/json"
           },
           "body": {
             "properties": {
               "service_name": "{{ .outputs.trigger.service_name }}",
               "azure_organization": "{{ .outputs.trigger.azure_organization }}",
               "description": "{{ .outputs.trigger.description }}",
               "azure_project": "{{ .outputs.trigger.azure_project }}"
             }
           }
         }
       }
     ],
     "connections": [
       { "sourceIdentifier": "trigger", "targetIdentifier": "trigger_pipeline" }
     ]
   }

   Replace YOUR_AZURE_ORGANIZATION with your Azure DevOps organization name and YOUR_WEBHOOK_NAME with the incoming webhook name you created in the Set up the backend section.

5. Click Publish to save the workflow.

Add secrets to Port

For the providers that use a webhook node (GitLab, Bitbucket, and Azure DevOps), store any required tokens as Port secrets so the workflow can reference them via {{ .secrets["<name>"] }}.

1. Go to your portal's Settings page.

2. Navigate to Credentials and add the secrets your workflow references, for example:

   • GITLAB_TRIGGER_TOKEN - the GitLab pipeline trigger token (GitLab only).

Secrets and integration actions

Secrets are not supported with integration actions. The GitHub workflow above authenticates automatically through your installed integration, so it does not need a secret. Secrets are used only in the webhook nodes for GitLab, Bitbucket, and Azure DevOps.

All done! The workflow is ready to be used 🚀

Execute the workflow

Head to the Self-Service page of your Port application:

1. Find Scaffold a new service and click on it to begin executing the workflow.

2. Enter a name for your new repository.

   Repository name restrictions

   Some Git providers (for example, GitHub) do not allow spaces in repository names.
   We recommend using underscores or hyphens instead of spaces.

3. For some of the available Git providers, additional inputs are required when executing the workflow.

   Bitbucket (Jenkins)

   When executing the Bitbucket scaffolder, you will need to provide two additional inputs:

   • Bitbucket Workspace Name - the name of the workspace to create the new repository in.
     • Bitbucket Project Key - the key of the Bitbucket project to create the new repository in.
       • To find the Bitbucket project key, go to https://bitbucket.org/YOUR_BITBUCKET_WORKSPACE/workspace/projects/, find the desired project in the list, and copy the value seen in the Key column in the table.

   Azure DevOps

   When executing the Azure DevOps scaffolder, you will need to provide the following additional inputs:

   • Azure Organization - the name of the Azure DevOps organization.
     • Azure Project - select the Azure DevOps project you want the repo to be created in.
     • Description - a brief description of the repository. (Optional)

4. Click Execute.

5. Follow the workflow's progress in the Workflow runs tab. Each node shows its status, and you can expand a node to inspect its output and logs.

6. Head over to the service catalog and you will see a service entity created with the repository linked to it:

   
   
   

Congratulations! You can now create services easily from Port 💪🏽

Possible daily routine integrations

• Send a slack message in the R&D channel to let everyone know that a new service was created, using an additional webhook node.
• Send a weekly/monthly report for managers showing all the new services created in this timeframe and their owners.

Conclusion

Creating a service is not just a periodic task developers undertake, but a vital step that can occur on a monthly basis. However, it's crucial to recognize that this is only a fragment of the broader experience that we're striving to create for developers. Our ultimate goal is to facilitate a seamless transition from ideation to production. In doing so, we aim to eliminate the need for developers to navigate through a plethora of tools, reducing friction and accelerating the time-to-production.
In essence, we're not just building a tool, but sculpting an ecosystem that empowers developers to bring new features to life with utmost efficiency.