The atsign-foundation GitHub organisation has accumulated a whole bunch of conventions and configuration, which until this document were being carried around in the heads of the team. The purpose of this guide is to make those conventions and configuration explicit.
We have the following GitHub Apps installed:
Allstar is an app from the Open Source Security Foundation (OSSF) that monitors the configuration of our GitHub repos.
We have an opt-in strategy that covers all the public repos, and make use of the default policies covering:
- Branch Protection
- Binary Artifacts
- Outside Collaborators
- SECURITY.md
- Dangerous Workflow
- Generic Scorecard Check
Backhub is a cloud to cloud backup solution for your GitHub repositories. Backups include metadata such as issues and come with daily snapshots up to 30 days back in time. Restore to GitHub or clone directly from BackHub. GitHub repository backups have never been easier.
A GitHub app to check that pull requests follow the Conventional Commits spec
This was implemented to ensure that we have high quality pull request (PR) titles, which can then feed in to high quality change logs.
The process begins by using Conventional Commits to ensure structured commit messages, which then become the basis for PR titles.
At the moment we don't mandate passing checks for this bot, but that may change.
New repos should be created from templates, as the templates take care of the boilerplate needed to pass the GitHub recommended community standards checks:
- README
- Code of conduct
- Contributing guide
- License
NB we implement issue templates and pull request template at an org level, though they can be overridden at the repo level.
The primary template is called archetype and simply takes care of the checklist above.
NB a public version of the archetype template can be found in the atsign-company org.
When a repo will be used to publish content to pub.dev the archetype-pubdev can be used to provide some additional framework examples.
We use Dependabot to keep an eye on dependencies for things like:
- GitHub Actions
- Dockerfiles
- Dart/Flutter pubspec.yaml
When Dependabot sees an update to a dependency it will raise a PR, which can then be tested before we make the decision to merge.
A malicious dependency might try to steal secrets, so Dependabot doesn't have access to secrets when it's running GitHub Actions.
In some cases this means that we've crafted tests so that they won't run when a PR originates from Dependabot, as otherwise they'd fail, and we wouldn't be able to merge the Dependabot PR due to a failed check.
It's common for Dependabot to raise multiple PRs for the same dependency changing in multiple places across a repo. This can be tedious, as once one change is merged all the others need to be rebased. So to save time we manually roll up a number of Dependabot PRs by merging their respective bramches together. At least Dependabot is smart enough to close the original PRs when the rollup is merged. Hopefully Dependabot will get the ability to handle rollups for itself.
GitHub Actions are used extensively across org repos to undertake:
Continuous Integration (CI) tests are in place to ensure that PRs are tested before being merged. These will usually consist of some combination of:
- Unit tests - tests that can be run standalone (NB it's expected that unit tests will be run before committing code).
- Functional tests - tests that require extra resources, such as an atPlatform Virtual Environment.
- End to End tests - tests that require multiple additional resources, such as secondary servers running different versions of code to ensure that new code still works with existing production code.
Automated tests also run linting tools against code. As with unit tests it's expected that lints will be run before code is committed, and the automated checks are just there as a safety net.
- C/C++ is linted with cppcheck
- Dart makes use of
dart analyze - Flutter code uses
flutter analyze, usually along with--no-fatal-infosto ensure that INFO level findings don't break tests. - Markdown is linted with pymarkdownlnt. If you're working on Markdown docs then it's recommended to have pymarkdownlnt installed in a virtual environment. This post provides details on setting things up.
- Python (and MicroPython) use either Flake8 or Ruff
- Rust uses clippy
Some repos are configured so that merges to trunk create a new release that is automatically deployed to the staging environment.
Repos may also have automation such that release tags create releases that are deployed to canary and production environments.
Scorecards is an automated tool that assesses a number of important heuristics ("checks") associated with software security and assigns each check a score of 0-10. You can use these scores to understand specific areas to improve in order to strengthen the security posture of your project. You can also assess the risks that dependencies introduce, and make informed decisions about accepting these risks, evaluating alternative solutions, or working with the maintainers to make improvements.
In order to keep the scores high we have:
- Branch protection.
- Continuous Integration (CI) tests wherever they make sense.
- Minimised permissions for GitHub Tokens in Actions.
- Dependencies pinned to SHAs in GitHub Actions, Dockerfiles and Python requirements.txt
The StepSecurity App can be used to find minimal token permissions and SHAs for Actions.
Workflows will pick up new issues and place them in Triage on the Dev Eng Sprint Planning Board
We make use of a number of project boards to organise work.
The process starts with an issue being raised, making use of the templates for bug, enhancement etc.
Automation is used to place issues in Triage, where they should be prioritised and where possible assigned to somebody knowledgeable about the work involved to resolve the issue.
Sufficiently high priority issues will be scheduled into two week sprints, other issues will be placed in the backlog.
Where it's not obvious how much effort is expected we make use of Planning Poker to get the wisdom of the team to determine an estimate. Issues are exported from GitHub Projects using the Dump Cards scripts.
The labels repo is used to manage a consistent set of labels across org repos.
There are often times when a change needs to be made to multiple repos, and these generally fall into two types: content changes and config changes.
When the same change is needed to content across multiple repos these can be accomplished with git-xargs and accompanying scripts.
For examples see (private repo) atsign-company/git-xargs_scripts
We use the Terraform GitHub Provider to orchestrate changes across multiple repos. Different parts of the underlying API(s) are supported by different resources within the provider, so usage will be very context dependent.
This Gist provides an example of applying branch protection rules (in order to pass Allstar compliance checks).
A complete profile helps to show the human side of our organisation, and gives you a chance to highlight your interests and contributions.
Please have MFA enabled, as it is safer for you, and this org.
Signing commits with GPG or SSH keys is encouraged, as it provides a stronger chain of custody for code.
See Signing GitHub commits with SSH keys for a guide to configuring your git client and GitHub.