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

# 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

<Steps>
<Step>

Open the project and select **Project settings** on the canvas.

</Step>
<Step>

On the **General** tab, select **Connect a Git repo**.

</Step>
<Step>

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

</Step>
<Step>

Select **Connect repository**.

</Step>
</Steps>

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:

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

Only environment admins can change the mode.

## Make a change from Git

<Steps>
<Step>

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

```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
```

</Step>
<Step>

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

</Step>
<Step>

Merge it. The sync applies the plan.

</Step>
</Steps>

## 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](/iac/gitops#held).
- **The console refuses an edit**: the link is **Read-only**. Change the
  file in the repository, or switch the mode.

## Stop managing from Git

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](/iac/gitops#unlinking).

## Next steps

- [Your first project](/iac/first-project): a cluster, project and
  app from scratch.
- [GitOps workflow](/iac/gitops): syncs, plans, held changes and write-back.
- [Checking changes](/iac/check): check files before you push.
- [Import](/iac/import): turn existing resources into files.
