> Index of every page on this site: [llms.txt](https://docs.a-line.cloud/llms.txt)

# 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.

## Links

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.

| Link | Directory holds | Who can create it |
| --- | --- | --- |
| Infrastructure | `clusters/`, `environments/`, `secrets/`, `buckets/`, `storages/`, `domains/`, `dns/` | An organization admin, after a second-factor check |
| Project | `project.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

| Link | Same directory twice | What is shared |
| --- | --- | --- |
| Infrastructure | Refused: 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. |
| Project | Allowed: 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](#held)).

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 run | Posted on | For |
| --- | --- | --- |
| `A-Line / plan (<environment>/<project>)` | A pull request's head commit | One linked project: what merging would apply |
| `A-Line / plan` | A pull request's head commit | All linked projects together (see below) |
| `A-Line / infra plan (<path>)` | A pull request's head commit | The infrastructure link at `<path>` |
| `A-Line / sync (<environment>/<project>)` | Each synced commit | One linked project: whether it applied |
| `A-Line / infra sync (<path>)` | Each synced commit | The infrastructure link at `<path>` |
| `A-Line / release (<environment>/<project>/<app>)` | Each commit an app builds | One 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:

| Mode | Dashboard edit | Takes 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 commit** | Committed to the tracked branch. | On the sync that commit starts. |
| **Read-only** | Refused 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](/iac/recovery) covers backing out of a removal, failed syncs and
rewritten history. [Who can do what](/iac/permissions) 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.
