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.

Prerequisites
  • 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​

Onboarding

As part of the onboarding process, you should already have an action named Scaffold a new service in your self-service tab.
In that case, you can hover over the action, click the ... button in the top right corner, and choose "Edit":

Then, skip to the Define backend type step.

If you skipped the onboarding, or you want to create the action from scratch, complete the Create the action's frontend steps below.

Create the action's frontend
  1. Click on New action:

  1. Each action in Port is directly tied to a blueprint. Since we are creating a repository, let's use the Service blueprint that was created for us as part of the onboarding process. Choose it from the dropdown.

  2. Fill in the basic details of the action like this, then click Next:

  1. The next step is to define the action's inputs. When someone uses this action, all we want them to enter is the new repository's name. Click on New input, fill in the form like this, then click on Create:
notes
  • We set the Required field to true to ensure that a name is always provided when using this action.
  • We set the type to Text since this is a name, but note all of the different types of input that Port allows.
  • When using Text inputs, you can set constraints and limitations to enforce certain patterns.

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.
  • Set Omit user inputs to Yes.
  • Fill out the rest of the form like this, then click Next:
Important

In our workflow, the cookiecutter uses the payload for the inputs. We omit the user inputs in order to avoid sending additional inputs to the workflow.

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 🥳


Setup the action's backend​

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

Important

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 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. Under .github/workflows, 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 19 to your GitHub organization name):
Github workflow (click to expand)
port-create-repo.yml
name: Scaffold a new service
on:
  workflow_dispatch:
    inputs:
      port_payload:
        required: true
        description: "Port's payload, including details for who triggered the action and general context (blueprint, run id, etc...)"
        type: string
    secrets:
      ORG_ADMIN_TOKEN:
        required: true
      PORT_CLIENT_ID:
        required: true
      PORT_CLIENT_SECRET:
        required: true
jobs:
  scaffold-service:
    env:
      ORG_NAME: <YOUR-ORG-NAME>
    runs-on: ubuntu-latest
    steps:
      - uses: port-labs/cookiecutter-gha@v1.1.1
        id: scaff
        with:
          portClientId: ${{ secrets.PORT_CLIENT_ID }}
          portClientSecret: ${{ secrets.PORT_CLIENT_SECRET }}
          token: ${{ secrets.ORG_ADMIN_TOKEN }}
          portRunId: ${{ fromJson(inputs.port_payload).context.runId }}
          repositoryName: ${{ fromJson(inputs.port_payload).payload.properties.service_name }}
          portUserInputs: '{"cookiecutter_app_name": "${{ fromJson(inputs.port_payload).payload.properties.service_name }}" }'
          cookiecutterTemplate: https://github.com/lacion/cookiecutter-golang
          blueprintIdentifier: "service"
          organizationName: ${{ env.ORG_NAME }}
tip

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​

After creating an action, it will appear under the Self-service tab 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:



Trigger bitbucket scaffolder

To trigger the Bitbucket scaffolder, you will need to provide two additional parameters:

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

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.