Deploy from a repository
Connect a repository to an app, and every push to its branch deploys the app's definition, with a plan, a record and a way back.
An app's definition can live in your own repository, next to the rest of your code. You connect the repository to the app once; from then on, every push to the branch you chose is a deployment: Authoric reads the commit, works out what would change in the app, applies it, and keeps a record of what it did.
This is the workflow you know from hosting a website from a repository, applied to a backend:
- Connect a repository to an app and pick a branch.
- Push. Each push to that branch deploys the definition at that commit.
- Open a pull request and Authoric comments on it with what merging would change.
- Look back at the app's Deployments list: every deployment, what it changed, who caused it and who approved it, and Roll back to any earlier one.
An app that is not connected to a repository works exactly as before: you build it in the console.
What a deployment carries
Today a definition holds the app's tables (their columns, indexes, foreign keys and settings), its roles and policies (who may do what, and which policies each role carries), its tables' custom actions, its agents, its scheduled jobs, its file storages, its settings (the brand on its email, and which of your email and external tool connections it may use), and its handlers (their code, which handler backs which action, what kind each one is and what it is for). The folder layout and every option are in The bundle.
Connect a repository
In the console, open the app, then App integrations › Repository. Choose the source-control
connection, the repository, the branch, and the folder that holds the definition (authoric by
default). Connecting queues the first deployment, of the branch's latest commit.
One repository is connected to an app. To run the same definition in more than one place, use one
app per environment, each connected to its own branch: main deploys production, staging deploys
the staging app. Moving a change from staging to production is a merge.
What differs between the two, such as the email connection staging sends through or how often a
job runs there, goes in the bundle's environments/ folder. Name each app's environment on its
Deployments page. See Environments.
Only the app owner, signed in to the console, can connect, re-point or disconnect a repository.
Export an app built in the console
An app you built in the console moves to a repository in one step. Connect the repository, then choose Export to repository on the app's Deployments page. Authoric opens a pull request on a new branch with the app's whole definition, in the connected folder. Merging it is the first deployment from the repository: every object the files name is taken over, never duplicated, and from then on it changes through pull requests. The plan posted on the pull request should list nothing but objects being taken over; anything else means the app changed after the export, so export again.
Authoric never merges the pull request and never commits to the connected branch.
What happens on a push
The push is queued, never applied inside the webhook, and each deployment goes through the same steps:
-
Read. The definition is read from the provider at the exact commit that was pushed, never from the webhook's payload and never from whatever the branch points at later.
-
Plan. Authoric compares it with the live app and lists every change in plain language, grouped the same way everywhere:
Group Means ▲ Widens authority Someone or something may do more than before: a handler that can now run raw SQL, send email or write files, or a job-only handler that becomes callable ✕ Removes Something is deleted, such as a handler the definition no longer has + Adds Something new appears ~ Changes Something changes without changing what anyone may do ▼ Narrows Someone or something may do less -
Wait, if it must. A removal always waits for a person to approve it. A widening waits while the app is protected. Everything else applies.
-
Apply. Changes are applied in order, additions first and removals last, one deployment at a time per app. If a step fails, the deployment stops there and says which step and why; nothing after it runs.
A deployment's status is one of: Queued, Planning, Needs approval, Approved, Applying, Live, Replaced (an earlier live one), Stopped (failed at a step), Rejected, Expired (nobody approved it within 7 days), Superseded (a newer push replaced it before it started) or Canceled.
A plan that cannot be applied fails before anything changes. Removing a handler that an endpoint or a scheduled job still runs, for example, fails the plan with what to change first.
Objects the repository manages
When a deployment creates a table, a role, a policy, a custom action, an agent, a scheduled job, a file storage, a
connection grant, the brand or a handler, or takes over one you made in the console with the same name, it is managed by the repository. The console shows it read-only with the file it comes
from, and every way to change it outside a deployment refuses (DEFINITION_CODE_MANAGED): the
console, agents, the AI author, and schema-changing SQL a handler runs. Asking the AI to change such a handler opens a pull request in
the repository instead, with its test run and capabilities in the description.
Anything made in the console that the definition does not name is left alone. A deployment never deletes something it did not create or take over.
Disconnecting the repository hands every object back to the console.
Pull requests
When a pull request targets the branch an app deploys from, Authoric posts one comment on it, kept up to date as you push, saying what merging would do to that app. Changes that would wait for an approver are marked "needs an approver in Authoric after merge". The commit also gets a status, so you can require it in your branch rules.
Preview before you deploy
Preview on the app's Deployments page shows the same plan for any branch's newest commit, without a pull request and without changing anything. For the connected branch, Deploy this commit then deploys exactly the commit you previewed, even if the branch has moved on since. For any other branch, the preview is what merging it into the connected branch would do.
Deploy latest deploys the connected branch's newest commit without the preview step.
Roll back
Every deployment that went live can be rolled back to from its row on the Deployments list. A rollback is a new deployment of that earlier definition, planned against the app as it is now, so a rollback that removes something still waits for an approver.
A rollback also pauses automatic deploys for the app, so the next push does not undo it. Pushes are still recorded, as canceled. Resume them from the app's Deployments page (Deploy on push) when the repository has caught up.
Break-glass editing
During an incident the app owner can turn on break-glass editing: for up to 24 hours, with a reason, the console may change objects the repository manages. A banner shows while it is on. Changes made meanwhile show up as drift, "live differs from the repository", until the repository catches up. You can propose a console change back to the repository as a pull request from the handler's page.
Authoric also checks each connected app against its last deployment every hour and shows any drift on the Deployments page.