GitHub actions integration

If you host your code on GitHub, you can take advantage of GitHub Actions and Control Room to set up any CI/CD workflow you need.

Robocorp provides and maintains GitHub Actions that are freely available and ready to use in your projects.

What are GitHub Actions?

GitHub Actions is a feature of GitHub that allows developers to set up various workflows that trigger based on specific events in GitHub repositories.

A common usage scenario is to run tests when a commit is pushed or a pull request is created (Continuous integration (CI)). Another is to push the code or its artifacts to another system, like a staging or production environment (Continuous Delivery (CD)).

GitHub actions are billed by usage, with a limited free plan available.

GitHub action: Update a robot in Robocorp Cloud

Action: Robocorp - Upload robot to Robocorp Cloud

Using this action, you can keep your robot code in sync between GitHub and Robocorp Cloud. Instead of manually updating the code of your robot in Robocorp Cloud when changes are made, you can automate the process by setting this action to trigger responding to the appropriate events for your needs and workflow.

Set up instructions

To set this action up, you will need to follow some setup steps, both on GitHub and Robocorp Cloud.

As an example, we will create a workflow that will upload the robot to Robocorp Cloud on each commit push on the main branch.

Robocorp Cloud set up

  1. If you haven't already, create a new robot in the appropriate workspace. Take note of the Robot ID property, that you can see on the robot detail page: Workspace ID property in Robocorp Cloud UI
  2. Create an API key in your workspace, and make sure that it has at least the write_robots permission associated with it: Create API key
  3. Take note of the Workspace ID property of your workspace. You can find the value by visiting the detail page for the workspace in the Organization settings section for your organization: Workspace ID property in Robocorp Cloud UI

GitHub repository set up

This is a typical use case, but you can customize the workflow in various ways to match your needs. Check the GitHub actions documentation for more information.

  1. Create a .github/workflows directory in your GitHub repository, and add into it a new file for your workflow with the .yml extension. You can choose the name for the file, for example, trigger-robocorp-cloud.yml.

  2. Add this content to the file and push it to the repository's main branch:

name: Upload to Robocorp Cloud

on:
  push:
    branches:
      - main

jobs:
  upload-to-robocorp-cloud:
    runs-on: ubuntu-latest
    name: Upload to Robocorp Cloud
    steps:
      - uses: actions/[email protected]
      - name: Use Node.js 12.x
        uses: actions/[email protected]
        with:
          node-version: 12.x
      - name: Upload Robot to Robocorp Cloud
        uses: robocorp/[email protected]
        with:
          workspace-key: ${{ secrets.ROBOCORP_WORKSPACE_KEY }}
          workspace-id: ${{ secrets.ROBOCORP_WORKSPACE_ID }}
          robot-id: ${{ secrets.ROBOCORP_ROBOT_ID }}
  1. As you can see, we are not hardcoding the needed access information in the file, but we are using the Secrets feature provided by GitHub.

    Access the Settings tab of your repository, and select the Secrets section. Click on the New repository secret button, and add the three secrets:

    • ROBOCORP_WORKSPACE_KEY, with the value of the API key you created in Robocorp Cloud.
    • ROBOCORP_WORKSPACE_ID, with the ID of the workspace that contains the robot.
    • ROBOCORP_ROBOT_ID, with the ID of the robot in the workspace in Robocorp Cloud.
  2. Push any change to your repository's main branch, and the code will be checked out and pushed to your robot in Robocorp Cloud.

GitHub action: Trigger a process run in Robocorp Cloud

Action: Trigger Robocorp Cloud process run

Using this action, you can trigger any process in Robocorp Cloud. A typical use case for this action is in test automation. You can have a process set up in Robocorp Cloud that performs tests on the application or website that you are developing and then run the tests when various triggers happen in your repository, like when new code is merged into a branch, or a pull request is opened, etc.

You can also combine the two GitHub actions into a workflow that updates the robot in Robocop Cloud and then runs it once if that fits your needs. You can also add any other available GitHub action to create the best fitting workflow for your use case.

Set up instructions

To set this action up, you will need to follow some setup steps, both on GitHub and Robocorp Cloud.

As an example, we will create a workflow that will trigger the specified robot in Robocorp Cloud on each pull request that is opened for the main branch of the repository.

Robocorp Cloud set up

  1. Choose an existing process or set up a new one. Get the process ID for your process from the URL of the page in Robocorp Cloud.

    The process ID will be the last part of the URL. For example in the URL https://cloud.robocorp.com/xxx/xxx/processes/ae9cce11-c967-4add-879d-2ed0902eeb27, the process ID will be ae9cce11-c967-4add-879d-2ed0902eeb27.

  2. Create an API key in your workspace, and make sure that it has at least the trigger_processes permission associated with it: Create API key
  3. Take note of the Workspace ID property of your workspace. You can find the value by visiting the detail page for the workspace in the Organization settings section for your organization: Workspace ID property in Robocorp Cloud UI

GitHub repository set up

  1. Create a .github/workflows directory in your GitHub repository, and add a new file for your workflow with the .yml extension in it. You can choose the name for the file, for example, trigger-robocorp-cloud.yml.

  2. Add this content to the file and push it to the repository's main branch:

name: Trigger a process in Robocorp Cloud

on:
  pull_request:
    branches:
      - main

jobs:
  run-process:
    runs-on: ubuntu-latest
    name: Trigger process
    steps:
      - name: Trigger Robocorp Cloud process run
        uses: robocorp/[email protected]
        with:
          api-key: ${{ secrets.ROBOCORP_WORKSPACE_KEY }}
          workspace-id: ${{ secrets.ROBOCORP_WORKSPACE_ID }}
          process-id: ${{ secrets.ROBOCORP_PROCESS_ID }}
          payload: '{"foo":"bar"}'
          await-complete: true

Note that you can pass work item information using the payload key.

Using the await-complete key, you can determine whether the action should wait for robot completion before continuing or not.

See all available options on the Action's homepage on the GitHub marketplace.

  1. As you can see, we are not hardcoding the needed access information in the file, but we are using the Secrets feature provided by GitHub.

Access the Settings tab of your repository, and select the Secrets section. Click on the New repository secret button, and add the three secrets:

  • ROBOCORP_WORKSPACE_KEY with the value of the API key you created in Robocorp Cloud.
  • ROBOCORP_WORKSPACE_ID with the ID of the workspace that contains the robot.
  • ROBOCORP_PROCESS_ID with the ID of the process in the workspace in Robocorp Cloud.
  1. Create a pull request to the main branch, and the robot will be triggered.

Learn more

Check out the official guide to GitHub actions for a lot more information, guides, and tutorials.

June 28, 2021