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 a basic knowledge of working with Port. If you haven't done so, go ahead and complete the quickstart.
You will need a Github repository in which you can place a workflow 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 Github 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 your organization's daily routine could look like:

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

To get started, head to the Self-service tab in your Port application, and click on New action:

Each action in Port is directly tied to a blueprint. Since we are creating a repository, the Service blueprint we created in the quickstart guide is an obvious candidate. Choose it from the dropdown.
Fill in the basic details of the action like this, then click Next:

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.

Now we'll define the backend of the action. Port supports multiple invocation types, for this tutorial we will use a Github workflow.
- Replace the Organization and Repository values with your values (this is where the workflow will reside and run).
- Name the workflow portCreateRepo.yaml.
- 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.

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

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.

Now let's create the workflow file that contains our logic. Under ".github/workflows", create a new file named portCreateRepo.yaml and use the following snippet as its content:

Change <YOUR-ORG-NAME> to the name of the organization in which you want to create the new repository.

Github workflow (click to expand)

# portCreateRepo.yaml

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
        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 }}

      - name: "Report deployment Entity to port 🚢"
        uses: port-labs/port-github-action@v1
        with:
          clientId: ${{ secrets.PORT_CLIENT_ID }}
          clientSecret: ${{ secrets.PORT_CLIENT_SECRET }}
          identifier: ${{ fromJson(inputs.port_payload).payload.properties.service_name }}
          blueprint: service
          properties: |
            {
              "url": "https://github.com/${{ env.ORG_NAME }}/${{ fromJson(inputs.port_payload).payload.properties.service_name }}",
              "language": "golang"
            }

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:

Click on Create to begin executing the action.
Enter a name for your new repository, then click Execute. A small popup will appear, click on View details:

This page provides details about the action run. As you can see, the backend returned Success and the repo was successfully created:

💡 Note the Log stream at the bottom, this can be used to report progress, results and errors

Congrats! 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.

More guides & tutorials will be available soon, in the meantime feel free to reach out with any questions via our community slack or Github project.

Scaffold a new service

The goal of this guide​

Setup the action's frontend​

Setup the action's backend​

Execute the action​

Possible daily routine integrations​

Conclusion​