{"id":20770722,"url":"https://github.com/ably/repository-audit","last_synced_at":"2025-04-30T14:09:25.688Z","repository":{"id":42522003,"uuid":"410234509","full_name":"ably/repository-audit","owner":"ably","description":"Oversight for our estate of repositories, in particular those in the public domain. Audit. Monitor. Conform.","archived":false,"fork":false,"pushed_at":"2023-07-19T04:25:50.000Z","size":711,"stargazers_count":11,"open_issues_count":22,"forks_count":2,"subscribers_count":21,"default_branch":"main","last_synced_at":"2025-03-30T16:46:36.324Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ably.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-09-25T09:49:52.000Z","updated_at":"2023-01-04T11:44:18.000Z","dependencies_parsed_at":"2023-02-08T17:46:00.093Z","dependency_job_id":null,"html_url":"https://github.com/ably/repository-audit","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ably%2Frepository-audit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ably%2Frepository-audit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ably%2Frepository-audit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ably%2Frepository-audit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ably","download_url":"https://codeload.github.com/ably/repository-audit/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251717055,"owners_count":21632228,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-17T12:11:37.457Z","updated_at":"2025-04-30T14:09:25.630Z","avatar_url":"https://github.com/ably.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ably Repository Audit\n\n[![Check Workflow Status](https://github.com/ably/repository-audit/actions/workflows/check.yml/badge.svg)](https://github.com/ably/repository-audit/actions/workflows/check.yml)\n[![Run Workflow Status](https://github.com/ably/repository-audit/actions/workflows/run.yml/badge.svg)](https://github.com/ably/repository-audit/actions/workflows/run.yml)\n\n## Overview\n\nAudit. Monitor. Conform.\n\nThis tool is being designed by the SDK Team at Ably to provide oversight of our repositories,\nthose public in our [`ably` org](https://github.com/ably/), and beyond.\n\nIt is partnered with the\n['Ably Repository Audit' GitHub App](https://github.com/apps/ably-repository-audit),\nwhere this tool authenticates as that app in order to do its work.\n\n### Why?\n\nOversight. Monitoring.\n\nWhile GitHub clearly understand that their users have a desire to gain a bird's eye view of activity across their organization(s)\n(see [their September 2021 announcement of 'audit log streaming' entering public beta](https://github.blog/2021-09-16-audit-log-streaming-public-beta/)),\nthe reality is that with our current interfaces to GitHub (being `git` clients and their browser UI) we have limitations,\ndue to the manual nature of all these interactions:\n\n- To check if a repository is configured correctly we need to navigate via the browser UI to its settings page\n- To check if two repositories are configured the same then we need to load up two browser UIs side-by-side\n- If a repository is used infrequently then its settings can drift out of sync with what we're tending to use elsewhere\n- We often grant several people permission to change repository settings and these changes (deliberate or accidental) may not be spotted for some time\n- There are things we care about but we need to care about them across hundreds of repositories, public and private, across multiple GitHub orgs\n\n### What?\n\nEssentially a [lint](https://en.wikipedia.org/wiki/Lint_(software)) tool for our repository configurations.\nWhile this tool may examine repository _contents_ (a.k.a. source code) in time (for example, to check for presence of standard files),\nwe're focussing initially on settings which are available to most of us only via GitHub's browser UI.\n\n#### Naming / Vocabulary\n\nWe care about others and have empathy for their views ('tech needs humanity' is [one of Ably's core values](https://ably.com/blog/ably-values)).\nIt's important that we make concerted efforts to remove non-inclusive terminology from our nomenclature.\nThis includes the branch names we use in our repositories, especially the default branch names, for both public and private repositories.\n\n#### Consistency / Principle of Least Astonishment\n\nDevelopers working with Ably (as maintainers or customers) should be able to, wherever idiomatically and logically possible,\nseamlessly move from repository to repository with minimal friction. This means consistent:\n\n- Use of labels for issues and pull requests ([#2](https://github.com/ably/repository-audit/issues/2))\n- Appearance of 'Projects', 'Wikis' and 'Issues' tabs on repository home pages ([#11](https://github.com/ably/repository-audit/issues/11))\n- Appearance of 'Releases', 'Packages' and 'Environments' sections in the side column on repository home pages ([#16](https://github.com/ably/repository-audit/issues/16))\n- Presence and contents of `LICENSE` ([#26](https://github.com/ably/repository-audit/issues/26))\n- Presence and contents of `COPYRIGHT`\n- Presence and contents of `MAINTAINERS.md`\n- Presence and broad layout of `README.md`\n\n#### Guard Rails / Workflow\n\nAs a company Ably is very focussed on a 'written first' approach to the way that we approach our work.\n\nAn implicit principle of written first is that we aim to keep things [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself),\nmeaning that we would rather be able to point people towards a canonical location where process-oriented instructions live.\nIn other words, our response to a query about the way to do something should be along the lines of\n'look over there, where this is documented'.\n\nExtending this principle out - where it is possible for us to install guard rails that naturally, innately steer people onto the correct tracks - we don't have to explicitly write this down in plain English (because it's a switch or rule that was installed somewhere).\nIn which case, this tool is here to periodically check that those guard rails are consistently configured correctly.\nFor example:\n\n- Allowed Behaviour of the Merge button ([#11](https://github.com/ably/repository-audit/issues/11))\n- Branch protection rule for the default branch (typically `main`)\n\n### How?\n\nThe questions that needed answering in order to bring this tool to life were:\n\n1. **Who does it run as (the 'actor')?** As a [GitHub App](https://docs.github.com/en/developers/apps/getting-started-with-apps/about-apps#about-github-apps) (see [Runtime Requirements](#runtime-requirements)).\n2. **Where does it run?** In GitHub-hosted runners (see [the run workflow](https://github.com/ably/repository-audit/blob/main/.github/workflows/run.yml)).\n3. **How does it get triggered?** Automatically when code is pushed to this repository, periodically to keep the report output fresh and manually if there is a need to update the report before the next periodic update (see [the run workflow](https://github.com/ably/repository-audit/blob/main/.github/workflows/run.yml)).\n4. **What form does the report take?** Markdown. Because:\n    - The GitHub browser UI provides us a free rendering engine for markdown\n    - If formatted logically, markdown is very git-diff friendly\n    - _Keeps It Simple_ and is universally understood by many\n5. **Where does the report output go?** Downstream repositories ([internal/private](https://github.com/ably/repository-audit-report-internal) and [public](https://github.com/ably/repository-audit-report)). See previous answer regarding markdown for the reason why this needs be no more complex than that.\n6. **Is there any potential for monitoring changes to the report output over time?** Yes. Each update to the report is a `git` commit and will generally only update a small part of the report reflecting what has changed since the report was last run. This means we can use `git` tools and the GitHub browser UI to examine these report diffs over time.\n\n## Runtime Requirements\n\nThis tool needs a private key for the GitHub App in order to sign access token requests.\nThat private key is created and downloaded, in PEM format, from the 'Private keys' area within the app's 'General' settings\n([here](https://github.com/organizations/ably/settings/apps/ably-repository-audit),\nonly accessible to those with permissions to act as\n[GitHub App managers](https://docs.github.com/en/organizations/managing-peoples-access-to-your-organization-with-roles/permission-levels-for-an-organization#github-app-managers)).\nThis tool expects that file to be at:\n\n    app-private-key.pem\n\nThis tool also requires the following to be available in the process' environment:\n\n- **`APP_ID`**: Number. The 'App ID' available under 'About' in 'General' settings for the GitHub App.\n- **`APP_CLIENT_ID`**: String. The 'Client ID' available under 'About' in 'General' settings for the GitHub App.\n- **`APP_CLIENT_SECRET`**: String. A 'Client secret' generated under 'Client secrets' in 'General' settings for the GitHub App.\n- **`ORG_INSTALLATION_IDS`**: String, [YAML](http://yaml.org/) formatted. The `installation_id`(s) for the GitHub App within the org(s) that it has been installed into. See [Org Installations](#org-installations) for details.\n\n## Miscellaneous Notes\n\n### Environment Variable and Secret Names\n\nTo make this codebase more navigable we've conformed naming of secrets in the three locations you'll find them, that is:\n\n1. As secrets configured via GitHub's Web UI\n2. As environment variables fed into the Node.js process at runtime\n3. In the source code, populated from `process.env`\n\nThe naming of these secrets, in particular the need to avoid the `GITHUB_` prefix, is constrained by factors which can be found in the GitHub Actions documentation:\n\n- [Security Guides: Encrypted secrets: Naming your secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets#naming-your-secrets):\n- [Learn GitHub Actions: Environment variables: Default environment variables](https://docs.github.com/en/actions/learn-github-actions/environment-variables#default-environment-variables)\n\n### Deploy Keys for Downstream Repositories\n\nThe [run workflow](.github/workflows/run.yml) publishes updates to the report as Git commits to the downstream repositories:\n\n- [ably/repository-audit-report-internal](https://github.com/ably/repository-audit-report-internal): private, only visible to teams within the `ably` org\n- [ably/repository-audit-report](https://github.com/ably/repository-audit-report): public, open\n\nIn order to do this it uses the `INTERNAL_REPORT_REPOSITORY_SSH_KEY` and `PUBLIC_REPORT_REPOSITORY_SSH_KEY` secrets.\n\nCreation and installation of a deploy key involves the following steps:\n\n#### 1. Generate the key pair\n\nUsing `ssh-keygen` on your local machine - for example:\n\n    ssh-keygen -f /tmp/ably-deploy-key -t ed25519 -C \"ably-repository-audit[bot]@noreply.ably.com\"\n\nContrary to the instructions in\n[GitHub's server-configuration-oriented documentation](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#generating-a-new-ssh-key),\nleave the passphrase empty.\n\n#### 2. Install public key\n\nCopy file contents to clipboard:\n\n    cat /tmp/ably-deploy-key.pub | pbcopy\n\nNavigate to the downstream repository's 'Deploy keys' in 'Settings'\n([here](https://github.com/ably/repository-audit-report-internal/settings/keys) for private/internal,\n[here](https://github.com/ably/repository-audit-report/settings/keys) for public,\nrequires `Admin`\n[permissions](https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/repository-permission-levels-for-an-organization))\nand click 'Add deploy key'.\n\nPaste your clipboard contents into 'Key'.\n\nEnter something logical for 'Title' - for example: `repository-audit publish key`\n\n#### 3. Install private key\n\nCopy file contents to clipboard:\n\n    cat /tmp/ably-deploy-key | pbcopy\n\nNavigate to this repository's 'Secrets' for 'Actions' in 'Settings'\n([here](https://github.com/ably/repository-audit/settings/secrets/actions),\nrequires `Admin`\n[permissions](https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/repository-permission-levels-for-an-organization))\nand click 'New repository secret'.\n\nPaste your clipboard contents into 'Value'.\n\nProvide the name expected by the workflow into 'Name':\n\n- `INTERNAL_REPORT_REPOSITORY_SSH_KEY` for the private/internal downstream target repository\n- `PUBLIC_REPORT_REPOSITORY_SSH_KEY` for the public downstream target repository\n\n#### 4. Cleanup locally\n\nDelete the key pair from your local workstation:\n\n```\nrm /tmp/ably-deploy-key\nrm /tmp/ably-deploy-key.pub\n```\n\n### Org Installations\n\nThese are available, for an org into which the GitHub App associated with this tool has been installed, from the browser's address bar (end of URL with prefix `https://github.com/organizations/ORG-NAME/settings/installations/`) if you click 'Configure' under 'Installed GitHub Apps` in org settings.\n\nAt runtime the tool looks for a file named `installations.yml`, whose contents must contain one or more orgs alongside their installation ids.\nFor example (mock installation ids):\n\n```yml\nably: 123\nably-labs: 456\nably-forks: 789\n```\n\nThis file is created by the [rehearse](.github/workflows/rehearse.yml) and [run](.github/workflows/run.yml) workflows from the `ORG_INSTALLATION_IDS` repository secret.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fably%2Frepository-audit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fably%2Frepository-audit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fably%2Frepository-audit/lists"}