Enhancement: Add composite actions for starting and stopping maintena…

…nce periods on Oh Dear

CHANGELOG.md

@@ -8,6 +8,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 For a full diff see [`1.5.1...main`][1.5.1...main].
 
+### Added
+
+- Added composite actions `oh-dear/maintenance-period/start` and `oh-dear/maintenance-period/stop` for starting and stopping maintenance periods on [ohdear.app](https://ohdear.app) ([#123]), by [@localheinz]
+
 ## [`1.5.1`][1.5.1]
 
 For a full diff see [`1.5.0...1.5.1`][1.5.0...1.5.1].
@@ -143,5 +147,6 @@ For a full diff see [`1.0.0...main`][1.0.0...main].
 [#82]: https://github.com/ergebnis/.github/pull/82
 [#87]: https://github.com/ergebnis/.github/pull/87
 [#96]: https://github.com/ergebnis/.github/pull/96
+[#123]: https://github.com/ergebnis/.github/pull/123
 
 [@localheinz]: https://github.com/localheinz

README.md

@@ -22,6 +22,8 @@ This repository provides the following composite actions:
 - [`ergebnis/.github/actions/github/pull-request/merge`](#github-pull-request-merge)
 - [`ergebnis/.github/actions/github/pull-request/request-review`](#github-pull-request-review)
 - [`ergebnis/.github/actions/github/release/create`](#github-release-create)
+- [`ergebnis/.github/actions/oh-dear/maintenance-period/start`](#oh-dear-maintenance-period-start)
+- [`ergebnis/.github/actions/oh-dear/maintenance-period/stop`](#oh-dear-maintenance-period-stop)
 
 ### <a name="composer-determine-cache-directory"> `ergebnis/.github/actions/composer/determine-cache-directory`
 
@@ -514,6 +516,98 @@ none
 
 A release is created by the user who owns the GitHub token specified with the `github-token` input.
 
+### <a name="oh-dear-maintenance-period-start"> `ergebnis/.github/actions/oh-dear/maintenance-period/start`
+
+This action starts a [maintenance period](https://ohdear.app/docs/general/maintenance-windows) on [Oh Dear!](https://ohdear.app).
+
+```yaml
+name: "Deploy"
+
+on:
+  push:
+    branches:
+      - "main"
+
+jobs:
+  deploy:
+    name: "Deploy"
+
+    runs-on: "ubuntu-latest"
+
+    steps:
+    - name: "Checkout"
+      uses: "actions/[email protected]"
+      with:
+          fetch-depth: 50
+
+    - name: "Start maintenance period on ohdear.app"
+      uses: "ergebnis/.github/actions/oh-dear/maintenance-period/[email protected]"
+      with:
+        oh-dear-api-token: "${{ secrets.OH_DEAR_API_TOKEN }}"
+        oh-dear-site-id: "${{ secrets.OH_DEAR_SITE_ID }}"
+```
+
+For details, see [`actions/oh-dear/maintenance-period/start/action.yaml`](actions/oh-dear/maintenance-period/start/action.yaml).
+
+#### Inputs
+
+- `oh-dear-api-token`, required: The Oh Dear API token of a user with permission to start a maintenance period
+- `oh-dear-site-id`, required: Site identifer of an Oh Dear site for which to start a maintenance period
+
+#### Outputs
+
+none
+
+#### Side Effects
+
+A maintenance period is started by the user who owns the Oh Dear API token specified with the `oh-dear-api-token` input for the site identified by the `oh-dear-site-id` input.
+
+### <a name="oh-dear-maintenance-period-stop"> `ergebnis/.github/actions/oh-dear/maintenance-period/stop`
+
+This action stops a [maintenance period](https://ohdear.app/docs/general/maintenance-windows) on [Oh Dear!](https://ohdear.app).
+
+```yaml
+name: "Deploy"
+
+on:
+  push:
+    branches:
+      - "main"
+
+jobs:
+  deploy:
+    name: "Deploy"
+
+    runs-on: "ubuntu-latest"
+
+    steps:
+    - name: "Checkout"
+      uses: "actions/[email protected]"
+      with:
+          fetch-depth: 50
+
+    - name: "Stop maintenance period on ohdear.app"
+      uses: "ergebnis/.github/actions/oh-dear/maintenance-period/[email protected]"
+      with:
+        oh-dear-api-token: "${{ secrets.OH_DEAR_API_TOKEN }}"
+        oh-dear-site-id: "${{ secrets.OH_DEAR_SITE_ID }}"
+```
+
+For details, see [`actions/oh-dear/maintenance-period/stop/action.yaml`](actions/oh-dear/maintenance-period/stop/action.yaml).
+
+#### Inputs
+
+- `oh-dear-api-token`, required: The Oh Dear API token of a user with permission to stop a maintenance period
+- `oh-dear-site-id`, required: Site identifer of an Oh Dear site for which to stop a maintenance period
+
+#### Outputs
+
+none
+
+#### Side Effects
+
+A maintenance period is stopped by the user who owns the Oh Dear API token specified with the `oh-dear-api-token` input for the site identified by the `oh-dear-site-id` input.
+
 ## Changelog
 
 Please have a look at [`CHANGELOG.md`](CHANGELOG.md).

actions/oh-dear/maintenance-period/start/action.yaml

@@ -0,0 +1,28 @@
+# https://docs.github.com/en/actions/creating-actions/creating-a-composite-action
+# https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions#inputs
+# https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions#runs-for-composite-run-steps-actions
+# https://ohdear.app/docs/integrations/api/maintenance-windows#creating-a-new-maintenance-period-on-demand
+
+name: "Starts maintenance period"
+
+description: "Starts maintenance period"
+
+inputs:
+  oh-dear-api-token:
+    description: "Oh Dear API token of a user with permission to start maintenance period"
+    required: true
+  oh-dear-site-id:
+    description: "Site identifer of an Oh Dear site for which to start a maintenance period"
+    required: true
+
+runs:
+  using: "composite"
+
+  steps:
+    - name: "Start maintenance period on ohdear.app"
+      run: |
+        curl -X POST https://ohdear.app/api/sites/${{ inputs.oh-dear-site-id }}/start-maintenance \
+          -H "Authorization: Bearer ${{ inputs.oh-dear-api-token }}" \
+          -H "Accept: application/json" \
+          -H "Content-Type: application/json"
+      shell: "bash"

actions/oh-dear/maintenance-period/stop/action.yaml

@@ -0,0 +1,28 @@
+# https://docs.github.com/en/actions/creating-actions/creating-a-composite-action
+# https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions#inputs
+# https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions#runs-for-composite-run-steps-actions
+# https://ohdear.app/docs/integrations/api/maintenance-windows#creating-a-new-maintenance-period-on-demand
+
+name: "Starts maintenance period"
+
+description: "Starts maintenance period"
+
+inputs:
+  oh-dear-api-token:
+    description: "Oh Dear API token of a user with permission to start maintenance period"
+    required: true
+  oh-dear-site-id:
+    description: "Site identifer of an Oh Dear site for which to start a maintenance period"
+    required: true
+
+runs:
+  using: "composite"
+
+  steps:
+    - name: "Stop maintenance period on ohdear.app"
+      run: |
+        curl -X POST https://ohdear.app/api/sites/${{ inputs.oh-dear-site-id }}/stop-maintenance \
+          -H "Authorization: Bearer ${{ inputs.oh-dear-api-token }}" \
+          -H "Accept: application/json" \
+          -H "Content-Type: application/json"
+      shell: "bash"