Skip to main content

Promoting between projects

Promotion copies a finished team or workflow from your current project into another project in the same organisation, together with everything it depends on. A typical use is building and testing in a development project, then promoting to the project your organisation uses day to day.

Promotion lives in Settings → Project → Releases.

Before you start​

  • Switch to the source project. Promotion always copies from your current project.
  • You need the project Admin role in the source project, or Owner or Admin in the organisation. See Members and roles.
  • You need to be a member of the target project. The target list only shows your other projects in the same organisation. You can't promote to another organisation.
  • Your organisation mustn't be read-only. If a trial has ended, you can preview a promotion but not run it.

What gets copied​

Choose a team or a workflow. FYAI works out its dependencies and copies them too:

You promoteFYAI also copies
A teamIts member agents
An agent (as part of a team or workflow)Its model configuration and functions
A functionThe model configurations and integrations it uses
A workflowThe agents, teams and functions its steps use

Platform-provided models aren't copied, because every project already has them.

How existing items are handled​

FYAI matches agents, teams, functions, model configurations and integrations by name in the target project:

  • No match — a new copy is created, and references between the copies are rewired (a team points to the new agents, a workflow step to the new agent or team, and so on).
  • A match exists — the existing item is reused and left as it is, unless you tick Update existing entities, in which case its settings are overwritten from the source. Integrations are never overwritten.

Workflows are always created new, even if one with the same name exists. Promoting the same workflow twice gives you two copies in the target project.

Credentials​

These are not copied. Re-enter them in the target project after promoting:

  • API keys on model configurations
  • secrets and environment variable values on integrations (OAuth connectors keep their provider settings, so people just need to connect again)
  • an agent's client secret
  • an agent's execution environment (cleared; choose one in the target project)
warning

Function settings such as environment variables and request headers are copied as they are. If a function holds a secret directly in its settings rather than in an integration, it is copied to the target project. Check functions before promoting them.

Promote a team or workflow​

  1. Switch to the project you want to promote from.
  2. Go to Settings → Project → Releases and stay on the Promote tab.
  3. Choose Teams or Workflows, find the item, and select its upload icon (Promote to another project).
  4. In Promote Team or Promote Workflow:
    • choose the Target project
    • tick Update existing entities if items that already exist in the target should be overwritten (it's off by default)
  5. Select Preview changes. FYAI analyses dependencies and shows the Review promotion plan:
    • Will create — new items that will be copied
    • Already exists — items found by name in the target
    • Credential warnings (secrets will NOT be copied) — what you'll need to set up afterwards
    • any blocking issues, which stop the promotion
  6. Select Promote, or Back to change your choices.
  7. Review the result: how many items were created, skipped, updated and failed, and which credentials to reconfigure. Select Done.

If one item fails, the others still go ahead; the result lists what failed.

After promoting​

  1. Switch to the target project.
  2. Enter the API keys and integration credentials listed in the result, and choose execution environments for agents that need one.
  3. Test the promoted team or workflow. See Testing agents and teams and Testing workflows.
  4. Recreate any workflow schedules and webhooks you need; these aren't promoted.

Each item created or updated by a promotion gets a change-history entry recording that it came from a promotion.

Promotion history​

The History tab in Releases lists past promotions in your organisation: the item promoted, its type, the source and target project codes, and how many items were created and updated. Filter by Source project or Target project, and select Refresh to reload.

Any member can view history. Promotions that were stopped by blocking issues aren't recorded.

Rolling back a promotion​

Rolling back deletes the teams, agents, functions and model configurations that the promotion created. It doesn't:

  • delete workflows or integrations the promotion created — delete those yourself
  • undo changes made to existing items with Update existing entities
  • touch items that already existed

Rollback is available through the Platform API and the platform MCP server (get_promotion_history, then rollback_promotion with the promotion's ID). It needs the same project Admin rights as promoting.

Promoting with the API or MCP​

The same steps are available programmatically: analyze_promotion previews a promotion, execute_promotion runs it, get_promotion_history lists past promotions and rollback_promotion rolls one back. The entity type is team or workflow, and projects are identified by project code.