Ansible playbooks with templated configuration to apply to all LinkORB code repositories.
What benefits do you get from using repo-ansible for your repository?
- CodeSpace devcontainers
LAMP-based devcontainer with Apache, MariaDB and a phpMyAdmin. - automated security and dependency updates via Dependabot
Organization-wide settings ensure security alerts and pull requests are enabled for all repositories, and repo-ansible, doubles down on this configuration, makes sure that security and minor version updates created by Dependabot will automatically get merged. - Contributors support
Community guidelines, contributing notes, git hooks, codeowners for automated PR assignment, QA tooling/configuration, and the standardized LinkORB pull request template. - Standardized repository files, GitHub repository management, and much more to come!
The playbook depends on the repo.yml configuration file which must reside at the root of your repository.
This configuration let's you define variables that are used throughout generation of repository files, workflows,
and in general standardisation across the organization repositories.
For example, you use repo.yml to define your projects repository name, description, license, visibility, code owners,
etc.
For all the options and switches, please refer to the JSON Schema definition of the configuration file: repo.schema.yaml.
Review README.md file auto-generation, switches and rules
The content for each section of this README was either retrieved from repo.yaml or Markdown partials stored in the
docs/partials folder. Managing content in this way allows you to centrally define documentation in
repo.schema.yaml inherited by each affected codebase while also allowing you to define repo-specific content in
repo.yaml and within the /docs/partials folder as Markdown partials.
When a playbook generates the README, it checks for Markdown partials in the /docs folder. If present, they override
repo-specific content defined in repo.yaml or content inherited from repo.schema.yaml defaults.
For example, if you define readme.usage.content in repo.yaml, but a Markdown file named readme.usage.md exists
in the /docs foder, the dynamic README inserts the Markdown content.
To make this possible, tasks defined in retrieve-docs-data.yaml retrieve the docs files data such as the filename
and path for each Markdown file so README.md.j2 can check for the presence of Markdown files for each README section
and insert Markdown content if there is a match.
Ansible is required. How do I install Ansible on my system? Encountered issues with Ansible execution?
Grab the latest version of the repository and its dependencies.
$ git clone https://github.com/linkorb/repo-ansible.git /tmp/repo-ansible
$ pip3 install -r /tmp/repo-ansible/requirements.txtNote
During execution your repository's' README.md will be overwritten with the generation rules used in repo-ansible. If you're running the playbook for the first time on your repository, be sure to Review README.md file auto-generation, switches and rules ↑
/your-repository $ ansible-playbook /tmp/repo-ansible/playbook-cwd.yaml
PLAY [localhost] **************************************************************************
TASK [Gathering Facts] ********************************************************************
ok: [localhost]
...The playbook will load and validate repo.yaml according to the schema; then proceed to apply templates and checks to
your repository.
We welcome contributions to make this repository even better. Whether it's fixing a bug, adding a feature, or improving documentation, your help is highly appreciated. To get started, fork this repository then clone your fork.
Be sure to familiarize yourself with LinkORB's Contribution Guidelines for our standards around commits, branches, and pull requests, as well as our code of conduct before submitting any changes.
If you are unable to implement changes you like yourself, don't hesitate to open a new issue report so that we or others may take care of it.
Check out our other projects at linkorb.com/engineering.
By the way, we're hiring!
