# Add a workflow a workspace manages

> Add a workflow to a workspace's repositories. name (lowercase letters, digits and hyphens) makes its path managed/<name>.yml. source is a workflow file in one of the workspace's repositories, owner/repo/.g1t/workflows/file.yml@ref; g1t copies it at the commit ref names, and the copy runs until it is copied again (update_workspace_managed_workflow with refresh). mode is required (a repository's workflow of the same name: is set aside, and no one in the repository can turn it off, so its check can be required by a ruleset) or default (a repository's own workflow of the same name runs in its place, and the repository's admins can turn it off). repositories lists names and patterns (* matches any characters, ! excludes), read in order, the last match deciding; empty or left out is every repository. visibility is all (the default), public or private.

<div class="g1t-endpoint"><span class="g1t-method" data-method="post">POST</span><code>/workspaces/{workspace}/actions/managed-workflows</code></div>

A source in a private repository runs in private repositories only, so visibility must be private. Owners only. Returns the workflow.

g1t copies the source when you save it, and that copy runs in each repository the workflow targets, as the repository's own workflow, with its token and secrets. A source in a private repository runs in private repositories only: give visibility private.

- **Authentication:** Required. Send an [access token](/reference/api/#authentication) as `Authorization: Bearer`.
- **MCP tool:** [`workflow`](/reference/mcp/#workflow) with `action` `add_managed_workflow`, and the same inputs
- **Scope:** An access token needs [`workspace:admin`](/guides/authentication/#scopes).

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `workspace` | string | Yes | The workspace's name, e.g. "acme". |

## Body parameters

Send a JSON object. Names are `snake_case`, as in responses; the `camelCase` spelling is accepted too.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | Lowercase letters, digits and hyphens: its path is managed/&lt;name>.yml. |
| `source` | string | Yes | A workflow file in one of the workspace's repositories: owner/repo/.g1t/workflows/file.yml@ref. |
| `mode` | string | Yes | required: a repository cannot take its place or turn it off. default: a repository's workflow of the same name takes its place. One of `required`, `default`. |
| `repositories` | array of strings | No | Repository names and patterns (* matches any characters, ! excludes); empty is every repository. |
| `visibility` | string | No | Which repositories, by visibility. A private source needs private. One of `all`, `public`, `private`. |

## Example request

```sh
curl -X POST https://api.g1t.sh/workspaces/flagon-io/actions/managed-workflows \
  -H "Authorization: Bearer $G1T_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "security-scan",
    "source": "flagon-io/policies/.g1t/workflows/security-scan.yml@main",
    "mode": "required",
    "repositories": [
      "*",
      "!sandbox-*"
    ]
  }'
```

## Example response

A successful request answers `200` with:

```json
{
  "name": "security-scan",
  "path": "managed/security-scan.yml",
  "workflow_name": "Security scan",
  "source": "flagon-io/policies/.g1t/workflows/security-scan.yml@main",
  "source_sha": "4f1c2a9e0b7d3c5a8e6f1b2d4c7a9e0f3b5d8c1a",
  "source_private": false,
  "mode": "required",
  "repositories": [
    "*",
    "!sandbox-*"
  ],
  "visibility": "all",
  "content": "name: Security scan\non: [push, pull_request]\njobs:\n  scan:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - run: ./scripts/scan.sh\n",
  "created_at": "2026-10-12T09:30:00Z",
  "updated_at": "2026-10-12T09:30:00Z",
  "updated_by": "ada"
}
```

## Errors

A failed request answers with one of these statuses and a body like `{"error": {"code": "not_found", "message": "Repository not found."}}`. See [errors](/reference/api/#errors).

| Status | Code | When |
| --- | --- | --- |
| 401 | `unauthenticated` | A token is required, or the one sent is not valid. |
| 403 | `forbidden` | The token is valid but not allowed to do this, such as a member-only change, or a token without the scope it needs. |
| 404 | `not_found` | It does not exist, or you cannot see it. |
| 409 | `conflict` | The request conflicts with the current state. |
| 422 | `invalid` | The input is not valid. `message` says which field and why. |