> For the complete documentation index, see llms.txt.
Skip to main content

Check out Port for yourself ➜ 

Scaffold a new service

This guide will walk you through setting up a self-service action to allow 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 action 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.
Available Github Integrations

This guide includes one or more steps that require integration with GitHub.
Port supports two GitHub integrations:

  • GitHub (Legacy) - uses a GitHub app, which is soon to be deprecated.
  • GitHub (Ocean) - uses the Ocean framework, recommended for new integrations.

Both integration options are present in this guide via tabs, choose the one that fits your needs.

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 an action they can simply execute.
  • Track created services using a wide array of visualizations.

Prerequisites​

  • A Port account with permissions to create self-service actions.
  • 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.

Implementation​

Set up the action's frontend​

  1. Head to the Self-service page of your portal.

  2. Click on the + Action button in the top-right corner (or in the middle if there are no actions yet):

  3. Fill the basic form with the Title and Description and select Create and Service for the Operation and Blueprint respectively.


  4. Click Next to proceed to the User Form tab, then click on + Input.

  5. Enter Service name as the Title, select Text for the Type, set Required to True, and click on the Create button.


    If using Bitbucket, you will need to create these two additional inputs:

    Bitbucket Requirements
    Input NameTypeRequiredAdditional Information
    Bitbucket Workspace NameStringYesThe name of the workspace in which to create the new repository.
    Bitbucket Project KeyStringYesThe key of the Bitbucket project in which to create the new repository.

  6. Click Next to configure the Backend.

Define backend type​

Now we'll define the backend of the action. Port supports multiple invocation types, depending on the Git provider you are using.

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-service.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. Note that the service name will be the same as the repository name. Copy the following JSON snippet and paste it in the payload code box:

    {
      "port_context": {
          "runId": "{{ .run.id }}"
      },
      "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 Create.

The action's frontend is now ready 🥳


Set up 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).

      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 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 workflow file that contains our logic.
    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):

    Personal (user) account note

    If you are scaffolding repositories under a personal GitHub account (user-owned repositories), the integration cannot rely on organization-level webhooks to discover newly created repositories immediately.

    To avoid githubRepository relation 404s when creating the service entity, set createPortEntity: true in your workflow under the step that uses port-labs/cookiecutter-gha@..., so the repository entity is created in Port as part of the scaffold.

    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
          description:
            required: false
            description: Description of the service
            type: string
          port_context:
            required: true
            description: Includes the action's run id
            type: string

    jobs:
      scaffold-service:
        runs-on: ubuntu-latest
        env:
          ORG_NAME: <YOUR-ORG-NAME>

        steps:
          - uses: actions/checkout@v4
          
          - name: Extract runId from port_context
            run: |
              echo "PORT_RUN_ID=$(echo '${{ inputs.port_context }}' | jq -r .runId)" >> $GITHUB_ENV

          - name: Create a log message
            uses: port-labs/port-github-action@v1
            with:
              clientId: ${{ secrets.PORT_CLIENT_ID }}
              clientSecret: ${{ secrets.PORT_CLIENT_SECRET }}
              baseUrl: https://api.port.io
              operation: PATCH_RUN
              runId: ${{ env.PORT_RUN_ID }}
              logMessage: "Starting scaffolding of service and repository: ${{ inputs.service_name }}"

          - 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 }}
              portRunId: ${{ fromJson(inputs.port_context).runId }}
              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: false


          - name: Create Service in Port with Repository Relation
            uses: port-labs/port-github-action@v1
            with:
              clientId: ${{ secrets.PORT_CLIENT_ID }}
              clientSecret: ${{ secrets.PORT_CLIENT_SECRET }}
              baseUrl: https://api.port.io
              operation: UPSERT
              identifier: "${{ inputs.service_name }}_service"
              title: "${{ inputs.service_name }} Service"
              blueprint: "service"
              createMissingRelatedEntities: true
              relations: |
                { "repository": "${{ inputs.service_name }}" }

          - name: Create a log message
            uses: port-labs/port-github-action@v1
            with:
              clientId: ${{ secrets.PORT_CLIENT_ID }}
              clientSecret: ${{ secrets.PORT_CLIENT_SECRET }}
              baseUrl: https://api.port.io
              operation: PATCH_RUN
              runId: ${{ env.PORT_RUN_ID }}
              logMessage: "Finished scaffolding of service and repository: ${{ inputs.service_name }}"

          - name: Report action status to Port
            uses: port-labs/port-github-action@v1
            with:
              clientId: ${{ secrets.PORT_CLIENT_ID }}
              clientSecret: ${{ secrets.PORT_CLIENT_SECRET }}
              baseUrl: https://api.port.io
              operation: PATCH_RUN
              runId: ${{ env.PORT_RUN_ID }}
              status: "SUCCESS"
              summary: "Scaffolding of service and repository finished successfully"

          - name: Report failure status to Port
            if: failure()
            uses: port-labs/port-github-action@v1
            with:
              clientId: ${{ secrets.PORT_CLIENT_ID }}
              clientSecret: ${{ secrets.PORT_CLIENT_SECRET }}
              baseUrl: https://api.port.io
              operation: PATCH_RUN
              runId: ${{ env.PORT_RUN_ID }}
              status: "FAILURE"
              summary: "Failed to scaffold service and 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.

    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 action.

    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.

  4. Click Execute. Click the button to view the action's progress.

  5. 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.

  6. Head over to the service catalog and you will see a microservice 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.
  • 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.