Add manually triggered action for pushing docker image by SHA (#636)

* Add manually triggered action for pushing docker image by SHA

* Add pull request trigger for testing

* Reference image variable correctly

* Fix env var usage

* Singularize event

* Add publish documentation

.github/workflows/push_docker_image.yml

@@ -0,0 +1,40 @@
+name: Publish Docker images on-demand
+on:
+  workflow_dispatch:
+    inputs:
+      image:
+        description: Image to push (either `api` or `ingestion_server`)
+        required: true
+
+jobs:
+  push:
+    name: Publish requested Docker image
+    runs-on: ubuntu-latest
+    permissions:
+      packages: write
+      contents: read
+    steps:
+      - name: Log in to GitHub Docker Registry
+        uses: docker/login-action@v1
+        with:
+          registry: https://ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Download image `${{ github.event.inputs.image }}`
+        uses: dawidd6/action-download-artifact@v2
+        with:
+          workflow: ci_cd.yml
+          workflow_conclusion: success
+          pr: ${{github.event.pull_request.number}}
+          name: ${{ github.event.inputs.image }}
+          path: /tmp
+
+      - name: Load and tag image `${{ github.event.inputs.image }}`
+        env:
+          INPUT_IMAGE: ${{ github.event.inputs.image }}
+        run: |
+          docker load --input /tmp/$INPUT_IMAGE.tar
+          docker tag openverse-$INPUT_IMAGE \
+            ghcr.io/wordpress/openverse-$INPUT_IMAGE:${{ github.sha }}
+          docker push --all-tags ghcr.io/wordpress/openverse-$INPUT_IMAGE

api/docs/guides/index.md

@@ -11,5 +11,6 @@ quickstart
 run
 test
 document
+publish
 deploy
 ```

api/docs/guides/publish.md

@@ -0,0 +1,45 @@
+# Publish
+
+The production API and ingestion server Docker images are published to [Github Container Registry](ghcr.io).
+They can be found here:
+* API: [ghcr.io/wordpress/openverse-api](https://ghcr.io/wordpress/openverse-api)
+* Ingestion server: [ghcr.io/wordpress/openverse-ingestion_server](https://ghcr.io/wordpress/openverse-ingestion_server)
+
+These images are published under two conditions: on release, or manually.
+
+## On release
+
+When a new release is cut, the [CI/CD action will run](https://github.com/WordPress/openverse-api/actions/workflows/ci_cd.yml?query=event%3Arelease).
+The final step of this action uploads the Docker images to their respective registries with the following tags:
+* Release reference name, typically the git tag (e.g. `v2.4.2`)
+* `latest`
+* The commit SHA of the tagged commit (e.g. `b25879b84ec9d7b650be689c03384937a93eb06d`)
+
+In some cases, releases may not alter the Docker image.
+For instance, in a release where only the API was changed, the ingestion server image would have the same Docker image hash.
+In these instances, the new tags are added to the existing image.
+
+## Manually
+
+The Docker image for a particular service can also be published manually.
+This process is initiated by the [Publish Docker images on-demand](https://github.com/WordPress/openverse-api/actions/workflows/push_docker_image.yml) action.
+The workflow file for this action can be found here: [`push_docker_image.yml`](https://github.com/WordPress/openverse-api/blob/main/.github/workflows/push_docker_image.yml).
+
+This action **will only publish & tag a service's image with the commit SHA** (i.e. it will not tag with `latest` or the git reference name).
+This is useful for cases where one or more Docker images need to be tested on a staging environment before being merged and cut with a release.
+Note that this action can only run on branches/commits/tags that were made within the last 90 days [due to GitHub's default artifact retention policy](https://docs.github.com/en/organizations/managing-organization-settings/configuring-the-retention-period-for-github-actions-artifacts-and-logs-in-your-organization).
+
+### Steps
+
+_Note: [GitHub's documentation provides screenshots for the various steps](https://github.blog/changelog/2020-07-06-github-actions-manual-triggers-with-workflow_dispatch)_
+
+% TODO: Add screenshots to the below steps once the button is available in the GitHub UI
+
+1. Navigate to the `openverse-api` "Actions" tab in GitHub: [github.com/WordPress/openverse-api/actions](https://github.com/WordPress/openverse-api/actions).
+2. Select the "Publish Docker images on-demand" workflow.
+3. Click the "Run workflow" button.
+4. Select the target branch to build (this can also be `main`).
+5. For the `image` parameter, specify either `api` or `ingestion_server`.
+6. Click the green "Run workflow" button.
+
+The newest run should appear in the Action list, and its status can be tracked from there.

api/docs/guides/test.md

@@ -8,7 +8,7 @@
    ```
    This step is a part of the {doc}`"Quickstart" <./quickstart>` process.
 
-3. Run the tests in an interactive TTY connected to a `web` container.
+2. Run the tests in an interactive TTY connected to a `web` container.
    ```bash
    just api-test
    ```