Workflows from Git Repositories

ACTIVATE can read workflows straight from GitHub and from GitLab servers your organization has registered. This page walks through the full flow: connecting your account, adding a workflow whose YAML lives in a repository, running it from the web, the CLI, or the API, calling repository workflows from other workflows, and checking repositories out on a cluster.

How Repository Access Works

Every repository read happens as you, using the account you connected under Account > Connections. ACTIVATE never holds a credential of its own for your repositories, so a workflow can only reach the projects your GitHub or GitLab account can see. Public repositories can be read without a connection; for GitLab, the server still has to be registered for your organization.

Step 1: Connect Your Account

Navigate to your account settings (Username > Account) and click Connections.

• GitHub: click Link GitHub and authorize the connection, then install the GitHub App on the organizations or the personal account that own the repositories you want to use. Repositories in an organization without the app installed are not visible to ACTIVATE, even if your account can see them on GitHub.
• GitLab: each registered server has its own row. Click Connect to authorize through GitLab, or Use a token to paste a personal access token with the read_api scope. If your organization's server isn't listed, ask an organization administrator to register it.

For the full steps, please see Connections.

Step 2: Add a Remote Workflow

A remote workflow keeps its YAML in a repository. ACTIVATE fetches the file each time the workflow runs, so changes pushed to the repository take effect without editing anything on the platform.

Navigate to the Workflows page.

Click + Add.

Enter a Name and select Remote as the workflow type, then fill in the repository fields:

• Repository URL: a GitHub repository URL, or the URL of a project on one of your organization's GitLab servers. The host decides which connection is used.
• Branch: the branch to read from. Defaults to main.
• YAML Path: the path of the workflow file within the repository, for example workflow.yaml or workflows/preprocess.yml. An absolute https:// URL is also accepted.
• Thumbnail Path: optional. A path within the repository, or an absolute URL, for the image shown on the workflow card. Private GitLab projects are supported; a thumbnail in a private GitHub repository is not displayed.
• Readme Path: optional. For GitHub repositories this can be a path within the repository, for example README.md. For GitLab projects use an absolute https:// URL; a repository-relative README path is not fetched from GitLab.

Click Add Workflow. The workflow appears on the Workflows page and behaves like any other workflow; open it to see the form generated from its YAML.

Step 3: Run It

From the Web

Open the workflow and use the Run tab as you would for any workflow. For more information, please see Running Workflows.

From the CLI

You don't need to add a workflow to run one. pw workflows run accepts a repository reference and runs the workflow.yaml (or workflow.yml) at its root:

# GitHub, default branch
pw workflows run github.com/parallelworks/my-workflow
 
# GitHub, pinned to a tag
pw workflows run github.com/parallelworks/my-workflow@v1.2.0
 
# A project on a registered GitLab server, pinned to a branch
pw workflows run https://gitlab.example.com/research/cfd-pipeline@main
 
# With inputs
pw workflows run -i '{"cluster": "my-cluster"}' https://gitlab.example.com/research/cfd-pipeline

GitHub repositories are read by the CLI itself, so a private repository uses the GitHub credentials already on your machine (GH_TOKEN, GITHUB_TOKEN, gh auth login, or a git credential helper). GitLab projects are read by the platform with the account you connected, so nothing GitLab-related is needed on your machine.

For every option, please see pw workflows run.

From the API or SDK

POST /api/workflow-runs takes the same reference in the repository field instead of workflow, yaml, or marketplace:

{
  "repository": "https://gitlab.example.com/research/cfd-pipeline@main",
  "inputs": { "cluster": "my-cluster" }
}

The response is the same as for any other run. For more information, please see the SDKs.

Approving Workflow Permissions

A workflow read from a repository is code you didn't write on the platform, so it is never trusted automatically. If the YAML declares account variables (variables:) or platform permissions, the first run shows a Workflow permissions required dialog listing exactly what it asks for. Click Approve & Run to continue. Your approval is remembered for that repository, so later runs only ask again if the workflow requests something new.

On the CLI, the same prompt appears in the terminal; pass --trust to grant everything the workflow declares without prompting.

Calling a Repository Workflow from a Step

The uses field runs another workflow as a step. Besides marketplace/<slug> and workflow/<name>, it accepts a repository reference, which runs the workflow.yaml at the root of that repository:

jobs:
  preprocess:
    steps:
      - name: Mesh the geometry
        uses: github/parallelworks/mesh-tools@v2.1.0
        with:
          input_file: ${{ inputs.geometry }}
 
      - name: Run the solver
        uses: https://gitlab.example.com/research/cfd-solver@main
        with:
          mesh: ${{ steps.mesh.outputs.path }}

• GitHub: github/<owner>/<repo>[@<ref>] or the repository URL.
• GitLab: the project URL, https://<host>/<group>/<project>[@<ref>].

When @<ref> is omitted the repository's default branch is used. The called workflow's inputs are passed with with. A repository workflow called this way is subject to the same permission approval as one run directly. For more information, please see jobs.<job>.steps[*].uses.

Checking Out a Repository on a Cluster

The checkout action clones a repository into the workflow run directory, on the user workspace or on a cluster when the step has an ssh target:

jobs:
  build:
    steps:
      - uses: parallelworks/checkout
        with:
          repo: https://gitlab.example.com/research/cfd-solver
          branch: main
        ssh:
          remoteHost: ${{ inputs.cluster.ip }}

Public repositories are cloned directly. If the clone fails because the repository is private, the step fetches an archive of the repository through ACTIVATE using your connected GitHub or GitLab account and unpacks it in place, so your credentials never reach the cluster. Only repositories referenced by the workflow itself can be fetched this way, and the result has no .git directory.

Troubleshooting

• The repository can't be read, or the workflow says the project isn't visible. Check the Connections page: for GitHub, your account must be linked and the GitHub App installed on the organization that owns the repository; for GitLab, you must be connected on the server whose host matches the URL, and your GitLab account must be a member of the project.
• "Unregistered GitLab host". The URL's host isn't one of the servers registered for your organization. Ask an organization administrator to register it. Public projects on unregistered hosts can still be run from the CLI, which reads them anonymously.
• The workflow card has no thumbnail. For GitHub, a thumbnail in a private repository is fetched by your browser without credentials and can't be shown; use a public image URL. For GitLab, thumbnails are served through the platform and work for private projects.
• Certificate errors against a self-managed GitLab server. The server registration needs a custom CA certificate or a different verification mode; see GitLab Servers.