Skip to Content

Manage a project from Git

Link a project to a folder in a GitHub repository, so its apps follow YAML files and changes go through pull requests.

Goal: a project whose apps, domains and settings live as YAML files in your repository. A push applies them, and edits in the console become pull requests.

Before you start

  • A project, even an empty one.
  • GitHub connected under Settings > Integrations, with access to the repository.
  • To have console edits written back, the GitHub App needs write access to the repository's contents and pull requests.

Connect the repository

Open the project and select Project settings on the canvas.

On the General tab, select Connect a Git repo.

Pick the Repository and the branch, and enter a Folder, such as projects/shop. Leave it empty for the repository root.

Select Connect repository.

A-Line.cloud writes the project's project.yaml into the folder. From then on, the project's apps follow the files there.

If connecting fails with a Grant write access link, the GitHub App cannot write to the repository yet. Follow the link, grant access, and connect again.

Pick how console edits are handled

The General tab now shows the link: Repository, Branch, Path, Status and Link ID. Select Change mode to choose:

ModeA console edit
Pull request (default)Is proposed as a pull request. It takes effect when the pull request is merged.
Direct commitIs committed to the branch and applied on the next sync.
Read-onlyIs refused. Edit the files in the repository instead.

Only environment admins can change the mode.

Make a change from Git

Add an app file to the folder, for example apps/web.yaml:

# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
source:
  image: ghcr.io/example/web:1.0.0
port: 3000
replicas: 2

Open a pull request. The A-Line / plan (<environment>/<project>) check lists what the change will create, update or remove.

Merge it. The sync applies the plan.

Verify

  • The new app appears on the project canvas.
  • The link's Status on the General tab shows the last sync. Last sync failed means a file was refused; open the plan for the file and the error.

Troubleshooting

  • Connect GitHub in the Integrations settings first: no repository is available. Connect GitHub under Settings > Integrations.
  • A change is waiting and not applied: some changes are held until someone confirms them, such as raising a pool's node count or deleting an app with volumes. See held changes.
  • The console refuses an edit: the link is Read-only. Change the file in the repository, or switch the mode.

Select Unlink repository on the General tab. The apps keep running as they are and become editable in the console again. The files stay in the repository. See unlinking.

Next steps

On this page