> This page is for version v2026-02-09 (default).
> For other versions, use one of these documentation indexes:
> - v2026-02-09 (default): https://docs.extend.ai/2026-02-09/llms.txt
> - v2025-04-21: https://docs.extend.ai/2025-04-21/llms.txt
> - v2024-12-23: https://docs.extend.ai/2024-12-23/llms.txt

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.extend.ai/llms.txt
> Use this file to discover all available pages before exploring further.
>
> ## API version
> The current API version is `2026-02-09`, served at the site root (no version prefix in URLs).
> If this page URL contains `/2025-04-21/` or `/2024-12-23/`, you are reading an older API version.
> Prefer the current docs at https://docs.extend.ai/llms.txt unless the user explicitly needs that older version.
> Do not treat older-version pages as the source of truth for new integrations.

# GitHub App Integration

> Connect a GitHub workflow file to Extend so pull requests validate workflow changes and pushes deploy new workflow versions.

The GitHub App integration lets you manage workflow definitions from a repository. You can import a workflow from a JSON or YAML file, link an existing workflow to a file, validate changes in pull requests, and deploy new workflow versions when the linked branch changes.

Use this when you want workflow changes reviewed in GitHub before they become deployed versions in Extend.

## Before you start

You need:

* An Extend workspace where you can create or update workflows.
* Permission to install the Extend GitHub App on the GitHub account or organization.
* A workflow file ending in `.json`, `.yaml`, or `.yml`.

The file should use the same workflow shape as the [Create Workflow Version API](/api-reference/endpoints/workflow/create-workflow-version). At minimum, it can include a `name` and a `steps` array:

If you already built the workflow in Extend, you can export it as JSON or YAML from the workflow menu and commit that file to your repository.

![Workflow menu showing the Export options for YAML and JSON files](/_fern-img/8c0739329a389b5d37e2d112a1f7cd45a6ab4524a5e85755a0da65a000b93fe3.webp)

```json
{
  "name": "Invoice processing",
  "steps": [
    { "name": "trigger", "type": "TRIGGER", "next": [{ "step": "parse" }] },
    { "name": "parse", "type": "PARSE", "next": [{ "step": "extract" }] },
    {
      "name": "extract",
      "type": "EXTRACT",
      "config": {
        "extractor": { "id": "ex_abc123", "version": "latest" }
      },
      "next": [{ "step": "review" }]
    },
    { "name": "review", "type": "HUMAN_REVIEW" }
  ]
}
```

> **Tip**
>
> `EXTRACT`, `CLASSIFY`, and `SPLIT` steps can embed their processor configuration inline (`extractorConfig`, `classifierConfig`, `splitterConfig`) instead of referencing a saved processor by ID. A fully inline workflow file contains no workspace-specific processor IDs, so the same file validates and deploys against any workspace — useful when the same repository manages workflows for multiple environments. See [Saved processors vs. inline configs](/workflows/configuring-workflows#saved-processors-vs-inline-configs).

For the full step reference, see [Configuring Workflows](/workflows/configuring-workflows).

## 1. Link an existing workflow

Start from the workflow you want GitHub to manage. Click the versions button in the bottom-left of the workflow builder to open the workflow version side panel, then click **Link to GitHub**.

![Workflow version side panel showing the Link to GitHub button](/_fern-img/7d61414c24fb11b429fd2b577b188bea298ef75e20778488cc519e5fb1d3cd07.webp)

If no GitHub account is connected, choose **Manage accounts for this workspace**. GitHub opens in a new window and asks which account and repositories the Extend GitHub App can access.

![Link to GitHub dialog with the account selector open and the manage accounts option visible](/_fern-img/55c8f4af6f00a8df26564ef3064aa253f595f58d67a5cc9460de61a2977a8932.webp)

On GitHub, choose whether Extend can access all repositories or only selected repositories, then approve the installation.

![GitHub App installation page showing selected repositories and requested permissions](/_fern-img/bebe63f108ab5e268f1a24cb20c4a47160a011658393554173c2abf593ff97ec.webp)

After installation, return to Extend. The connected GitHub account appears in the account selector.

> **Note**
>
> The GitHub App controls which repositories Extend can read. Inside Extend, linked workflow files are stored for the current workspace and workflow.

Select the GitHub account, repository, branch, and workflow file. Optional: check **Create new version from current file** to deploy the selected file now. Then click **Link workflow**.

![Link to GitHub dialog with a repository, branch, and workflow JSON file selected](/_fern-img/3763dfff78b4f5b29439a5f174873d3586562bac81b832552b63f433c9ce260e.webp)

After linking, Extend shows a GitHub indicator on the workflow. The indicator points to the repository file and branch.

### Import from GitHub instead

Use import when the workflow should be created from a repository file instead of linking a file to an existing workflow.

1. Open **Workflows**.
2. Click **New workflow** and choose **Import from GitHub**.
3. Select the GitHub account, repository, branch, and workflow file.
4. Optional: check **Create new version from current file** to deploy the imported file immediately.
5. Click **Import workflow**.

Extend validates the selected file. If the file includes valid steps, Extend creates the workflow draft from those steps and links the workflow to that GitHub file. The import flow uses the same GitHub file picker as linking an existing workflow.

## 2. Validate pull requests

When a pull request changes a linked workflow file, Extend creates an **Extend workflow validation** check on the pull request.

The check validates the proposed file against the workflow schema and step rules for the target branch. It does not deploy a workflow version.

If validation fails, fix the workflow file and push another commit to the pull request.

![GitHub pull request showing the Extend workflow validation check passing](/_fern-img/db8086df7c762e23c34a018ebe7e7b62d93c1e94a32fa22789625ba379e26d07.webp)

## 3. Deploy from pushes

When a push changes a linked workflow file on the linked branch, Extend validates the file and deploys a new workflow version. GitHub shows an **Extend workflow deployment** check for the commit.

![GitHub commit checks panel showing the Extend workflow deployment check passing](/_fern-img/701d133b532957e38e3d9aa0ccdc437f371f7f9c6b57fd6503f007f0f0c63445.webp)

If multiple linked workflow files are changed together, Extend validates them first. A validation failure blocks deployment for the changed linked files in that push.

After a successful deployment, the workflow version history in Extend includes GitHub source metadata such as the repository, path, branch, commit, and author.

![Extend workflow version history showing versions deployed from GitHub commits](/_fern-img/0c0b418881972c442d69a55699f55fe5d5dd8c91c634217f0fa697619f147651.webp)

## 4. Update or unlink the source

To change the linked file, open **Link to GitHub** again and select a different repository, branch, or file.

To stop deploying from GitHub, choose **Unlink from GitHub** on the workflow. Future pushes to that file will no longer create workflow versions for the workflow.

## How the integration works

* Extend reads workflow files through the GitHub App installation token.
* Extend only lists repositories and files that the installed GitHub App can access.
* Only `.json`, `.yaml`, and `.yml` workflow files are selectable.
* Pull request events run validation checks only.
* Push events on the linked branch can deploy new workflow versions.
* GitHub webhook requests are verified with GitHub's `X-Hub-Signature-256` signature before Extend processes them.

## Troubleshooting

| Problem                                   | What to check                                                                                                                      |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| No repositories appear                    | Reopen the GitHub App installation and confirm the repository is selected.                                                         |
| No files appear                           | Confirm the repository contains a `.json`, `.yaml`, or `.yml` workflow file on the selected branch.                                |
| Pull request check failed                 | Open the check details and fix the workflow schema or step validation error.                                                       |
| Push did not deploy                       | Confirm the push touched the linked file on the linked branch.                                                                     |
| Deployment failed after validation passed | If the file omits `steps`, Extend deploys from the current workflow draft. Make sure the draft is fully configured before pushing. |

## Next steps

#### [Configuring Workflows](/workflows/configuring-workflows)

See every supported step type and routing rule.

#### [Workflow Versioning](/workflows/workflow-versioning)

Learn how deployed workflow versions work.