# Workflows from Git Repositories > Source: https://parallelworks.com/docs/run/workflows/git-repositories # 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. | | GitHub | GitLab | |---|---|---| | Set up by | A platform administrator configures the GitHub App once ([Admin Panel](/docs/admin-panel#github)) | An organization administrator registers each server ([GitLab Servers](/docs/organization-admin/settings/gitlab-servers)) | | You connect by | Linking your GitHub account and installing the GitHub App on your account or organization | Clicking **Connect** (OAuth) or **Use a token** (personal access token) per server | | Repository reference | `OWNER/REPO`, `github.com/OWNER/REPO`, or `https://github.com/OWNER/REPO` | The project URL, `https:////` | | Pin a branch, tag, or commit | Append `@` | Append `@` | | Which servers | github.com | Any server registered for your organization, including self-managed instances on private networks | ## Step 1: Connect Your Account Navigate to your account settings (**Username** > **Account**) and click **Connections**. ![Screenshot of the Connections page with a GitHub card and a GitLab card.](/content-images/docs/run/workflows/git-repositories/connections-page.png?v=bc751568) - **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](/docs/organization-admin/settings/gitlab-servers). For the full steps, please see [**Connections**](/docs/account-settings/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. ![Screenshot of the user clicking Workflows in the navigation bar.](/content-images/docs/run/workflows/git-repositories/click-workflows-page.png?v=6fc4a472) Click **+ Add**. ![Screenshot of the user clicking the Add Workflow button.](/content-images/docs/run/workflows/git-repositories/click-add-workflow.png?v=a61bdba4) 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. ![Screenshot of the user adding a remote workflow from a GitHub repository.](/content-images/docs/run/workflows/git-repositories/add-github-workflow.png?v=e0484bad) ![Screenshot of the user adding a remote workflow from a GitLab project.](/content-images/docs/run/workflows/git-repositories/add-gitlab-workflow.png?v=ef0d7fca) 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**](/docs/run/workflows/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: ```bash # 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`](/docs/cli/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`: ```json { "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**](/docs/sdk). ### 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/` and `workflow/`, it accepts a repository reference, which runs the `workflow.yaml` at the root of that repository: ```yaml 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//[@]` or the repository URL. - GitLab: the project URL, `https:////[@]`. When `@` 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..steps[*].uses`](/docs/run/workflows/building-workflows/yaml-fields#jobsjobstepsuses). ## Checking Out a Repository on a Cluster The [`checkout`](/docs/run/workflows/building-workflows/actions#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: ```yaml 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](/docs/organization-admin/settings/gitlab-servers#connection-options).