#############
Prerequisites
#############

.. _package-layout:

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 :file:`.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 :file:`Makefile`.
neophile has no opinions about what this make target does, except that it should make changes in the :file:`requirements` directory if dependencies need to be updated.

.. _actions-setup:

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 :guilabel:`Settings`, and then go to :menuselection:`Developer settings --> GitHub Apps` at the bottom of the menu on the left.
From that screen, you can select :guilabel:`New GitHub App`.

Since all you need are GitHub App credentials, you can leave most of the settings black.
Uncheck the :guilabel:`Active` box under "Webhook" since neophile doesn't run as a web hook.
Under :menuselection:`Repository permissions`, grant neophile write access to :menuselection:`Contents` and :menuselection:`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 :menuselection:`Secrets and variables --> Actions` from the organization settings page).
To match the workflow examples (see :doc:`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 <https://api.slack.com/apps>`__.
(This URL seems weirdly difficult to find from a workspace.)
Create a new app (choose :guilabel:`From scratch`) associated with the workspace to which you want to send alerts.
Then, in the settings page for that app, select :menuselection:`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 :menuselection:`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 :doc:`github-actions`), use the secret name ``SLACK_ALERT_WEBHOOK``.
