# How to Automate Fastio Workspace Provisioning with GitLab CI

Automating Fastio workspace provisioning with GitLab CI ensures that every deployment environment has an isolated, securely configured file storage space. By combining GitLab's CI/CD pipeline capabilities with Fastio's APIs, development teams can eliminate manual setup overhead. This guide explains how to integrate workspace creation directly into your deployment workflows, enabling ephemeral staging environments and secure coordination layers for AI agents.

Source: https://fast.io/resources/automate-fastio-workspace-gitlab-ci/
Last reviewed: 2026-02-23

## What Is Automated Workspace Provisioning?

Automating Fastio workspace provisioning with GitLab CI ensures that every deployment environment has an isolated, securely configured file storage space. Instead of manually creating shared folders or relying on static cloud buckets, development teams can use infrastructure-as-code principles to generate dynamic storage environments on the fly. 

Fastio operates as an intelligent workspace rather than basic storage. When you provision a new workspace through a deployment pipeline, intelligence is native from the start. Once Intelligence is enabled for the workspace, files uploaded are indexed, making them searchable by meaning and queryable through chat. For developer teams running complex applications, build artifacts, test logs, and deployment assets become immediately available to both human reviewers and AI agents.

Automated provisioning connects the software development lifecycle directly to your team's collaboration platform. When a new feature branch is pushed to GitLab, the CI/CD pipeline can spin up a dedicated Fastio workspace. AI agents can then analyze the generated build logs within that workspace using a consolidated MCP toolset. This approach removes manual setup work and ensures every testing environment has the storage context it needs.

Helpful references: [Fastio Workspaces](/product/workspaces/), [Fastio Collaboration](/product/collaboration/), and [Fastio AI](/product/ai/).

## Why Automate Fastio with GitLab CI/CD?

Integrating workspace management into your CI/CD pipelines changes how teams handle deployment data. GitLab CI automates infrastructure provisioning, reducing manual setup errors compared to typical administrative workflows. 

Ephemeral workspaces improve security during staging and testing phases. Creating temporary Fastio workspaces that exist only for the duration of a test run limits the exposure of sensitive development data. Once the pipeline finishes and the code is merged, the CI process can automatically archive or delete the workspace to keep data clean.

Fastio also provides a coordination layer where agent output becomes team output. Human team members and AI systems share the same workspaces and the same intelligence. Developers use the web UI to review assets, while AI agents interact with the environment using a consolidated MCP toolset via Streamable HTTP at `https://mcp.fast.io/mcp` or legacy SSE at `https://mcp.fast.io/sse`.

After a test job uploads compliance reports or regression screenshots, the next GitLab job can wait on workspace activity with `GET /current/activity/poll/{entityId}?wait=95&lastactivity={timestamp}` or search the audit log with `GET /current/events/search/` before continuing the deployment.

## Prerequisites for GitLab CI Integration

Before automating workspace provisioning, configure the authentication and environment variables within your GitLab repository. 

**1. Obtain Fastio API Credentials**
Create an API key in Settings > Devices & Agents > API Keys, or with `POST /current/user/auth/key/`. Authenticated pipeline calls use `Authorization: Bearer {api_key}` against `https://api.fast.io/current/`.

**2. Configure GitLab CI/CD Variables**
Store your Fastio credentials securely in GitLab. Go to your repository settings, select CI/CD, and expand the Variables section. Add `FASTIO_API_TOKEN` for the API key and `FASTIO_ORG_ID` for the organization ID used in workspace creation. Mark both as "Masked" so they do not appear in job logs, and "Protected" if you only want them exposed to protected branches and tags.

**3. Prepare Your Agent Tooling**
If your pipeline involves AI agents, configure their access using your Fastio API token. Connecting agents to the remote MCP server at `https://mcp.fast.io/mcp` or the REST API gives your pipeline access to a consolidated toolset for agentic file management.

## How to Configure Your .gitlab-ci.yml File

To provision a Fastio workspace automatically, define a job in your `.gitlab-ci.yml` file that interacts with the Fastio API. The following configuration shows the API calls needed to provision a workspace during a deployment stage.

```yaml
stages:
  - setup_environment
  - test
  - cleanup

provision_workspace:
  stage: setup_environment
  image: curlimages/curl:latest
  script:
    - echo "Provisioning dynamic Fastio workspace for branch $CI_COMMIT_REF_SLUG"
    - |
      WORKSPACE_RESPONSE=$(curl -s -X POST "https://api.fast.io/current/org/$FASTIO_ORG_ID/create/workspace/" \
        -H "Authorization: Bearer $FASTIO_API_TOKEN" \
        -H "Content-Type: application/x-www-form-urlencoded")
    - WORKSPACE_ID=$(echo "$WORKSPACE_RESPONSE" | grep -oE '[0-9]{19}' | head -1)
    - echo "WORKSPACE_ID=$WORKSPACE_ID" >> workspace.env
    - echo "Successfully provisioned workspace $WORKSPACE_ID"
  artifacts:
    reports:
      dotenv: workspace.env
  only:
    - merge_requests
```

This pipeline configuration does three things:

**Step 1: Execute the Provisioning Request**
The script uses `curl` to send a form-encoded POST to `https://api.fast.io/current/org/{org_id}/create/workspace/` with a Bearer API key. Files added to that workspace are indexed so Ripley, the built-in RAG agent, can answer from them.

**Step 2: Extract the Workspace Identifier**
After the API responds, the script reads the new 19-digit workspace ID. Later jobs use that ID to upload files with `POST /current/upload/` or invite reviewers with `POST /current/workspace/{workspace_id}/members/{email_or_user_id}/`.

**Step 3: Export the Variable to the Pipeline**
By writing the identifier to a `workspace.env` file and defining it as a `dotenv` artifact, the `$WORKSPACE_ID` variable becomes available to all downstream jobs in the GitLab pipeline.

## Managing Ephemeral Workspaces for Staging Environments

Once you provision the workspace, your pipeline uses it as an intelligent data room for the duration of the testing cycle. Ephemeral workspaces help manage the complex assets generated during automated testing.

When UI testing frameworks capture failure screenshots or performance profiling videos, the CI runner can upload these directly to the new Fastio workspace. Once Intelligence is enabled for the workspace, files are indexed so Ripley, the built-in RAG agent, can answer from them. An AI debugging agent can then use the MCP tools over Streamable HTTP at `https://mcp.fast.io/mcp` to analyze the failure logs, cross-reference them with the visual assets, and write a cited summary.

A pipeline can create an organization with `POST /current/org/create/`, add a workspace with `POST /current/org/{org_id}/create/workspace/`, and invite a QA lead with `POST /current/workspace/{workspace_id}/members/{email_or_user_id}/`. The agent keeps uploading logs while the human reviews the same intelligently indexed workspace.

To manage concurrent access when multiple pipeline jobs write logs at the same time, isolate outputs into separate directories and use Fastio's version history and audit log to track and restore revisions if needed.

## Integrating the OpenClaw Setup in CI/CD

For teams relying on agent frameworks for testing and deployment automation, connecting agents to Fastio's remote MCP server or REST API expands what CI runners can accomplish. Agents can interact with your Fastio infrastructure using LLMs such as Claude, GPT-4, or Gemini.

During the setup phase of your `.gitlab-ci.yml`, runners authenticate using scoped Fastio API credentials. Pipeline scripts can invoke agents to manage files, upload coverage reports, and query build artifacts without complex manual scripting.

This integration is useful because it works without extra setup beyond the initial API key. The runner can import a dataset from a URL with the MCP `upload` tool (`web-import`):

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call",
 "params":{"name":"upload","arguments":{"action":"web-import","url":"https://example.com/report.pdf",
 "profile_type":"workspace","profile_id":"1234567890123456789"}}}
```

The same import is available over REST as `POST /current/web_upload/` with form fields `source_url`, `file_name`, `profile_id`, `profile_type=workspace`, and `folder_id`.

## Handling Workspace Deletion and Cleanup in GitLab

When automating Fastio workspace provisioning with GitLab CI, you need to ensure ephemeral environments are properly decommissioned. If your pipeline creates a new workspace for every feature branch but fails to delete them afterward, you will quickly encounter storage sprawl and organizational clutter.

To prevent this, define a dedicated cleanup job in your `.gitlab-ci.yml` file. Configure this job with the `when: always` directive, which guarantees that the cleanup step executes regardless of whether the preceding build or test jobs succeeded or failed.

The cleanup job reads `$WORKSPACE_ID` from the provisioning stage and archives or deletes that workspace through the MCP `workspace` tool (`archive` or `delete`):

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call",
 "params":{"name":"workspace","arguments":{"action":"archive"}}}
```

You can also list remaining environments with `GET /current/org/{org_id}/list/workspaces/` or `GET /current/workspaces/all/`, then archive the ones the pipeline created. A scheduled GitLab job can run that list-and-archive loop so the dashboard stays focused on active branches.

## Evidence and Best Practices for Implementation

Implementing automated workspace provisioning means following infrastructure-as-code principles. Your deployment strategy should account for rate limits, permission boundaries, and graceful failure handling.

Always implement retry logic when automating API calls from GitLab CI. Network blips or temporary runner disconnections can cause initial provisioning requests to fail. A reliable script attempts the creation process multiple times with exponential backoff before marking the CI job as failed. HTTP 429 with error code 1671 means the call is rate limited; back off until the `x-ve-limit-expires` header. 

By treating your intelligent workspaces as code, you guarantee that every branch, merge request, and deployment has access to the exact coordination layer it requires.

## Frequently asked questions

### How to create a Fastio workspace from GitLab CI?

Add a job that sends a Bearer API key to POST https://api.fast.io/current/org/{org_id}/create/workspace/ as application/x-www-form-urlencoded. Store the API key and org ID as masked GitLab CI/CD variables, then pass the new 19-digit workspace ID to later jobs as a dotenv artifact.

### Can I automate Fastio using CI/CD?

Yes. GitLab runners can create workspaces with POST /current/org/{org_id}/create/workspace/, upload artifacts with POST /current/upload/, manage version history across parallel jobs, invite reviewers with POST /current/workspace/{workspace_id}/members/{email_or_user_id}/, and call MCP tools over Streamable HTTP at https://mcp.fast.io/mcp.

### What is an ephemeral workspace?

An ephemeral workspace is a temporary storage environment created specifically for a single task or test run. In CI/CD workflows, ephemeral workspaces are provisioned when a pipeline starts to store build logs and artifacts, and are automatically deleted when the pipeline finishes to ensure strict data security.

### How can a GitLab pipeline react to workspace file activity?

Long-poll with GET /current/activity/poll/{entityId}?wait=95&lastactivity={timestamp}, or search the audit log with GET /current/events/search/. After a job uploads reports, the next job can wait on that activity and continue the deployment.

### How does Intelligence Mode benefit CI/CD pipelines?

Workspace intelligence automatically indexes files uploaded to a workspace, enabling Ripley, the built-in RAG agent. When a CI/CD pipeline uploads test failures or deployment logs, debugging agents can query those logs with semantic search and return cited analysis.

## About Fast.io

Fast.io provides shared workspaces where people and AI agents work on the same files, with built-in semantic search and citation-backed chat over what they hold. Agents reach it through a remote MCP server at https://mcp.fast.io/mcp, a REST API at https://api.fast.io/current/, and a command line client published on npm as @vividengine/fastio-cli.