Skip to Content

GitOps workflow

How linked repositories sync, how dashboard edits are written back and which changes wait for confirmation.

Your repository is the source of truth. A-Line.cloud reads the tracked branch, works out what differs from what is running, and applies the difference. Changes you make in the dashboard to settings the repository owns go back to the repository as a pull request.

A link connects a directory of a repository, reached through one of your organization's GitHub installations, to A-Line.cloud. The branch defaults to the repository's default branch.

LinkDirectory holdsWho can create it
Infrastructureclusters/, environments/, secrets/, buckets/, storages/, domains/, dns/An organization admin, after a second-factor check
Projectproject.yaml, apps/, sites/A member of the project's environment

An organization has at most ten live infrastructure links.

Linking an existing project exports its current settings into the directory, so A-Line.cloud needs write permission on the repository. If the GitHub installation lacks it, the link is refused with github_permissions_required. Linking an existing project to a directory that already holds a project.yaml marks the link broken; existing files are never overwritten. Use create from repository for such a directory, or pick another path.

Sharing a directory

LinkSame directory twiceWhat is shared
InfrastructureRefused: a second live link to the same repository, branch and path fails with 409 link_exists.Several links may point at different directories of one repository. Each cluster, environment and secret group belongs to the first link that declares it. Another link declaring the same one gets a resource_managed_elsewhere refusal for it; the rest of its sync still applies.
ProjectAllowed: several projects can link the same directory.Each project syncs on its own, and a push to the branch syncs every link on it. A project has at most one live link. An app is only removed by the link that owns it.

Creating a second project from the same directory into the same environment fails with 409, because the project name is taken.

When an infrastructure link gives up a cluster, environment or secret group, the other links of the organization sync again so one of them can claim it.

Plan and apply

Every sync reads the files, checks them and produces a plan:

  • Changes: what the sync will create, update or remove.
  • Refusals: files that cannot be applied, each with the file, an error code and a message. Fix the file and push again.
  • Held: changes that wait for someone to confirm them (see held changes).

An infrastructure link syncs on a push to the tracked branch, when it is created, when you start a sync by hand, and after a held change is confirmed. Both kinds of link are also checked every few minutes, so a push whose notification never arrived is still applied.

Environments are applied first, so clusters and secret groups in the same push can name a new environment.

Checks on GitHub

A-Line.cloud reports on the repository as GitHub check runs, one per link, so a repository with several linked projects shows each of them:

Check runPosted onFor
A-Line / plan (<environment>/<project>)A pull request's head commitOne linked project: what merging would apply
A-Line / planA pull request's head commitAll linked projects together (see below)
A-Line / infra plan (<path>)A pull request's head commitThe infrastructure link at <path>
A-Line / sync (<environment>/<project>)Each synced commitOne linked project: whether it applied
A-Line / infra sync (<path>)Each synced commitThe infrastructure link at <path>
A-Line / release (<environment>/<project>/<app>)Each commit an app buildsOne app's release: build, deploy (publish for a static site), then live

Names use the environment and project slugs, so renaming a project's display name keeps the same check; the display name shows in the check's title.

A-Line / plan sums up every project's plan: it fails when any project fails, is neutral when any project is neutral or would hold changes, and passes otherwise. Its summary lists each project with its result and a link to it in the console. Branch protection and rulesets match check names exactly, so require A-Line / plan rather than the per-project checks: it keeps working when you link more projects to the repository.

Each app that builds from the repository posts its own release check, so a failed release stays red next to the ones that passed. The check follows the commit through the whole release: "Building", "Build succeeded, deploying", "Rolling out" ("Publishing" for a static site), then "Live" with the app's address. A failure names the step that failed (build or rollout) and why. Its summary lists the Build, Deploy and Live steps with how long each took, and "Details" opens the build and deploy log. A build of a stopped app ends neutral as "Built; not deployed", and a release a newer one overtook ends cancelled as "Superseded".

Earlier builds posted A-Line / build and then A-Line / build (<environment>/<project>/<app>) checks; if a branch protection rule or ruleset requires either name, it now stays pending, so require the per-app A-Line / release (<environment>/<project>/<app>) checks instead.

Fields owned by Git

Once a link applies a resource, the fields the file sets belong to the repository. A direct write to one of them through the API fails with 409 field_managed_in_git. Fields a file leaves out stay editable in the dashboard.

Writing dashboard edits back

Project links and infrastructure links share one change mode. It decides what happens to a dashboard edit of a field the link's files set:

ModeDashboard editTakes effect
Pull request (the default)Collected into a draft change set, proposed as one pull request. The edited resource shows the pending pull request.When the pull request is merged and the branch syncs.
Direct commitCommitted to the tracked branch.On the sync that commit starts.
Read-onlyRefused with 409 link_read_only: "This project is managed in Git (read-only). Change it in <repo>/<path>." The dashboard shows the resource but disables its controls.Only through the repository.

Edits keep the file's comments and key order; only the changed values move. For an infrastructure link this covers its clusters, pools (count, node type, autoscaling, storage) and environments. Auto-apply of billable changes keeps its meaning: a write-back only changes the files, and the sync that follows holds or applies the change as it would for any push.

In read-only mode the console also refuses to create or delete apps and domains in the project, remove a node from a pool or cancel such a removal. Syncs from the repository keep applying.

The write-back GitHub App

Pull request and Direct commit need the write-back GitHub App installed on the repository with Contents: write and Pull requests: write. Read-only only reads the repository and needs no write-back App.

The import dialog, the infrastructure link form and the link settings check the App before they save. If the App is missing, the mode shows Needs setup and you can't continue. The setup step that follows links to the App's install page for the repository. After you install it, check again. The API checks the same thing at save time and answers 409 github_writeback_required (with install_url) or 409 github_permissions_required.

If the App is uninstalled later, the link shows a warning with the same fix, and edits are refused rather than dropped.

Project links are switched by admins of the project's environment and infrastructure links by organization admins (after a second-factor check), in the link's settings. Infrastructure links that existed before change modes start as Read-only.

An app that runs in a linked project but has no file in the repository can be adopted into Git: A-Line.cloud proposes it as apps/<name>.yaml.

Held changes

Some changes are not applied by the sync alone. They are held, listed under pending actions, and wait for someone to confirm or dismiss them:

  • creating a cluster or a pool, and raising a pool's node count;
  • removing the file of an app with volumes, or of one that set allow_delete: true with delete_data (the app is held as a pending deletion; an app without volumes is removed, its backups kept);
  • removing an environment file;
  • deleting a bucket, storage or domain with delete: true.

Recovery covers backing out of a removal, failed syncs and rewritten history. Who can do what lists the role each action needs.

Confirming always needs a second-factor check. Depending on the change, the confirm dialog also asks you to:

  • type the resource's name;
  • acknowledge that a committed machine stays billed until the end of its term;
  • accept the terms of service (creating a cluster);
  • acknowledge that cryptocurrency mining is not allowed.

Creating clusters and pools and adding nodes runs the balance and order checks at confirm time.

A confirmed change of an infrastructure link is applied by the confirm itself. A confirmed change of a project link is applied by the next sync.

Billable changes without confirmation

An infrastructure link can be set to apply some billable changes without holding them: load balancers and higher autoscaling ceilings. Cluster and pool creation and node count increases are always held.

Unlinking

Removing an infrastructure link supersedes its held changes and releases the resources it owned. They keep running as they are, and become editable in the dashboard again.

On this page