diff --git a/guides/runbooks/README.md b/guides/runbooks/README.md new file mode 100644 index 0000000..a92839c --- /dev/null +++ b/guides/runbooks/README.md @@ -0,0 +1,5 @@ +# Runbooks + +This directory of runbooks contains various documents detailing the 'how' and 'where' of various un-connecting parts of the Pulsar organization. + +Aimed to be as helpful and concise as possible to inform the Pulsar maintainers of where certain things might be, or how to fix various situations. diff --git a/guides/runbooks/secrets.md b/guides/runbooks/secrets.md new file mode 100644 index 0000000..ed0a832 --- /dev/null +++ b/guides/runbooks/secrets.md @@ -0,0 +1,411 @@ +# Secrets + +This document attempts to cover the 'where' of various secrets, and what they control. + +## 1. GitHub Organization Level Secrets + +The following secrets are stored as `Actions` secrets in the `pulsar-edit` organization. + +Accessible from `https://github.com/organizations/pulsar-edit/settings/secrets/actions`. + +### 1.1 `NPM_PUBLISH_TOKEN` + +#### Description + +This token allows publish access to our `@pulsar-edit` NPM account. Likely this token was generated by a user on the NPM organization that has publish access. + +#### Important + +The secret has very limited _visibility_, only being visible to the repositories we know need to use it, and any new repo **must** be given access to this secret via its own “visibility” setting. + +#### Ownership + +- Accurate as of: August 2025 +- Who: confused-Techie + +## 2 `pulsar-edit/pulsar` Repository Level Secrets + +The following secrets are stored as `Actions` secrets in the `pulsar-edit/pulsar` repository. + +Accessible from `https://github.com/pulsar-edit/pulsar/settings/secrets/actions`. + +### 2.1 `APPLEID` + +#### Description + +The AppleID of a developer Apple account. Allows us to sign macOS binaries produced in GitHub Actions. + +#### Important + +These permissions will fail if the developer has not agreed to the newest Apple Developer terms of service. + +#### Ownership + +- Accurate as of: August 2025 +- Who: meadowsys + +### 2.2 `APPLEID_PASSWORD` + +#### Description + +The AppleID password of a developer Apple account, that allows us to sign macOS binaries produced in GitHub Actions. + +#### Important + +These permissions will fail if the developer has not agreed to the newest Apple Developer terms of service. + +#### Ownership + +- Accurate as of: August 2025 +- Who: meadowsys + +### 2.3 `CSC_KEY_PASSWORD` + +#### Description + +The password to decrypt the certificate given in `CSC_LINK`. Tied to an Apple developer account that allows us to sign macOS binaries produced in GitHub Actions. + +#### Important + +These permissions will fail if the developer has not agreed to the newest Apple Developer terms of service. + +#### Ownership + +- Accurate as of: August 2025 +- Who: meadowsys + +### 2.4 `CSC_LINK` + +#### Description + +The HTTPS link to a certificate. Tied to an Apple developer account that allows us to sign macOS binaries produced in GitHub Actions. + +#### Important + +These permissions will fail if the developer has not agreed to the newest Apple Developer terms of service. + +#### Ownership + +- Accurate as of: August 2025 +- Who: meadowsys + +### 2.5 `ELECTRON_NEXT_BINARIES_UPLOAD_TOKEN` + +#### Description + +A GitHub PAT token that gives access to `pulsar-edit/pulsar-electron-next-binaries`. This ensures that releases can be created and binaries uploaded to it. + +#### Important + +PAT tokens by default have an expiration date, and if/when this token expires it **must** be updated via this secret. + +#### Ownership + +- Accurate as of: August 2025 +- Who: DeeDeeG + +### 2.6 `ROLLING_RELEASE_UPLOAD_TOKEN` + +#### Description + +A GitHub PAT token that gives access to `pulsar-edit/pulsar-rolling-releases`. This ensures that releases can be created and binaries uploaded to it. + +#### Important + +PAT tokens by default have an expiration date, and if/when this token expires it **must** be updated via this secret. + +#### Ownership + +- Accurate as of: August 2025 +- Who: DeeDeeG + +### 2.7 `TEAM_ID` + +#### Description + +A value tied to an Apple developer account that allows us to sign macOS binaries produced in GitHub Actions. + +#### Important + +These permissions will fail if the developer has not agreed to the newest Apple Developer terms of service. + +#### Ownership + +- Accurate as of: August 2025 +- Who: meadowsys + +## 3. CirrusCI Secrets + +The following secrets are stored within CirrusCI as 'Secured Variables'. While a 'Secured Variable' doesn't have any title or way to look it up, this document will use the names we assign to them within `pulsar-edit/pulsar/.cirrus.yml`. + +### 3.1 `GITHUB_TOKEN` + +#### Description + +A GitHub PAT token with zero permissions. This token is used so that CirrusCI's API requests to GitHub are authenticated and have a higher API rate limit. This was done due to a high number of requests when downloading `ripgrep`. + +#### Important + +PAT tokens by default have an expiration date, and if/when this token expires it **must** be updated by creating a new CirrusCI 'Secured Variable' and either modifying the variable within `.cirrus.yml` in `pulsar-edit/pulsar`, or updating the 'Environment variable overrides' entry for `GITHUB_TOKEN` in the Cirrus CI web UI. + +**PERMISSIONS** + +This token requires **zero** permissions, as it doesn't access any organization specific resources. + +#### Ownership + +- Accurate as of: August 2025 +- Who: DeeDeeG + +### 3.2 `ROLLING_UPLOAD_TOKEN` + +#### Description + +Identical to `2.6`. + +#### Important + +PAT tokens by default have an expiration date, and if/when this token expires it **must** be updated by creating a new CirrusCI 'Secured Variable' and modifying the variable within `.cirrus.yml` in `pulsar-edit/pulsar`. + +#### Ownership + +- Accurate as of: August 2025 +- Who: DeeDeeG + +### 3.3 `CSC_LINK` + +#### Description + +Identical to `2.4`. + +#### Important + +Identical to `2.4`. + +#### Ownership + +Identical to `2.4`. + +### 3.4 `CSC_KEY_PASSWORD` + +#### Description + +Identical to `2.3`. + +#### Important + +Identical to `2.3`. + +#### Ownership + +Identical to `2.3`. + +### 3.5 `APPLEID` + +#### Description + +Identical to `2.1`. + +#### Important + +Identical to `2.1`. + +#### Ownership + +Identical to `2.1`. + +### 3.6 `APPLEID_PASSWORD` + +#### Description + +Identical to `2.1`. + +#### Important + +Identical to `2.1`. + +#### Ownership + +Identical to `2.1`. + +### 3.7 `TEAM_ID` + +#### Description + +Identical to `2.7`. + +#### Important + +Identical to `2.7`. + +#### Ownership + +Identical to `2.7`. + +### 3.8 `ROLLING_UPLOAD_TOKEN` + +#### Description + +Identical to `2.6`. + +#### Important + +PAT tokens by default have an expiration date, and if/when this token expires it **must** be updated by creating a new CirrusCI 'Secured Variable' and modifying the variable within `.cirrus.yml` in `pulsar-edit/pulsar`. + +#### Ownership + +- Accurate as of: August 2025 +- Who: DeeDeeG + +## 4. Google Cloud: Secret Manager + +The following secrets are stored in GCP's 'Secret Manager'. To access you **must** be added to the 'pulsar' GCP project. To modify any of these secrets you **must** be given `secretmanager.secrets.update` permissions within GCP. + +### 4.1 `ASC_MICROSERVICE_DB_DB` + +#### Description + +The database name for Pulsar's Package Registry Database. + +This is used by the `pulsar-edit/package-frontend` microservice `auth-state-cleanup` to preform periodic cleanup of saved `state` keys used to protect against cross-site request forgery attacks during the GitHub OAuth signup flow. + +#### Important + +The value here is defined in DigitalOcean's `db-pgsql-pulsar` dashboard, under the 'Connection Pools' tab. As this is the 'table' that the microservice connects to. + +#### Ownership + +N/A + +### 4.2 `ASC_MICROSERVICE_DB_HOST` + +#### Description + +The database hostname for Pulsar's Package Registry Database. + +Identical to `4.1`. + +#### Important + +The value here is defined in DigitalOcean's `db-pgsql-pulsar` dashboard, under the 'Overview' tab under 'Connection Details'. As this DigitalOcean controls the hostname we connect to. + +#### Ownership + +N/A + +### 4.3 `ASC_MICROSERVICE_DB_PASS` + +#### Description + +The database password for Pulsar's Package Registry Database. + +Identical to `4.1`. + +#### Important + +The value here is defined in DigitalOcean's `db-pgsql-pulsar` dashboard, under the 'Users & Databases' tab. As this defines the user's available. + +#### Ownership + +N/A + +### 4.4 `ASC_MICROSERVICE_DB_PORT` + +#### Description + +The database port for Pulsar's Package Registry Database. + +Identical to `4.1`. + +#### Important + +The value here is defined in DigitalOcean's `db-pgsql-pulsar` dashboard, under the 'Overview' tab under 'Connection Details'. As this DigitalOcean controls the port we connect to. + +#### Ownership + +N/A + +### 4.5 `ASC_MICROSERVICE_DB_SSL_CERT` + +#### Description + +The database SSL certificate for Pulsar's Package Registry Database. + +Identical to `4.1`. + +#### Important + +The value here is defined in DigitalOcean's `db-pgsql-pulsar` dashboard, under the 'Overview' tab under 'Connection Details'. As this DigitalOcean controls the SSL certificate we use. + +#### Ownership + +N/A + +### 4.6 `ASC_MICROSERVICE_DB_USER` + +#### Description + +The database username for Pulsar's Package Registry Database. + +Identical to `4.1` + +#### Important + +Identical to `4.3`. + +#### Ownership + +N/A + +### 4.7 `DISCORD_SPONSOR_WEBHOOK` + +#### Description + +The Webhook URL used to post to the `#donations` Discord channel as the user `GitHub Sponsors`. This URL is used by the `pulsar-edit/package-frontend` microservice `webhooks` to post modified webhooks from GitHub Sponsors, more about this process in 4.9. + +#### Important + +This will likely never change, but it's value is stored in the Pulsar Discord Server: Server Settings > Apps > Integrations > Webhooks > GitHub Sponsors + +#### Ownership + +The value of this URL is owned and controlled by Discord. + +### 4.8 `GH_TOKEN_DOWNLOAD_MICROSERVICE` + +#### Description + +A GitHub PAT token with zero permissions. This token is used so that the `pulsar-edit/frontend` microservice `download` has higher rate limits against the GitHub API. + +#### Important + +PAT tokens by default have an expiration date, and if/when this token expires it **must** be updated by updating the value in GCP's Secret Manager Dashboard. + +#### Permissions + +This token requires **zero** permissions, as it doesn't access any organization specific resources. + +#### Ownership + +- Accurate as of: August 2025 +- Who: confused-Techie + +### 4.9 `WEBHOOKS_MICROSERVICE_TOKEN` + +#### Description + +A secret token that validates a legit webhook request from Github. + +This token is a random string manually inserted into the webhook details for Pulsar's GitHub Sponsors webhook. The same exact token is then used in this variable on GCP, so that when the `webhook` microservice receives a request it can check if the two tokens match, so that it knows the request came from GitHub. + +If it did, it will then modify the webhook data to be compatible in Discord, so that GitHub Sponsors alerts can be sent in the `#donations` Discord channel. + +#### Important + +It's best to avoid ever changing this value. As it **must** be changed along with the token used in the GitHub Sponsors Webhook settings (which are different than GitHub Webhook settings). + +If changed, this value is currently a random string, and is consumed by the `pulsar-edit/package-frontend` microservice `webhooks`. + +#### Ownership + +N/A