Git repositories

Keep forms, vars files, configuration and playbooks 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, and their vars files	`forms`, or the root; vars files in `vars`
Use for playbooks ?	The Ansible playbooks that jobs run	`playbooks`, or the root
Use for workflows ?	The workflow files, which the designer also saves back into it	any folder
Use for inventories ?	One inventory, named after the repository, which a form names with `inventory:`	the root: `inventory.yaml`, `group_vars`, `host_vars`

Without the subfolder, the repository root is used. One repository can hold everything; if you split them, only Use for forms, Use for workflows and Use for inventories may be on several: 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 forms, vars files, configuration and playbooks, with the switches 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

Only forms can come from several repositories; config and playbooks each come from one. The vars files come from the vars folder of the first forms repository that has 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 `vars` folder of the first Use for forms repository that has one, otherwise `VARS_FILES_PATH`
Workflows	Every Use for workflows repository plus `WORKFLOWS_PATH`, together

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 Pull column and in Show last pull output (or Show last push output), which hold 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 is reset to failed: after a restart, at the next start; within a minute once the node that runs its git operation stops answering for 2 minutes; and in any case after 2 hours. Run Pull 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