See the building workflows page if you have not already. If you are looking for the documentation for a specific action, find the name of the action from the sidebar on the right.

Actions

Certain operations that are used regularly in workflows have been abstracted into actions, and can be executed in a workflow using the following syntax:

jobs:
  job-name:
    steps:
      - uses: parallelworks/<name of action>
        with:
          action_input_2: value_1
          action_input_2: value_2

Note that valid action inputs passed to the action through the with property depend on the action. Below is a list of actions and their input fields.

checkout

Checks out a git repo. The example below is the simplest possible usage:

jobs:
  job-name:
    steps:
      - uses: parallelworks/checkout
        with:
          repo: https://github.com/parallelworks/interactive_session.git
          branch: main

If you want to only check out part of a repo, you can define sparse_checkout:

jobs:
  job-name:
    steps:
      - uses: parallelworks/checkout
        with:
          repo: https://github.com/parallelworks/interactive_session.git
          branch: main
          sparse_checkout:
            - utils
            - platforms

To clone the repo to the file system of a cluster, use the ssh field at the job or step level to specify the cluster.

jobs:
  job-name:
    steps:
      - uses: parallelworks/checkout
        with:
          repo: https://github.com/parallelworks/interactive_session.git
          branch: main
        ssh:
          remoteHost: ${{ inputs.cluster.ip }}
on:
  execute:
    inputs:
      cluster:
        type: compute-clusters
        optional: false

Inputs:

• repo string: Specifies the git repo to be cloned. Required.
• branch string: Specifies the branch to be cloned. Required.
• sparse_checkout string[]: Only clone files that match the patterns defined in the array.
• path string: Where to clone the git repo to. Defaults to the workflow run directory.

update-session

Updates a session with information. If you want to use sessions, this action is always necessary because sessions have no initial information on what to display. See Building Sessions for example usage.

Shared Inputs:

• name string: Name of the session to update. Must be present in sessions property of YAML. Required.
• type string: Type of session, must be either 'link' or 'tunnel'. Default is tunnel.
• target string: Id of the target compute cluster (get using an expression like ${{inputs.cluster_input_name.id}}). Defaults to user workspace.

Tunnel Inputs:

• remotePort int: Port to read on the target. Required for tunnel sessions.
• remoteHost string: Host of the target. Default is localhost.
• slug string: Added at the end of session url. Defaults to empty string.
• localPort int: Port on the local machine. Defaults to a random open port.
• openAI boolean: Whether the session is an OpenAI session. Default is false.

Link Inputs:

• url string: The url of the link for the session.

slurm-agent

You can use the slurm-agent action to provision a node and start an ssh server so that you can run commands on it through ssh. Note that you must use a cluster with a partition for this to properly work. See Building Sessions for example usage.

Inputs:

• wait boolean: Whether to wait for the node to provision. Defaults to true.
• sbatch-flags object: Use these flags for the sbatch command. Defaults to none. You can find a list of flags here under job submission.

wait-for-agent

This action should only be used if you already used slurm-agent with wait: false passed as an input to the with property, which might be a good idea if you want the workflow job to perform other operations while the slurm-agent node is configuring.

permissions:
  - '*'
sessions:
  session: 
jobs:
  main:
    ssh:
      remoteHost: ${{ inputs.resource.ip }}
    steps:
      - uses: parallelworks/slurm-agent
        id: slurmstep
        with:
          wait: false
      - run: echo "Perform some other operations here, like a checkout action or second slurm-agent"
      - uses: parallelworks/wait-for-agent
        id: waitstep
        with:
          agentId: ${{ needs.main.steps.slurmstep.outputs.agentId }}
      - name: Get open port
        ssh:
          jumpNodeHost: ${{ inputs.resource.ip }}
          remoteHost: ${{ needs.main.steps.waitstep.outputs.remoteHost }}:${{ needs.main.steps.waitstep.outputs.sshPort }}
        run: |
          echo sessionPort="$(pw agent open-port)" >> $OUTPUTS
          cat $OUTPUTS
      - uses: parallelworks/update-session
        with:
          status: running
          name: ${{ sessions.session }}
          target: ${{ inputs.resource.id }}
          remoteHost: ${{ needs.main.steps.waitstep.outputs.remoteHost }}
          remotePort: ${{ needs.main.outputs.sessionPort }}
      - name: Serve port
        run: |
          cat << EOF > myServer.go
          package main

          import (
              "fmt"
              "net/http"
          )
          func hello(w http.ResponseWriter, req *http.Request) {
              fmt.Fprintf(w, "Hello from slurm agent server!\n")
          }

          func main() {
              http.HandleFunc("/", hello)
              http.ListenAndServe(":${{ needs.main.outputs.sessionPort }}", nil)
          }
          EOF
          go run myServer.go
        ssh:
          jumpNodeHost: ${{ inputs.resource.ip }}
          remoteHost: ${{ needs.main.steps.waitstep.outputs.remoteHost }}:${{ needs.main.steps.waitstep.outputs.sshPort }}
'on':
  execute:
    inputs:
      resource:
        label: Resource Target
        type: compute-clusters
        autoselect: true
        optional: false

Inputs:

• agentId string: The id of the agent to wait for. The output from the slurm-agent action includes this field (see usage in example above).