Skip to main content

Scaffold a new service

This guide takes 7 minutes to complete, and aims to demonstrate the power of self-service actions in Port.

  • This guide assumes you have a Port account and that you have finished the onboarding process. We will use the Service blueprint that was created during the onboarding process.
  • You will need a Git repository (Github, GitLab, or Bitbucket) in which you can place a workflow/pipeline that we will use in this guide. If you don't have one, we recommend creating a new repository named Port-actions.

The goal of this guide

In this guide we will create an action that initializes a new Git repository. In reality, such an action can be used by developers to scaffold new services.

After completing it, you will get a sense of how it can benefit different personas in your organization:

  • Developers will be able to scaffold new services easily.
  • R&D managers will be able to get an overview of new services - how many were created and by who.
  • Platform engineers will be able to control permissions to ensure only the relevant people can create new services.

Setup the action's frontend


As part of the onboarding process, you should already have an action named Scaffold a new service in your self-service tab.

If you skipped the onboarding, follow the instructions listed here.

  1. Head to the Self-service page of your portal. Hover over the Scaffold a new service action, click the ... button in the top right corner, and choose "Edit":

  2. The action's basic details should look like the image below. You can click on the User Form tab to see the user inputs created for the action. When ready, click on the Backend tab to proceed.

Define backend type

Now we'll define the backend of the action. Port supports multiple invocation types, one of them should be selected for you depending on the Git provider you selected in the beginning of the onboarding process.

Fill out the form with your values:

  • Replace the Organization and Repository values with your values (this is where the workflow will reside and run).

  • Name the workflow port-create-repo.yml.

  • Fill out your workflow details:

  • Scroll down to the Configure the invocation payload section.
    This is where you can define which data will be sent to your backend each time the action is executed.

    For this example, we will send two details that our backend needs to know - the service name, and the id of the action run.
    Copy the following JSON snippet and paste it in the payload code box:

    "port_context": {
    "runId": "{{ }}"
    "service_name": "{{ .inputs.service_name }}"

The last step is customizing the action's permissions. For simplicity's sake, we will use the default settings. For more information, see the permissions page. Click Save.

The action's frontend is now ready 🥳

Setup the action's backend

Now we want to write the logic that our action will trigger.


If the Github organization which will house your workflow is not the same as the one you'll create the new repository in, install Port's Github app 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).


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 the ... in the top right corner, then click Credentials. Copy your Client ID and Client secret.
  1. In the repository where your 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.

  1. Now let's create the workflow file that contains our logic. First, ensure that you have a .github/workflows directory, then create a new file named port-create-repo.yml and use the following snippet as its content (remember to change <YOUR-ORG-NAME> on line 22 to your GitHub organization name):

The GitHub workflow example below assumes that you will use the cookiecutter template specified in line 34. If you would instead prefer to use a template from a private repository, replace line 34 in the template below with the following, ensuring to specify the GitHub org and repo name where instructed: cookiecutterTemplate: https://oauth2:$$<SPECIFY GITHUB ORG NAME HERE>/$<SPECIFY TEMPLATE REPO HERE>.git. If the template GitHub repo is not within the same organization where this repo will be placed, please ensure you replace the ORG_ADMIN_TOKEN parameter with a token containing the same parameters used when you created the token in the previous step.

Github workflow (click to expand)
name: Scaffold a new service
required: true
description: Includes the action's run id
required: true
description: The name of the new service
type: string
required: true
required: true
required: true
runs-on: ubuntu-latest
- uses: port-labs/cookiecutter-gha@v1.1.1
id: scaff
portClientId: ${{ secrets.PORT_CLIENT_ID }}
portClientSecret: ${{ secrets.PORT_CLIENT_SECRET }}
token: ${{ secrets.ORG_ADMIN_TOKEN }}
portRunId: ${{ fromJson(inputs.port_context).runId }}
repositoryName: ${{ inputs.service_name }}
portUserInputs: '{"cookiecutter_app_name": "${{ inputs.service_name }}" }'
blueprintIdentifier: "service"
organizationName: ${{ env.ORG_NAME }}

This workflow uses Port's cookiecutter Github action to scaffold the new repository.

Cookiecutter template

The cookiecutter templates provided in the workflows 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 workflow.

All done! The action is ready to be used 🚀

Execute the action

Head back to the Self-service page of your Port application:

  1. Click on Create to begin executing the action.

  2. Enter a name for your new repository, then click Execute. A small popup will appear, click on View details:

Bitbucket only - additional inputs

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, find the desired project in the list, and copy the value seen in the Key column in the table

  1. This page provides details about the action run. As you can see, the backend returned Success and the repo was successfully created (this can take a few moments):

Logging action progress

💡 Note the Log stream at the bottom, this can be used to report progress, results and errors. Click here to learn more.

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.
  • Send a weekly/monthly report for managers showing all the new services created in this timeframe and their owners.


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.