ListSky

ListSky is a repository app that can manage any number of BlueSky lists.

When a pull request is merged to main, the contents of the Data directory are used to update each list on BlueSky.

The application also publishes the contents of all lists through GitHub Pages. See: ListSky

How to add people to these lists

There are 2 ways to submit an update to the lists:

1. Create a pull request (preferred)
2. Create an issue

Each is explained below.

1. Create a pull request (fast option, bit technical)

This tool will update lists on BlueSky based on edits made to CSV files in the Data directory.

1. Fork this repository

2. Make your edits to a list CSV in the Data directory

   (eg. edit Data/list-ci.csv to add a new Collective Intelligence person)

3. Commit and push your change to your fork

4. Create a pull request for your change to the source repository

5. Tests will run against your pull request to make sure there are no mistakes

6. Your pull request will be reviewed, and if it passes it will be merged into the main repository

Here's an example pull request. If in doubt, ask a developer friend to help!

2. Create an issue (bit slower, bit less technical)

You could also create a new issue. Make sure you provide enough info about the people you want to add. (As a minimum, provide a name, description, BlueSky account, and state which list you'd like to add them to.)

• Name
• Description
• Record type (individual / organisation / community / bot)
• BlueSky account
• List(s) to add them to

You can also add details of a number of other accounts:

• Other accounts (optional)
  • Mastodon
  • Twitter
  • LinkedIn
  • YouTube
  • GitHub
  • RSS feed url
  • Website url
  • Blog url

This is a bit less technical - someone will review this and manually modify the list. It'll also go a bit slower as they have a little more work to do this way.

Required fields

Please ensure you provide a value for:

• Name - name of the person/organisation/community/bot to include in the list
• Type - type of record (see below)
• Description - a description of the record you're adding that links it to the list
• AccountName_BlueSky - the AT account name - for BlueSky these are often suffixed with .bsky.social, eg. instantiator.bsky.social

All other columns are optional, but very helpful!

Type of record

When editing a CSV record, note that it must have a value in the Type column. This can be:

• Individual - a person who should be included in the list
• Organisation - a charity, company, government department, etc. (ie. a formal organisation)
• Community - an account representing an association of people that's not a formal organisation
• Bot - a helpful bot that ought to be included in the list

NB. Match the spelling and capitalisation above - in particular the UK English spelling of Organisation!

Build your own ListSky

1. Fork this repository
2. You may need to enable github actions through GitHub
3. Create secrets to configure your instance (described in the following section)
4. Create all the lists you're going to use, and get their ids
5. Create new CSV files in the Data directory for each list, copy headings from existing CSV files
6. Modify Data/lists.jsonc to point to your new lists and new CSV files
7. Set up branch protections to prevent accidental pushes to main
8. Require that the tests pass before pull requests can be merged (use workflow on-pull-request-run-tests)

Configuration

To configure the runtime environment, provide values for the following GithHub Actions repository secrets:

• Server_AT (the AT server, eg. bsky.social)
• AccountName_AT (the account that publishes the lists, eg. instantiator.bsky.social)
• AppPassword_AT (create an app password for this use case)
• Path_AllListsMetadataJson (relative path to your config, probably best left as: Data/lists.jsonc)

To test locally, create a file called test.env file in the root of this repository, and provide values for these properties:

Server_AT=
AccountName_AT=
AppPassword_AT=
Path_AllListsMetadataJson=
GITHUB_REPO=
GITHUB_USER=

NB. GITHUB_REPO and GITHUB_USER are provided by GitHub Actions, so do not need to be provided as repository secrets.

Developer notes

Build and test locally

Use the run-tests.sh script. This will first source environment variables from your test.env file - so that you can test from

./run-tests.sh

⚠️ Warning. The tests clean up after themselves by deleting all lists on the test profile starting with the words: Unit test

Use the test-app.sh script with the apply command to run the application with environment variables from test.env.

./test-app.sh apply

Testing workflows

Install act and the GitHub CLI...

brew install act
brew install gh

You'll need to provide a github token to act to be able to interact with you repository. gh auth token can provide this, and we pass that in to act as a secret called GITHUB_TOKEN

gh auth login

Use act to simulate running tests on a pull request:

act -W .github/workflows/on-pull-request-run-tests.yaml --secret-file test.env -s GITHUB_TOKEN="$(gh auth token)" -j "on-pull-request-run-tests"

Use act to invoke the tests action directly:

act -W .github/workflows/actions/run-tests.yaml --secret-file test.env -s GITHUB_TOKEN="$(gh auth token)" -j "run-listsky-tests"

Use act to simulate a push to main:

act -W .github/workflows/on-push-to-main-apply.yaml --secret-file test.env -s GITHUB_TOKEN="$(gh auth token)" -j "on-push-to-main-apply"