Skip to content

Ansible playbooks with templated configuration to apply to all LinkORB code repositories.

License

Notifications You must be signed in to change notification settings

linkorb/repo-ansible

Repository files navigation

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!

Quick start

Ensure that Docker is installed on your system and you are using either Linux, MacOS, or WSL under Windows.

Create and configure a repo.yaml file for your repository. Reference the configuration table below and the associated repo.schema.yaml file.

Run repo-ansible for your project via docker:

# always pull latest version first
docker pull ghcr.io/linkorb/repo-ansible:latest
docker run --rm -v "$PWD":/app ghcr.io/linkorb/repo-ansible:latest

This command will execute the repo-ansible playbook-cwd.yaml in your current directory and report on the tasks that reported changes throughout the execution.

Note

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 file auto-generation

Running repo-ansible playbooks manually

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 jsonschema

Run the playbook

/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.

Short reference configuration

Required properties are bolded. YAML hierarchies are represented by newlines in the property column. The table is not exhaustive, only the most common properties and groups are documented in here. Refer to the repo.schema.yaml file for a complete overview of properties.

Property Default Description
version string - Version of compatible repo-ansible release. Automatically updated during repo-ansible runs.
name string - The git repository name.
description string - Repository description that shows up in the sidebar on GitHub, and as the first line of the README after the repository name.
type string - Classification of repository type. Influences what additional files repo-ansible will generate when run.
The last 3 listed types have been deprecated and should not be used on new projects.  Accepted values:php-web,php-library,php-cli,nodejs-web,nodejs-library,nodejs-cli,other,application,library,symfony-bundle,
codeowners array - Each array item contains a file/directory pattern and an array of individuals or teams responsible for reviewing and maintaining files/directories that match the specified pattern. For a list of allowed patterns, refer to CODEOWNERS syntax.
license string proprietary Repository license  Accepted values:mit,gpl-v3,proprietary,
license_year number - Year when the license was applied to the repository. Used with the MIT license, as it includes the year as part of the generated LICENSE file. Defaults to current year if not set.
visibility string private GitHub repository visibility.  Accepted values:public,private,
lifecycle string - Project lifecycle stage.  Accepted values:dev-research,dev-prod-bound,dev-prod,dev-maintenance,deprecated-prod,archived,
user_scope array - Additional project classification in terms of users served.  Accepted values:external-customer-facing-app,internal-team-facing-app,enables-external-customer-facing-apps,enables-internal-team-facing-apps,internal-devops-tooling,
github
topics array
- GitHub topics. An array of strings.
github
default_branch string
main Default branch configuration in GitHub (default main). Override for older repositories that still use master branch. Consider updating your repository to include a main branch and remove this option.
github
workflows
review boolean
true The review workflow will trigger for pull requests and will check if the commit messages conform with conventional commits, and if cards are referenced as part of the commit message.
github
features
dependabot_auto_merge boolean
true Generate workflow that automatically merges Dependabot PRs for patch and minor version releases.
Note that merging the PR won't automatically trigger other followup workflows.
github
features
downloads boolean
true Enable repository downloads.
github
features
squash_merge boolean
true Allow squash-merging pull requests.
github
features
merge_commit boolean
true Allow merging pull requests with merge commit.
github
features
rebase_merge boolean
true Allow rebase-merging pull requests.
github
features
sdlc_workflows boolean
false EXPERIMENTAL Software Development Lifecycle Workflows. Property will likely be removed in the future, and enabled by default, when workflows have been stabilized.
github
features
wiki boolean
false Enable Wiki tab.
github
features
issues boolean
false Enable issues tab.
github
features
projects boolean
false Enable projects tab.
reviewdog
platforms array
[] A broad way to categorize programming languages, libraries, and frameworks, and for which we have an external tool we can use to assure code quality during review.  Accepted values:php,twig,
devcontainer
custom_docker_compose_yaml boolean
false When enabled the compose file located at .devcontainer/docker-compose.yaml will no longer get automatically updated. Allowing users to customize their docker-compose setup.
devcontainer
postCreateCommand string
- Additional (shell) commands to run when the containers is created. For a typical project you would specify commands that only need to run once when the project is setup. For example you might add a command in here to load database fixtures for your project.
devcontainer
postStartCommand string
- Additional (shell) commands to run when the container is started. This event takes place after the create event, but opposed to the create event it's triggered every time the container is started (including when it's resumed from a suspended state). In a typical JavaScript application you might set it to run a npm run dev or equivalent step.
devcontainer
customizations_vscode
extensions array
- Additional extensions to install. Refer to the group_vars/all.yaml file for extensions installed by default.
devcontainer
customizations_vscode
settings object
- Settings overrides for VSCode and installed extensions. Refer to the group_vars/all.yaml file regarding proper format and default values.
devcontainer
private_packagist boolean
true Repository requires private packagist access. Property is ignored is not of type php-*, or the other (deprecated) types: application, library, symfony-bundle.
devcontainer
repository string
ghcr.io/linkorb/php-docker-base Image to use for devcontainer (registry image URL)
devcontainer
tag string
php8-review Image tag
helm_charts boolean false Enable generation of Helm charts.
archived boolean false Setting this option to true will cause the repository to be archived. Once archived, it can only be unarchived manually.
omit_files array [] EXPERIMENTAL A list of files to skip during file generation.

Readme file auto-generation

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 define repo-specific content in repo.yaml and within the /docs/partials folder as Markdown partials.

For example, if you define readme.usage.content in repo.yaml, but a Markdown file named readme.usage.md exists in the /docs folder, 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.

Contributing

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.

Brought to you by the LinkORB Engineering team


Check out our other projects at linkorb.com/engineering. By the way, we're hiring!