Git repositories

Keep forms, configuration, playbooks and vars files in git

For admins who keep forms, configuration and playbooks in git: what a repository can hold and which source wins.

What a repository is for

A repository is a git remote that AnsibleForms clones and keeps up to date, and each one has switches that say what it holds:

Switch	What AnsibleForms reads from it	Folder in the repository
Use for config ?	`config.yaml` with the categories, roles and constants	the root
Use for forms ?	The form files, which the designer also saves back into it	`forms`, or the root
Use for playbooks ?	The Ansible playbooks that jobs run	`playbooks`, or the root
Use for vars files ?	The vars files that forms load	`vars`, or the root

Without the subfolder, the repository root is used. One repository can hold everything; if you split them, only Use for forms may be on several (their forms are merged): the other switches take the first repository and log a warning.

Every repository is cloned into a subfolder named after it, under REPO_PATH.

One repository for everything

A single repository can hold all four kinds of content, with every switch enabled and one subfolder per kind.

forms-repo/
├── config.yaml        # categories, roles and constants
├── forms/             # form files (*.yaml)
├── playbooks/         # Ansible playbooks and roles
└── vars/              # vars files used by forms

One repository per purpose

Separate repositories let teams own their part, with one switch each and the files directly in the root.

Repository	Switch	Content in the root
`af-config`	Use for config ?	`config.yaml`
`af-forms-network`, `af-forms-storage`	Use for forms ?	The form files of each team, merged into one list
`af-playbooks`	Use for playbooks ?	The playbooks and roles
`af-vars`	Use for vars files ?	The vars files

Only forms can come from several repositories; config, playbooks and vars files each come from one.

How repositories combine with local folders

Repository content replaces the matching local folder; this table summarizes where each kind of file is read from.

Content	Read from, first match wins
Configuration	1. the database, when the configuration is kept there (`ENABLE_CONFIG_IN_DATABASE`) 2. `config.yaml` of the Use for config repository 3. `config.yaml` of a Use for forms repository, when no repository is used for config 4. `CONFIG_PATH`
Forms	Every Use for forms repository plus `FORMS_STAGING_PATH`; `FORMS_FOLDER_PATH` only when there is none
Playbooks	The Use for playbooks repository, otherwise `ANSIBLE_PATH`
Vars files	The Use for vars files repository, otherwise `VARS_FILES_PATH`

Forms from several repositories are merged into one list. When two of them hold a form with the same name, the first one loaded is kept and the warning skipping duplicate form <name> is logged, so keep form names unique across repositories.

Troubleshooting

Most problems show in the Status column and in Show output, which holds git’s own error message.

A repository clone or pull failed: authentication, known hosts and local changes.
The forms repository is not cloned yet: the designer cannot save before the first clone.
A repository stuck in running after a restart is reset to failed at the next start; run Trigger again.

In this section

Each topic has a page of its own:

Page	What it covers
Adding a repository	The Repositories page, every field of a repository, and declaring one in the config seed
Authentication	HTTPS with a token, SSH with the generated key, and custom git commands
Pulling changes	Scheduled, manual and API pulls, and local changes
Designer and push	Edit forms in the designer and push them to the repository