External Writes — Admin Guide
Most of Align's integrations only read. This page lists what Align writes to systems outside Align, and what makes it happen. There are two kinds of write:
- writes that follow from an integration setting an admin turned on;
- writes that Max, Align's assistant, proposes and a person confirms.
Sentry, Railway, Prometheus, Grafana, Loki and Fireflies only read, apart from the one Sentry uninstall described below. See Integrations for each one.
Writes that follow from your settings
| System | What Align writes | When | Turned on by |
|---|---|---|---|
| GitHub | A comment on a linked pull request | Someone adds a comment to an entry with a linked pull request. Internal and AI-generated comments are not sent. | Sync comments to GitHub PRs in the project's Integrations tab. Off by default. |
| GitHub | An Align CI check run on a commit | Test results for the commit arrive from a GitHub Actions workflow | Testing / CI, per linked repository, in the project's Integrations tab |
| GitHub | An Align Traceability check run on a pull request | A pull request is opened or updated | Align, on request. There is no in-app setting. |
| TaskFlow | A new task | An entry is created in an Align project mapped to TaskFlow | A project mapping under Workspace / Project Sync |
| TaskFlow | Changes to a task | An entry linked to a TaskFlow task is edited; Sync with Push or Both also pushes the mapped project's entries | The same mapping |
| TaskFlow | The task's status | Any status change on a linked entry, whatever made it | Status sync |
| TaskFlow | A comment | Someone adds a comment to a linked entry. Internal and AI-generated comments are not sent. | Comment sync |
| TaskFlow | An approval request | A cost approval is submitted on a record linked to a TaskFlow task | Push Align cost approvals to Taskflow |
| TaskFlow | A key result check-in | A mapped release, entry or cost approval changes, and once a day | OKR Rollup Mappings |
| Slack | A notification message | A notification is routed to Slack | Notification routing in Settings → Notifications |
| Any web address | An HMAC-signed POST of an Align event | The event happens | A subscription under Outbound Webhooks in Settings → Developer → Webhooks |
| Any web address | A POST to a fixed https address | An automation rule's conditions are met | A project automation rule with a call webhook action |
The TaskFlow switches are under Sync Feature Flags in the TaskFlow panel, and all start off. Turning one off stops new activity but does not undo what was already synced.
One more write happens only when you remove a connection: disconnecting an Alignsoft installation in Align also asks Sentry to uninstall it.
Writes Max proposes
Max can send work to GitHub and Replit, or record a link to a task in another system. Every such action needs explicit confirmation: nothing is written until a person confirms it on Max's card.
What Max can do
| Action, as shown on the card | What it writes | Who can propose it |
|---|---|---|
| Link Align Entry to GitHub Issue | A comment on the GitHub issue or pull request linking back to the entry, and the link in Align | Admin, Manager, Tech Lead |
| Create Draft Task in Replit | A draft task in a Replit workspace | Admin, Manager, Tech Lead, Developer, Tester |
| Send Align Entry to Replit Agent | The entry, sent to Replit Agent as an implementation request | Admin, Manager, Tech Lead, Developer, Tester |
| Link External Task | A link in Align between an entry and a task elsewhere. Nothing is sent outside Align. | Every role except Client and Viewer |
| Unlink External Task | Removes that link. Nothing is sent outside Align. | Every role except Client and Viewer |
| Preview Sync Changes | Nothing. It shows what a sync from an external task would change. | Every role except Client and Viewer |
Platform admins can propose any of these.
The Replit actions need the workspace's Replit Agent connection in Settings → Integrations, which a platform admin must first allow for the workspace. Create Draft Task in Replit uses the project's Replit Workspace ID from the project's Integrations tab.
Turning it on
All of these must be true:
- The workspace's feature flags. A platform admin turns on Max (AI Assistant), MCP Server and Max External Writes for the workspace, in Platform Admin → Tenants → [tenant] → Feature Flags. See the Platform Admin Guide.
- The platform switch, for actions that write outside Align. The GitHub and Replit actions also need live external writes switched on for the Align platform. This is a server setting that Align's operators control. The Align-only actions (link, unlink, preview) do not need it.
- The role, as listed in the table above.
For platform operators, the server settings are:
| Variable | Purpose | Default |
|---|---|---|
ASSISTANT_EXTERNAL_WRITES_ENABLED | Must be true for any live external write. | Off |
ASSISTANT_EXTERNAL_WRITES_PILOT_ORGS | Comma-separated workspace IDs allowed to make live writes. Empty means all. | Empty |
ASSISTANT_EXTERNAL_WRITES_SANDBOX_ONLY | GitHub only. Unless set to false, the target repository must be in the sandbox list. | On |
ASSISTANT_EXTERNAL_WRITES_SANDBOX_REPOS | GitHub only. Comma-separated owner/repo values allowed as targets. | Empty |
The confirmation card
When a user asks Max to act on another system:
- Max proposes. A card appears in the Max panel showing the target system, the entry, and a preview of what will be sent. For a GitHub link, the preview is the exact comment. An action that cannot be undone from Align says so.
- The user reviews, and can cancel.
- The user confirms. Align checks the flags, the role and the platform switch again, then makes the write and reports the outcome.
For a GitHub link, Align checks the platform switch and the sandbox list as soon as Max proposes. If either blocks it, the card says why and cannot be confirmed. Preview Sync Changes shows Run preview instead of a confirm button, because it never writes.
Align records each proposal and its outcome: who proposed and confirmed it, the system and action, the result, and any error.
Turning External Writes off
- For one workspace: a platform admin turns off Max External Writes in the workspace's feature flags. Confirming a pending card then fails with "External write actions are not enabled for your organisation."
- For the platform: Align's operators turn off
ASSISTANT_EXTERNAL_WRITES_ENABLED. No new GitHub or Replit write is made. The Align-only actions keep working.