Skip to main content

Get Started with Workflows

Introduction​

This quickstart tutorial will guide you through setting up a Workflow in IDP to automate GitHub repository onboarding for users. While this tutorial uses GitHub as the git provider, the same steps can be applied to other git providers as well.

info

We now have a new Workflows homepage which is behind a Feature Flag IDP_ENABLE_WORKFLOWSV2. To enable the feature flag, please contact Harness Support

Pre-requisite​

Add Connector​

A connector with Git credentials that has appropriate write permissions is required to create a repository in your GitHub organization.

  1. Go to Admin -> Git Integrations.
  2. Add a New Git Integration with type as GitHub.
  3. Now Select the GitHub Connector and Save Changes, follow the steps to add a new connector
info

Make sure the Connector URL used here is pointed towards the org where you want to create the new repo and the token used have write permission for the repo also Enable the API while creating connector.

Create Harness Pipeline with IDP Stage​

A Harness Pipeline serves as an orchestrator for IDP Workflows.

  1. Go to Admin -> Select Project.
  2. Now start with Create a Pipeline.

  1. Add a Name, select the type as Inline and Continue.

  1. Add Stage and Select Stage Type as Developer Portal.

  1. Select the infrastructure as Harness Cloud.

  1. Now let's create some variables that we will use in further steps. Navigate to the Variables tab in the right corner of the Pipeline Studio, and add the following Custom Variables (stick to the exact naming convention for variables as provided, as these will be used as a reference to input values into the pipeline). The variables are of Type String, and their Values are set to Runtime Input.
    • github_org
    • github_repo
    • github_username

Add another variable github_token as Type Secret and add the GitHub PAT for Values.

Apply the changes

  1. Now Continue to Execution and Add Step, under Git Repository Setup select Create Repo.

  1. Under Step Parameters, select the Repository Type as Public if the connector you have created use a token generated by your GitHub admin, else you might not have access to the private repo created.

  2. Add the Connector you created above.

  3. Now under Organization and Repository Name add the variables you created as Expressions (<+pipeline.variables.github_org> and <+pipeline.variables.github_repo>).

  4. Add a Repository Description, Apply Changes.

  1. Now add a Run Step to add your username as an admin to the repo created, with the following curl command, make sure to add a container registry and image, under optional configuration. Container Registry is a Harness Docker Registry Connector used to specify the image on which Harness will run commands, such as images from Docker Hub.
curl -L \
  -X PUT \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <+pipeline.variables.github_token>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/repos/<+pipeline.variables.github_org>/<+pipeline.variables.github_repo>/collaborators/<+pipeline.variables.github_username> \
  -d '{"permission":"admin"}'

Create Workflow​

The Workflow is defined in a YAML file named workflow.yaml. The syntax of the template definition is owned by backstage.io while the workflow runs on a Harness pipeline of your choice.

The following is the example Workflow with Workflows Action to create a new repository.

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
# some metadata about the template itself
metadata:
  name: Workflows-Quickstart
  title: Create a New GitHub Repository
  description: Creates a new GitHub Repository 
spec:
  owner: service.owner
  type: service
  # these are the steps which are rendered in the frontend with the form input
  parameters:
    - title: Fill in the repo details
      required:
        - github_org_name
        - github_repo_name
        - github_username
      properties:
        github_org_name:
          title: GitHub Organization
          type: string
          description: Name the org where you want to add the new repository
        github_repo_name:
          title: Repository Location
          type: string
          description: Name the new repository that you want to create 
        github_username:
          title: GitHub Username
          type: string
          description: Add Your GitHub Username 
        token:
          title: Harness Token
          type: string
          ui:widget: password
          ui:field: HarnessAuthToken       
  # here's the steps that are executed in series in the scaffolder backend
  steps:
    - id: trigger
      name: Onboarding a New GitHub Repository
      action: trigger:harness-custom-pipeline
      input:
        url: "URL_of_the_Harness_Pipeline_Created_Above"
        inputset:
          github_org: ${{ parameters.github_org_name }}
          github_repo: ${{ parameters.github_repo_name }}
          github_username: ${{parameters.github_username}}
        apikey: ${{ parameters.token }}
    # The final step is to register our new component in the catalog.

  output:
    links:
      - title: Pipeline Details
        url: ${{ steps.trigger.output.PipelineUrl }}

In the above Workflow we have used the Harness Trigger Workflow Action, which takes the exact variable name github_org and github_repo you created for your pipeline as input and a token as apikey

warning

The token property used to fetch the Harness Auth Token is hidden on the Review Step using ui:widget: password. However, for this to function correctly in a multi-page workflow, the token property must be included under the first page.

parameters:
  - title: <PAGE-1 TITLE>
    properties:
      property-1:
        title: title-1
        type: string
      property-2:
        title: title-2
    token:
      title: Harness Token
      type: string
      ui:widget: password
      ui:field: HarnessAuthToken
  - title: <PAGE-2 TITLE>
    properties:
      property-1:
        title: title-1
        type: string
      property-2:
        title: title-2
  - title: <PAGE-n TITLE>
  1. Copy the above Workflow file in your git provider, replace the value of input.url under steps with the Harness pipeline URL you created and save it as workflow.yaml.

Register Workflow in IDP​

  1. In the left navigation, select Workflows, and then select Register New Workflow.

  1. Enter the URL to your new workflow.yaml.

  2. Select Import.

  1. Now click on the Workflow name

Use Workflows to Create a Repo​

  1. Once you're on the entity page for Workflow, Launch the Workflow.

  1. Now fill the fields as:
    • Repository Location: Add a name for the repository you wanted to create.
    • GitHub Organization: Add the org where you want to add your new repository, usually GitHub URL are of the format https://github.com/org_name/repo_name/

  1. Now Trigger the flow, it will create a new GitHub repo.

Delete the Workflow​

If you want to unregister or delete the Workflow follow the steps mentioned here.