Prerequisites

Required package layout

neophile is a very opinionated program designed primarily to support packages built from the templates maintained by the SQuaRE team of Vera C. Rubin Observatory. Some of its features therefore only work with packages laid out in the way provided by those templates.

pre-commit updates will work with any package that has a .pre-commit-config.yaml at the top level, but only pre-commit modules maintained in GitHub are supported. Those are the only ones for which neophile knows how to determine the current version.

Python dependencies are regenerated by running make update-deps at the top level, so packages using frozen dependencie must provide a suitable Makefile. neophile has no opinions about what this make target does, except that it should make changes in the requirements directory if dependencies need to be updated.

GitHub Actions setup

Create a GitHub app

In order to create pull requests to update dependencies, neophile must run as a GitHub App. The credentials provided automatically to a workflow can be used to create a pull request, but normal CI workflows will not run for those pull requests (to avoid loops), and therefore the pull requests cannot be easily verified or merged.

The easiest way to do this is to create a new private GitHub App for the organization that wants to use neophile. Go to the organization page, select Settings, and then go to Developer settings ‣ GitHub Apps at the bottom of the menu on the left. From that screen, you can select New GitHub App.

Since all you need are GitHub App credentials, you can leave most of the settings black. Uncheck the Active box under “Webhook” since neophile doesn’t run as a web hook. Under Repository permissions, grant neophile write access to Contents and Pull requests.

Then, once you’ve created the application, make note of the App ID field on the application page and generate a new client secret. Store these as organization-wide secrets (via Secrets and variables ‣ Actions from the organization settings page). To match the workflow examples (see Using neophile from GitHub Actions), use the secret names NEOPHILE_APP_ID and NEOPHILE_PRIVATE_KEY.

(The App ID is public, so it can go into a variable instead of a secret if you wish. Storing them both as secrets has the advantage of keeping them together if they need to be changed.)

Create a Slack incoming webhook

If you want alerting for failed actions, you will need to create a Slack app (or use an existing one if you already have a suitable one), and then create a Slack incoming webhook for the Slack channel to which you want to send alerts.

To create a new Slack app, go to api.slack.com/apps. (This URL seems weirdly difficult to find from a workspace.) Create a new app (choose From scratch) associated with the workspace to which you want to send alerts. Then, in the settings page for that app, select Incoming Webhooks in the menu on the left and create an incoming webhook for the channel to which you want to send alerts.

This will give you a secret URL that can be used to post messages. Copy that URL into an organization-wide secret (via Secrets and variables ‣ Actions from the organization settings page) for the organization in which neophile will be running (the same organization in which you created the GitHub App above). To match the workflow examples (see Using neophile from GitHub Actions), use the secret name SLACK_ALERT_WEBHOOK.