> For the complete documentation index, see [llms.txt](https://docs.flowcp.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flowcp.ai/guides/github-actions.md).

# Use FlowCP in GitHub Actions

You can drive FlowCP from a GitHub Actions workflow with the `flowcp` CLI: re-import your OpenAPI spec when it changes, run the MCP capability test suite, publish a server, or sync skills, prompts, and widgets from your repo — all on every push or pull request.

> Looking for the zero-config option? If you connect your app as a **Git repository** with the FlowCP GitHub App, FlowCP automatically re-imports your spec when a pull request merges — no workflow required. See [Connect your API](/guides/connect-your-api.md). Use the CLI approach below when you want CI to also **test** and **publish**, or to gate publishing on your own checks.

## 1. Create an API token

The browser device-code login (`flowcp login`) can't run on a CI runner, so authenticate with a long-lived **API token** instead. On your machine:

```bash
flowcp login                       # one time, interactive
flowcp token create --name "github-actions"
```

Copy the token (`flowcp_pat_…`) — it's shown only once.

## 2. Store it as a repository secret

In your GitHub repo: **Settings → Secrets and variables → Actions → New repository secret**. Name it `FLOWCP_TOKEN` and paste the token.

## 3. Add a workflow

Use the bundled composite action:

```yaml
# .github/workflows/flowcp.yml
name: FlowCP

on:
  push:
    branches: [main]
    paths: ['openapi.yaml'] # run when your spec changes

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Re-import the OpenAPI spec
        uses: inovastudio/mcp-builder/.github/actions/flowcp@main
        with:
          api-token: ${{ secrets.FLOWCP_TOKEN }}
          args: import run --app app_123

      - name: Run the MCP capability tests
        uses: inovastudio/mcp-builder/.github/actions/flowcp@main
        with:
          api-token: ${{ secrets.FLOWCP_TOKEN }}
          args: server test --server srv_123

      - name: Publish
        uses: inovastudio/mcp-builder/.github/actions/flowcp@main
        with:
          api-token: ${{ secrets.FLOWCP_TOKEN }}
          args: server publish --server srv_123
```

### Action inputs

| Input          | Required | Default                 | Description                                                     |
| -------------- | -------- | ----------------------- | --------------------------------------------------------------- |
| `args`         | yes      | —                       | Arguments passed to `flowcp` (e.g. `import run --app app_123`). |
| `api-token`    | yes      | —                       | Your `FLOWCP_TOKEN` secret.                                     |
| `api-url`      | no       | `https://api.flowcp.ai` | FlowCP API base URL.                                            |
| `workspace-id` | no       | resolved from token     | Workspace id, if you prefer to set it explicitly.               |
| `version`      | no       | `latest`                | The `flowcp` npm version to install.                            |

## Without the composite action

If you'd rather not depend on the action, install the CLI directly and use the environment variables:

```yaml
- uses: actions/setup-node@v4
  with:
    node-version: 20
- run: npm install -g flowcp
- run: flowcp import run --app app_123 && flowcp server test --server srv_123
  env:
    FLOWCP_TOKEN: ${{ secrets.FLOWCP_TOKEN }}
```

`FLOWCP_TOKEN` authenticates every command; `FLOWCP_API_URL` and `FLOWCP_WORKSPACE_ID` are optional overrides.

## Useful commands in CI

| Command                               | Use                                                       |
| ------------------------------------- | --------------------------------------------------------- |
| `flowcp import run --app <id>`        | Re-import the OpenAPI document after a spec change        |
| `flowcp server test --server <id>`    | Run the MCP capability test suite (gate publishing on it) |
| `flowcp server publish --server <id>` | Make the MCP endpoint live                                |
| `flowcp sync push --prune`            | Upload local skills, prompts, and widgets to the server   |

Add `--json` to any command for machine-readable output you can pipe into `jq`.

## Security notes

* Treat `FLOWCP_TOKEN` like a password: keep it in GitHub Secrets, never in the workflow file. It is stored hashed on the server.
* A token is scoped to the workspace and user that created it.
* Rotate or revoke at any time with `flowcp token list` / `flowcp token revoke <id>`. Revocation takes effect immediately.
* Set an expiry with `flowcp token create --name ci --expires-in 90` to force periodic rotation.